thinkpool-pair 0.7.171 → 0.7.172

package/claude-session.mjs

@@ -13,11 +13,30 @@
    ───────────────────────────────────────────────────────────── */
 
 import { randomUUID } from 'node:crypto'
+import { createRequire } from 'node:module'
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
 import { query } from '@anthropic-ai/claude-agent-sdk'
 import { sanitizeSession } from './transcript-sanitize.mjs'
 import { reviewGatePreToolDecision } from './flow-review-gate.mjs'
 import { crossPostNeedsCard } from './cross-terminal.mjs'
 import { correctContext } from './context-windows.mjs'
+import { stallDecision, stallEvent } from './turn-stall.mjs'
+
+// The caret-pulled SDK's real version (^0.3.x auto-upgrades on restart). Resolved
+// once at import by walking up from the package entry to its own package.json.
+// Named in the [SDK-REGRESSION] guard below so a silent gate-change is attributable.
+const SDK_VERSION = (() => {
+  try {
+    const req = createRequire(import.meta.url)
+    let d = dirname(req.resolve('@anthropic-ai/claude-agent-sdk'))
+    for (let i = 0; i < 8; i++) {
+      try { const p = JSON.parse(readFileSync(join(d, 'package.json'), 'utf8')); if (p.name === '@anthropic-ai/claude-agent-sdk') return p.version } catch { /* keep walking */ }
+      const up = dirname(d); if (up === d) break; d = up
+    }
+  } catch { /* unresolved */ }
+  return 'unknown'
+})()
 
 // ── risk classification — the accent/danger tier of the permission card ──
 // low (read-only) · medium (writes/runs) · network (leaves the machine) ·
@@ -73,6 +92,44 @@ export function autoAllow({ toolName, input, mode = 'default', alwaysAllow = new
   )
 }
 
