docs(turn-stages): the settle hold is 20s, not the 10s this page claimed #1079

Merged

coilysiren merged 1 commit from aos/claude/turn-stages-hold-doc into main

2026-08-19 15:37:06 +00:00

coilyco-ops commented

2026-08-19 15:35:45 +00:00

Member

Closes #1078.

What changes

One paragraph in docs/sirens-echo-turn-stages.md. It said a reply can be held "for up to 10 seconds after it is ready". The cap is turnProgressEvery, which deriveKnobs sets to turnProgressAfter * 2, and settleDelay returns turnProgressEvery - remainder, so the beat bounds the hold rather than the wait. At the packaged 10s wait that is 20 seconds.

docs/sirens-echo-progress.md already described the same mechanism correctly at a twenty second grid, so the two pages disagreed and the one carrying the bold claim was the wrong one.

The measurement

Telemetry refuted it in the open. On sirens-dowel over 24h to 2026-08-19, turn.progress.settle ran p50 15.97s against p95 19.9997s, on 33 of 120 turns. A p50 of 15.97s is not reachable under a 10s ceiling.

Why this is not a typo fix

The sentence continues into "whether that trade is right is a separate question from whether it is visible", so it is the sentence someone weighs when deciding whether the hold is acceptable. Halving the cost halves the argument.

It also misplaced where the hold bites. Splitting turns into stages shows the settle dominating ordinary turns rather than slow ones:

22.3s turn - 9.5s settle, 10.0s model across 2 calls, 0.63s tools
35.3s turn - 20.0s settle, 12.2s model across 2 calls, 1.12s tools
17.2s turn - 0s settle, 15.1s model across 2 calls, 2.02s tools

Against a 300.8s turn where the settle was 0s and model time was 99%. A reader on "up to 10 seconds" would rank the settle behind tool time on a median turn, where it is second only to the model.

The rewrite names the derivation rather than restating a literal, so the prose cannot drift from the knob again the way it just did.

Validation

pre-commit run --all-files passes clean, including dead cross-links and Markdown size caps.

Scope

Docs only. No behaviour change, no knob change, nothing that moves capability, so this sits on the permitted side of the #929 freeze amendment. The hold itself is unchanged and whether to keep it is still open.

Closes #1078. ## What changes One paragraph in `docs/sirens-echo-turn-stages.md`. It said a reply can be held "for up to 10 seconds after it is ready". The cap is `turnProgressEvery`, which `deriveKnobs` sets to `turnProgressAfter * 2`, and `settleDelay` returns `turnProgressEvery - remainder`, so the beat bounds the hold rather than the wait. At the packaged 10s wait that is **20 seconds**. `docs/sirens-echo-progress.md` already described the same mechanism correctly at a twenty second grid, so the two pages disagreed and the one carrying the bold claim was the wrong one. ## The measurement Telemetry refuted it in the open. On sirens-dowel over 24h to 2026-08-19, `turn.progress.settle` ran p50 **15.97s** against p95 **19.9997s**, on 33 of 120 turns. A p50 of 15.97s is not reachable under a 10s ceiling. ## Why this is not a typo fix The sentence continues into "whether that trade is right is a separate question from whether it is visible", so it is the sentence someone weighs when deciding whether the hold is acceptable. Halving the cost halves the argument. It also misplaced where the hold bites. Splitting turns into stages shows the settle dominating ordinary turns rather than slow ones: * 22.3s turn - **9.5s** settle, 10.0s model across 2 calls, 0.63s tools * 35.3s turn - **20.0s** settle, 12.2s model across 2 calls, 1.12s tools * 17.2s turn - 0s settle, 15.1s model across 2 calls, 2.02s tools Against a 300.8s turn where the settle was 0s and model time was 99%. A reader on "up to 10 seconds" would rank the settle behind tool time on a median turn, where it is second only to the model. The rewrite names the derivation rather than restating a literal, so the prose cannot drift from the knob again the way it just did. ## Validation `pre-commit run --all-files` passes clean, including `dead cross-links` and `Markdown size caps`. ## Scope Docs only. No behaviour change, no knob change, nothing that moves capability, so this sits on the permitted side of the #929 freeze amendment. The hold itself is unchanged and whether to keep it is still open.

coilyco-ops added 1 commit

2026-08-19 15:35:45 +00:00

docs(turn-stages): the settle hold is 20s, not the 10s this page claimed

ci / image-build (pull_request) Successful in 30s

Details

ci / test (pull_request) Successful in 1m1s

Details

ci / publish-echo-image (pull_request) Has been skipped

Details

ci / publish-observed (pull_request) Has been skipped

Details

5ee6754480

The cap is turnProgressEvery, which deriveKnobs sets to turnProgressAfter
* 2, and settleDelay returns turnProgressEvery - remainder, so the beat
bounds the hold rather than the wait. sirens-echo-progress.md already had
it right at a twenty second grid, so the two pages disagreed.

Telemetry refuted it in the open: turn.progress.settle on sirens-dowel ran
p50 15.97s against p95 19.9997s over 24h, and a p50 of 15.97s is not
reachable under a 10s ceiling.

The sentence carries a decision rather than a fact, since it continues into
whether the trade is right, so half the number is half the argument. Names
the derivation so the prose cannot drift from the knob again, and records
that the settle dominates ordinary turns rather than slow ones.

Closes coilyco-gaming/sirens-echo#1078

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

coilyco-ops requested review from coilysiren

2026-08-19 15:35:45 +00:00