polygram 0.12.0-rc.9 → 0.12.0

package/lib/process/hook-event-tail.js

@@ -51,6 +51,9 @@ const KNOWN_EVENT_NAMES = new Set([
   'SubagentStop',
   'Stop',
   'Notification',
+  // 0.12.0-rc.13: compaction lifecycle (carry `trigger` + custom_instructions).
+  'PreCompact',
+  'PostCompact',
 ]);
 
 /**
@@ -87,6 +90,10 @@ function normalizeHookEvent(raw) {
     prompt:              raw?.prompt ?? null,
     stopHookActive:      raw?.stop_hook_active ?? null,
     lastAssistantMessage: raw?.last_assistant_message ?? null,
+    // PreCompact/PostCompact payload: trigger distinguishes auto vs manual
+    // compaction; custom_instructions is the `/compact <hint>` text (manual).
+    trigger:             raw?.trigger ?? null,
+    customInstructions:  raw?.custom_instructions ?? null,
     receivedAtMs:        raw?.polygram_received_at_ms ?? null,
     raw,
   };

package/lib/process/hook-settings.js

@@ -44,6 +44,13 @@ const HOOK_EVENTS = [
   'SubagentStop',
   'Stop',
   'Notification',
+  // 0.12.0-rc.13: compaction lifecycle. PreCompact fires when claude is about
+  // to (auto-)compact — the moment that detaches the channels MCP bridge.
+  // PostCompact fires after, when context has dropped (used to re-arm the
+  // per-chat compaction warning). Both confirmed supported by the pinned CLI
+  // (2.1.142) and carry a `trigger: auto|manual` field.
+  'PreCompact',
+  'PostCompact',
 ];
 
 /**

package/lib/process/process.js

@@ -160,6 +160,28 @@ 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;
+  }
+
+  /**
+   * 0.13 D1 (S9): does this process have an open interactive question?
+   * Backends without the ask feature return false; CliProcess overrides.
+   * ProcessManager._evictLRU treats true like inFlight (eviction pin).
+   */
+  hasOpenQuestions() {
+    return false;
+  }
+
   /**
    * Push priority='now' style steer (rare; legacy of OpenClaw shape).
    * Hot-path-safe.

package/lib/process-guard.js

@@ -193,7 +193,60 @@ function _makeUnhandledRejectionHandler(opts) {
 }
 
 /**
- * Convenience: install both handlers in one call.
+ * Swallow EPIPE/EIO on the process's own stdout/stderr so a broken pipe during
+ * shutdown can't become an uncaughtException.
+ *
+ * rc.50 stopped the re-entrant LOOP (the handler no longer re-throws), but the
+ * write errors themselves still surface: when `launchctl kickstart` destroys the
+ * tmux pane, in-flight `console.log`/`console.error` calls hit a now-dead pty.
+ * Because stdout/stderr are TTYs, those writes throw EIO **synchronously** — each
+ * unguarded throw becomes an uncaughtException. Observed live on the rc.29→rc.30
+ * restart (2026-06-08): 100 `write EIO` rows then a circuit-breaker panic-exit on
+ * every deploy, interrupting the graceful drain.
+ *
+ * This guards BOTH delivery paths:
+ *   (a) sync: wraps `write()` to drop EPIPE/EIO throws (TTY case — the real one);
+ *   (b) async: attaches an `error` listener for the pipe case (errors arrive as
+ *       events). Genuine, non-EPIPE/EIO errors still surface unchanged.
+ *
+ * @returns {{ uninstall: function() }}
+ */
+function guardStdio({ streams = [process.stdout, process.stderr] } = {}) {
+  const guarded = streams.filter(Boolean);
+  const isBrokenPipe = (err) => err && (err.code === 'EPIPE' || err.code === 'EIO');
+  const onError = (err) => { if (isBrokenPipe(err)) return; throw err; };
+  const restores = [];
+
+  for (const s of guarded) {
+    s.on?.('error', onError);
+    restores.push(() => s.off?.('error', onError));
+
+    if (typeof s.write === 'function' && !s.__polygramStdioGuarded) {
+      const origWrite = s.write;
+      s.write = function guardedWrite(...args) {
+        try {
+          return origWrite.apply(this, args);
+        } catch (err) {
+          if (!isBrokenPipe(err)) throw err;
+          // Pane is gone — nothing to write to. Invoke the write callback (the
+          // last arg, if any) so callers awaiting it don't hang, and report
+          // backpressure (false) instead of throwing to uncaughtException.
+          const cb = args[args.length - 1];
+          if (typeof cb === 'function') { try { cb(err); } catch { /* ignore */ } }
+          return false;
+        }
+      };
+      s.__polygramStdioGuarded = true;
+      restores.push(() => { s.write = origWrite; delete s.__polygramStdioGuarded; });
+    }
+  }
+
+  return { uninstall() { for (const r of restores) r(); } };
+}
+
+/**
+ * Convenience: install both handlers in one call (plus the stdio guard, so the
+ * shutdown broken-pipe writes never reach the uncaughtException handler).
  * @returns {{ uninstall: function() }}
  */
 function installSafetyHandlers(opts) {
@@ -201,10 +254,12 @@ function installSafetyHandlers(opts) {
   const onRejection = _makeUnhandledRejectionHandler(opts);
   process.on('uncaughtException', onException);
   process.on('unhandledRejection', onRejection);
+  const stdio = guardStdio();
   return {
     uninstall() {
       process.off('uncaughtException', onException);
       process.off('unhandledRejection', onRejection);
+      stdio.uninstall();
     },
   };
 }
@@ -235,6 +290,7 @@ module.exports = {
   claimPidFile,
   releasePidFile,
   installSafetyHandlers,
+  guardStdio,
   _makeUncaughtHandler,
   _makeUnhandledRejectionHandler,
 };

package/lib/process-manager.js

@@ -41,6 +41,33 @@ const CALLBACK_TO_EVENT = {
   onAssistantMessageStart:      'assistant-message-start',
   onAutonomousAssistantMessage: 'autonomous-assistant-message',
   onCompactBoundary:            'compact-boundary',
+  // 0.12.0-rc.13: per-chat compaction warning. CliProcess emits
+  // 'compaction-warn' {kind:'proactive'|'reactive', pct?} when (proactive)
+  // context crosses the chat's threshold at turn-end, or (reactive) claude is
+  // auto-compacting now. The callback posts a chat message proposing /compact
+  // — opt-in per chat. See docs/0.12.0-file-send.md / lib/compaction-warn.js.
+  onCompactionWarn:             'compaction-warn',
+  // 0.12.0 background-work visibility (Use 3). CliProcess emits 'bg-work-status'
+  // {state:'running'|'cleared', count?} when a detached background shell is first
+  // observed running idle past its turn, and again when it clears. The callback
+  // posts/edits a "⏳ working in background" status message so a long job reads as
+  // working, not stuck. See docs/0.12.0-background-work-lifecycle-plan.md.
+  onBgWorkStatus:               'bg-work-status',
+  // 0.12 interactive questions: CliProcess emits 'question-asked'
+  // {sessionKey, chatId, threadId, turnId, toolCallId, questions} when claude calls
+  // the `ask` tool. The callback (polygram) renders the Telegram inline keyboard;
+  // the user's tap/typed answer routes back via pm.answerQuestion → writeQuestionAnswer.
+  onQuestionAsked:              'question-asked',
+  // 0.12.0 question-progress-resume: CliProcess emits 'question-resumed' (no payload) when a
+  // blocking `ask` resolves with a real answer and the turn resumes working. The callback
+  // re-arms the per-turn reactor (it cleared during the wait, no hooks re-lit it). See
+  // docs/0.12.0-question-resume-progress-spec.md.
+  onQuestionResumed:            'question-resumed',
+  // 0.13 D2: CliProcess emits 'input-dropped' {turnId, msgId, chatId, source}
+  // when a ledgered input was confirmed dropped (never seen/acked by cycle-end
+  // + confirm window, contract observed). polygram redelivers ONCE via the D4
+  // tail (lib/handlers/drop-redeliver.js).
+  onInputDropped:               'input-dropped',
   onQueueDrop:                  'queue-drop',
   onThinking:                   'thinking',
   // Tmux backend: TUI shows in-pane approval prompt. SDK backend
@@ -48,31 +75,15 @@ const CALLBACK_TO_EVENT = {
   // onApprovalRequired to route tmux prompts through the SAME
   // approval card UI used by SDK's canUseTool flow.
   onApprovalRequired:           'approval-required',
-  // rc.7: tmux backend autosteer "NEW-TURN" extra reply. Fires when
-  // the TUI's queue dequeued an autosteered paste as a fresh user
-  // turn (because primary turn ended before fold could happen). The
-  // payload is { msgId, text, sessionId, backend } and polygram
-  // routes it to Telegram as a reply to the autosteered msgId. SDK
-  // backend never emits this — its PostToolBatch fold path
-  // guarantees one combined reply.
-  onExtraTurnReply:             'extra-turn-reply',
-  // rc.9: pair-of with onExtraTurnReply. Fires the MOMENT TmuxProcess
-  // sees the dequeued user-message in JSONL, which is the start of
-  // turn 2 — gives polygram a hook to re-engage typing indicator and
-  // re-apply the ✍ reaction on the autosteered msg (otherwise the
-  // user sees a silent gap from when clearAutosteeredReactions fired
-  // at primary turn 1 success until the extra-turn reply lands).
-  // Payload: { msgId, sessionId, backend }.
-  onExtraTurnStarted:           'extra-turn-started',
-  // rc.11.1: observability — autosteer resolution + match-miss events.
-  // - autosteer-resolution: { msgId, via: 'fold'|'new-turn' } —
-  //   confirms which JSONL signal resolved each autosteered msgId.
-  // - autosteer-match-miss: { phase, *_head, pending_count } —
-  //   fires when JSONL has the queue/dequeue signal but content
-  //   doesn't match any pending. The signature of the rc.11.1 bug
-  //   (oneLine ' / ' vs newline mismatch) would have shown up here.
-  onAutosteerResolution:        'autosteer-resolution',
-  onAutosteerMatchMiss:         'autosteer-match-miss',
+  // 0.13 P4: the tmux-era rows (onExtraTurnReply/-Started, onAutosteerResolution/
+  // -MatchMiss) were removed — zero emitters on any backend since the 0.12 tmux
+  // deletion; the 'autosteer-resolution' audit trail returns as D2 ledger events.
+  // 0.13 D3: 'turn-start' (UserPromptSubmit; payload {hasPending, anchorMsgId})
+  // and 'idle' get polygram-side consumers — the session feedback controller's
+  // start/stop edges for cycles with no pending turn. ('idle' is ALSO wired
+  // internally for LRU waiters in _wireCallbacks — both fire.)
+  onTurnStart:                  'turn-start',
+  onIdle:                       'idle',
   // R8: tmux backend autosteer paste failure. TmuxProcess.injectUserMessage
   // fires `inject-fail` when its fire-and-forget paste rejects. Before
   // this was wired the event had no consumer — a failed autosteer was
@@ -220,7 +231,23 @@ class ProcessManager {
       // caller receives a proc whose start() has fully resolved.
       const pendingStart = this._starting.get(sessionKey);
       if (pendingStart) await pendingStart;
-      return existing;
+      // Reload-on-drift (cli): a warm cli proc can't hot-swap model/effort
+      // (spawn-time flags). If the resolved config has drifted and the proc is
+      // idle, kill it (preserves session_id) and fall through to a cold respawn
+      // → --resume keeps the conversation, the new --model/--effort takes
+      // effect. In-flight cli procs and SDK procs (no wouldReloadFor — they
+      // apply model live) are reused unchanged.
+      if (typeof existing.wouldReloadFor === 'function' && existing.wouldReloadFor(spawnContext)) {
+        this._logEvent('cli-config-reload', {
+          sessionKey,
+          from_model: existing.model,
+          from_effort: existing.effort,
+        });
+        await this.kill(sessionKey, 'config-reload');
+        // fall through to the cold-spawn path below — respawns with --resume
+      } else {
+        return existing;
+      }
     }
 
     // Provisional new-process cost — ask the factory but don't start yet.
@@ -228,16 +255,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);
@@ -261,8 +308,16 @@ 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; }
+      // PIN (0.13 D1, S9): a session blocked on an open interactive question is
+      // NOT evictable — the keyboard is live and claude is blocked on the ask;
+      // killing it silently strands both. Skip like inFlight.
+      if (typeof p.hasOpenQuestions === 'function' && p.hasOpenQuestions()) { pinnedSkipped++; continue; }
       if (!oldest || (p.lastUsedTs || 0) < (oldest.lastUsedTs || 0)) {
         oldest = p;
         oldestKey = k;
@@ -273,6 +328,7 @@ class ProcessManager {
         active: this.procs.size,
         totalCost: this.totalCost,
         budget: this.budget,
+        pinnedSkipped,
       });
       return false;
     }
