@enderfga/claw-orchestrator 5.1.0 → 6.0.1

package/skills/references/multi-engine.md

@@ -39,6 +39,7 @@ Default engine. Long-running subprocess with streaming JSON I/O. Tested with Cla
 - Fork subagent (`forkSubagent`), tool search (`enableToolSearch`), OpenTelemetry logging toggles (`otelLogUserPrompts`, `otelLogRawApiBodies`), `xhigh` effort tier (Opus 4.7), and `stats.pluginErrors` capture — see [CLI 2.1.121 options in SKILL.md](../SKILL.md) and [tools.md](./tools.md)
 
 > **Behavior changes from upstream Claude CLI 2.1.121** (worth knowing if you set permission rules):
+>
 > - `--agent` / `--print` now enforce agent frontmatter `permissionMode`, `tools`, `disallowedTools` (was advisory). Affects `council` agent personas.
 > - `Bash(find:*)` permission rule no longer auto-approves `find -exec` or `find -delete`. Add explicit rules if you depend on these.
 > - `--dangerously-skip-permissions` also skips prompts for `.claude/skills/` directory. Treat with care.
@@ -47,7 +48,7 @@ Default engine. Long-running subprocess with streaming JSON I/O. Tested with Cla
 ```typescript
 await manager.startSession({
   name: 'claude-task',
-  engine: 'claude',       // default, can omit
+  engine: 'claude', // default, can omit
   model: 'opus',
   cwd: '/project',
 });
@@ -140,6 +141,7 @@ in print mode. Verified against `agy` **1.1.13**.
   `gemini-3.1-pro has no "medium" effort (available: low, high)`. The adapter
   passes the requested effort through rather than substituting a tier the caller
   did not ask for; run `agy models` to see the tiers a slug actually exposes.
+
 - Permission modes: `bypassPermissions` → `--dangerously-skip-permissions`,
   `default` → `--sandbox` (terminal-restricted), and
   `sandboxMode: 'read-only'` → `--mode plan` (takes precedence). Other modes
@@ -325,12 +327,12 @@ is not the answer on every engine. See "Stats & Monitoring" in `sessions.md`.
 
 Team tools (`team_list`, `team_send`) operate on the same virtual-team layer for **every** engine: the "team" is the set of all active sessions managed by SessionManager.
 
-| Engine | `team_list` | `team_send` |
-|--------|------------|-------------|
-| Claude | Lists other active SessionManager sessions | Routes via cross-session inbox |
-| Codex | Lists other active SessionManager sessions | Routes via cross-session inbox |
+| Engine      | `team_list`                                | `team_send`                    |
+| ----------- | ------------------------------------------ | ------------------------------ |
+| Claude      | Lists other active SessionManager sessions | Routes via cross-session inbox |
+| Codex       | Lists other active SessionManager sessions | Routes via cross-session inbox |
 | Antigravity | Lists other active SessionManager sessions | Routes via cross-session inbox |
-| Cursor | Lists other active SessionManager sessions | Routes via cross-session inbox |
+| Cursor      | Lists other active SessionManager sessions | Routes via cross-session inbox |
 
 Messages are delivered via the inbox system — idle sessions receive immediately, busy sessions queue for later delivery.
 
@@ -349,12 +351,13 @@ If OpenClaw gateway is running, everything is automatic:
 await manager.startSession({
   name: 'task',
   engine: 'claude',
-  model: 'openclaw',        // gateway routes to your configured model
+  model: 'openclaw', // gateway routes to your configured model
   cwd: '/project',
 });
 ```
 
 What happens behind the scenes:
+
 1. Plugin reads `~/.openclaw/openclaw.json` for gateway port + auth
 2. Starts a local proxy server (random port, auto-managed)
 3. Claude Code CLI sends Anthropic-format requests → proxy converts to OpenAI → gateway → any model
@@ -363,12 +366,12 @@ What happens behind the scenes:
 
 Override with environment variables if needed:
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `GATEWAY_URL` | Auto-detected from openclaw.json | Gateway endpoint (e.g. `http://127.0.0.1:18789/v1`) |
-| `GATEWAY_KEY` | Auto-detected from openclaw.json | Gateway auth password/token |
-| `GEMINI_API_KEY` | - | Direct Gemini API access (bypasses gateway) |
-| `OPENAI_API_KEY` | - | Direct OpenAI API access (bypasses gateway) |
+| Variable         | Default                          | Description                                         |
+| ---------------- | -------------------------------- | --------------------------------------------------- |
+| `GATEWAY_URL`    | Auto-detected from openclaw.json | Gateway endpoint (e.g. `http://127.0.0.1:18789/v1`) |
+| `GATEWAY_KEY`    | Auto-detected from openclaw.json | Gateway auth password/token                         |
+| `GEMINI_API_KEY` | -                                | Direct Gemini API access (bypasses gateway)         |
+| `OPENAI_API_KEY` | -                                | Direct OpenAI API access (bypasses gateway)         |
 
 ### Architecture
 
