docs: correct current provider and planning semantics

AGENTS.md

@@ -10,7 +10,7 @@ These instructions apply throughout the repository.
 - The only agent world actions are adjacent move, infect current cell, capture an abandoned infected current cell from a non-allied controller, and wait. Nothing accompanies that action: there is no agent communication and no diplomacy intent.
 - Infection and agent position are independent. Movement does not remove infection.
 - Full agent visibility is deliberate. Do not add fog of war, detection, scanners, or last-known positions.
-- Zero swarm (`zero-swarm-v1`) is the sole cognition architecture: one Agent Zero planning call per tick regardless of roster size, issuing structured directives that TypeSafe Jev reflex workers resolve. Do not reintroduce a second cognition architecture or a mode switch between them. The deterministic-worker path is an ablation control for the comparison CLIs, not a second production architecture.
+- Zero swarm (`zero-swarm-v1`) is the sole cognition architecture: Agent Zero makes an OpenRouter planning call only when strategic replanning is required, issuing structured directives that TypeSafe Jev reflex workers resolve each tick. Do not reintroduce a second cognition architecture or a mode switch between them. The deterministic-worker path is an ablation control for the comparison CLIs, not a second production architecture.
 - Agent personalities, agent-to-agent communication, formal alliances and diplomacy, per-worker goals, and prose memories were removed by the zero-swarm migration and are not deferred features. Do not reintroduce them. See `docs/adr/0033-retire-legacy-multi-agent-architecture.md`.
 - Do not add leaders, voting, kicking, merging, ranks, shared ownership, resources, inventory, structures, combat, terrain bonuses, crafting, accounts, GPS validation, player progression, or mobile packaging before the roadmap calls for them.
 

README.md

@@ -2,32 +2,32 @@
 
 Hex Zero is an agent-first geographic experiment. A configurable roster of model-backed agents moves, infects, and captures territory on a real H3 map while the World Lab exposes every safe decision record. Full agent visibility is deliberate; there is no fog of war.
 
-`zero-swarm-v1` is the sole cognition architecture. One OpenRouter generative planner, Agent Zero, makes one planning call per tick regardless of roster size, under the versioned contract `swarm-planner-v1`. Each plan carries a strategy summary and a per-worker directive set. Worker nodes resolve their directives with TypeSafe Jev reflex cognition, choosing among enumerated `action_N` candidates with a probability distribution and a confidence value, over the deterministic H3 world engine.
+`zero-swarm-v1` is the sole cognition architecture. Workers make reflex decisions each active worker tick. Agent Zero makes one OpenRouter planning call only when strategic replanning is required (for example, after roster changes, directive completions, or elevated pressure), under the versioned contract `swarm-planner-v1`; otherwise the last valid directive set is reused with no planner call. Each plan carries a strategy summary and a per-worker directive set. Worker nodes resolve their directives with TypeSafe Jev reflex cognition, choosing among enumerated `action_N` candidates with a probability distribution and a confidence value, over the deterministic H3 world engine.
 
 Directives carry: identifier, agent identifier, mission (`expand` | `hold` | `relocate` | `reinforce` | `evade`), a nullable target cell, priority (`low` | `normal` | `high`), risk tolerance (`low` | `medium` | `high`), issue and expiry ticks, and an optional note of at most 160 characters. When no replan is triggered, the previous plan's directives are reused without a planning call. Replans are triggered by: `initial`, `periodic-review`, `directive-complete`, `directive-expired`, `worker-request`, `worker-stalled`, `territory-loss`, `high-pressure`, `player-disinfection`, and `roster-changed`.
 
-Cognition sources are `zero-llm` (Agent Zero via OpenRouter), `jev-reflex` (TypeSafe Jev via OpenRouter), and `deterministic-fallback`. The deterministic-worker baseline—workers that resolve directives without a model call—is retained as the ablation control that isolates what Jev's reflex calls contribute, not as a second production architecture.
+Cognition sources are `zero-llm` (Agent Zero via OpenRouter), `jev-reflex` (TypeSafe Jev via the TypeSafe API), and `deterministic-fallback`. Routing summary: Agent Zero → OpenRouter; Workers → TypeSafe Jev API. The deterministic-worker baseline—workers that resolve directives without a model call—is retained as the ablation control that isolates what Jev's reflex calls contribute, not as a second production architecture.
 
 The capability-gated objective version is `durable-influence-v3`. Without simulated-player pressure, scenarios use a `durable-influence-v2`-compatible objective.
 
 ## Workspace
 