@@ -280,12 +336,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(() => {
@@ -446,6 +523,14 @@ class ProcessManager {
     return p.injectUserMessage(opts);
   }
 
+  // 0.12 interactive questions: hand an answer back to a blocking `ask` tool call.
+  // Returns false if the session is gone (claude is dead → nothing to answer).
+  answerQuestion(sessionKey, toolCallId, result) {
+    const p = this.procs.get(sessionKey);
+    if (!p || p.closed || typeof p.writeQuestionAnswer !== 'function') return false;
+    return p.writeQuestionAnswer(toolCallId, result);
+  }
+
   steer(sessionKey, text, opts) {
     const p = this.procs.get(sessionKey);
     if (!p || p.closed) return false;

package/lib/questions/questions.js

@@ -0,0 +1,187 @@
+/**
+ * Interactive-question state machine + Telegram rendering (0.12 ask feature).
+ *
+ * Pure, I/O-free: given an `ask` tool call's questions and the accumulated state,
+ * produce the Telegram message body + inline keyboard for the CURRENT question,
+ * apply a button tap or a free-text reply, and assemble the final answer payload.
+ * All Telegram sends / DB writes / bridge writes live in the callers
+ * (lib/handlers/questions.js, callbacks.js, cli-process.js) — this module is the
+ * testable core.
+ *
+ * Design: docs/0.12.0-interactive-questions-design.md. Sequential, one question
+ * at a time (P1–P2: single-select, multiSelect, free-text "Other"). Body is
+ * rendered PLAIN-TEXT (no parse_mode) because option labels/descriptions are
+ * agent-authored and must not reach the Markdown→HTML pipeline (security finding).
+ */
+
+'use strict';
+
+const MAX_LABEL = 40;       // Telegram button labels truncate ~64; keep well under
+const MAX_OTHER = 1000;     // cap on the user's free-text answer entering claude's context
+const MAX_PREVIEW = 500;
+
+function truncLabel(label) {
+  const s = String(label ?? '');
+  return s.length > MAX_LABEL ? s.slice(0, MAX_LABEL - 1) + '…' : s;
+}
+
+/** Initial state for an ask call's questions array. */
+function initState(questions) {
+  return {
+    questions: Array.isArray(questions) ? questions : [],
+    qIndex: 0,
+    answers: [],          // accumulated: [{ header, selected:[label...], other? }]
+    toggles: {},          // current multiSelect question: { '<optIndex>': true }
+    awaitingOther: false, // current question is in free-text capture mode
+  };
+}
+
+function currentQuestion(state) {
+  return state.questions[state.qIndex] || null;
+}
+
+function isDone(state) {
+  return state.qIndex >= state.questions.length;
+}
+
+/**
+ * Render the CURRENT question as { text, reply_markup }. callbackBase is the
+ * `q:<qid>:<token>` prefix; actions append `:opt:<i>` / `:submit` / `:other`.
+ * Returns null when the set is already done.
+ */
+function renderCurrent(state, callbackBase) {
+  const q = currentQuestion(state);
+  if (!q) return null;
+  const multi = q.multiSelect === true;
+  const total = state.questions.length;
+  const opts = Array.isArray(q.options) ? q.options : [];
+
+  const lines = [];
+  if (total > 1) lines.push(`Question ${state.qIndex + 1} of ${total}`);
+  if (q.header) lines.push(String(q.header));
+  lines.push(String(q.question ?? ''));
+  lines.push('');
+  opts.forEach((o, i) => {
+    // Multi-select renders as a checklist (☐ unchecked / ☑️ checked) so it's legible as a
+    // tap-to-toggle-then-Submit control, NOT a single-select button. Single-select keeps `•`.
+    const mark = multi ? (state.toggles[i] ? '☑️ ' : '☐ ') : '• ';
+    lines.push(`${mark}${truncLabel(o.label)}${o.description ? ` — ${o.description}` : ''}`);
+    if (o.preview) lines.push(String(o.preview).slice(0, MAX_PREVIEW));
+  });
+  if (multi) lines.push('\nTap to check/uncheck — pick one or more, then Submit.');
+
+  const rows = opts.map((o, i) => ([{
+    // The checkbox glyph on the BUTTON is the load-bearing affordance: an unchecked option
+    // must show ☐ (not a bare label) or it reads like a single-select tap-to-submit button.
+    text: `${multi ? (state.toggles[i] ? '☑️ ' : '☐ ') : ''}${truncLabel(o.label)}`,
+    callback_data: `${callbackBase}:opt:${i}`,
+  }]));
+  if (multi) {
+    const any = Object.values(state.toggles).some(Boolean);
+    rows.push([{
+      text: any ? '✅ Submit' : '✅ Submit (pick at least one)',
+      callback_data: `${callbackBase}:submit`,
+    }]);
+  }
+  if (q.allowOther !== false) {
+    rows.push([{ text: '✏️ Type my own', callback_data: `${callbackBase}:other` }]);
+  }
+
+  return { text: lines.join('\n'), reply_markup: { inline_keyboard: rows } };
+}
+
+/** Parse the action suffix of a callback (everything after `q:<qid>:<token>:`). */
+function parseAction(suffix) {
+  const s = String(suffix ?? '');
+  if (s === 'submit') return { type: 'submit' };
+  if (s === 'other') return { type: 'other' };
+  const m = s.match(/^opt:(\d+)$/);
+  if (m) return { type: 'opt', i: Number(m[1]) };
+  return { type: 'unknown' };
+}
+
+function recordAndAdvance(state, answer) {
+  const next = {
+    ...state,
+    answers: [...state.answers, answer],
+    qIndex: state.qIndex + 1,
+    toggles: {},
+    awaitingOther: false,
+  };
+  return next;
+}
+
+/**
+ * Apply a button tap. Returns:
+ *   { state, kind:'toggled' }                 — multiSelect toggle, re-render
+ *   { state, kind:'awaiting-other' }          — user wants to type their own
+ *   { state, kind:'reject', message }         — invalid (e.g. submit with none)
+ *   { state, kind:'advanced', receipt, done } — answer recorded; done if set complete
+ */
+function applyTap(state, action) {
+  const q = currentQuestion(state);
+  if (!q) return { state, kind: 'reject', message: 'No active question.' };
+  const opts = Array.isArray(q.options) ? q.options : [];
+  const multi = q.multiSelect === true;
+
+  if (action.type === 'other') {
+    if (q.allowOther === false) return { state, kind: 'reject', message: 'Free text not allowed here.' };
+    return { state: { ...state, awaitingOther: true }, kind: 'awaiting-other' };
+  }
+
+  if (action.type === 'opt') {
+    if (action.i < 0 || action.i >= opts.length) {
+      return { state, kind: 'reject', message: 'Unknown option.' };
+    }
+    if (multi) {
+      const toggles = { ...state.toggles };
+      if (toggles[action.i]) delete toggles[action.i]; else toggles[action.i] = true;
+      return { state: { ...state, toggles }, kind: 'toggled' };
+    }
+    // single-select: record + advance
+    const label = opts[action.i].label;
+    const next = recordAndAdvance(state, { header: q.header, selected: [label] });
+    return { state: next, kind: 'advanced', receipt: label, done: isDone(next) };
+  }
+
+  if (action.type === 'submit') {
+    if (!multi) return { state, kind: 'reject', message: 'Nothing to submit.' };
+    const picked = Object.keys(state.toggles).filter(k => state.toggles[k]).map(Number).sort((a, b) => a - b);
+    if (picked.length === 0) return { state, kind: 'reject', message: 'Pick at least one option.' };
+    const labels = picked.map(i => opts[i].label);
+    const next = recordAndAdvance(state, { header: q.header, selected: labels });
+    return { state: next, kind: 'advanced', receipt: labels.join(', '), done: isDone(next) };
+  }
+
+  return { state, kind: 'reject', message: 'Unknown action.' };
+}
+
+/**
+ * Apply a free-text reply (the user's "Other" answer). Only valid when the
+ * current question is in awaitingOther mode. Returns the same advanced shape.
+ */
+function applyFreeText(state, text) {
+  const q = currentQuestion(state);
+  if (!q || !state.awaitingOther) return { state, kind: 'reject', message: 'Not awaiting a typed answer.' };
+  const other = String(text ?? '').slice(0, MAX_OTHER);
+  const next = recordAndAdvance(state, { header: q.header, selected: [], other });
+  return { state: next, kind: 'advanced', receipt: other, done: isDone(next) };
+}
+
+/** Final tool result once the set is done. */
+function assemble(state) {
+  return { answers: state.answers };
+}
+
+module.exports = {
+  initState,
+  currentQuestion,
+  isDone,
+  renderCurrent,
+  parseAction,
+  applyTap,
+  applyFreeText,
+  assemble,
+  MAX_LABEL,
+  MAX_OTHER,
+};

package/lib/questions/store.js

@@ -0,0 +1,105 @@
+/**
+ * pending_questions store — persistence for the 0.12 interactive-question flow.
+ *
+ * Mirrors lib/approvals/store.js: per-row 128-bit callback token, status
+ * lifecycle, audit-kept rows (never deleted; 'pending' at boot → 'expired').
+ * One OPEN question per session at a time. The answer routes back to claude on
+ * tool_call_id (a `question_answer` bridge message).
+ */
+
+'use strict';
+
+const { newToken, tokensEqual } = require('../approvals/store');
+
+// Option A (2026-06-09): don't expire a question before the turn that's blocking on
+// it can. A blocking `ask` can live at most the 30-min turn ABSOLUTE cap
+// (DEFAULT_TURN_ABSOLUTE_MS) — the keep-alive resets the idle cap but not the absolute
+// — so align here. The user answers any time within the turn's life, not an arbitrary
+// 8-min window. (Truly-unbounded "answer hours later" needs the non-blocking redesign.)
+const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000;
+
+function createQuestionStore(rawDb, now = () => Date.now()) {
+  const insertStmt = rawDb.prepare(`
+    INSERT INTO pending_questions (
+      bot_name, session_key, chat_id, thread_id, turn_id, tool_call_id,
+      callback_token, questions_json, state_json, created_ts, timeout_ts
+    ) VALUES (
+      @bot_name, @session_key, @chat_id, @thread_id, @turn_id, @tool_call_id,
+      @callback_token, @questions_json, @state_json, @created_ts, @timeout_ts
+    )
+  `);
+  const getByIdStmt        = rawDb.prepare(`SELECT * FROM pending_questions WHERE id = ?`);
+  const getOpenForSessStmt = rawDb.prepare(`
+    SELECT * FROM pending_questions WHERE session_key = ? AND status = 'pending'
+     ORDER BY created_ts DESC LIMIT 1`);
+  const getByToolCallStmt  = rawDb.prepare(`SELECT * FROM pending_questions WHERE tool_call_id = ? LIMIT 1`);
+  const setMsgIdsStmt      = rawDb.prepare(`UPDATE pending_questions SET message_ids_json = ? WHERE id = ?`);
+  const updateStateStmt    = rawDb.prepare(`
+    UPDATE pending_questions SET state_json = @state_json, awaiting_other = @awaiting_other
+     WHERE id = @id AND status = 'pending'`);
+  const claimStmt          = rawDb.prepare(`
+    UPDATE pending_questions SET from_id = @from_id
+     WHERE id = @id AND from_id IS NULL AND status = 'pending'`);
+  const resolveStmt        = rawDb.prepare(`
+    UPDATE pending_questions SET status = @status, answered_ts = @answered_ts
+     WHERE id = @id AND status = 'pending'`);
+  const listTimedOutStmt   = rawDb.prepare(`SELECT * FROM pending_questions WHERE status = 'pending' AND timeout_ts < ?`);
+  const listOpenStmt       = rawDb.prepare(`SELECT * FROM pending_questions WHERE bot_name = ? AND status = 'pending'`);
+
+  return {
+    issue({ bot_name, session_key, chat_id, thread_id = null, turn_id = null, tool_call_id, questions, state, timeoutMs = DEFAULT_TIMEOUT_MS }) {
+      if (!bot_name || !session_key || !chat_id || !tool_call_id) {
+        throw new Error('issue: bot_name, session_key, chat_id, tool_call_id required');
+      }
+      const created_ts = now();
+      const res = insertStmt.run({
+        bot_name,
+        session_key,
+        chat_id: String(chat_id),
+        thread_id: thread_id != null ? String(thread_id) : null,
+        turn_id,
+        tool_call_id,
+        callback_token: newToken(),
+        questions_json: JSON.stringify(questions ?? []),
+        state_json: JSON.stringify(state ?? {}),
+        created_ts,
+        timeout_ts: created_ts + timeoutMs,
+      });
+      return getByIdStmt.get(res.lastInsertRowid);
+    },
+
+    getById(id) { return getByIdStmt.get(id); },
+    getOpenForSession(session_key) { return getOpenForSessStmt.get(session_key); },
+    getByToolCallId(tool_call_id) { return getByToolCallStmt.get(tool_call_id); },
+    setMessageIds(id, ids) { return setMsgIdsStmt.run(JSON.stringify(ids ?? []), id).changes; },
+
+    updateState(id, state, awaitingOther = false) {
+      return updateStateStmt.run({ id, state_json: JSON.stringify(state ?? {}), awaiting_other: awaitingOther ? 1 : 0 }).changes;
+    },
+
+    /**
+     * Authorize a responder. Claim-on-first-tap: if no from_id is recorded yet,
+     * the first interacting user claims the question; thereafter only that user
+     * may answer. Returns { ok, claimed }.
+     */
+    claimOrCheck(id, from_id) {
+      if (from_id == null) return { ok: false, claimed: false };
+      const claimed = claimStmt.run({ id, from_id }).changes > 0;
+      if (claimed) return { ok: true, claimed: true };
+      const row = getByIdStmt.get(id);
+      return { ok: row && Number(row.from_id) === Number(from_id), claimed: false };
+    },
+
+    resolve(id, status) {
+      if (!['answered', 'cancelled', 'timeout', 'expired'].includes(status)) {
+        throw new Error(`bad status: ${status}`);
+      }
+      return resolveStmt.run({ id, status, answered_ts: now() }).changes;
+    },
+
+    sweepTimedOut() { return listTimedOutStmt.all(now()); },
+    listOpen(bot_name) { return listOpenStmt.all(bot_name); },
+  };
+}
+
+module.exports = { createQuestionStore, tokensEqual, DEFAULT_TIMEOUT_MS };