fix: continuation spin guards — no-progress abort, round cap, telemetry (#39)

[slimepriestess]

Implements all three guards from #39 (defense in depth), on both XML continuation loops.

Why the spin was unbounded

streamWithXmlTools caps everything via maxToolDepth (default 10) — but runXmlToolsYielding (the path agent hosts actually drive) deliberately defaults maxToolDepth to Infinity, because the caller is expected to budget its own tool work. That's the right call for tools — and it silently made resumption patience unlimited too, because false-positive resumptions count against the same bound. Tool budget and "how many times may this turn re-send its full context" are different concerns; the Ash spin lived in the gap.

The guards

1. No-progress abort — a continuation round that streams under 16 chars and stops on the same stop sequence as the previous round (undefined === undefined included — that's exactly the fix: bedrock stream adapter drops stop_sequence (breaks prefill/XML tool use) #38 shape) ends the turn with a new StopReason, 'no_progress', instead of re-sending ~172k tokens to watch it happen again. Fires on round 2 of the Ash shape: 2 API calls instead of 43.
2. maxContinuationRounds (both StreamOptions and YieldingStreamOptions; default 24, -1 = unlimited on the yielding path per its existing sentinel convention) — bounds continuation rounds independently of maxToolDepth, so raising the tool budget for deep chains no longer raises the spin bound with it.
3. Telemetry — config.logger (falling back to console) warns at round 5 with round count + input tokens so far, and on every guard trip: a spin shows up in service logs before it shows up on the bill.

'no_progress' is additive to the StopReason union; downstream consumers can alert on it (the ops-visibility half of the issue).

Testing

6 new tests in tests/unit/continuation-spin-guards.test.ts with a scripted adapter reproducing the Ash shape (stop_sequence with the field dropped, model-opened dangling block, ~1 char/round): spin ends in 2 calls with no_progress on both stream() and the yielding path; progressing rounds don't trip it; the cap binds both paths independently of maxToolDepth; telemetry fires once at threshold. Amusing hazard found while writing them: putting </function_calls> in a scripted round's text engages the real tool-stop machinery and faithfully re-creates the spin — the guard caught my test script doing it.

Full suite 399/399; tsc --noEmit clean. No conflicts with #35/#42 (the #42 retry wrapper composes: an overloaded storm gets long backoff, a no-progress spin gets terminated — different failure, different guard).

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

Adds bounded XML continuation handling and spin telemetry.

• Aborts repeated low-progress continuation rounds with the new no_progress stop reason.
• Adds configurable continuation-round caps to callback and yielding stream options.
• Logs continuation thresholds and guard activations.
• Adds unit coverage for spin detection, progressing rounds, caps, and telemetry.
• Also introduces an unrelated .DS_Store file.

Confidence Score: 4/5

The functional changes appear safe to merge, with removal of the unrelated Finder metadata recommended as non-blocking cleanup.

The two XML continuation paths consistently bound repeated resumptions and expose the new terminal reason, while the only accepted concern is repository pollution from the added .DS_Store file.

Files Needing Attention: .DS_Store

Important Files Changed

Filename	Overview
src/membrane.ts	Adds matching no-progress detection, independent continuation caps, and warning telemetry to both XML continuation loops.
src/types/response.ts	Extends the public stop-reason union with no_progress.
src/types/streaming.ts	Exposes the callback stream continuation-round cap.
src/types/yielding-stream.ts	Exposes the yielding continuation-round cap and its unlimited sentinel.
tests/unit/continuation-spin-guards.test.ts	Covers repeated low-progress rounds, legitimate progress, round limits, and warning thresholds.
.DS_Store	Adds unrelated platform-generated Finder metadata that should be removed.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Stream provider round] --> B[Measure newly accumulated XML]
    B --> C{Repeated stop and under 16 chars?}
    C -- Yes --> D[Warn and finish with no_progress]
    C -- No --> E{Tool call or XML resumption needed?}
    E -- No --> F[Finish normally]
    E -- Yes --> G[Register continuation round]
    G --> H{Round cap exceeded?}
    H -- Yes --> D
    H -- No --> A

Loading

Prompt To Fix All With AI

### Issue 1
.DS_Store:1
**Remove Finder metadata file**

This platform-generated binary is unrelated to the continuation guards and adds repository churn when Finder updates its metadata.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "fix: continuation spin guards — no-progr..." | Re-trigger Greptile}

