@enderfga/claw-orchestrator 4.14.0 → 5.0.0

package/skills/references/observability.md

@@ -43,8 +43,8 @@ every engine passes through.
 | `tokensEstimated` | `true` when the counts came from `estimateTokens()` (see below) |
 | `durationMs` | Wall-clock for the turn |
 | `toolCalls` / `toolErrors` | Per-turn deltas |
-| `ok` | `false` for a turn that threw or reported `is_error` |
-| `error` | Failure text, truncated to 500 chars |
+| `ok` | `false` for a turn that threw, or that the session's own `turnsSucceeded` counter did not count (see `sessions.md`). Falls back to "nothing was thrown" when the counter cannot be read |
+| `error` | Failure text, truncated to 500 chars. Absent when the turn resolved but the engine did not count it as succeeded (an interrupted or non-SUCCESS turn), so a failed row does not always carry one |
 | `parent` | council id / fanout id / autoloop run id, when the turn belongs to one |
 
 Deltas rather than totals means summing a query window gives that window's spend

package/skills/references/openai-compat.md

@@ -148,7 +148,8 @@ Sample response:
       "model": "claude-opus-4-6",
       "cwd": "/home/user/projects",
       "created": "2026-04-09T03:12:18.441Z",
-      "turns": 14,
+      "turns": 68,
+      "turns_succeeded": 14,
       "tokens_in": 248312,
       "tokens_out": 38201,
       "cached_tokens": 198104,
@@ -159,6 +160,11 @@ Sample response:
 }
 ```
 
+`turns_succeeded` is one per request; `turns` is not comparable to it on these
+sessions — the Claude CLI emits a `user` event per tool-result batch and `turns`
+counts those, so the gap above is tool use, not failures. Compare
+`turns_succeeded` against your own request count.
+
 The single most important field is **`cached_tokens`**. If it grows turn-over-turn, the persistent CLI is being reused and Anthropic prompt caching is warming. If it stays at 0, something is killing the session every turn — check that no client is sending `X-Session-Reset` unintentionally and that `OPENAI_COMPAT_NEW_CONVO_HEURISTIC` is not set when it shouldn't be.
 
 ## Smoke tests

package/skills/references/sessions.md

@@ -138,6 +138,29 @@ tokens the session has been billed for in total, which only ever grows.
 (`codex`, `agy`, `cursor`, `opencode`); those sessions log a warning the first
 time it is called.
 
+`stats.turns` and `stats.turnsSucceeded` are the same kind of distinction.
+`turns` counts turns that reached the engine, whatever their outcome, including
+the ones that then failed. `turnsSucceeded` counts only the ones the engine
+reported as successful, and it is one per send on every engine.
+
+**The two are only comparable on the one-shot engines.** There `turns` is also
+one per send, so the difference between them is the failure count. On `claude`
+and a persistent `custom`, `turns` counts `user` events — and the CLI emits one
+per tool-result batch as well as the prompt echo, so a send that used eight tools
+counts nine. Compare `turnsSucceeded` against the number of sends there, never
+against `turns`.
+
+Which outcome counts as a success is the engine's own verdict, not the exit
+code's: `codex` fails a turn that emits `turn.failed` while exiting 0, `agy`
+requires a `SUCCESS` status *and* a zero exit (it can report success and then die
+in cleanup), `gemini` succeeds on exit 53 because its turn limit resolves,
+`codex-app` requires `status: 'completed'` so a turn cancelled through
+`interrupt()` does not count, and `opencode` refuses a turn on purpose when
+read-only enforcement did not load.
+
+The run ledger's `ok` reads this same counter, so a turn cannot be a failure on
+`/v1/sessions` and a success in `clawo runs`.
+
 ### Cost Tracking
 
 ```typescript