pikiclaw 0.3.62 → 0.3.63

package/dist/agent/drivers/claude-tui.js

@@ -43,8 +43,8 @@ import { tmpdir } from 'node:os';
 import { Q, agentLog, agentWarn, buildStreamPreviewMeta, computeContext, joinErrorMessages, emitSessionIdUpdate, normalizeClaudeModelId, pushRecentActivity, summarizeClaudeToolUse, summarizeClaudeToolResult, previewToolCallInput, previewToolCallResult, detectClaudeApiError, } from '../utils.js';
 import { encodePathAsDirName, getHome, whichSync } from '../../core/platform.js';
 import { stripAnsiEscapes } from '../../core/utils.js';
-import { AGENT_STREAM_HARD_KILL_GRACE_MS, CLAUDE_TUI_STALL_QUIET_MS, CLAUDE_TUI_STALL_PENDING_TOOL_MS, } from '../../core/constants.js';
-import { claudeParse, createClaudeStreamState, claudeContextWindowFromModel, claudeEffectiveContextWindow, registerClaudeBackgroundAgentLaunch, pendingClaudeBackgroundAgentCount, } from './claude.js';
+import { AGENT_STREAM_HARD_KILL_GRACE_MS, CLAUDE_TUI_STALL_QUIET_MS, CLAUDE_TUI_STALL_PENDING_TOOL_MS, CLAUDE_TUI_STALL_PTY_DEAD_MS, CLAUDE_TUI_STOP_HOLD_QUIET_TTL_MS, } from '../../core/constants.js';
+import { claudeParse, createClaudeStreamState, claudeContextWindowFromModel, claudeEffectiveContextWindow, registerClaudeBackgroundAgentLaunch, pendingClaudeBackgroundAgentCount, registerClaudeBackgroundBashLaunch, pendingClaudeBackgroundBashCount, extractClaudeBackgroundTaskId, } from './claude.js';
 async function loadPty() {
     // Dynamic import keeps node-pty an optional dependency — if it's not
     // installed the print-mode dispatcher in claude.ts will catch the throw
@@ -391,6 +391,12 @@ export function applyHookToolEvent(ev, s) {
             s.claudeToolsById.set(toolUseId, { name: toolName, summary: desc || kind || 'Sub-agent' });
             return true;
         }
+        // Background Bash — register like a backgrounded agent so the turn's Stop
+        // holds the PTY open until its <task-notification> lands, instead of
+        // SIGTERMing the still-running command (and its future report-back turn).
+        if (toolName === 'Bash' && ev.tool_input?.run_in_background === true) {
+            registerClaudeBackgroundBashLaunch(s, toolUseId);
+        }
         const summary = summarizeClaudeToolUse(toolName, ev.tool_input || {});
         pushRecentActivity(s.recentActivity, summary);
         s.seenClaudeToolIds.add(toolUseId);
@@ -457,6 +463,14 @@ export function applyHookToolEvent(ev, s) {
                 s.activity = s.recentActivity.join('\n');
             }
         }
+        // Background Bash launch ack → map task id → tool_use for notification
+        // resolution (bash notifications usually omit <tool-use-id>).
+        if (toolName === 'Bash' && s.bgBashToolUseIds?.has(toolUseId)
+            && !s.bgAgentCompletedToolUseIds?.has(toolUseId)) {
+            const taskId = extractClaudeBackgroundTaskId(ev.tool_response);
+            if (taskId && !s.bgTaskIdToToolUse.has(taskId))
+                s.bgTaskIdToToolUse.set(taskId, toolUseId);
+        }
         s.seenClaudeToolResultIds.add(toolUseId);
         return true;
     }
@@ -630,10 +644,23 @@ const BG_RESETTLE_QUIET_MS = 30_000;
  *    is still expected. Hold until a fresh Stop or BG_RESETTLE_QUIET_MS of
  *    JSONL silence.
  *  - `terminate`: the Stop is the genuine end of the turn.
