@a1hvdy/cc-openclaw 0.9.2 → 0.11.0

package/dist/src/openai-compat/voice-recovery.js

@@ -0,0 +1,231 @@
+/**
+ * voice-recovery — server-side bridge that ensures voice delivery via
+ * `[[tts:text]]...[[/tts:text]]` markers even when Savvy doesn't emit them.
+ *
+ * v0.10.3 turns cc-openclaw from a passive text proxy into an active
+ * voice-aware bridge for three failure modes:
+ *
+ *   1. Savvy emits `<tool_calls>` XML for a native OpenClaw voice tool
+ *      (e.g. `message.voice`) that cc-openclaw can't execute. The XML
+ *      lands as raw text in the SSE stream. → `translateVoiceToolCalls`
+ *      rewrites it as `[[tts:text]]` markers.
+ *
+ *   2. User explicitly asks for voice but Savvy produces markerless text
+ *      (the dominant failure observed in the 2026-05-11 evening test).
+ *      → `autoWrapMissingMarkers` wraps the first sentence/paragraph
+ *      in markers so OpenClaw's `maybeApplyTtsToPayload` triggers.
+ *
+ *   3. Hint-loss between turns. → `detectVoiceIntent` gates recovery so
+ *      it only fires on explicit voice requests, never on accidental
+ *      voice-keyword matches in non-voice prompts.
+ *
+ * All functions are PURE — no side effects, no IO, no logging. Tests
+ * exercise them directly via `tests/voice-recovery.test.ts`.
+ */
+// ── Constants ─────────────────────────────────────────────────────────────
+/** Word-boundary regex for explicit voice-delivery intent in user prompts.
+ *  Kept TIGHT to avoid false positives: "voice" alone is too broad (could be
+ *  asking about TTS config); "send a voice note" / "speak" / "in voice" are
+ *  the intended triggers. */
+const VOICE_INTENT_REGEX = /\b(voice\s*notes?|voice\s*messages?|send\s+(?:me\s+)?(?:a\s+)?voice|in\s+voice|speak\s+(?:it|the|me|to|aloud)|say\s+(?:it|the|me).*aloud|tell\s+me\s+(?:out\s+loud|aloud)|read\s+(?:it|the|this)\s+aloud)\b/i;
+/** Markers OpenClaw's `maybeApplyTtsToPayload` looks for. */
+const TTS_OPEN = '[[tts:text]]';
+const TTS_CLOSE = '[[/tts:text]]';
+/** Default max chars inside the spoken block. Matches the TTS_RULE budget. */
+export const DEFAULT_MAX_SPOKEN_CHARS = 500;
+// ── Diagnostic logging (v0.10.4) ──────────────────────────────────────────
+/** v0.10.4 — env-gated debug logger for triangulating voice-recovery
+ *  failure mode on Telegram vs. direct-probe paths. Single-line JSON for
+ *  grep-ability via `pm2 logs openclaw-gateway | grep _voice_debug`.
+ *  Disabled unless `CC_OPENCLAW_VOICE_DEBUG=1`. Safe to leave in code
+ *  permanently — the gate is a single string equality check. */
+export function _logVoiceDebug(label, fields) {
+    if (process.env.CC_OPENCLAW_VOICE_DEBUG !== '1')
+        return;
+    try {
+        const payload = { _voice_debug: label, ...fields, ts: new Date().toISOString() };
+        // eslint-disable-next-line no-console
+        console.error(JSON.stringify(payload));
+    }
+    catch {
+        // Logging must never throw into the request path
+    }
+}
+// ── Public API ────────────────────────────────────────────────────────────
+/** Detect whether the user's prompt explicitly requests a voice note. */
+export function detectVoiceIntent(userPrompt) {
+    if (!userPrompt)
+        return false;
+    return VOICE_INTENT_REGEX.test(userPrompt);
+}
+/** Check whether the reply text already contains a complete `[[tts:text]]`
+ *  block (open + close pair). */
+export function hasTtsMarkers(text) {
+    if (!text)
+        return false;
+    const openIdx = text.indexOf(TTS_OPEN);
+    if (openIdx === -1)
+        return false;
+    const closeIdx = text.indexOf(TTS_CLOSE, openIdx + TTS_OPEN.length);
+    return closeIdx !== -1;
+}
+/** Pattern matching `<tool_calls>` or `<tool_use>` or `<function_calls>` XML
+ *  blocks whose `name` attribute looks like a voice/TTS delivery tool.
+ *  Matches names: `voice`, `speak`, `tts`, `sendVoice`, `send_voice`,
+ *  `message.voice`, `message_voice`, `messageVoice`, and `message.send` if
+ *  it carries an `audioAsVoice` or `as_voice` argument. Permissive on
+ *  purpose — Phase H of the ship plan analyzes the actual tool name from
+ *  a sysprompt dump and may narrow this in v0.10.4. */
+const VOICE_TOOL_NAME_REGEX = /(?:voice|speak|tts|send[\s_-]?voice|message[.\s_-]?voice|message[.\s_-]?send.*?(?:audioAsVoice|as[\s_-]?voice))/i;
+/** Loose regex catching the common Anthropic-style tool-call XML envelopes. */
+const TOOL_CALL_XML_BLOCK_REGEX = /<(tool_calls?|tool_use|function_calls?)\b[^>]*>([\s\S]*?)<\/\1>/gi;
+/** Inside a tool-call XML block (or the full <tag name="..."> opening),
+ *  find the `name` attribute or `<name>` field or JSON-style `"name":"..."`. */
+const TOOL_NAME_REGEX = /name\s*=\s*"([^"]+)"|<name>\s*([^<]+?)\s*<\/name>|"name"\s*:\s*"([^"]+)"/i;
+/** Inside a tool-call XML block, extract the spoken text argument. Tries
+ *  several common shapes: `<text>X</text>`, `<input>X</input>`,
+ *  `<content>X</content>`, `"text":"X"`, `"input":"X"`, `"content":"X"`.
+ *  Returns the first non-empty match, trimmed. */
+function extractSpokenText(xmlBody) {
+    const xmlTagPatterns = [/<text>([\s\S]*?)<\/text>/i, /<input>([\s\S]*?)<\/input>/i, /<content>([\s\S]*?)<\/content>/i, /<speech>([\s\S]*?)<\/speech>/i];
+    for (const re of xmlTagPatterns) {
+        const m = xmlBody.match(re);
+        if (m && m[1]) {
+            const trimmed = m[1].trim();
+            if (trimmed)
+                return trimmed;
+        }
+    }
+    const jsonPatterns = [/"text"\s*:\s*"((?:[^"\\]|\\.)*)"/i, /"input"\s*:\s*"((?:[^"\\]|\\.)*)"/i, /"content"\s*:\s*"((?:[^"\\]|\\.)*)"/i, /"speech"\s*:\s*"((?:[^"\\]|\\.)*)"/i];
+    for (const re of jsonPatterns) {
+        const m = xmlBody.match(re);
+        if (m && m[1]) {
+            const decoded = m[1].replace(/\\n/g, '\n').replace(/\\"/g, '"').replace(/\\\\/g, '\\').trim();
+            if (decoded)
+                return decoded;
+        }
+    }
+    return null;
+}
+/** If `text` contains a `<tool_calls>` XML block targeting a voice-delivery
+ *  tool, extract the spoken-text argument. Returns the spoken text or null. */
+export function extractTtsToolCallText(text) {
+    if (!text)
+        return null;
+    TOOL_CALL_XML_BLOCK_REGEX.lastIndex = 0;
+    let match;
+    while ((match = TOOL_CALL_XML_BLOCK_REGEX.exec(text)) !== null) {
+        const body = match[2] ?? '';
+        // Search the FULL match (including opening tag) so `name="..."` attributes
+        // on the outer <tool_use name="speak"> tag are caught. Also handles
+        // JSON-style `"name":"..."` payloads inside the body.
+        const nameMatch = match[0].match(TOOL_NAME_REGEX);
+        const toolName = (nameMatch?.[1] ?? nameMatch?.[2] ?? nameMatch?.[3] ?? '').trim();
+        if (toolName && VOICE_TOOL_NAME_REGEX.test(toolName)) {
+            const spoken = extractSpokenText(body);
+            if (spoken)
+                return spoken;
+        }
+    }
+    return null;
+}
+/** Rewrite `text`: if a voice-tool XML block is present, remove it and
+ *  insert a `[[tts:text]]<spoken>[[/tts:text]]` block in its place. Idempotent
+ *  when no voice-tool XML is present. */
+export function translateVoiceToolCalls(text) {
+    if (!text)
+        return text;
+    TOOL_CALL_XML_BLOCK_REGEX.lastIndex = 0;
+    // Walk the matches, build a replacement.
+    let result = '';
+    let lastEnd = 0;
+    let match;
+    TOOL_CALL_XML_BLOCK_REGEX.lastIndex = 0;
+    while ((match = TOOL_CALL_XML_BLOCK_REGEX.exec(text)) !== null) {
+        const body = match[2] ?? '';
+        // Search the FULL match (including opening tag) so `name="..."` attributes
+        // on the outer <tool_use name="speak"> tag are caught. Also handles
+        // JSON-style `"name":"..."` payloads inside the body.
+        const nameMatch = match[0].match(TOOL_NAME_REGEX);
+        const toolName = (nameMatch?.[1] ?? nameMatch?.[2] ?? nameMatch?.[3] ?? '').trim();
+        if (toolName && VOICE_TOOL_NAME_REGEX.test(toolName)) {
+            const spoken = extractSpokenText(body);
+            if (spoken) {
+                result += text.slice(lastEnd, match.index);
+                result += `${TTS_OPEN}${spoken}${TTS_CLOSE}`;
+                lastEnd = match.index + match[0].length;
+            }
+        }
+    }
+    result += text.slice(lastEnd);
+    return result;
+}
+/** Truncate at a sentence boundary if possible, otherwise hard-cut.
+ *  Used to keep the spoken portion within the voice-budget. */
+function truncateAtSentence(text, maxChars) {
+    if (text.length <= maxChars)
+        return text;
+    const slice = text.slice(0, maxChars);
+    // Try last sentence-ending punctuation
+    const lastSentence = Math.max(slice.lastIndexOf('. '), slice.lastIndexOf('! '), slice.lastIndexOf('? '));
+    if (lastSentence > maxChars * 0.5)
+        return slice.slice(0, lastSentence + 1);
+    // Otherwise hard-cut at last space
+    const lastSpace = slice.lastIndexOf(' ');
+    if (lastSpace > maxChars * 0.5)
+        return slice.slice(0, lastSpace) + '…';
+    return slice + '…';
+}
+/** If `text` is missing voice markers, find a reasonable spoken summary
+ *  (first paragraph up to `maxSpokenChars`) and wrap it. Returns text with
+ *  the marker block prepended; the original first paragraph is left in place
+ *  as text expansion. Idempotent when markers already present. */
+export function autoWrapMissingMarkers(text, maxSpokenChars = DEFAULT_MAX_SPOKEN_CHARS) {
+    if (!text)
+        return text;
+    if (hasTtsMarkers(text))
+        return text;
+    const trimmed = text.trim();
+    if (!trimmed)
+        return text;
+    // Pick the first paragraph (up to the first blank line). The ★ Insight
+    // block typically appears below — leave it alone.
+    const firstBlankLine = trimmed.search(/\n\s*\n/);
+    const firstPara = firstBlankLine === -1 ? trimmed : trimmed.slice(0, firstBlankLine).trim();
+    // Strip leading boilerplate Savvy sometimes adds ("Let me send the voice note now.")
+    const filtered = firstPara
+        .replace(/^(?:i (?:have|got) what i need\.?\s*)?let me send (?:the\s+)?voice (?:note|message)(?:\s+now)?\.?\s*/i, '')
+        .replace(/^(?:here(?:'s|\s+is)|on\s+it|sending\s+(?:a\s+)?voice(?:\s+note)?)[:.]?\s*/i, '')
+        .trim();
+    // Fall back to the original first paragraph if filtering removed everything
+    const spokenRaw = filtered || firstPara;
+    const spoken = truncateAtSentence(spokenRaw, maxSpokenChars);
+    if (!spoken)
+        return text;
+    // Prepend the marker block; keep the rest of the original text as text expansion.
+    // Use \n\n separator so the marker block is visually distinct.
+    return `${TTS_OPEN}${spoken}${TTS_CLOSE}\n\n${text}`;
+}
+/** Convenience helper: run the full recovery pipeline on a reply when the
+ *  user has expressed voice intent. Returns the (possibly rewritten) text. */
+export function applyVoiceRecovery(userPrompt, replyText, maxSpokenChars = DEFAULT_MAX_SPOKEN_CHARS) {
+    if (!detectVoiceIntent(userPrompt)) {
+        return { text: replyText, recovered: false, via: 'none' };
+    }
+    // First try translating any tool-call XML
+    const translated = translateVoiceToolCalls(replyText);
+    if (translated !== replyText && hasTtsMarkers(translated)) {
+        return { text: translated, recovered: true, via: 'tool-translate' };
+    }
+    // If markers already present, nothing to do
+    if (hasTtsMarkers(translated)) {
+        return { text: translated, recovered: false, via: 'none' };
+    }
+    // Auto-wrap the first paragraph
+    const wrapped = autoWrapMissingMarkers(translated, maxSpokenChars);
+    if (wrapped !== translated && hasTtsMarkers(wrapped)) {
+        return { text: wrapped, recovered: true, via: 'auto-wrap' };
+    }
+    return { text: translated, recovered: false, via: 'none' };
+}
+//# sourceMappingURL=voice-recovery.js.map

package/dist/src/openai-compat/voice-recovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice-recovery.js","sourceRoot":"","sources":["../../../src/openai-compat/voice-recovery.ts"],"names":[],"mappings":"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"}

package/dist/src/session/session-manager.d.ts

@@ -28,6 +28,8 @@ export declare class SessionManager {
     private sessions;
     private _pendingSessions;
     private cleanupTimer;
+    private stalledWatchTimer;
+    private _recentSpawns;
     private pluginConfig;
     private persistedSessions;
     private _debouncedSave;
@@ -207,5 +209,54 @@ export declare class SessionManager {
     }): UltrareviewResult;
     ultrareviewStatus(id: string): UltrareviewResult | undefined;
     private _cleanupIdleSessions;
+    /**
+     * v0.10.0 — runtime stalled-session watchdog.
+     *
+     * Fires every STALLED_WATCH_INTERVAL_MS. For each session that is
+     * currently `isBusy === true` (mid-turn) AND whose underlying
+     * PersistentClaudeSession has not received any subprocess event for
+     * STALLED_SESSION_KILL_MS, the watchdog:
+     *
+     *   1. Logs the stall
+     *   2. Emits a `session_stalled_killed` trajectory event
+     *   3. Calls session.stop() (SIGTERM, then SIGKILL after STOP_SIGKILL_DELAY_MS)
+     *   4. Removes the entry from the in-memory `sessions` Map
+     *
+     * The in-flight `sendMessage()` promise will reject with the existing
+     * `TURN_TIMEOUT_MS` error or a session-stop error. The outer agent-runner
+     * then fast-fails to the cross-engine fallback (`openai-codex/gpt-5.4`)
+     * rather than waiting the full provider envelope (900s).
+     *
+     * Threshold is overridable via `CC_OPENCLAW_STALLED_KILL_MS` env var.
+     *
+     * Mirrors `gateway-pm2-wrapper.sh:53-60` boot-time orphan reaper.
+     */
+    private _watchStalledSessions;
+    /**
+     * Resolve the stalled-session kill threshold. Env var
+     * `CC_OPENCLAW_STALLED_KILL_MS` overrides STALLED_SESSION_KILL_MS at
+     * runtime so the value can be tuned without rebuild.
+     */
+    private _stalledThresholdMs;
+    /**
+     * v0.10.1 — record a fresh subprocess spawn for the runaway-loop
+     * watchdog. Trims entries older than RUNAWAY_LOOP_WINDOW_MS so the
+     * array length is bounded.
+     */
+    private _recordSpawn;
+    /**
+     * v0.10.1 — true when the spawn rate over RUNAWAY_LOOP_WINDOW_MS
+     * exceeds the configured threshold (env-overridable). Called by
+     * `_doStartSession` BEFORE recording the new spawn — i.e. the check
+     * fires when the (N+1)-th spawn attempt would push the count over.
+     */
+    private _isRunawayLoop;
+    /**
+     * v0.10.1 — resolve the runaway-loop spawn threshold. Env var
+     * `CC_OPENCLAW_LOOP_MAX_SUBPROCS` overrides RUNAWAY_LOOP_MAX_SUBPROCS
+     * for runtime tuning without rebuild. Clamped to [2, 20] to prevent
+     * accidental disable (0/1) or unbounded raise.
+     */
+    private _runawayThreshold;
 }
 export {};

package/dist/src/session/session-manager.js

@@ -111,13 +111,19 @@ import { PersistentCustomSession } from '../engines/persistent-custom-session.js
 import { overrideModelPricing, } from '../types.js';
 import { resolveAlias, isClaudeModel } from '../models.js';
 import { Council } from '../council/council.js';
-import { PERSIST_DISK_TTL_MS, DEBOUNCED_SAVE_MS, CLEANUP_INTERVAL_MS, TURN_TIMEOUT_MS, GREP_HISTORY_FETCH, TEAM_LIST_TIMEOUT_MS, TEAM_SEND_TIMEOUT_MS, RESULT_TTL_MS, ULTRAPLAN_TIMEOUT_MS, ULTRAREVIEW_POLL_INTERVAL_MS, STOP_SIGKILL_DELAY_MS, SESSION_EVENT, DEFAULT_HISTORY_LIMIT, } from '../constants.js';
+import { PERSIST_DISK_TTL_MS, DEBOUNCED_SAVE_MS, CLEANUP_INTERVAL_MS, TURN_TIMEOUT_MS, GREP_HISTORY_FETCH, TEAM_LIST_TIMEOUT_MS, TEAM_SEND_TIMEOUT_MS, RESULT_TTL_MS, ULTRAPLAN_TIMEOUT_MS, ULTRAREVIEW_POLL_INTERVAL_MS, STOP_SIGKILL_DELAY_MS, SESSION_EVENT, DEFAULT_HISTORY_LIMIT, STALLED_SESSION_KILL_MS, STALLED_WATCH_INTERVAL_MS, RUNAWAY_LOOP_MAX_SUBPROCS, RUNAWAY_LOOP_WINDOW_MS, } from '../constants.js';
+import * as trajectory from '../lib/trajectory.js';
 import { getGatewayUrl, getGatewayKey, getAnthropicApiKey, getOpenaiApiKey, getGeminiApiKey, getGeminiBin, getCodexBin, getCursorBin, } from '../lib/config.js';
 // ─── SessionManager ──────────────────────────────────────────────────────────
 export class SessionManager {
     sessions = new Map();
     _pendingSessions = new Map();
     cleanupTimer = null;
+    stalledWatchTimer = null;
+    // v0.10.1: rolling spawn-timestamp log for the runaway-loop watchdog.
+    // Each new subprocess spawn pushes Date.now(); entries older than
+    // RUNAWAY_LOOP_WINDOW_MS are trimmed before each check.
+    _recentSpawns = [];
     pluginConfig;
     persistedSessions;
     _debouncedSave;
@@ -149,6 +155,11 @@ export class SessionManager {
         this._debouncedSave = makeDebounced(() => savePersistedSessionsAsync(this.persistedSessions, this.logger), DEBOUNCED_SAVE_MS);
         // Start TTL cleanup timer
         this.cleanupTimer = setInterval(() => this._cleanupIdleSessions(), CLEANUP_INTERVAL_MS);
+        // v0.10.0: Start runtime stalled-session watchdog. Mirrors the
+        // boot-time orphan reaper in gateway-pm2-wrapper.sh:53-60, but runs
+        // continuously. Catches subprocesses that hang at `model_call:started`
+        // without emitting any output for STALLED_SESSION_KILL_MS.
+        this.stalledWatchTimer = setInterval(() => this._watchStalledSessions(), STALLED_WATCH_INTERVAL_MS);
     }
     // ─── Session Lifecycle ─────────────────────────────────────────────────
     async startSession(config) {
@@ -176,6 +187,24 @@ export class SessionManager {
         if (this.sessions.size >= this.pluginConfig.maxConcurrentSessions) {
             throw new Error(`Max concurrent sessions (${this.pluginConfig.maxConcurrentSessions}) reached`);
         }
+        // v0.10.1: runaway-loop watchdog. Refuse the spawn if OpenClaw is
+        // hammering us with new-session requests faster than a real
+        // conversation justifies. See RUNAWAY_LOOP_MAX_SUBPROCS comment in
+        // constants.ts for the 2026-05-11 incident context.
+        if (this._isRunawayLoop()) {
+            const count = this._recentSpawns.length;
+            const thresholdMax = this._runawayThreshold();
+            const windowMs = RUNAWAY_LOOP_WINDOW_MS;
+            this.logger.warn(`[watchdog] refusing new session "${name}" — runaway loop detected (${count} spawns in last ${Math.round(windowMs / 1000)}s, threshold=${thresholdMax})`);
+            try {
+                trajectory.emit('runaway_loop_killed', { count, windowMs, thresholdMax, attemptedName: name }, name);
+            }
+            catch {
+                // Trajectory is observability — must never block the refusal
+            }
+            throw new Error(`cc-openclaw: runaway loop — ${count} subprocess spawns in last ${Math.round(windowMs / 1000)}s exceeds threshold ${thresholdMax}; aborting to prevent gateway thrash`);
+        }
+        this._recordSpawn();
         // Auto-resume: if we have a persisted claudeSessionId for this name, inject it.
         // Skip when config.skipPersistence is set (e.g. openai-compat bridge sessions
         // that must NOT resume stale CLI state from a previous server run).
@@ -738,6 +767,10 @@ export class SessionManager {
             clearInterval(this.cleanupTimer);
             this.cleanupTimer = null;
         }
+        if (this.stalledWatchTimer) {
+            clearInterval(this.stalledWatchTimer);
+            this.stalledWatchTimer = null;
+        }
         // Stop ultrareview pollers
         for (const [, timer] of this.ultrareviewPollers)
             clearInterval(timer);
@@ -1384,5 +1417,136 @@ export class SessionManager {
         if (pruned)
             savePersistedSessionsAsync(this.persistedSessions);
     }
+    /**
+     * v0.10.0 — runtime stalled-session watchdog.
+     *
+     * Fires every STALLED_WATCH_INTERVAL_MS. For each session that is
+     * currently `isBusy === true` (mid-turn) AND whose underlying
+     * PersistentClaudeSession has not received any subprocess event for
+     * STALLED_SESSION_KILL_MS, the watchdog:
+     *
+     *   1. Logs the stall
+     *   2. Emits a `session_stalled_killed` trajectory event
+     *   3. Calls session.stop() (SIGTERM, then SIGKILL after STOP_SIGKILL_DELAY_MS)
+     *   4. Removes the entry from the in-memory `sessions` Map
+     *
+     * The in-flight `sendMessage()` promise will reject with the existing
+     * `TURN_TIMEOUT_MS` error or a session-stop error. The outer agent-runner
+     * then fast-fails to the cross-engine fallback (`openai-codex/gpt-5.4`)
+     * rather than waiting the full provider envelope (900s).
+     *
+     * Threshold is overridable via `CC_OPENCLAW_STALLED_KILL_MS` env var.
+     *
+     * Mirrors `gateway-pm2-wrapper.sh:53-60` boot-time orphan reaper.
+     */
+    _watchStalledSessions() {
+        const thresholdMs = this._stalledThresholdMs();
+        const now = Date.now();
+        for (const [name, managed] of this.sessions) {
+            // Skip sessions that aren't currently in-flight; idle TTL cleanup
+            // handles those.
+            if (!managed.session.isBusy)
+                continue;
+            // PersistentClaudeSession.stats.lastActivity is an ISO string updated
+            // on every NDJSON event from the subprocess (persistent-session.ts:395).
+            // If null, the session never received a single event — definitely stuck.
+            const stats = managed.session.getStats();
+            const lastActivityIso = stats.lastActivity;
+            const lastEventMs = lastActivityIso
+                ? new Date(lastActivityIso).getTime()
+                : managed.lastActivity;
+            const ageMs = now - lastEventMs;
+            if (ageMs <= thresholdMs)
+                continue;
+            this.logger.warn(`[watchdog] killing stalled session ${name} (busy, no subprocess event for ${Math.round(ageMs / 1000)}s, threshold=${Math.round(thresholdMs / 1000)}s)`);
+            try {
+                trajectory.emit('session_stalled_killed', {
+                    ageMs,
+                    lastActivity: lastActivityIso,
+                    thresholdMs,
+                    model: managed.config.model,
+                    cwd: managed.cwd,
+                    isBusy: true,
+                }, managed.claudeSessionId ?? name);
+            }
+            catch {
+                // Trajectory is observability — must never block recovery
+            }
+            try {
+                managed.session.stop();
+            }
+            catch {
+                // Best-effort — subprocess may already be dead
+            }
+            this.sessions.delete(name);
+            // Don't touch persistedSessions: the disk record may still be
+            // resumable if the stall was transient (e.g. network blip during
+            // model call). PERSIST_DISK_TTL_MS will GC it eventually.
+        }
+    }
+    /**
+     * Resolve the stalled-session kill threshold. Env var
+     * `CC_OPENCLAW_STALLED_KILL_MS` overrides STALLED_SESSION_KILL_MS at
+     * runtime so the value can be tuned without rebuild.
+     */
+    _stalledThresholdMs() {
+        const raw = process.env.CC_OPENCLAW_STALLED_KILL_MS;
+        if (raw) {
+            const parsed = Number.parseInt(raw, 10);
+            if (Number.isFinite(parsed) && parsed >= 10_000)
+                return parsed;
+        }
+        return STALLED_SESSION_KILL_MS;
+    }
+    /**
+     * v0.10.1 — record a fresh subprocess spawn for the runaway-loop
+     * watchdog. Trims entries older than RUNAWAY_LOOP_WINDOW_MS so the
+     * array length is bounded.
+     */
+    _recordSpawn() {
+        const now = Date.now();
+        this._recentSpawns.push(now);
+        const cutoff = now - RUNAWAY_LOOP_WINDOW_MS;
+        // Trim leading entries that have fallen out of the window. The array
+        // stays sorted ascending since we only ever push Date.now().
+        let drop = 0;
+        while (drop < this._recentSpawns.length && this._recentSpawns[drop] < cutoff)
+            drop++;
+        if (drop > 0)
+            this._recentSpawns.splice(0, drop);
+    }
+    /**
+     * v0.10.1 — true when the spawn rate over RUNAWAY_LOOP_WINDOW_MS
+     * exceeds the configured threshold (env-overridable). Called by
+     * `_doStartSession` BEFORE recording the new spawn — i.e. the check
+     * fires when the (N+1)-th spawn attempt would push the count over.
+     */
+    _isRunawayLoop() {
+        // Trim stale entries before the rate decision so a long quiet period
+        // followed by a burst doesn't carry stale counters.
+        const now = Date.now();
+        const cutoff = now - RUNAWAY_LOOP_WINDOW_MS;
+        let drop = 0;
+        while (drop < this._recentSpawns.length && this._recentSpawns[drop] < cutoff)
+            drop++;
+        if (drop > 0)
+            this._recentSpawns.splice(0, drop);
+        return this._recentSpawns.length >= this._runawayThreshold();
+    }
+    /**
+     * v0.10.1 — resolve the runaway-loop spawn threshold. Env var
+     * `CC_OPENCLAW_LOOP_MAX_SUBPROCS` overrides RUNAWAY_LOOP_MAX_SUBPROCS
+     * for runtime tuning without rebuild. Clamped to [2, 20] to prevent
+     * accidental disable (0/1) or unbounded raise.
+     */
+    _runawayThreshold() {
+        const raw = process.env.CC_OPENCLAW_LOOP_MAX_SUBPROCS;
+        if (raw) {
+            const parsed = Number.parseInt(raw, 10);
+            if (Number.isFinite(parsed) && parsed >= 2 && parsed <= 20)
+                return parsed;
+        }
+        return RUNAWAY_LOOP_MAX_SUBPROCS;
+    }
 }
 //# sourceMappingURL=session-manager.js.map