-| Path                          | Responsibility                                                   |
-| ----------------------------- | ---------------------------------------------------------------- |
-| `apps/world-lab`              | Next.js developer/admin map, controls, inspector, and event log  |
-| `apps/game-api`               | Hono HTTP boundary and in-memory simulation service              |
-| `packages/world-engine`       | Pure world validation and consequence application                |
-| `packages/agent-runtime`      | OpenRouter provider boundary and explicit scripted testing seams |
-| `packages/shared`             | Runtime-validated schemas and inferred domain types              |
-| `packages/experiment-archive` | Durable SQLite imports and bounded research queries              |
+| Path                          | Responsibility                                                                              |
+| ----------------------------- | ------------------------------------------------------------------------------------------- |
+| `apps/world-lab`              | Next.js developer/admin map, controls, inspector, and event log                             |
+| `apps/game-api`               | Hono HTTP boundary and in-memory simulation service                                         |
+| `packages/world-engine`       | Pure world validation and consequence application                                           |
+| `packages/agent-runtime`      | OpenRouter planner, TypeSafe Jev reflex provider, model catalog, and scripted testing seams |
+| `packages/shared`             | Runtime-validated schemas and inferred domain types                                         |
+| `packages/experiment-archive` | Durable SQLite imports and bounded research queries                                         |
 
 ## Local development
 
 Requirements are Node.js 24.18.0 and pnpm 11.21.0. Copy the example environment file to the repository-root `.env`, replace only the placeholder key, install dependencies, and start both applications:
 
 ```bash
 cp .env.example .env
-# Edit .env and set OPENROUTER_API_KEY.
+# Edit .env and set OPENROUTER_API_KEY and TYPESAFE_API_KEY.
 corepack enable
 pnpm install --frozen-lockfile
 pnpm dev
@@ -37,9 +37,9 @@ For deterministic local automation, `pnpm dev:test-provider` sets
 `HEXZERO_PROVIDER=scripted`. `HEXZERO_EXPERIMENT_DB` overrides the local
 experiment archive path.
 
-Open the World Lab at <http://localhost:3000>. The Game API binds to <http://127.0.0.1:8787>; Next.js narrowly proxies `/api/game/*` to it. `OPENROUTER_API_KEY` is the only required OpenRouter environment value. Select a compatible model for Agent Zero in World Lab. Each assignment may use the provider's default reasoning behavior, disable optional reasoning, or select only an effort advertised by that model's catalog metadata. The Jev worker model is pinned server-side and shown as system information.
+Open the World Lab at <http://localhost:3000>. The Game API binds to <http://127.0.0.1:8787>; Next.js narrowly proxies `/api/game/*` to it. `OPENROUTER_API_KEY` (Agent Zero) and `TYPESAFE_API_KEY` (Jev workers) are both required for real runs. Select a compatible model for Agent Zero in World Lab. Each assignment may use the provider's default reasoning behavior, disable optional reasoning, or select only an effort advertised by that model's catalog metadata. The Jev worker model is pinned server-side and shown as system information.
 
-Each tick makes one Agent Zero planning call and one Jev reflex call per active worker; each call may incur an initial third-party OpenRouter charge plus at most one in-deadline repair or transient-retry charge. All workers observe the same frozen pre-tick world; valid decisions resolve together while an individual provider failure is retained as that worker's final lost tick. Start is deliberately disabled when the server has no key. This development API has no authentication or provider-account balance enforcement. Its experiment-scoped attempt and credit-admission limits are operator safeguards, not an upstream billing guarantee, so it is not suitable for unauthenticated public deployment.
+Each tick makes one Jev reflex call per active worker; an Agent Zero planning call is made only when strategic replanning is required and may incur an OpenRouter charge plus at most one in-deadline repair or transient-retry charge. TypeSafe monetary cost is not reported. All workers observe the same frozen pre-tick world; valid decisions resolve together while an individual provider failure is retained as that worker's final lost tick. Start is deliberately disabled when the server has no key. This development API has no authentication or provider-account balance enforcement. Its experiment-scoped attempt and credit-admission limits are operator safeguards, not an upstream billing guarantee, so it is not suitable for unauthenticated public deployment.
 
 State is held only in the Game API process. The API captures one active safe experiment with bounded complete tick groups while the browser snapshot remains bounded without splitting a tick. The sole export format is schema version 12, which carries `swarmArchitectureVersion: 'zero-swarm-v1'`, an independent safe bounded provider-attempt ledger including work that did not produce a committed turn, and tick attribution. Pre-swarm exports (schema versions 9–11) are not readable by current code; inspecting them requires checking out a Git revision predating the zero-swarm migration. The Agent Zero model assignment and reasoning profile may be changed between ticks. A saved slug absent from the current compatible catalog is preserved and blocks execution until explicitly replaced. Agent Zero returns one structured plan under `swarm-planner-v1`; each Jev worker returns a candidate choice with a probability distribution and confidence value. The runtime extracts and conservatively repairs JSON before strict local schemas and the world engine apply authoritative validation.
 
@@ -62,7 +62,7 @@ reasoning profile; it may incur a small charge and is cached by model, profile,
 and contract version. `pnpm compare:live` runs the paid Jev-versus-deterministic-worker
 comparison, which requires an explicit provider-cost acknowledgement and an
 operator-selected Zero model, and enforces hard attempt and credit-admission
-caps. Both read `OPENROUTER_API_KEY` from the repository-root `.env`.
+caps. Both read `OPENROUTER_API_KEY` from the repository-root `.env`; `pnpm compare:live` also requires `TYPESAFE_API_KEY`.
 
 ## Development map source
 

docs/ARCHITECTURE.md

@@ -187,8 +187,9 @@ World reset reconstructs deterministic positions, 127 open cells, empty events a
 
 Agent Zero is the generative planner for the roster; every applied scenario
 designates one roster agent for the role through `patientZeroAgentId`, which
-World Lab badges HEX-0. One OpenRouter call per
-tick, under the `swarm-planner-v1` contract, produces a strategy summary,
+World Lab badges HEX-0. One OpenRouter call under the `swarm-planner-v1`
+contract is made only when strategic replanning is required; otherwise the
+last directive set is reused. When called, it produces a strategy summary,
 per-worker directives, and Agent Zero's own action candidate. Workers resolve
 their directives with TypeSafe Jev reflex cognition; Agent Zero receives no
 extra movement, action, infection, capture, or ownership authority beyond the

docs/GAMEPLAY_FOUNDATION.md

@@ -13,8 +13,9 @@
 
 ## Current Agent Zero planning slice
 
-In the zero-swarm architecture one Agent Zero planning call runs per tick
-regardless of roster size. Agent Zero issues a strategy summary and
+In the zero-swarm architecture Agent Zero makes an OpenRouter planning call
+only when strategic replanning is required; otherwise the last valid directive
+set is reused with no planner call. Agent Zero issues a strategy summary and
 per-worker structured directives (fields: mission, nullable target cell,
 priority, risk tolerance, issue tick, expiry tick, optional note up to 160
 characters). Workers resolve their directive via TypeSafe Jev reflex cognition
@@ -354,12 +355,12 @@ Every experiment export should preserve the complete initial scenario configurat
 
 ## Simultaneous decision dispatch
 
-Simultaneous gameplay semantics must not depend on one inference provider's batch feature. The simulation service should own a provider-neutral decision dispatcher. In the zero-swarm architecture, a tick involves one planning call (Agent Zero) followed by concurrent Jev reflex calls for each worker:
+Simultaneous gameplay semantics must not depend on one inference provider's batch feature. The simulation service should own a provider-neutral decision dispatcher. In the zero-swarm architecture, a tick involves an optional planning call (Agent Zero, only when strategic replanning is required) followed by one Jev reflex call per worker (currently issued sequentially; every worker observes the same frozen pre-tick state and actions resolve together):
 
 1. Freeze the authoritative snapshot.
 2. Build Agent Zero's world observation and each worker's reflex observation.
 3. Dispatch Agent Zero's planning call through the configured transport under the shared tick deadline.
-4. Distribute the resulting directives to workers; dispatch all worker Jev calls concurrently.
+4. Distribute the resulting directives to workers; issue one Jev reflex call per worker sequentially.
 5. Preserve one shared tick deadline and per-worker result identity.
 6. Retry only against the saved observation.
 7. Convert unfinished decisions to lost turns; fall back to `deterministic-fallback` for workers whose Jev call fails.

docs/SECURITY.md

@@ -87,7 +87,7 @@ profile, abort signal, and the tick's shared deadline. Agent-authored output
 cannot mutate the world directly or enter another same-tick observation.
 Cancellation discards every result from the uncommitted tick.
 
-The OpenRouter planner receives one bounded strategic observation per tick and is instructed to return exactly one plain JSON object naming opaque worker and target choices plus a Zero-action selection. TypeSafe Jev receives a compact semantic observation with opaque legal candidate IDs per worker and returns a probability distribution over candidates; a second question in the same request returns an optional bounded replan probability. The runtime performs bounded extraction and conservative repair for wrappers such as code fences, surrounding prose, and trailing commas, then rejects missing text, unusable JSON, unknown fields, or output truncation before the deterministic world engine validates all resolved components independently.
+When strategic replanning is required, the OpenRouter planner receives one bounded strategic observation and is instructed to return exactly one plain JSON object naming opaque worker and target choices plus a Zero-action selection. TypeSafe Jev receives a compact semantic observation with opaque legal candidate IDs per worker and returns a probability distribution over candidates; a second question in the same request returns an optional bounded replan probability. The runtime performs bounded extraction and conservative repair for wrappers such as code fences, surrounding prose, and trailing commas, then rejects missing text, unusable JSON, unknown fields, or output truncation before the deterministic world engine validates all resolved components independently.
 
 The request uses the selected model, messages, `max_tokens`, `stream: false`, and at most one normalized reasoning object selected from sanitized model metadata. Provider default omits the object. Off is offered only for non-mandatory reasoning and sends `{ enabled: false, exclude: true }`; an advertised effort sends `{ enabled: true, effort, exclude: true }`. It deliberately sends no tools, `tool_choice`, `response_format`, `provider.require_parameters`, standalone `reasoning_effort`, or model-specific parameter. Model IDs are never inspected or special-cased. Transport/provider failures, unavailable-model/profile failures, text/JSON contract failures, and later simulation-rule rejection remain distinct safe outcomes. The adapter never silently substitutes a model or scripted behavior.