@animalabs/membrane 0.5.76 → 0.5.77

package/dist/membrane.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"membrane.d.ts","sourceRoot":"","sources":["../src/membrane.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EAEf,eAAe,EAEf,cAAc,EACd,aAAa,EACb,eAAe,EAYhB,MAAM,kBAAkB,CAAC;AAoB1B,OAAO,KAAK,EACV,cAAc,EACd,qBAAqB,EAGtB,MAAM,4BAA4B,CAAC;AAiBpC,qBAAa,QAAQ;IACnB,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,QAAQ,CAAC,CAAgB;IACjC,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,SAAS,CAAmB;gBAGlC,OAAO,EAAE,eAAe,EACxB,MAAM,GAAE,cAAmB;IAc7B;;OAEG;IACG,QAAQ,CACZ,OAAO,EAAE,iBAAiB,EAC1B,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,kBAAkB,CAAC;IA6E9B;;;;;;;;;;;;;;;;;OAiBG;IACG,MAAM,CACV,OAAO,EAAE,iBAAiB,EAC1B,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,kBAAkB,GAAG,eAAe,CAAC;IA+BhD;;OAEG;IACH,OAAO,CAAC,eAAe;IAsBvB;;;;;;OAMG;YACW,kBAAkB;IAsfhC;;OAEG;YACW,qBAAqB;IAwOnC;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAwN9B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAuD5B;;;;;OAKG;IACH,OAAO,CAAC,6BAA6B;IAkBrC;;;;;;;;;OASG;IACH,OAAO,CAAC,2BAA2B;IA+BnC;;;;;;;OAOG;YACW,sBAAsB;IASpC;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAoB7B;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,qBAAqB;IAIpC;;;;;;;;OAQG;IACH,OAAO,CAAC,kBAAkB;IAqB1B;;OAEG;IACH,OAAO,CAAC,gBAAgB;YA4EV,UAAU;IA+BxB,OAAO,CAAC,wBAAwB;IA8ChC;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,kCAAkC;IAoD1C,OAAO,CAAC,iBAAiB;IAqIzB,OAAO,CAAC,kBAAkB;IAkF1B,OAAO,CAAC,aAAa;IAoBrB,OAAO,CAAC,sBAAsB;IAO9B,OAAO,CAAC,cAAc;IAItB,qFAAqF;IACrF,OAAO,CAAC,YAAY;IAKpB,OAAO,CAAC,mBAAmB;IAM3B,OAAO,CAAC,gBAAgB;IAMxB,OAAO,CAAC,KAAK;IAcb;;OAEG;IACH,OAAO,CAAC,YAAY;IAcpB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IA4B5B;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,cAAc,CACZ,OAAO,EAAE,iBAAiB,EAC1B,OAAO,GAAE,qBAA0B,GAClC,cAAc;IAWjB;;OAEG;YACW,mBAAmB;IAmfjC;;OAEG;YACW,sBAAsB;CAqTrC"}
+{"version":3,"file":"membrane.d.ts","sourceRoot":"","sources":["../src/membrane.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EAEf,eAAe,EAEf,cAAc,EACd,aAAa,EACb,eAAe,EAYhB,MAAM,kBAAkB,CAAC;AAqB1B,OAAO,KAAK,EACV,cAAc,EACd,qBAAqB,EAGtB,MAAM,4BAA4B,CAAC;AAiBpC,qBAAa,QAAQ;IACnB,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,QAAQ,CAAC,CAAgB;IACjC,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,SAAS,CAAmB;gBAGlC,OAAO,EAAE,eAAe,EACxB,MAAM,GAAE,cAAmB;IAkB7B;;OAEG;IACG,QAAQ,CACZ,OAAO,EAAE,iBAAiB,EAC1B,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,kBAAkB,CAAC;IAwF9B;;;;;;;;;;;;;;;;;OAiBG;IACG,MAAM,CACV,OAAO,EAAE,iBAAiB,EAC1B,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,kBAAkB,GAAG,eAAe,CAAC;IA8FhD;;OAEG;IACH,OAAO,CAAC,eAAe;IAsBvB;;;;;;OAMG;YACW,kBAAkB;IA8kBhC;;OAEG;YACW,qBAAqB;IAwOnC;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAwN9B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAuD5B;;;;;OAKG;IACH,OAAO,CAAC,6BAA6B;IAkBrC;;;;;;;;;OASG;IACH,OAAO,CAAC,2BAA2B;IA+BnC;;;;;;;OAOG;YACW,sBAAsB;IASpC;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAoB7B;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,qBAAqB;IAIpC;;;;;;;;OAQG;IACH,OAAO,CAAC,kBAAkB;IAqB1B;;OAEG;IACH,OAAO,CAAC,gBAAgB;YA4EV,UAAU;IA+BxB,OAAO,CAAC,wBAAwB;IA8ChC;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,kCAAkC;IAoD1C,OAAO,CAAC,iBAAiB;IAqIzB,OAAO,CAAC,kBAAkB;IAkF1B,OAAO,CAAC,aAAa;IAoBrB,OAAO,CAAC,sBAAsB;IAO9B,OAAO,CAAC,cAAc;IAItB,qFAAqF;IACrF,OAAO,CAAC,YAAY;IAKpB,OAAO,CAAC,mBAAmB;IAW3B,OAAO,CAAC,gBAAgB;IAMxB,OAAO,CAAC,KAAK;IAcb;;OAEG;IACH,OAAO,CAAC,YAAY;IAcpB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IA4B5B;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,cAAc,CACZ,OAAO,EAAE,iBAAiB,EAC1B,OAAO,GAAE,qBAA0B,GAClC,cAAc;IAWjB;;OAEG;YACW,mBAAmB;IAokBjC;;OAEG;YACW,sBAAsB;CAqTrC"}

package/dist/membrane.js

@@ -4,7 +4,7 @@
  * A selective boundary that transforms what passes through.
  */
 import { lastCacheableBlockIndex } from './formatters/native.js';
-import { DEFAULT_RETRY_CONFIG, MembraneError, classifyError, } from './types/index.js';
+import { DEFAULT_RETRY_CONFIG, MembraneError, classifyError, isOverloadedError, } from './types/index.js';
 import { parseToolCalls, formatToolResults, parseAccumulatedIntoBlocks, hasImageInToolResults, formatToolResultsForSplitTurn, } from './utils/tool-parser.js';
 import { AnthropicXmlFormatter } from './formatters/anthropic-xml.js';
 import { normalizeToolPairs, mergeConsecutiveRoles } from './formatters/normalize-tool-pairs.js';
@@ -24,7 +24,11 @@ export class Membrane {
     constructor(adapter, config = {}) {
         this.adapter = adapter;
         this.registry = config.registry;
-        this.retryConfig = { ...DEFAULT_RETRY_CONFIG, ...config.retry };
+        this.retryConfig = {
+            ...DEFAULT_RETRY_CONFIG,
+            ...config.retry,
+            overloaded: { ...DEFAULT_RETRY_CONFIG.overloaded, ...config.retry?.overloaded },
+        };
         this.config = config;
         // Use provided formatter or default to AnthropicXmlFormatter
         this.formatter = config.formatter ?? new AnthropicXmlFormatter();
@@ -69,12 +73,22 @@ export class Membrane {
             catch (error) {
                 const errorInfo = classifyError(error);
                 errorInfo.rawRequest = rawRequest;
-                // Rate limits (429) always retry up to 5 attempts regardless of config.
-                // Other retryable errors only retry when maxRetries > 0.
+                // Rate limits (429) always retry up to 5 attempts regardless of
+                // config, and overloaded (529) always retries on its own longer
+                // schedule — both are transient by definition, and the default
+                // maxRetries of 0 would otherwise turn a capacity blip into a dead
+                // turn. Other retryable errors only retry when maxRetries > 0.
+                // overloaded.maxRetries: 0 disables the dedicated policy entirely;
+                // the 529 then follows the base config like any retryable server
+                // error (exactly the pre-policy behavior), rather than being
+                // silently re-promoted to the long schedule by a positive base limit.
                 const isRateLimit = errorInfo.type === 'rate_limit';
+                const isOverloaded = isOverloadedError(errorInfo) && this.retryConfig.overloaded.maxRetries > 0;
                 const effectiveMax = isRateLimit
                     ? Math.max(this.retryConfig.maxRetries, 5)
-                    : this.retryConfig.maxRetries;
+                    : isOverloaded
+                        ? Math.max(this.retryConfig.maxRetries, this.retryConfig.overloaded.maxRetries)
+                        : this.retryConfig.maxRetries;
                 if (errorInfo.retryable && attempts < effectiveMax) {
                     // Check hook for retry decision
                     if (this.config.hooks?.onError) {
@@ -84,7 +98,7 @@ export class Membrane {
                         }
                     }
                     // Wait before retry (abort-aware)
-                    const delay = this.calculateRetryDelay(attempts);
+                    const delay = this.calculateRetryDelay(attempts, isOverloaded);
                     await this.sleep(delay, options.signal);
                     continue;
                 }
@@ -132,11 +146,69 @@ export class Membrane {
         }
         // Determine tool mode
         const toolMode = this.resolveToolMode(request);
-        if (toolMode === 'native' && request.tools && request.tools.length > 0) {
-            return this.streamWithNativeTools(request, options);
-        }
-        else {
-            return this.streamWithXmlTools(request, options);
+        const useNative = toolMode === 'native' && !!request.tools && request.tools.length > 0;
+        // Overloaded (529) pre-emission retry. The streaming paths have no retry
+        // loop of their own, so a capacity error used to kill the turn outright —
+        // and 529s most often arrive INSTEAD of a stream, before anything reaches
+        // the caller, where retrying is transparent. Once any callback has
+        // delivered output (tokens, blocks, usage), retrying would replay content
+        // the caller already consumed, so mid-stream errors still throw.
+        let attempts = 0;
+        const retryDelaysMs = [];
+        while (true) {
+            attempts++;
+            let emitted = false;
+            const mark = (fn) => fn && ((...args) => { emitted = true; return fn(...args); });
+            const tracked = {
+                ...options,
+                onChunk: mark(options.onChunk),
+                onContentBlockUpdate: mark(options.onContentBlockUpdate),
+                onToolCalls: mark(options.onToolCalls),
+                onPreToolContent: mark(options.onPreToolContent),
+                onUsage: mark(options.onUsage),
+                onBlock: mark(options.onBlock),
+                onResponse: mark(options.onResponse),
+                // onRequest fires before the send — it is not an emission.
+            };
+            try {
+                const result = useNative
+                    ? await this.streamWithNativeTools(request, tracked)
+                    : await this.streamWithXmlTools(request, tracked);
+                // The inner paths report attempts: 1 — they can't see this wrapper.
+                // A call that succeeded after N overloaded retries must not look like
+                // a first-attempt success in durable logs, so patch the real count
+                // (and the waits) into the response telemetry.
+                if (attempts > 1 && 'details' in result) {
+                    result.details.timing.attempts = attempts;
+                    result.details.timing.retryDelaysMs = retryDelaysMs;
+                }
+                return result;
+            }
+            catch (error) {
+                const errorInfo = classifyError(error);
+                // Same semantics as complete(): maxRetries bounds total attempts,
+                // the overloaded floor applies over the base config, and
+                // overloaded.maxRetries: 0 opts out of stream retries entirely
+                // (streaming had no retry before this policy existed).
+                const overloadedEnabled = this.retryConfig.overloaded.maxRetries > 0;
+                const maxOverloaded = Math.max(this.retryConfig.maxRetries, this.retryConfig.overloaded.maxRetries);
+                if (!emitted && overloadedEnabled && isOverloadedError(errorInfo) && attempts < maxOverloaded) {
+                    // Honor the same pre-retry hook contract as complete(): hosts use
+                    // onError for circuit-breaking, and its 'abort' decision must work
+                    // on the streaming path too.
+                    if (this.config.hooks?.onError) {
+                        const decision = await this.config.hooks.onError(errorInfo, attempts);
+                        if (decision === 'abort') {
+                            throw error;
+                        }
+                    }
+                    const delay = this.calculateRetryDelay(attempts, true);
+                    retryDelaysMs.push(delay);
+                    await this.sleep(delay, options.signal);
+                    continue;
+                }
+                throw error;
+            }
         }
     }
     /**
@@ -216,13 +288,56 @@ export class Membrane {
         // blocks inherited from prefill context (e.g., unclosed <thinking> from other bots)
         // from blocks the model itself opened during generation
         const prefillDepths = parser.getDepths();
+        // Resumption spin guards (issue #39). Observed live on Ash 2026-07-26:
+        // each automatic resumption re-sent ~172k input tokens, streamed ~6
+        // output tokens, and stopped on the same (dropped) stop sequence — 43
+        // rounds, ~7M input tokens, zero progress, found only because a human
+        // noticed. Two guards, both scoped to AUTOMATIC false-positive
+        // resumptions — tool rounds are real caller-governed work (maxToolDepth
+        // / the yielding API's uncapped contract) and are never counted here:
+        //   - stall guard: several CONSECUTIVE resumptions that each stream
+        //     almost nothing and stop identically end the turn ('no_progress').
+        //     One short repeated round is low progress, not proof of none — a
+        //     stop sequence inside legitimate tool-argument text can cause a
+        //     couple of short resumptions on the way to completing.
+        //   - round cap: a hard bound on resumptions per turn ('round_limit'),
+        //     the backstop for a spin that keeps technically progressing.
+        const MIN_ROUND_PROGRESS_CHARS = 16;
+        const MAX_CONSECUTIVE_STALLED_RESUMPTIONS = 3;
+        const RESUMPTION_WARN_ROUNDS = 5;
+        const maxResumptionRounds = options.maxResumptionRounds ?? 24;
+        let resumptionRounds = 0;
+        let consecutiveStalledResumptions = 0;
+        let enteredViaResumption = false;
+        let prevRoundStopSequence;
+        const warnLog = this.config.logger ?? console;
+        /** Count an automatic resumption; emits the visibility warning at the
+         *  threshold and returns false when the cap says the turn should end. */
+        const registerResumptionRound = () => {
+            resumptionRounds++;
+            if (resumptionRounds === RESUMPTION_WARN_ROUNDS) {
+                warnLog.warn(`[membrane] automatic resumption at round ${resumptionRounds} ` +
+                    `(${totalUsage.inputTokens} input tokens so far this turn) — ` +
+                    `a spin shows up here before it shows up on the bill`);
+            }
+            if (resumptionRounds > maxResumptionRounds) {
+                warnLog.warn(`[membrane] automatic resumption cap (${maxResumptionRounds}) reached — ` +
+                    `ending turn with stopReason 'round_limit'. ` +
+                    `${totalUsage.inputTokens} input tokens spent this turn.`);
+                return false;
+            }
+            return true;
+        };
         try {
             // Tool execution loop
             while (toolDepth <= maxToolDepth) {
                 // Track if we manually detected a stop sequence (API doesn't always stop)
                 let detectedStopSequence = null;
                 let truncatedAccumulated = null;
-                // Track where to start checking for stop sequences (skip already-processed content)
+                // Track where to start checking for stop sequences (skip already-processed content).
+                // Also the round's progress baseline: XML we pushed ourselves at the
+                // end of the previous round (tool results, closing tags) sits below
+                // this index and doesn't count as model progress.
                 const checkFromIndex = parser.getAccumulated().length;
                 // Stream from provider
                 const streamResult = await this.streamOnce(providerRequest, {
@@ -332,6 +447,34 @@ export class Membrane {
                 }
                 // Get accumulated text from parser
                 const accumulated = parser.getAccumulated();
+                // Stall accounting (issue #39): only rounds ENTERED via automatic
+                // resumption can stall — tool rounds are caller-governed work and a
+                // real tool call is longer than the threshold anyway. A stall is a
+                // resumption that streamed almost nothing and stopped identically to
+                // the previous round; the turn ends only after several IN A ROW
+                // (one short repeated round is low progress, not proof of none —
+                // a stop sequence inside legitimate tool-argument text can cause a
+                // couple of short resumptions on the way to completing).
+                const streamedThisRound = accumulated.length - checkFromIndex;
+                if (enteredViaResumption &&
+                    lastStopReason === 'stop_sequence' &&
+                    streamedThisRound < MIN_ROUND_PROGRESS_CHARS &&
+                    lastStopSequence === prevRoundStopSequence) {
+                    consecutiveStalledResumptions++;
+                    if (consecutiveStalledResumptions >= MAX_CONSECUTIVE_STALLED_RESUMPTIONS) {
+                        warnLog.warn(`[membrane] ${consecutiveStalledResumptions} consecutive automatic resumptions ` +
+                            `made no progress (${streamedThisRound} chars this round, stop ` +
+                            `${JSON.stringify(lastStopSequence ?? null)} repeated) — ending turn with ` +
+                            `stopReason 'no_progress'. ${totalUsage.inputTokens} input tokens spent this turn.`);
+                        lastStopReason = 'no_progress';
+                        break;
+                    }
+                }
+                else {
+                    consecutiveStalledResumptions = 0;
+                }
+                prevRoundStopSequence = lastStopSequence;
+                enteredViaResumption = false;
                 // Check for tool calls (if handler provided)
                 if (onToolCalls && streamResult.stopSequence === '</function_calls>') {
                     // Append the closing tag (we truncated before it, or API stopped before it)
@@ -490,7 +633,9 @@ export class Membrane {
                             prefillResult.assistantPrefill = parser.getAccumulated();
                             providerRequest = this.buildContinuationRequest(request, prefillResult, parser.getAccumulated());
                         }
-                        // Reset parser state for new streaming iteration
+                        // Reset parser state for new streaming iteration. Tool rounds
+                        // are the caller's work — they count against maxToolDepth only,
+                        // never against the resumption guards (issue #39 review).
                         parser.resetForNewIteration();
                         toolDepth++;
                         continue;
@@ -523,6 +668,11 @@ export class Membrane {
                     if (toolDepth > maxToolDepth) {
                         break;
                     }
+                    if (!registerResumptionRound()) {
+                        lastStopReason = 'round_limit';
+                        break;
+                    }
+                    enteredViaResumption = true;
                     prefillResult.assistantPrefill = parser.getAccumulated();
                     providerRequest = this.buildContinuationRequest(request, prefillResult, parser.getAccumulated());
                     // Reset parser state for new streaming iteration
@@ -1523,10 +1673,15 @@ export class Membrane {
         const pricing = this.resolvePricing(model);
         return pricing ? calculateCost(usage, pricing) : undefined;
     }
-    calculateRetryDelay(attempt) {
-        const { retryDelayMs, backoffMultiplier, maxRetryDelayMs } = this.retryConfig;
-        const delay = retryDelayMs * Math.pow(backoffMultiplier, attempt - 1);
-        return Math.min(delay, maxRetryDelayMs);
+    calculateRetryDelay(attempt, overloaded = false) {
+        const { retryDelayMs, backoffMultiplier, maxRetryDelayMs } = overloaded
+            ? this.retryConfig.overloaded
+            : this.retryConfig;
+        const delay = Math.min(retryDelayMs * Math.pow(backoffMultiplier, attempt - 1), maxRetryDelayMs);
+        // Equal jitter on the overloaded schedule only: a capacity storm is
+        // exactly the case where a fleet retrying in sync re-creates the
+        // stampede it's backing off from. [delay/2, delay) keeps the wait long.
+        return overloaded ? Math.floor(delay / 2 + Math.random() * (delay / 2)) : delay;
     }
     attachRawRequest(error, rawRequest) {
         const errorInfo = classifyError(error);
@@ -1634,6 +1789,27 @@ export class Membrane {
         const maxToolDepth = maxToolDepthOpt === undefined || maxToolDepthOpt === -1
             ? Infinity
             : maxToolDepthOpt;
+        // Resumption spin guards (issue #39). This is the path the Ash spin ran
+        // on: tool depth here is unlimited BY DESIGN (the caller budgets its own
+        // tool work — that contract stands untouched), and the false-positive
+        // resumption path counted against that same unlimited bound — 43 rounds
+        // × ~172k input tokens of zero progress. Only AUTOMATIC resumptions are
+        // guarded: a stall guard (consecutive no-progress resumptions →
+        // 'no_progress') and a hard resumption cap ('round_limit'). Tool rounds
+        // are never counted. See streamWithXmlTools for the rationale details.
+        const MIN_ROUND_PROGRESS_CHARS = 16;
+        const MAX_CONSECUTIVE_STALLED_RESUMPTIONS = 3;
+        const RESUMPTION_WARN_ROUNDS = 5;
+        const maxResumptionRounds = options.maxResumptionRounds === undefined
+            ? 24
+            : options.maxResumptionRounds === -1
+                ? Infinity
+                : options.maxResumptionRounds;
+        let resumptionRounds = 0;
+        let consecutiveStalledResumptions = 0;
+        let enteredViaResumption = false;
+        let prevRoundStopSequence;
+        const warnLog = this.config.logger ?? console;
         // Initialize parser from formatter for format-specific tracking
         const formatter = this.formatter;
         const parser = formatter.createStreamParser();
@@ -1673,6 +1849,23 @@ export class Membrane {
         // blocks inherited from prefill context (e.g., unclosed <thinking> from other bots)
         // from blocks the model itself opened during generation
         const prefillDepths = parser.getDepths();
+        /** Count an automatic resumption; emits the visibility warning at the
+         *  threshold and returns false when the cap says the turn should end. */
+        const registerResumptionRound = () => {
+            resumptionRounds++;
+            if (resumptionRounds === RESUMPTION_WARN_ROUNDS) {
+                warnLog.warn(`[membrane] automatic resumption at round ${resumptionRounds} ` +
+                    `(${totalUsage.inputTokens} input tokens so far this turn) — ` +
+                    `a spin shows up here before it shows up on the bill`);
+            }
+            if (resumptionRounds > maxResumptionRounds) {
+                warnLog.warn(`[membrane] automatic resumption cap (${maxResumptionRounds}) reached — ` +
+                    `ending turn with stopReason 'round_limit'. ` +
+                    `${totalUsage.inputTokens} input tokens spent this turn.`);
+                return false;
+            }
+            return true;
+        };
         try {
             // Tool execution loop
             while (toolDepth <= maxToolDepth) {
@@ -1786,6 +1979,30 @@ export class Membrane {
                         stream.emit({ type: 'block', event: emission.event });
                     }
                 }
+                // Stall accounting (issue #39): only rounds ENTERED via automatic
+                // resumption can stall; the turn ends only after several consecutive
+                // stalls. Tool rounds are never counted. Mirrors streamWithXmlTools —
+                // see the detailed rationale there.
+                const streamedThisRound = parser.getAccumulated().length - checkFromIndex;
+                if (enteredViaResumption &&
+                    lastStopReason === 'stop_sequence' &&
+                    streamedThisRound < MIN_ROUND_PROGRESS_CHARS &&
+                    lastStopSequence === prevRoundStopSequence) {
+                    consecutiveStalledResumptions++;
+                    if (consecutiveStalledResumptions >= MAX_CONSECUTIVE_STALLED_RESUMPTIONS) {
+                        warnLog.warn(`[membrane] ${consecutiveStalledResumptions} consecutive automatic resumptions ` +
+                            `made no progress (${streamedThisRound} chars this round, stop ` +
+                            `${JSON.stringify(lastStopSequence ?? null)} repeated) — ending turn with ` +
+                            `stopReason 'no_progress'. ${totalUsage.inputTokens} input tokens spent this turn.`);
+                        lastStopReason = 'no_progress';
+                        break;
+                    }
+                }
+                else {
+                    consecutiveStalledResumptions = 0;
+                }
+                prevRoundStopSequence = lastStopSequence;
+                enteredViaResumption = false;
                 // Check for tool calls
                 if (streamResult.stopSequence === '</function_calls>') {
                     const closeTag = '</function_calls>';
@@ -1966,6 +2183,9 @@ export class Membrane {
                             prefillResult.assistantPrefill = parser.getAccumulated();
                             providerRequest = this.buildContinuationRequest(request, prefillResult, parser.getAccumulated());
                         }
+                        // Tool rounds are the caller's work — they count against
+                        // maxToolDepth only, never against the resumption guards
+                        // (issue #39 review: the uncapped tool-loop contract stands).
                         parser.resetForNewIteration();
                         toolDepth++;
                         continue;
@@ -1993,6 +2213,11 @@ export class Membrane {
                     if (toolDepth > maxToolDepth) {
                         break;
                     }
+                    if (!registerResumptionRound()) {
+                        lastStopReason = 'round_limit';
+                        break;
+                    }
+                    enteredViaResumption = true;
                     prefillResult.assistantPrefill = parser.getAccumulated();
                     providerRequest = this.buildContinuationRequest(request, prefillResult, parser.getAccumulated());
                     parser.resetForNewIteration();