+ *
+ * The `hold-background` path carries a quiet-TTL: a genuinely-running
+ * background agent keeps emitting hook/sidecar/JSONL traffic, so a hold whose
+ * every channel has been silent past CLAUDE_TUI_STOP_HOLD_QUIET_TTL_MS is a
+ * phantom (lost <task-notification> / completion never observed). Releasing
+ * it as a normal Stop keeps the turn's clean semantics — letting the stall
+ * watchdog reap it instead would mislabel a finished turn 'stalled' and
+ * inject a confusing auto-resume prompt into the next turn.
  */
 export function decideClaudeTuiStop(input) {
-    if (input.pendingBackgroundAgents > 0)
+    if (input.pendingBackgroundAgents > 0) {
+        const ttl = input.holdQuietTtlMs ?? CLAUDE_TUI_STOP_HOLD_QUIET_TTL_MS;
+        const lastActivityAt = Math.max(input.stoppedAt, input.lastJsonlEventAt, input.lastTaskNotificationAt, input.lastHookOrSidecarEventAt ?? 0);
+        if (input.now - lastActivityAt > ttl)
+            return 'terminate'; // 幽灵 hold:全通道静默超 TTL
         return 'hold-background';
+    }
     const stopIsStale = input.lastTaskNotificationAt > 0 && input.lastTaskNotificationAt >= input.stoppedAt;
     if (stopIsStale) {
         const quietMs = input.resettleQuietMs ?? BG_RESETTLE_QUIET_MS;
@@ -656,8 +683,22 @@ export function decideClaudeTuiStop(input) {
  * the freeze can also hit mid-execution, but a legitimately long foreground
  * command must not get shot — claude's own Bash timeout fires PostToolUse
  * well inside CLAUDE_TUI_STALL_PENDING_TOOL_MS.
+ *
+ * Fast path: `lastPtyDataAt` is raw PTY output (any repaint frame counts). A
+ * healthy TUI animates continuously mid-turn — spinner, stream ticks, status
+ * line — so PTY byte-silence is the cheapest possible "event loop is dead"
+ * detector. When BOTH the PTY and all structured signals have been silent
+ * past `ptyDeadMs`, declare the stall immediately instead of waiting out the
+ * 10/30-minute quiet thresholds. Long thinking and long foreground commands
+ * keep painting frames, which routes them to the slow thresholds as before.
  */
 export function decideClaudeTuiStall(input) {
+    const ptyAt = input.lastPtyDataAt ?? 0;
+    if (ptyAt > 0) {
+        const ptyDeadMs = input.ptyDeadMs ?? CLAUDE_TUI_STALL_PTY_DEAD_MS;
+        if (input.now - Math.max(ptyAt, input.lastProgressAt) > ptyDeadMs)
+            return 'stall';
+    }
     const threshold = input.pendingToolCount > 0
         ? (input.pendingToolMs ?? CLAUDE_TUI_STALL_PENDING_TOOL_MS)
         : (input.quietMs ?? CLAUDE_TUI_STALL_QUIET_MS);
@@ -934,9 +975,15 @@ export async function doClaudeTuiStream(opts) {
     }
     agentLog(`[claude-tui] pid=${proc.pid}`);
     const dbg = process.env.PIKICLAW_CLAUDE_TUI_DEBUG === '1';
+    /** Wall-clock of the last raw PTY byte — stall watchdog fast-path signal. */
+    let lastPtyDataAt = Date.now();
     proc.onData((data) => {
         // We deliberately do not parse the TUI screen output. The JSONL is the
         // canonical source of structured events. Stash bytes only when debugging.
+        // Raw byte arrival doubles as the cheapest liveness signal: a healthy TUI
+        // repaints continuously mid-turn, so PTY silence = event loop dead — feeds
+        // the stall watchdog's fast path (decideClaudeTuiStall.lastPtyDataAt).
+        lastPtyDataAt = Date.now();
         if (dbg) {
             try {
                 fs.appendFileSync(ptyLogPath, data);
@@ -1007,6 +1054,8 @@ export async function doClaudeTuiStream(opts) {
     let lastToolEventAt = start;
     let lastSidecarEventAt = 0;
     let stallKilled = false;
+    /** Last state.stoppedAt for which pendingHookToolIds was reconciled. */
+    let lastClearedStopAt = 0;
     /** Hook-reported tools still executing: PreToolUse seen, no PostToolUse. */
     const pendingHookToolIds = new Set();
     // Append-only tool-events log fed by PreToolUse / PostToolUse hooks. We
@@ -1264,17 +1313,40 @@ export async function doClaudeTuiStream(opts) {
         // has reported its <task-notification> AND the latest Stop is fresher than
         // the latest notification (i.e. the model's wrap-up segment finished).
         if (state.stoppedAt && !stopHookFired) {
+            // A fired Stop means no foreground tool is genuinely mid-flight any
+            // more. Surviving entries in pendingHookToolIds are lost PostToolUse
+            // hook events (MCP flap / hook timeout ate them) — clearing here stops
+            // them from silently pushing the stall watchdog onto the 30-minute
+            // pending-tool threshold for the rest of the turn.
+            if (state.stoppedAt !== lastClearedStopAt) {
+                lastClearedStopAt = state.stoppedAt;
+                if (pendingHookToolIds.size) {
+                    agentWarn(`[claude-tui] Stop fired with ${pendingHookToolIds.size} unmatched PreToolUse event(s) — clearing (lost PostToolUse hooks)`);
+                    pendingHookToolIds.clear();
+                }
+            }
             const pendingBg = pendingClaudeBackgroundAgentCount(s);
             const decision = decideClaudeTuiStop({
                 stoppedAt: state.stoppedAt,
                 pendingBackgroundAgents: pendingBg,
                 lastTaskNotificationAt: s.lastTaskNotificationAt || 0,
                 lastJsonlEventAt: lastMainJsonlEventAt,
+                lastHookOrSidecarEventAt: Math.max(lastToolEventAt, lastSidecarEventAt),
+                // Background *Bash* is silent by nature (no sidecar/hook traffic while
+                // it runs) — give it the long pending-tool budget; agent-only holds
+                // keep the default TTL (live agents emit sidecar events constantly).
+                holdQuietTtlMs: pendingClaudeBackgroundBashCount(s) > 0
+                    ? CLAUDE_TUI_STALL_PENDING_TOOL_MS
+                    : undefined,
                 now: Date.now(),
             });
             if (decision === 'terminate') {
                 stopHookFired = true;
                 stopHookSeenAt = Date.now();
+                if (pendingBg > 0) {
+                    // 幽灵 hold 释放:计数说还有后台 agent,但所有通道静默已超 TTL。
+                    agentWarn(`[claude-tui] releasing phantom hold — ${pendingBg} background agent(s) still counted pending but every channel quiet past TTL; treating Stop as final`);
+                }
                 agentLog(`[claude-tui] Stop hook fired — draining JSONL for ${POST_STOP_DRAIN_MS}ms before SIGTERM`);
             }
             else if (decision === 'hold-background' && pendingBg !== lastLoggedPendingBg) {
@@ -1300,19 +1372,32 @@ export async function doClaudeTuiStream(opts) {
         // once so the turn continues instead of spinning forever in the IM card.
         if (!stopHookFired && !timedOut && !interrupted && !stallKilled) {
             const lastProgressAt = Math.max(start, lastMainJsonlEventAt, lastToolEventAt, lastSidecarEventAt, state.stoppedAt || 0, state.promptSubmittedAt || 0);
+            // Pending background work (agents + bash) extends the stall budget the
+            // same way a pending foreground tool does: a silent 15-minute background
+            // build must not get shot by the 10-minute quiet threshold. The PTY
+            // fast path still catches true process freezes within minutes.
+            const pendingBgForStall = pendingClaudeBackgroundAgentCount(s);
+            // PTY fast path is for *mid-turn* freezes only. While the TUI idles in a
+            // post-Stop background hold it legitimately paints nothing — a static
+            // screen there is healthy, not frozen. Stop being the freshest signal is
+            // exactly that hold state → disarm the fast path (0 = unavailable).
+            const nonStopProgressAt = Math.max(start, lastMainJsonlEventAt, lastToolEventAt, lastSidecarEventAt, state.promptSubmittedAt || 0);
+            const inPostStopHold = !!state.stoppedAt && state.stoppedAt >= nonStopProgressAt;
             const stallDecision = decideClaudeTuiStall({
                 now: Date.now(),
                 lastProgressAt,
-                pendingToolCount: pendingHookToolIds.size,
+                pendingToolCount: pendingHookToolIds.size + pendingBgForStall,
+                lastPtyDataAt: inPostStopHold ? 0 : lastPtyDataAt,
             });
             if (stallDecision === 'stall') {
                 stallKilled = true;
                 const quietMin = Math.round((Date.now() - lastProgressAt) / 60_000);
+                const ptyQuietS = Math.round((Date.now() - lastPtyDataAt) / 1000);
                 s.stopReason = 'stalled';
                 if (!s.errors) {
-                    s.errors = [`Claude process went silent mid-turn for ${quietMin}m (no JSONL, hook, or sub-agent events) — known claude CLI freeze. Terminated for auto-resume.`];
+                    s.errors = [`Claude process went silent mid-turn for ${quietMin}m (no JSONL, hook, or sub-agent events; PTY quiet ${ptyQuietS}s) — known claude CLI freeze. Terminated for auto-resume.`];
                 }
-                agentWarn(`[claude-tui] stall detected: no progress for ${quietMin}m (pendingTools=${pendingHookToolIds.size}) — terminating TUI pid=${proc.pid} for auto-resume`);
+                agentWarn(`[claude-tui] stall detected: no progress for ${quietMin}m (pendingTools=${pendingHookToolIds.size}, ptyQuiet=${ptyQuietS}s) — terminating TUI pid=${proc.pid} for auto-resume`);
                 pushRecentActivity(s.recentActivity, `Agent stalled (${quietMin}m silent) — restarting turn`);
                 s.activity = s.recentActivity.join('\n');
                 emit();

package/dist/agent/drivers/claude.js

@@ -328,6 +328,8 @@ function ensureClaudeBgAgentState(s) {
         s.bgAgentLaunchedToolUseIds = new Set();
     if (!s.bgAgentCompletedToolUseIds)
         s.bgAgentCompletedToolUseIds = new Set();
+    if (!s.bgBashToolUseIds)
+        s.bgBashToolUseIds = new Set();
     if (!s.bgTaskIdToToolUse)
         s.bgTaskIdToToolUse = new Map();
     if (typeof s.lastTaskNotificationAt !== 'number')
@@ -341,7 +343,27 @@ export function registerClaudeBackgroundAgentLaunch(s, toolUseId) {
     ensureClaudeBgAgentState(s);
     s.bgAgentLaunchedToolUseIds.add(id);
 }
-/** Launched background agents whose <task-notification> hasn't arrived yet. */
+/**
+ * Record a `Bash` tool_use launched with `run_in_background: true`.
+ *
+ * Background Bash lives *inside the claude process* exactly like a
+ * backgrounded sub-agent: its tool_result is a launch ack, the real
+ * completion arrives later as a `<task-notification>` which re-invokes the
+ * model in the same process. Before this registration existed only Task/Agent
+ * launches counted as "pending background work" — a turn that backgrounded a
+ * Bash command would hit Stop, decideClaudeTuiStop saw pending=0 and
+ * terminated the PTY, killing the command and its future report-back turn
+ * (the「claude 后台任务一停止就被掐死」failure).
+ */
+export function registerClaudeBackgroundBashLaunch(s, toolUseId) {
+    const id = String(toolUseId || '').trim();
+    if (!id)
+        return;
+    ensureClaudeBgAgentState(s);
+    s.bgAgentLaunchedToolUseIds.add(id);
+    s.bgBashToolUseIds.add(id);
+}
+/** Launched background tasks (agents + bash) whose <task-notification> hasn't arrived yet. */
 export function pendingClaudeBackgroundAgentCount(s) {
     const launched = s?.bgAgentLaunchedToolUseIds;
     if (!launched?.size)
@@ -354,6 +376,51 @@ export function pendingClaudeBackgroundAgentCount(s) {
     }
     return pending;
 }
+/** Pending background *Bash* tasks specifically. Unlike agents (whose sidecar
+ *  JSONL keeps emitting events while alive), a background command is silent by
+ *  nature — callers use this to pick a longer hold/stall budget. */
+export function pendingClaudeBackgroundBashCount(s) {
+    const bash = s?.bgBashToolUseIds;
+    if (!bash?.size)
+        return 0;
+    const completed = s?.bgAgentCompletedToolUseIds;
+    let pending = 0;
+    for (const id of bash) {
+        if (!completed?.has(id))
+            pending++;
+    }
+    return pending;
+}
+/**
+ * Pull the background task id out of a launch ack. Claude Code's backgrounded
+ * Bash tool_result reads like "Command running in background with ID: bash_3
+ * (output: …)" — the id is what the later <task-notification> carries (its
+ * <tool-use-id> is often omitted for bash), so mapping id → tool_use here is
+ * what lets applyClaudeTaskNotification resolve the completion.
+ */
+export function extractClaudeBackgroundTaskId(content) {
+    let text = '';
+    if (typeof content === 'string')
+        text = content;
+    else if (Array.isArray(content)) {
+        text = content
+            .filter((b) => b?.type === 'text' && typeof b.text === 'string')
+            .map((b) => b.text)
+            .join('\n');
+    }
+    else if (content && typeof content === 'object') {
+        try {
+            text = JSON.stringify(content);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!text || !/background/i.test(text))
+        return null;
+    const m = text.match(/\b(?:ID|id)\s*[:：]?\s*[`"']?([A-Za-z0-9][A-Za-z0-9_-]{1,63})/);
+    return m ? m[1] : null;
+}
 /**
  * Parse a `<task-notification>` wrapper out of a user event's content.
  * Shape (observed, Claude Code 2.x):
@@ -583,6 +650,12 @@ export function claudeParse(ev, s) {
                 s.claudeToolsById.set(toolId, { name: toolName, summary: subAgent.description || 'Run task' });
                 continue;
             }
+            // Background Bash — same in-process lifecycle as a backgrounded agent:
+            // launch ack now, <task-notification> later. Register so the TUI driver
+            // holds the PTY open instead of SIGTERMing the command mid-flight.
+            if (toolName === 'Bash' && block?.input?.run_in_background === true) {
+                registerClaudeBackgroundBashLaunch(s, toolId);
+            }
             const tool = {
                 name: toolName,
                 summary: summarizeClaudeToolUse(block?.name, block?.input || {}),
@@ -667,6 +740,15 @@ export function claudeParse(ev, s) {
                 tool.result = previewToolCallResult(block?.content);
                 tool.status = block?.is_error ? 'failed' : 'done';
             }
+            // Background Bash launch ack → map its task id to the tool_use so the
+            // later <task-notification> (which usually omits <tool-use-id> for bash)
+            // can resolve and decrement the pending count.
+            if (tool?.name === 'Bash' && s.bgBashToolUseIds?.has(toolId)
+                && !s.bgAgentCompletedToolUseIds?.has(toolId)) {
+                const taskId = extractClaudeBackgroundTaskId(block?.content);
+                if (taskId && !s.bgTaskIdToToolUse.has(taskId))
+                    s.bgTaskIdToToolUse.set(taskId, toolId);
+            }
             pushRecentActivity(s.recentActivity, summarizeClaudeToolResult(tool, block, ev.tool_use_result));
             // MCP / Skill tool_result with multimodal content — recurse for image
             // entries so the final StreamResult carries them. Filesystem-reading

package/dist/core/constants.js

@@ -306,6 +306,29 @@ export const CLAUDE_TUI_STALL_QUIET_MS = 10 * 60_000;
  * silent for this long means the freeze hit mid-execution.
  */
 export const CLAUDE_TUI_STALL_PENDING_TOOL_MS = 30 * 60_000;
+/**
+ * Fast-path stall: a healthy claude TUI repaints continuously while a turn is
+ * in flight (spinner frames, stream ticks, status line) — the PTY never goes
+ * byte-silent for minutes. If NO PTY output arrives for this long AND every
+ * structured signal is equally quiet, the process event loop itself is gone
+ * (the 2.1.160 mid-turn freeze: attachment lands → next API call never
+ * assembles). Declare the stall now instead of waiting out the 10/30-minute
+ * quiet thresholds — turns a 10-30 分钟「卡死」into a ~3 分钟自愈。
+ * False-positive safe: long thinking / long Bash keep painting frames, which
+ * refreshes the PTY signal and defers this path to the slow thresholds.
+ */
+export const CLAUDE_TUI_STALL_PTY_DEAD_MS = 3 * 60_000;
+/**
+ * TTL for the post-Stop `hold-background` path. The hold protects
+ * run_in_background agents living inside the claude process — but a live
+ * agent keeps emitting hook/sidecar/JSONL traffic. If the hold sees no
+ * activity on ANY channel for this long, the pending count is phantom (lost
+ * <task-notification>, agents already finished): release as a NORMAL Stop.
+ * Without this TTL the stall watchdog eventually fires instead, mislabels the
+ * cleanly-finished turn 'stalled', and injects a confusing auto-resume prompt
+ * (the「回合明明答完了还被注入 Continue」symptom).
+ */
+export const CLAUDE_TUI_STOP_HOLD_QUIET_TTL_MS = 10 * 60_000;
 /** Codex-specific grace period added to the user-configured timeout. */
 export const CODEX_STREAM_HARD_KILL_GRACE_MS = 5_000;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pikiclaw",
-  "version": "0.3.62",
+  "version": "0.3.63",
   "description": "Put the world's smartest AI agents in your pocket. Command local Claude & Gemini via IM. | 让最好用的 IM 变成你电脑上的顶级 Agent 控制台",
   "type": "module",
   "bin": {