@@ -384,46 +387,47 @@ Claude Code CLI (Anthropic format)
 Integrate **any** coding agent CLI without writing engine-specific code. You provide a `CustomEngineConfig` that maps your CLI's flags to OpenClaw session concepts.
 
 Two protocol modes:
+
 - **Persistent** (`persistent: true`) — long-running subprocess with stream-json I/O over stdin/stdout (like Claude Code)
 - **One-shot** (`persistent: false`, default) — new process spawned per `send()` (like Codex/Antigravity)
 
 ### CustomEngineConfig
 
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `name` | string | yes | Display name (used in logs, session IDs) |
-| `bin` | string | yes | Binary path or command name |
-| `binEnv` | string | | Env var name that overrides `bin` at runtime |
-| `persistent` | boolean | | `true` = persistent subprocess, `false` = one-shot (default) |
-| `args` | object | yes | CLI flag mappings (see below) |
-| `permissionModes` | object | | Maps OpenClaw mode names to CLI-specific values |
-| `pricing` | object | | `{ input, output, cached? }` per 1M tokens |
-| `contextWindow` | number | | Context window size (default: 200,000) |
-| `env` | object | | Extra environment variables for the CLI process |
-| `sanitizePatterns` | string[] | | Regex patterns to redact from stderr |
+| Field              | Type     | Required | Description                                                  |
+| ------------------ | -------- | -------- | ------------------------------------------------------------ |
+| `name`             | string   | yes      | Display name (used in logs, session IDs)                     |
+| `bin`              | string   | yes      | Binary path or command name                                  |
+| `binEnv`           | string   |          | Env var name that overrides `bin` at runtime                 |
+| `persistent`       | boolean  |          | `true` = persistent subprocess, `false` = one-shot (default) |
+| `args`             | object   | yes      | CLI flag mappings (see below)                                |
+| `permissionModes`  | object   |          | Maps OpenClaw mode names to CLI-specific values              |
+| `pricing`          | object   |          | `{ input, output, cached? }` per 1M tokens                   |
+| `contextWindow`    | number   |          | Context window size (default: 200,000)                       |
+| `env`              | object   |          | Extra environment variables for the CLI process              |
+| `sanitizePatterns` | string[] |          | Regex patterns to redact from stderr                         |
 
 ### args field
 
-| Key | Example | Description |
-|-----|---------|-------------|
-| `print` | `"-p"` | Non-interactive/print mode flag |
-| `outputFormat` | `"--output-format"` | Output format flag |
-| `outputFormatValue` | `"stream-json"` | Value for stream-json output |
-| `inputFormat` | `"--input-format"` | Input format flag (persistent only) |
-| `inputFormatValue` | `"stream-json"` | Value for stream-json input |
-| `skipPermissions` | `"-y"` | Skip all permissions flag |
-| `permissionMode` | `"--permission-mode"` | Permission mode flag |
-| `model` | `"--model"` | Model selection flag |
-| `systemPrompt` | `"--system-prompt"` | System prompt override flag |
-| `appendSystemPrompt` | `"--append-system-prompt"` | Append system prompt flag |
-| `maxTurns` | `"--max-turns"` | Max agent turns flag |
-| `resume` | `"--resume"` | Session resume flag (persistent only) |
-| `verbose` | `"--verbose"` | Verbose output flag |
-| `replayUserMessages` | `"--replay-user-messages"` | Replay user messages (persistent only) |
+| Key                      | Example                        | Description                                |
+| ------------------------ | ------------------------------ | ------------------------------------------ |
+| `print`                  | `"-p"`                         | Non-interactive/print mode flag            |
+| `outputFormat`           | `"--output-format"`            | Output format flag                         |
+| `outputFormatValue`      | `"stream-json"`                | Value for stream-json output               |
+| `inputFormat`            | `"--input-format"`             | Input format flag (persistent only)        |
+| `inputFormatValue`       | `"stream-json"`                | Value for stream-json input                |
+| `skipPermissions`        | `"-y"`                         | Skip all permissions flag                  |
+| `permissionMode`         | `"--permission-mode"`          | Permission mode flag                       |
+| `model`                  | `"--model"`                    | Model selection flag                       |
+| `systemPrompt`           | `"--system-prompt"`            | System prompt override flag                |
+| `appendSystemPrompt`     | `"--append-system-prompt"`     | Append system prompt flag                  |
+| `maxTurns`               | `"--max-turns"`                | Max agent turns flag                       |
+| `resume`                 | `"--resume"`                   | Session resume flag (persistent only)      |
+| `verbose`                | `"--verbose"`                  | Verbose output flag                        |
+| `replayUserMessages`     | `"--replay-user-messages"`     | Replay user messages (persistent only)     |
 | `includePartialMessages` | `"--include-partial-messages"` | Include partial messages (persistent only) |