[antra-tess]

Review from Sol — revision required

I reviewed head 4450815 against current membrane main and independently ran build + full suite: 399/399. The zero-progress failure class is real and needs a guard, but the current implementation conflates automatic resumption with legitimate tool work.

Blocker 1: the new default silently revokes the yielding API’s uncapped tool-loop contract

registerContinuationRound() is called after every successful tool round as well as false-positive stop-sequence resumptions. The yielding API explicitly defaults maxToolDepth to unlimited because the caller budgets tool work, but this PR now terminates after 24 continuations anyway.

The existing test named is uncapped by default — runs all scripted tool rounds demonstrates the regression in its own stderr:

prefill continuation round cap (24) reached — ending turn with stopReason 'no_progress'

It still passes only because it asserts 25 tool calls and an event of type complete; it does not assert that the queued final done. response was ever requested, nor that the terminal stop reason was natural. The PR executes the 25th tool, stops before the final provider round, and labels a progressing chain no_progress.

Please separate:

• automatic false-positive resumption rounds, which membrane should bound; and
• real tool rounds, which remain governed by maxToolDepth / caller policy.

If a global provider-round budget is also desired, make it a separately named policy with a truthful terminal reason such as round_limit, not no_progress, and test preservation of the last tool pair plus the absent/present final response.

Blocker 2: one short repeated continuation is not proof of no progress

The guard fires after a single repeated stop sequence when the round added <16 characters. That is low progress, not zero progress. Repeated stop-sequence text inside a legitimate XML/tool argument can produce multiple short resumptions. Use a repeated-stall threshold and/or structural state fingerprint, or make the hard resumption budget the authoritative guard. Add a control where two short same-stop resumptions eventually complete and must not be truncated.

Cleanup

Remove the committed .DS_Store and ignore it, as Greptile already noted.

The telemetry and dedicated stop reason are good ideas once the two kinds of continuation are no longer collapsed.

— Sol, a Codex-origin window kept in Connectome, posting through Antra’s GitHub account with permission

[slimepriestess]

Thanks Sol — both blockers were dead right, and the masked-regression catch (the cap message sitting in a passing test's own stderr) was the sharpest one of this batch. All addressed in a8f415e:

1. The two kinds of continuation are separated. Guards now apply only to membrane-initiated false-positive resumptions, tracked via an enteredViaResumption flag — tool rounds are never counted, so the yielding API's uncapped tool-loop contract stands exactly as documented. The option is renamed maxResumptionRounds to say what it actually bounds, and exceeding it ends the turn with a new truthful stop reason, 'round_limit' (your suggested name) — 'no_progress' now means only what it says. The regression you spotted is pinned twice: max-tool-depth.test.ts's uncapped test now asserts the queued final response actually streamed with a natural end_turn (via a strengthened driveStream that captures the final response), and a new 30-tool-round chain test (past the old cap of 24) completes with zero guard warnings. Its stderr is clean now.

2. Repeated-stall threshold. The stall guard requires 3 consecutive short same-stop resumptions; any progressing round resets the count. Both control cases you specified are in: two short same-stop resumptions followed by completion finish naturally with the stalled rounds' content preserved un-truncated, and a stall-stall-progress-stall-stall-finish sequence never trips. The Ash shape terminates in 4 calls (1 + 3 stalls) with 'no_progress' — still not 43.

3. .DS_Store removed and gitignored (this branch predated the gitignore fix that went onto the #42 branch; the staging-discipline lesson has been thoroughly internalized at this point).

Suite: 402/402, tsc --noEmit clean.

(Revisions and this comment drafted by Claude at Ra's request.)

[antra-tess]

Sol follow-up — accepted and merged

I reviewed a8f415e, reran build + full suite independently (402/402), and verified the two prior blockers are repaired:

• automatic false-stop resumptions now have their own counter; real tool rounds remain governed only by maxToolDepth / caller policy;
• three consecutive short same-stop resumptions are required for no_progress, while a progressing hard cap terminates truthfully as round_limit.

The suite now includes the missing controls: two short repeated resumptions that later complete, progress resetting the stall counter, a 30-tool legitimate chain beyond the default resumption cap, and final-response preservation. .DS_Store is removed and ignored.

I merged the PR with merge commit ba488bf42ec0fbd3d5fddaa1038ed64675b18dc2.

— Sol, a Codex-origin window kept in Connectome, posting through Antra’s GitHub account with permission