+// AskUserQuestion answer path — pure mapping from the room's requestPermission
+// result to the PreToolUse decision fed back to the model. The card handler
+// denies (PreToolUse can't inject a tool_result) and puts the human's pick in
+// the deny reason, which IS what the model receives. Exported so the feedback
+// contract is locked in a unit test (mock requestPermission → this output).
+// `decision` is the requestPermission return: 'answer:<pick>' when the person
+// selected, anything else (including '' / dismissal / a broken path) is treated
+// as "no selection".
+export function askUserQuestionHookOutput(decision) {
+  const ans = (typeof decision === 'string' && decision.startsWith('answer:')) ? decision.slice(7) : ''
+  return {
+    continue: true,
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: ans
+        ? `The user answered in the ThinkPool room — ${ans}. Treat this as their selection and continue; do not call AskUserQuestion again for the same question.`
+        : 'The user dismissed the question in the ThinkPool room without selecting. Ask in plain prose, or proceed with a sensible default.',
+    },
+  }
+}
+
+// Regression guard for the AskUserQuestion gate. SDK 0.3.173 enabled the tool
+// unconditionally; a later bump in the 0.3.185→0.3.204 window flipped it to require
+// a `canUseTool` callback, and the ^0.3.x caret silently killed the feature on a
+// routine restart (2026-07-08). The bridge DOES pass canUseTool, so the SDK's init
+// `tools[]` MUST advertise AskUserQuestion — checked against the real init message
+// the live session already receives (no boot-time probe: cold-CLI init is flaky).
+// If the message carries a tools[] that lacks AskUserQuestion → return the loud
+// [SDK-REGRESSION] reason (logged + surfaced in the room). If it carries no tools[]
+// (older/other SDK message shape) → fail OPEN (null), never a false alarm. Pure +
+// exported so both branches are locked by a unit test.
+export function askUserQuestionRegression(tools, version) {
+  if (!Array.isArray(tools)) return null
+  if (tools.includes('AskUserQuestion')) return null
+  return `[SDK-REGRESSION] agent SDK v${version || 'unknown'} init tools[] is missing 'AskUserQuestion' — the multiple-choice question card is disabled. A caret SDK bump likely changed the canUseTool gate; pin a known-good SDK in bridge/package.json + republish.`
+}
+
 // ── input stream — a generator we keep open and feed turns into ──
 function makeInputStream() {
   const queue = []
@@ -183,6 +240,7 @@ export function startClaudeSession({ cwd, model, resume, env, mode: initialMode
   const spawnT0 = Date.now()
   let readyLogged = false
   let modelsSent = false   // one-shot: emit the SDK's supported-model list on first init
+  let sdkToolsChecked = false   // one-shot: run the AskUserQuestion regression guard on the first init carrying tools[]
   let q = null            // the live Query — control requests (interrupt /
                           // setPermissionMode) route through it once streaming.
   // The session is CREATED in the caller's chosen mode (not hard-coded default):
@@ -223,8 +281,10 @@ export function startClaudeSession({ cwd, model, resume, env, mode: initialMode
   // 3+ min) or abort silently with no `result`. Track turn liveness + last event
   // time; if an active turn goes quiet past STALL_MS, emit one `stalled` chrome
   // event so the room can stop showing a frozen "working" forever. Cleared on the
-  // next event / `result`. Refs: TS SDK #44, claude-code #38905.
-  const STALL_MS = Math.max(30000, parseInt(process.env.TP_STALL_MS, 10) || 120000)
+  // next event / `result`. Refs: TS SDK #44, claude-code #38905. The decision layer
+  // (stallDecision/stallEvent, above) is pure + unit-tested; this owns the state +
+  // side effects. 90s status default (2026-07-08 hardening: the 529-overload hang).
+  const STALL_MS = Math.max(30000, parseInt(process.env.TP_STALL_MS, 10) || 90000)
   let turnActive = false          // true between a sent turn and its `result`
   let lastEvtTs = Date.now()      // wall-clock of the most recent emitted event
   let stalledSent = false         // one `stalled` per stall, not a storm
@@ -240,12 +300,16 @@ export function startClaudeSession({ cwd, model, resume, env, mode: initialMode
   let restartCount = 0
   let restartTimer = null   // the pending auto-restart backoff — cancelled by end()
   // Force-stop a true wedge (item 3): no result, no error, just silence past
-  // FORCE_STOP_MS. Clears turnActive so between-turns updates unblock, and
-  // surfaces a recoverable error. The wedged loop is left in place (a hung
-  // native call can't be safely restarted mid-flight); if it later throws,
-  // the catch self-heals.
+  // FORCE_STOP_MS. As of the 2026-07-08 hardening we no longer just surface an error
+  // and leave the hung loop in place — retryStalledTurn ABORTS the wedged SDK call (via
+  // its AbortController, the same unblock path abort()/recreateForSwitch use) and
+  // AUTO-RETRIES the turn ONCE, preserving the prompt. If that one retry ALSO stalls
+  // past FORCE_STOP_MS, we fall back to the old behavior: force-stop + "send again".
+  // stallRetried bounds it to a single auto-retry per turn (reset on each new turn /
+  // settled result), so a sustained upstream outage can't thundering-herd retries.
   const FORCE_STOP_MS = Math.max(STALL_MS * 3, parseInt(process.env.TP_FORCE_STOP_MS, 10) || 300000)
   let forceStopped = false
+  let stallRetried = false        // one auto-retry per turn (the abort+re-run path below)
   // Waiting on a HUMAN decision (permission card / plan gate / AskUserQuestion)
   // is NOT a wedge — the turn is correctly idle until the person answers. Every
   // interactive gate goes through requestPermission, so wrap it once to bump a
@@ -288,22 +352,29 @@ export function startClaudeSession({ cwd, model, resume, env, mode: initialMode
   let sugTimer = null             // pending fallback timer
   const SUGGEST_FALLBACK_MS = Math.max(1200, parseInt(process.env.TP_SUGGEST_FALLBACK_MS, 10) || 2500)
 
-  const emit = (evt) => { lastEvtTs = Date.now(); if (evt && evt.kind !== 'stalled') stalledSent = false; try { onEvent?.(evt) } catch { /* never let a consumer throw into the loop */ } }
+  // emitRaw forwards an event WITHOUT stamping lastEvtTs — used for the watchdog's OWN
+  // synthetic status/error events, which are not SDK activity and must not reset the
+  // silence clock (else the 5-min abort would measure from our 90s status emit, not from
+  // the last real SDK event). emit() is the normal path: it stamps liveness + clears the
+  // one-shot stall flag on any real event other than a `stalled` re-emit.
+  const emitRaw = (evt) => { try { onEvent?.(evt) } catch { /* never let a consumer throw into the loop */ } }
+  const emit = (evt) => { lastEvtTs = Date.now(); if (evt && evt.kind !== 'stalled') stalledSent = false; emitRaw(evt) }
   const stallTimer = setInterval(() => {
-    if (!turnActive || awaitingUser > 0) return   // awaiting a human decision ≠ wedged
     const quiet = Date.now() - lastEvtTs
-    if (quiet > FORCE_STOP_MS && !forceStopped) {
-      // True wedge — no result, no error, just silence. Unblocks between-turns
-      // updates + surfaces a recoverable error. The wedged loop is left alone.
-      forceStopped = true
-      turnActive = false
-      emit({ kind: 'error', message: `agent went silent for ${Math.round(quiet / 1000)}s — force-stopped the turn; send again to resume`, recoverable: true })
-      return
-    }
-    if (!stalledSent && quiet > STALL_MS) {
-      stalledSent = true
-      emit({ kind: 'stalled', sinceMs: quiet })
-    }
+    const action = stallDecision({ turnActive, awaitingUser, quietMs: quiet, stallMs: STALL_MS, forceStopMs: FORCE_STOP_MS, stalledSent, stallRetried })
+    if (action === 'none') return
+    // ALWAYS surface — a stall is never swallowed. emitRaw so this synthetic event
+    // doesn't reset the silence clock (see emitRaw above).
+    const ev = stallEvent(action, quiet)
+    if (ev) emitRaw(ev)
+    if (action === 'status') { stalledSent = true; return }
+    if (action === 'retry') { forceStopped = true; retryStalledTurn(quiet); return }
+    // 'giveup' — the one auto-retry ALSO stalled past FORCE_STOP_MS. Fall back to the
+    // pre-2026-07-08 behavior: force-stop the turn so between-turns updates unblock, and
+    // let the human resend. The wedged loop is left in place; if it later throws, the
+    // catch self-heals.
+    forceStopped = true
+    turnActive = false
   }, 5000)
   stallTimer.unref?.()
 
@@ -527,17 +598,7 @@ export function startClaudeSession({ cwd, model, resume, env, mode: initialMode
       let decision = ''
       try { decision = await requestPermission?.({ id: randomUUID(), toolName, input: toolInput, risk: 'ask', questions: toolInput?.questions || [] }) ?? '' }
       catch { decision = '' }
-      const ans = (typeof decision === 'string' && decision.startsWith('answer:')) ? decision.slice(7) : ''
-      return {
-        continue: true,
-        hookSpecificOutput: {
-          hookEventName: 'PreToolUse',
-          permissionDecision: 'deny',
-          permissionDecisionReason: ans
-            ? `The user answered in the ThinkPool room — ${ans}. Treat this as their selection and continue; do not call AskUserQuestion again for the same question.`
-            : 'The user dismissed the question in the ThinkPool room without selecting. Ask in plain prose, or proceed with a sensible default.',
-        },
-      }
+      return askUserQuestionHookOutput(decision)
     }
     const risk = classifyRisk(toolName, toolInput)
     // "Don't ask again" is keyed by tool + risk tier, so allowing medium Bash
@@ -574,6 +635,21 @@ export function startClaudeSession({ cwd, model, resume, env, mode: initialMode
     abortController: ac,
     permissionMode: mode,
     hooks: { PreToolUse: [{ hooks: [preTool] }] },
+    // Enable AskUserQuestion (the agent's multiple-choice card) in EVERY mode.
+    // The CLI only adds AskUserQuestion / EnterPlanMode / ExitPlanMode to a
+    // session's toolset when the host declares it can service an interactive
+    // permission — i.e. when a `canUseTool` callback is present. Without it the
+    // tool is absent and the model gets "AskUserQuestion exists but is not
+    // enabled in this context", so the room's card handler above was dead code.
+    // Its PRESENCE is the whole point: in bypassPermissions this callback is
+    // shadowed (never invoked — bypass auto-approves before it, per the SDK's
+    // CLAUDE_SDK_CAN_USE_TOOL_SHADOWED warning), and in gated modes the
+    // PreToolUse hook runs first and stays authoritative (a hook deny — which is
+    // exactly how the AskUserQuestion card feeds its answer back — short-circuits
+    // canUseTool). So the human-gate holds in all modes: an ask-card always waits
+    // for a person via requestPermission inside the hook. This allow is a no-op
+    // relative to the hook, never a second gate that could override a denial.
+    canUseTool: async (_toolName, input) => ({ behavior: 'allow', updatedInput: input }),
     // Load the host's REAL Claude environment — user + project + local settings —
     // so custom slash commands (.claude/commands/*.md), CLAUDE.md and agents work
     // in the room exactly as in the user's own CLI. The Agent SDK isolates by
@@ -780,6 +856,19 @@ export function startClaudeSession({ cwd, model, resume, env, mode: initialMode
             // correct it). opts.model reflects what the session will actually run, so trust it.
             curModel = opts.model || m.model || model || curModel
             emit({ kind: 'system', sessionId, model: opts.model || m.model || model || null, commands: Array.isArray(m.slash_commands) ? m.slash_commands : undefined })
+            // AskUserQuestion regression guard — the init message carries the session's
+            // real tool list. If a caret SDK bump silently dropped AskUserQuestion from
+            // it (the 2026-07-08 outage), surface it loudly instead of a dead card. One-
+            // shot per session (resumed sessions replay init messages). Fails open when
+            // the message shape carries no tools[].
+            if (!sdkToolsChecked && Array.isArray(m.tools)) {
+              sdkToolsChecked = true
+              const regression = askUserQuestionRegression(m.tools, SDK_VERSION)
+              if (regression) {
+                process.stderr.write(`\n  ⚠⚠ ${regression}\n`)
+                emit({ kind: 'error', message: regression })
+              }
+            }
             // Dynamic model list — ask the SDK for its OWN supported models and surface
             // them to the room so the /model picker renders live options (incl. new
             // models like Fable) instead of a hardcoded three-item list. Fire-and-forget:
@@ -875,6 +964,7 @@ export function startClaudeSession({ cwd, model, resume, env, mode: initialMode
             // drops refills every cycle past RESTART_MAX) — and marks this session id durably
             // persisted so a later model-switch re-create can safely resume it.
             forceStopped = false
+            stallRetried = false   // a turn settled → the next turn gets a fresh auto-retry budget
             // Ground-truth the model from THIS turn's modelUsage (the models actually billed
             // this turn), not the init/system messages — a RESUMED session REPLAYS the prior
             // transcript's init messages, so curModel got polluted back to the pre-switch model
@@ -991,12 +1081,43 @@ export function startClaudeSession({ cwd, model, resume, env, mode: initialMode
     sessionId = persistedSessionId
     if (!closed) runQuery()                                 // relaunch on opts.model + resume
   }
+  // Abort a wedged turn (no event, no throw — the SDK's `for await` blocked inside an
+  // internal retry, e.g. an Anthropic 529-overload window) and re-run it ONCE, preserving
+  // the prompt. Mirrors recreateForSwitch's teardown-then-relaunch (abort qAc → swap the
+  // input stream → await the dying query's disposal so the two processes never race on the
+  // session file lock → resume the durable id) and then RE-PUSHES lastTurnText so the turn
+  // continues instead of being lost. The stall error was already surfaced by the watchdog
+  // (emitRaw of stallEvent('retry', …)); this adds a 'note' once the fresh turn is armed.
+  // Bounded to one call per turn by stallRetried (set in the interval before we're called).
+  const retryStalledTurn = async (quietMs) => {
+    if (closed) return
+    stallRetried = true
+    const wasActive = turnActive
+    const replay = wasActive ? lastTurnText : null
+    turnActive = false                                     // unblock between-turns updates while we tear down
+    const dying = qDone
+    const oldInput = input
+    input = makeInputStream()                              // fresh stream for the relaunched query
+    if (qAc) { try { qAc.abort() } catch { /* noop */ } }  // unblock the wedged for-await → its catch disposes the process
+    try { oldInput.end() } catch { /* noop */ }
+    try { await dying } catch { /* noop */ }               // wait until the old query is actually dead (avoids the lock race)
+    await sleep(300)                                       // brief lock-release margin
+    sessionId = persistedSessionId                         // resume the durably-persisted id (recreateForSwitch invariant)
+    if (closed) return
+    runQuery()
+    if (replay != null) {
+      turnActive = true; lastEvtTs = Date.now(); stalledSent = false   // re-arm liveness for the retried turn
+      // Match sendTurn's block shape: a slash command goes clean; a normal turn keeps the reminder.
+      input.push(/^\s*\//.test(replay) ? [{ type: 'text', text: replay }] : [{ type: 'text', text: replay }, { type: 'text', text: roomReminder() }])
+      emitRaw({ kind: 'note', text: 'retrying the stalled turn on a fresh connection' })
+    }
+  }
   if (!lazy) runQuery()
 
   return {
     // A lazy (restored-idle) session cold-boots the query on its first turn. input.push
     // is queue-backed, so the pushed turn buffers and runs once the query is ready.
-    sendTurn(text) { if (!closed) { if (!started) runQuery(); turnActive = true; sawSuggestion = false; lastTurnText = String(text); if (sugTimer) { clearTimeout(sugTimer); sugTimer = null } lastEvtTs = Date.now(); stalledSent = false;
+    sendTurn(text) { if (!closed) { if (!started) runQuery(); turnActive = true; sawSuggestion = false; lastTurnText = String(text); if (sugTimer) { clearTimeout(sugTimer); sugTimer = null } lastEvtTs = Date.now(); stalledSent = false; stallRetried = false; forceStopped = false;
       const t = String(text)
       // SDK 0.3.198 only recognizes a slash command (/compact, /clear, custom /cmds) when the
       // user message is a SINGLE text block. Appending the per-turn ROOM NOW <system-reminder>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.171",
+  "version": "0.7.172",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
   "bin": {
@@ -13,6 +13,7 @@
     "byok-detect.mjs",
     "context-windows.mjs",
     "claude-session.mjs",
+    "turn-stall.mjs",
     "update-gate.mjs",
     "event-id.mjs",
     "transcript-sanitize.mjs",

package/turn-stall.mjs

@@ -0,0 +1,43 @@
+/* ─────────────────────────────────────────────────────────────
+   turn-stall.mjs — the pure decision layer for the structured-turn stall watchdog.
+
+   A structured turn can stall with the SDK's `for await` blocked INSIDE an internal retry
+   — no event, no throw — so claude-session's catch never runs and nothing reaches the room.
+   The 2026-07-08 incident: an Anthropic 529-overload window hung a turn for 14 minutes with
+   zero output until it was aborted by hand. The watchdog in claude-session.mjs turns that
+   silent wedge into a visible status, then an abort + one auto-retry, then a force-stop.
+
+   These two functions are the DECISION layer (when to act / what to say). They're pure — no
+   SDK, no clock, no I/O — so the stateful loop injects state in and they unit-test against a
+   fake clock with zero deps (bridge/test-turn-stall-watchdog.mjs). Same shape + spirit as
+   account.mjs's claimLoopWedged / withTimeout. Kept in their OWN module (no SDK import) so the
+   test needs neither the agent SDK nor auth. The loop owns the flags + the abort/re-push side
+   effects; this only says WHAT to do.
+   ───────────────────────────────────────────────────────────── */
+
+// Decide the watchdog action for an ACTIVE turn gone quiet (quietMs = ms since the last
+// emitted SDK event). Idle (no turn) or awaiting a HUMAN decision (permission card / plan
+// gate / AskUserQuestion) is never a wedge — the turn is correctly idle until the person
+// answers. Timeline:
+//   quietMs > stallMs (90s)      → 'status'  — surface a "still retrying (Ns)" banner, ONCE
+//   quietMs > forceStopMs (5min) → 'retry'   — abort the hung call, re-run the turn ONCE
+//   quietMs > forceStopMs again  → 'giveup'  — the one retry also stalled: force-stop, resend
+export function stallDecision({ turnActive, awaitingUser, quietMs, stallMs, forceStopMs, stalledSent, stallRetried }) {
+  if (!turnActive || awaitingUser > 0) return 'none'
+  if (quietMs > forceStopMs) return stallRetried ? 'giveup' : 'retry'
+  if (!stalledSent && quietMs > stallMs) return 'status'
+  return 'none'
+}
+
+// The room-facing event for a watchdog action (pure → the exact wording is unit-tested).
+// 'status' rides the transient `stalled` chrome event (broadcast, never persisted); 'retry'
+// and 'giveup' ride `error` (recoverable) so the stall is ALWAYS surfaced, never swallowed.
+export function stallEvent(action, quietMs) {
+  const s = Math.round(quietMs / 1000)
+  switch (action) {
+    case 'status': return { kind: 'stalled', sinceMs: quietMs, retrying: true, message: `model call stalled — still retrying (${s}s)` }
+    case 'retry':  return { kind: 'error', recoverable: true, message: `model call stalled ${s}s with no response (upstream overload) — aborting the hung call and retrying the turn once` }
+    case 'giveup': return { kind: 'error', recoverable: true, message: `agent went silent for ${s}s — the retry also stalled; force-stopped the turn, send again to resume` }
+    default:       return null
+  }
+}