fix: pin embedded harness selection per session

docs/gateway/configuration-reference.md

@@ -1271,6 +1271,7 @@ Codex app-server harness.
 - `fallback`: `"pi"` or `"none"`. `"pi"` keeps the built-in PI harness as the compatibility fallback when no plugin harness is selected. `"none"` makes missing or unsupported plugin harness selection fail instead of silently using PI. Selected plugin harness failures always surface directly.
 - Environment overrides: `OPENCLAW_AGENT_RUNTIME=<id|auto|pi>` overrides `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` disables PI fallback for that process.
 - For Codex-only deployments, set `model: "codex/gpt-5.4"`, `embeddedHarness.runtime: "codex"`, and `embeddedHarness.fallback: "none"`.
+- Harness choice is pinned per session id after the first embedded run. Config/env changes affect new or reset sessions, not an existing transcript. Legacy sessions with transcript history but no recorded pin are treated as PI-pinned. `/status` shows non-PI harness ids such as `codex` next to `Fast`.
 - This only controls the embedded chat harness. Media generation, vision, PDF, music, video, and TTS still use their provider/model settings.
 
 **Built-in alias shorthands** (only apply when the model is in `agents.defaults.models`):

docs/plugins/codex-harness.md

@@ -51,6 +51,21 @@ The Codex harness only claims `codex/*` model refs. Existing `openai/*`,
 `openai-codex/*`, Anthropic, Gemini, xAI, local, and custom provider refs keep
 their normal paths.
 
+Harness selection is not a live session control. When an embedded turn runs,
+OpenClaw records the selected harness id on that session and keeps using it for
+later turns in the same session id. Change `embeddedHarness` config or
+`OPENCLAW_AGENT_RUNTIME` when you want future sessions to use another harness;
+use `/new` or `/reset` to start a fresh session before switching an existing
+conversation between PI and Codex. This avoids replaying one transcript through
+two incompatible native session systems.
+
+Legacy sessions created before harness pins are treated as PI-pinned once they
+have transcript history. Use `/new` or `/reset` to opt that conversation into
+Codex after changing config.
+
+`/status` shows the effective non-PI harness next to `Fast`, for example
+`Fast · codex`. The default PI harness is omitted.
+
 ## Requirements
 
 - OpenClaw with the bundled `codex` plugin available.
@@ -218,7 +233,8 @@ auto-selection:
 
 Use normal session commands to switch agents and models. `/new` creates a fresh
 OpenClaw session and the Codex harness creates or resumes its sidecar app-server
-thread as needed. `/reset` clears the OpenClaw session binding for that thread.
+thread as needed. `/reset` clears the OpenClaw session binding for that thread
+and lets the next turn resolve the harness from current config again.
 
 ## Model discovery
 

docs/plugins/sdk-agent-harness.md

@@ -87,11 +87,14 @@ export default definePluginEntry({
 
 OpenClaw chooses a harness after provider/model resolution:
 
-1. `OPENCLAW_AGENT_RUNTIME=<id>` forces a registered harness with that id.
-2. `OPENCLAW_AGENT_RUNTIME=pi` forces the built-in PI harness.
-3. `OPENCLAW_AGENT_RUNTIME=auto` asks registered harnesses if they support the
+1. An existing session's recorded harness id wins, so config/env changes do not
+   hot-switch that transcript to another runtime.
+2. `OPENCLAW_AGENT_RUNTIME=<id>` forces a registered harness with that id for
+   sessions that are not already pinned.
+3. `OPENCLAW_AGENT_RUNTIME=pi` forces the built-in PI harness.
+4. `OPENCLAW_AGENT_RUNTIME=auto` asks registered harnesses if they support the
    resolved provider/model.
-4. If no registered harness matches, OpenClaw uses PI unless PI fallback is
+5. If no registered harness matches, OpenClaw uses PI unless PI fallback is
    disabled.
 
 Plugin harness failures surface as run failures. In `auto` mode, PI fallback is
@@ -100,6 +103,12 @@ provider/model. Once a plugin harness has claimed a run, OpenClaw does not
 replay that same turn through PI because that can change auth/runtime semantics
 or duplicate side effects.
 
+The selected harness id is persisted with the session id after an embedded run.
+Legacy sessions created before harness pins are treated as PI-pinned once they
+have transcript history. Use a new/reset session when changing between PI and a
+native plugin harness. `/status` shows non-default harness ids such as `codex`
+next to `Fast`; PI stays hidden because it is the default compatibility path.
+
 The bundled Codex plugin registers `codex` as its harness id. Core treats that
 as an ordinary plugin harness id; Codex-specific aliases belong in the plugin
 or operator config, not in the shared runtime selector.