-| `effort` | `"--effort"` | Effort level flag |
-| `workspace` | `"--workspace"` | Workspace/cwd flag (one-shot only) |
-| `extra` | `["--trust"]` | Additional static arguments |
+| `effort`                 | `"--effort"`                   | Effort level flag                          |
+| `workspace`              | `"--workspace"`                | Workspace/cwd flag (one-shot only)         |
+| `extra`                  | `["--trust"]`                  | Additional static arguments                |
 
 ### Example: Persistent mode (Claude Code-compatible CLI)
 
@@ -471,7 +475,7 @@ await manager.startSession({
   customEngine: {
     name: 'simple-agent',
     bin: '/usr/local/bin/simple-agent',
-    persistent: false,  // default
+    persistent: false, // default
     args: {
       print: '-p',
       outputFormat: '--output-format',
@@ -505,11 +509,11 @@ await manager.startSession({
   dangerouslySkipPermissions: true,
   customEngine: {
     name: 'antigravity',
-    bin: 'agy',           // install: curl -fsSL https://antigravity.google/cli/install.sh | bash
+    bin: 'agy', // install: curl -fsSL https://antigravity.google/cli/install.sh | bash
     binEnv: 'AGY_BIN',
     persistent: false,
     args: {
-      print: '-p',                                  // single-prompt headless mode
+      print: '-p', // single-prompt headless mode
       skipPermissions: '--dangerously-skip-permissions',
       workspace: '--add-dir',
       // NOTE: agy 1.0.2 has NO --output-format flag — output is plain text only.

package/skills/references/observability.md

@@ -30,22 +30,22 @@ every engine passes through.
 
 ### Row schema
 
-| Field | Meaning |
-|---|---|
-| `ts` | ISO timestamp of turn completion |
-| `session` | SessionManager session name |
-| `engine` | `claude` / `codex` / `codex-app` / `grok` / `opencode` / `agy` / `custom` |
-| `model` | Configured model, or the engine's own reported model when none was set |
-| `cwd` | Working directory the turn ran in |
-| `turn` | 1-based turn index within the session |
-| `tokensIn` / `tokensOut` / `cachedTokens` | **Per-turn deltas**, not session totals |
-| `costUsd` | Per-turn delta in USD |
-| `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 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 |
+| Field                                     | Meaning                                                                                                                                                                                          |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `ts`                                      | ISO timestamp of turn completion                                                                                                                                                                 |
+| `session`                                 | SessionManager session name                                                                                                                                                                      |
+| `engine`                                  | `claude` / `codex` / `codex-app` / `grok` / `opencode` / `agy` / `custom`                                                                                                                        |
+| `model`                                   | Configured model, or the engine's own reported model when none was set                                                                                                                           |
+| `cwd`                                     | Working directory the turn ran in                                                                                                                                                                |
+| `turn`                                    | 1-based turn index within the session                                                                                                                                                            |
+| `tokensIn` / `tokensOut` / `cachedTokens` | **Per-turn deltas**, not session totals                                                                                                                                                          |
+| `costUsd`                                 | Per-turn delta in USD — token count × the registry rate. On a flat-rate plan (a subscription seat) nobody was billed this: set `pricingOverrides` in the plugin config to zero the model out (`{"gpt-5.5": {"input": 0, "output": 0, "cached": 0}}`). Read [Zeroing a model's pricing](#zeroing-a-models-pricing) first — it disables `maxBudgetUsd` for that model, except on `grok`, which prices itself |
+| `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 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
 without double-counting.
@@ -98,11 +98,38 @@ Notes:
 - The check is "has the cap been reached", not "would this turn exceed it" — a
   turn's cost is unknown until it finishes, so the last allowed turn can overshoot.
   Size the cap accordingly.
-- A cap of `0` or a negative number means *unset*, not *refuse everything*.
+- A cap of `0` or a negative number means _unset_, not _refuse everything_.
 - Claude Code still receives `--max-budget-usd` as well: an in-CLI stop happens
   earlier and therefore costs less than an after-the-fact refusal.
 - `session_list` / `GET /session/list` expose `costUsd`, `budgetUsd` and
-  `budgetExhausted` so a stalled session shows *why* it stopped taking turns.
+  `budgetExhausted` so a stalled session shows _why_ it stopped taking turns.
+
+### Zeroing a model's pricing
+
+`pricingOverrides` zeroes the fiction that a subscription seat gets billed per token, and
+the cost figures above stop reporting money nobody paid. It also **disables `maxBudgetUsd`
+for that model**: the cap compares the session's accrued `getCost().totalUsd` against it,
+and that number is pricing-derived, so at a rate of 0 it never reaches any cap. There is
+no separate token or turn ceiling behind it.
+
+- `engine: 'claude'` keeps the CLI's own `--max-budget-usd`, which the CLI accounts itself
+  and which a zeroed registry rate does not touch. `engine: 'grok'` is outside this for a
+  different reason: it writes the engine's own `total_cost_usd` into `_stats.costUsd` and
+  never consults the registry, so zeroing a model's pricing does not disable its cap.
+  For codex, cursor, agy, opencode and custom the runtime check is the only one.
+- `maxTurns` (and `maxRounds` on a council) still bound the work, and they are the right
+  ceiling to reach for once a model prices at 0.
+- In a council the cap cannot bite before an agent's second turn in any case: the first
+  enters with nothing accrued, and one `sendMessage` runs up to `maxTurnsPerAgent` turns
+  inside the CLI, so it can pass the whole cap on its own.
+- `cursor` and `opencode` sessions started without a model price by their engine default,
+  which is `claude-sonnet-4-6` for both. Zeroing a Claude subscription therefore zeroes
+  those default sessions too, and their reported ids (`cursor-default`, `opencode-default`)
+  are display names that cannot themselves be overridden.
+
+The override is read once, in the `SessionManager` constructor, from the plugin config.
+`clawo serve`, `clawo-acp` and `clawo-mcp` do not pass one, so a ledger written by those
+processes prices at registry rates whichever way this is set.
 
 ## Accuracy: which engines report real usage
 
@@ -111,16 +138,16 @@ Where the engine reports usage, those counts are the engine's own. Where it does
 not, the wrapper falls back to `estimateTokens()` (characters ÷ 4) and the row is
 flagged `tokensEstimated: true`; the CLI marks those costs with a trailing `~`.
 
-| Engine | Token counts |
-|---|---|
-| `claude` | Engine-reported |
-| `codex` | Engine-reported |
-| `codex-app` | Engine-reported |
-| `grok` | Engine-reported — and so is the **cost**: this engine reports `total_cost_usd`, which the wrapper passes through instead of pricing tokens from the registry, so registry drift cannot affect a grok row |
-| `cursor` (legacy) | Engine-reported when the stream carries `usage`, else estimated |
-| `opencode` | Engine-reported when the run JSON carries `tokens`, else estimated |
-| `agy` | Engine-reported when the result event carries usage, else estimated |
-| `custom` | Depends on the CLI; estimated when it emits no usage |
+| Engine            | Token counts                                                                                                                                                                                             |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `claude`          | Engine-reported                                                                                                                                                                                          |
+| `codex`           | Engine-reported                                                                                                                                                                                          |
+| `codex-app`       | Engine-reported                                                                                                                                                                                          |
+| `grok`            | Engine-reported — and so is the **cost**: this engine reports `total_cost_usd`, which the wrapper passes through instead of pricing tokens from the registry, so registry drift cannot affect a grok row |
+| `cursor` (legacy) | Engine-reported when the stream carries `usage`, else estimated                                                                                                                                          |
+| `opencode`        | Engine-reported when the run JSON carries `tokens`, else estimated                                                                                                                                       |
+| `agy`             | Engine-reported when the result event carries usage, else estimated                                                                                                                                      |
+| `custom`          | Depends on the CLI; estimated when it emits no usage                                                                                                                                                     |
 
 So on an estimating engine the cap is best-effort. It will stop a runaway session;
 it is not an accounting guarantee, and it is not a substitute for the spend limits
@@ -130,3 +157,63 @@ Cost figures are also only as good as the pricing table: a model missing from
 `models.ts` prices at its family default, and subscription plans (Claude Max,
 ChatGPT Pro) bill nothing per token while the ledger still reports the API-rate
 equivalent. Read `costUsd` as "what this would cost at API rates".
+
+## `ok` vs `verified` (6.0.0)
+
+A row now carries two different judgements, and conflating them is the mistake
+this section exists to prevent.
+
+- **`ok`** — the engine's own terminal verdict for that turn. Codex fails a turn
+  that emits `turn.failed` while exiting 0; gemini succeeds on exit 53. It is a
+  careful signal, but it is the engine talking about itself.
+- **`verified`** — an acceptance contract ran against the work and every required
+  check passed. That is the runtime's own measurement.
+
+Three states, not two:
+
+| `verified` | Means                                               | CLI column |
+| ---------- | --------------------------------------------------- | ---------- |
+| `true`     | A contract ran and passed                           | `yes`      |
+| `false`    | A contract ran and a required check failed          | `NO`       |
+| absent     | **No contract was declared. Nothing checked this.** | `—`        |
+
+Absent is not false. An unchecked run is not a failed one, and reading it as
+either would make the ledger useless for the thing it is for.
+
+### Where the verdict comes from
+
+`verified` is **not written at turn time**, deliberately. The turns that produce
+the work all finish before the verifier that judges it, so stamping a verdict on
+them as they are written would be inventing one. It is joined in at read time
+from the run record via the row's `parent`, by `annotateVerdicts()`.
+
+Two consequences worth knowing:
+
+- A raw `runs/*.jsonl` line usually has no `verified` field. Read through
+  `clawo runs` / `GET /runs` / `getRunLedger()` to get the join.
+- Filtering on `--verified` happens _after_ the join. Pushing the filter into the
+  ledger read would match on a field no row carries yet and return nothing.
+
+### Other new row fields
+
+| Field                      | Source                                                                                                                                                          |
+| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `evidenceId`, `contractId` | Joined from the run record                                                                                                                                      |
+| `nodeKind`                 | The kernel node the turn belonged to (`agent`, `council`, `verifier`, …)                                                                                        |
+| `repoLang`                 | Detected from a manifest (`package.json`, `pyproject.toml`, `go.mod`, …). Never guessed — a wrong label would corrupt the comparison the field exists to enable |
+| `taskKind`                 | Caller-declared only. Never inferred from the prompt                                                                                                            |
+
+All are optional and absent on rows written before 6.0.0. The reader already
+skips unknown and missing keys, so old shards stay readable; nothing backfills
+them, because we cannot know retroactively.
+
+```bash
+clawo runs --since 7d --verified     # only turns whose contract passed
+clawo runs --since 7d --refuted      # only turns whose contract failed
+clawo runs --parent wf-abc123        # every turn of one workflow run
+```
+
+## Related
+
+- [`verification.md`](./verification.md) — what a contract is and how a verdict is produced
+- [`workflow.md`](./workflow.md) — where run records live

package/skills/references/openai-compat.md

@@ -11,13 +11,13 @@ Both modes share the same wire protocol; the difference is how a "new conversati
 
 ## Endpoint
 
-| | |
-|---|---|
-| **URL** | `http://127.0.0.1:18796/v1/chat/completions` |
-| **Models endpoint** | `GET /v1/models` |
-| **Inspection endpoint** | `GET /v1/sessions` (lists active openai-compat sessions with caching stats) |
-| **Auth** | Bearer token via `Authorization: Bearer $OPENCLAW_SERVER_TOKEN` (set the env var to enable; otherwise no auth and the server is loopback-only) |
-| **Wire format** | OpenAI Chat Completions, both streaming (SSE) and non-streaming |
+|                         |                                                                                                                                                |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| **URL**                 | `http://127.0.0.1:18796/v1/chat/completions`                                                                                                   |
+| **Models endpoint**     | `GET /v1/models`                                                                                                                               |
+| **Inspection endpoint** | `GET /v1/sessions` (lists active openai-compat sessions with caching stats)                                                                    |
+| **Auth**                | Bearer token via `Authorization: Bearer $OPENCLAW_SERVER_TOKEN` (set the env var to enable; otherwise no auth and the server is loopback-only) |
+| **Wire format**         | OpenAI Chat Completions, both streaming (SSE) and non-streaming                                                                                |
 
 ## Session keying
 
@@ -56,20 +56,20 @@ Without this flag, those frontends would silently continue the previous CLI sess
 
 The env var is read on every request, so ops can flip it via `launchctl setenv` (or equivalent) without restarting the server.
 
-| Mode | Best for | New-conversation signals |
-|---|---|---|
-| **Default** | OpenClaw main agent, cron jobs, subagents, scripted clients | `X-Session-Reset: 1` only |
+| Mode              | Best for                                                    | New-conversation signals                            |
+| ----------------- | ----------------------------------------------------------- | --------------------------------------------------- |
+| **Default**       | OpenClaw main agent, cron jobs, subagents, scripted clients | `X-Session-Reset: 1` only                           |
 | **`HEURISTIC=1`** | ChatGPT-Next-Web, Open WebUI, LobeChat, data labeling tools | `X-Session-Reset: 1` **and** `[system, user]` shape |
 
 ## Status webhook
 
 When `OPENAI_COMPAT_STATUS_URL` is set (full HTTP URL), each chat completion sends best-effort `POST` requests with `Content-Type: application/json` and body:
 
-| Field | Type | Meaning |
-|---|---|---|
-| `state` | string | `thinking` (turn started), `working` (a tool is running), or `idle` (turn finished or stream closed). |
-| `activity` | string | Short human-readable line, e.g. `Processing request...`, `Reading: foo.ts`, `Running: npm test...`. |
-| `tool` | string \| null | Tool name when `state === working`, otherwise `null`. |
+| Field      | Type           | Meaning                                                                                               |
+| ---------- | -------------- | ----------------------------------------------------------------------------------------------------- |
+| `state`    | string         | `thinking` (turn started), `working` (a tool is running), or `idle` (turn finished or stream closed). |
+| `activity` | string         | Short human-readable line, e.g. `Processing request...`, `Reading: foo.ts`, `Running: npm test...`.   |
+| `tool`     | string \| null | Tool name when `state === working`, otherwise `null`.                                                 |
 
 Failures are ignored (no retries). Use this from a small local HTTP handler that forwards status into your webchat UI.
 
@@ -78,17 +78,17 @@ Failures are ignored (no retries). Use this from a small local HTTP handler that
 When the request carries `tools`, the schemas have to reach the CLI somehow. Which
 mechanism is used depends on whether the engine keeps the conversation itself.
 
-| Engine | Turn 1 | Later turns |
-|---|---|---|
-| `claude` | Schemas go into the session system prompt (`--system-prompt`) | Nothing injected — the system prompt persists |
-| `codex`, `codex-app`, `agy`, `opencode`, `grok` | Full schema block prepended to the message | A short reminder of the calling convention, no schemas — but only once the conversation id has been captured; until then the full block is sent again |
-| `gemini`, one-shot `custom` | Full schema block prepended to the message | Full schema block again — these have no resume surface, so nothing persists between sends |
+| Engine                                          | Turn 1                                                        | Later turns                                                                                                                                           |
+| ----------------------------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `claude`                                        | Schemas go into the session system prompt (`--system-prompt`) | Nothing injected — the system prompt persists                                                                                                         |
+| `codex`, `codex-app`, `agy`, `opencode`, `grok` | Full schema block prepended to the message                    | A short reminder of the calling convention, no schemas — but only once the conversation id has been captured; until then the full block is sent again |
+| `gemini`, one-shot `custom`                     | Full schema block prepended to the message                    | Full schema block again — these have no resume surface, so nothing persists between sends                                                             |
 
 The middle row is the one worth understanding. Those engines resume a conversation by id, so
 everything injected stays in the transcript. Re-sending the full block each turn
 grows the prompt without bound — a 54-tool block runs to roughly 17k tokens, so a
 handful of turns is enough to overflow the context window mid-loop and fail the
-run outright. Sending *nothing* on resume turns is not the answer either: the
+run outright. Sending _nothing_ on resume turns is not the answer either: the
 block also carries the "emit a tool call, do not carry out the work yourself"
 framing, and without it the CLI starts doing the work directly.
 
@@ -116,16 +116,16 @@ does change mid-conversation.
 
 ## Environment variables
 
-| Variable | Default | Purpose |
-|---|---|---|
-| `OPENCLAW_SERVER_TOKEN` | (unset) | Bearer token for HTTP auth. Set to enable; written to `~/.openclaw/server-token` for the CLI. |
-| `OPENCLAW_RATE_LIMIT` | `300` | Max requests per IP per 60-second sliding window. |
-| `OPENCLAW_CORS_ORIGINS` | (loopback only) | Set to `*` to allow all origins (the `/v1/*` paths already do this). |
-| `OPENAI_COMPAT_NEW_CONVO_HEURISTIC` | (unset) | Set to `1` to enable webchat mode (see above). |
-| `OPENAI_COMPAT_TOOLS_PER_MESSAGE` | (unset) | Set to `1` to re-send the full tool schemas on every turn (see [Tool definitions](#tool-definitions-and-where-they-live)). Needed only when the tool set changes mid-conversation; costs per-turn prompt growth. |
-| `OPENAI_COMPAT_STATUS_URL` | (unset) | If set, the bridge POSTs JSON status updates to this URL (fire-and-forget, 2s timeout). See [Status webhook](#status-webhook). |
-| `OPENCLAW_SERVE_MAX_SESSIONS` | `32` | Max concurrent OpenAI-compat sessions in serve mode. Bumped from the in-plugin default of 5 because each distinct caller now gets its own `sys-<hash>` session. |
-| `OPENCLAW_SERVE_TTL_MINUTES` | `60` | Idle TTL for OpenAI-compat sessions in serve mode. Idle sessions are reaped by a 60s background loop; persisted disk registry is kept for 7 days so a returning caller is auto-resumed. |
+| Variable                            | Default         | Purpose                                                                                                                                                                                                          |
+| ----------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `OPENCLAW_SERVER_TOKEN`             | (unset)         | Bearer token for HTTP auth. Set to enable; written to `~/.openclaw/server-token` for the CLI.                                                                                                                    |
+| `OPENCLAW_RATE_LIMIT`               | `300`           | Max requests per IP per 60-second sliding window.                                                                                                                                                                |
+| `OPENCLAW_CORS_ORIGINS`             | (loopback only) | Set to `*` to allow all origins (the `/v1/*` paths already do this).                                                                                                                                             |
+| `OPENAI_COMPAT_NEW_CONVO_HEURISTIC` | (unset)         | Set to `1` to enable webchat mode (see above).                                                                                                                                                                   |
+| `OPENAI_COMPAT_TOOLS_PER_MESSAGE`   | (unset)         | Set to `1` to re-send the full tool schemas on every turn (see [Tool definitions](#tool-definitions-and-where-they-live)). Needed only when the tool set changes mid-conversation; costs per-turn prompt growth. |
+| `OPENAI_COMPAT_STATUS_URL`          | (unset)         | If set, the bridge POSTs JSON status updates to this URL (fire-and-forget, 2s timeout). See [Status webhook](#status-webhook).                                                                                   |
+| `OPENCLAW_SERVE_MAX_SESSIONS`       | `32`            | Max concurrent OpenAI-compat sessions in serve mode. Bumped from the in-plugin default of 5 because each distinct caller now gets its own `sys-<hash>` session.                                                  |
+| `OPENCLAW_SERVE_TTL_MINUTES`        | `60`            | Idle TTL for OpenAI-compat sessions in serve mode. Idle sessions are reaped by a 60s background loop; persisted disk registry is kept for 7 days so a returning caller is auto-resumed.                          |
 
 ## Inspection: `GET /v1/sessions`
 
@@ -235,14 +235,14 @@ Errors use the OpenAI error envelope:
 { "error": { "message": "...", "type": "invalid_request_error" } }
 ```
 
-| Status | When |
-|---|---|
-| 400 | `messages` empty/missing, no user message, invalid `max_tokens` |
-| 401 | Missing or wrong bearer token (when auth enabled) |
-| 415 | POST without `Content-Type: application/json` |
-| 429 | Rate limited (`OPENCLAW_RATE_LIMIT` exceeded) |
-| 503 | Failed to start a new session (model unavailable, CLI crashed at boot) |
-| 500 | Mid-turn failure |
+| Status | When                                                                   |
+| ------ | ---------------------------------------------------------------------- |
+| 400    | `messages` empty/missing, no user message, invalid `max_tokens`        |
+| 401    | Missing or wrong bearer token (when auth enabled)                      |
+| 415    | POST without `Content-Type: application/json`                          |
+| 429    | Rate limited (`OPENCLAW_RATE_LIMIT` exceeded)                          |
+| 503    | Failed to start a new session (model unavailable, CLI crashed at boot) |
+| 500    | Mid-turn failure                                                       |
 
 ## Related
 

package/skills/references/sessions.md

@@ -16,7 +16,7 @@ start() → send() → send() → ... → stop()
 const info = await manager.startSession({
   name: 'my-task',
   cwd: '/path/to/project',
-  model: 'opus',                    // alias or full name
+  model: 'opus', // alias or full name
   permissionMode: 'acceptEdits',
   effort: 'high',
   allowedTools: ['Bash', 'Read', 'Edit', 'Write'],
@@ -27,24 +27,24 @@ const info = await manager.startSession({
 
 Key options:
 
-| Option | Description |
-|--------|-------------|
-| `engine` | `'claude'` (default), `'codex'`, `'codex-app'`, `'agy'`, `'grok'`, `'opencode'`, or `'custom'` — see [Multi-Engine](./multi-engine.md) |
-| `model` | Model alias (`fable`, `opus`, `sonnet`, `haiku`, `agy-pro`) or full name |
-| `permissionMode` | `acceptEdits`, `bypassPermissions`, `plan`, `auto`, `manual`, `dontAsk` (`default` = legacy alias for `manual`) |
-| `effort` | `low`, `medium`, `high`, `max`, `auto` |
-| `bare` | Skip hooks, LSP, auto-memory, CLAUDE.md |
-| `worktree` | Run in isolated git worktree |
-| `appendSystemPrompt` | Append custom instructions to the system prompt |
+| Option               | Description                                                                                                                            |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `engine`             | `'claude'` (default), `'codex'`, `'codex-app'`, `'agy'`, `'grok'`, `'opencode'`, or `'custom'` — see [Multi-Engine](./multi-engine.md) |
+| `model`              | Model alias (`fable`, `opus`, `sonnet`, `haiku`, `agy-pro`) or full name                                                               |
+| `permissionMode`     | `acceptEdits`, `bypassPermissions`, `plan`, `auto`, `manual`, `dontAsk` (`default` = legacy alias for `manual`)                        |
+| `effort`             | `low`, `medium`, `high`, `max`, `auto`                                                                                                 |
+| `bare`               | Skip hooks, LSP, auto-memory, CLAUDE.md                                                                                                |
+| `worktree`           | Run in isolated git worktree                                                                                                           |
+| `appendSystemPrompt` | Append custom instructions to the system prompt                                                                                        |
 
 ### Sending Messages
 
 ```typescript
 const result = await manager.sendMessage('my-task', 'Fix the auth bug', {
-  effort: 'high',       // override effort for this message
-  plan: true,           // enter plan mode
-  timeout: 600_000,     // 10 min timeout
-  onChunk: (text) => process.stdout.write(text),  // streaming
+  effort: 'high', // override effort for this message
+  plan: true, // enter plan mode
+  timeout: 600_000, // 10 min timeout
+  onChunk: (text) => process.stdout.write(text), // streaming
 });
 
 console.log(result.output);
@@ -100,8 +100,8 @@ Mid-turn and thread control via Codex 0.137 v2 RPCs, surfaced as tools: `codex_i
 Switch models mid-conversation. The session restarts with `--resume` to preserve history:
 
 ```typescript
-await manager.switchModel('my-task', 'haiku');  // fast model for simple tasks
-await manager.switchModel('my-task', 'opus');   // back to powerful model
+await manager.switchModel('my-task', 'haiku'); // fast model for simple tasks
+await manager.switchModel('my-task', 'opus'); // back to powerful model
 ```
 
 ### Tool Management
@@ -111,11 +111,11 @@ Add/remove tool permissions at runtime:
 ```typescript
 await manager.updateTools('my-task', {
   allowedTools: ['Bash', 'Read'],
-  merge: true,                    // add to existing list
+  merge: true, // add to existing list
 });
 
 await manager.updateTools('my-task', {
-  removeTools: ['Bash'],          // revoke Bash access
+  removeTools: ['Bash'], // revoke Bash access
 });
 ```
 
@@ -152,7 +152,7 @@ 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
+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
@@ -207,15 +207,15 @@ Session stats are returned by `getStats()` and surfaced through `coding_session_
 
 Fields added in plugin v2.13.0 (Claude CLI 2.1.111):
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `retries` | number | Total API retries that occurred during the session |
-| `lastRetryError` | string \| undefined | Error message from the most recent retry (if any) |
+| Field            | Type                | Description                                        |
+| ---------------- | ------------------- | -------------------------------------------------- |
+| `retries`        | number              | Total API retries that occurred during the session |
+| `lastRetryError` | string \| undefined | Error message from the most recent retry (if any)  |
 
 Fields added in plugin v2.14.0 (Claude CLI 2.1.121):
 
-| Field | Type | Description |
-|-------|------|-------------|
+| Field          | Type                                   | Description                                                                                                                               |
+| -------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
 | `pluginErrors` | `Array<{plugin, reason}>` \| undefined | Plugins that failed to load due to unmet dependencies, captured from the `system/init` event. `undefined` when no plugin errors occurred. |
 
 ### `system/api_retry` events
@@ -238,3 +238,21 @@ All session engine classes expose an optional `pid` readonly property, providing
 const session = manager.getSession('my-session');
 console.log(session.pid); // e.g., 12345 or undefined
 ```
+
+## Verifying what a session did (6.0.0)
+
+A plain session leaves no verdict — it ran, and nothing checked the result. To
+check it, hand `verify_run` a contract and the directory:
+
+```jsonc
+verify_run({
+  cwd: "/repo",
+  contract: { checks: [{ type: "command", cmd: "npm", args: ["test"] }] }
+})
+```
+
+For work that should be checked as part of running it, use a workflow instead —
+see [`workflow.md`](./workflow.md).
+
+`SendOptions` also gained `nodeKind` and `taskKind`, both stamped onto the run
+ledger row. `taskKind` is caller-declared and never inferred from the prompt.