refactor(codex): simplify native context ownership

* fix(skills): keep managed prompt paths readable

* fix(skills): preserve only managed skill prompt paths

* chore: refresh proof gate

* fix(skills): refresh managed prompt snapshots

* fix(skills): preserve plugin prompt paths in state roots

* test(skills): use generic state-root path names

Signed-off-by: sallyom <somalley@redhat.com>

---------

Signed-off-by: sallyom <somalley@redhat.com>
Co-authored-by: sallyom <somalley@redhat.com>

.agents/skills/crabbox/SKILL.md

@@ -54,6 +54,13 @@ pnpm crabbox:run -- --help | sed -n '1,120p'
 - For broad OpenClaw maintainer `pnpm` gates, prefer the repo wrapper with
   `--provider blacksmith-testbox` or the repo Testbox helpers when the standing
   Testbox policy applies.
+- Cold Testbox acquisition and hydration often take tens of seconds. When broad
+  remote proof is likely, immediately start
+  `node scripts/crabbox-wrapper.mjs warmup --provider blacksmith-testbox --keep --timing-json`
+  in a background command session while inspecting, editing, and running
+  focused local tests. Poll later, reuse the returned `tbx_...` with
+  `--provider blacksmith-testbox --id <tbx_id>`, and stop it before handoff.
+  Do not warm speculatively when remote proof is unlikely.
 - Always report the actual provider and id. `cbx_...` means AWS Crabbox;
   `tbx_...` means Blacksmith Testbox through Crabbox. If the output only says
   `blacksmith testbox list`, use `blacksmith testbox list --all` before

.agents/skills/release-openclaw-maintainer/SKILL.md

@@ -150,9 +150,21 @@ Use this skill for release and publish-time workflow. Load `$release-private` if
 - Stable Windows Hub release closeout requires the signed
   `OpenClawCompanion-Setup-x64.exe`, `OpenClawCompanion-Setup-arm64.exe`, and
   `OpenClawCompanion-SHA256SUMS.txt` assets on the canonical
-  `openclaw/openclaw` GitHub Release. Use the public `Windows Node Release`
-  workflow after the matching `openclaw/openclaw-windows-node` release exists;
-  it verifies Authenticode signatures on Windows before uploading assets.
+  `openclaw/openclaw` GitHub Release. Pass the exact signed
+  `openclaw/openclaw-windows-node` release tag as `windows_node_tag` to
+  `OpenClaw Release Publish`, together with the candidate-approved
+  `windows_node_installer_digests` map; it prevalidates the published source
+  release and required installers against that map before any publish child,
+  dispatches the public `Windows Node Release` workflow while the OpenClaw
+  release is still a draft, carries those pinned source asset digests
+  unchanged, verifies the expected OpenClaw Foundation Authenticode signer on
+  Windows, re-downloads and checksum-verifies the promoted asset contract, and
+  blocks publication until the canonical asset contract is present. Use direct
+  `Windows Node Release` dispatch only for recovery, always with an exact tag,
+  never `latest`, and the explicit `expected_installer_digests` JSON map from
+  the approved source release. Recovery rejects unexpected
+  `OpenClawCompanion-*` target asset names, then replaces the expected contract
+  assets with the pinned source bytes.
 - Website Windows Hub download links should target exact canonical
   `openclaw/openclaw/releases/download/vYYYY.M.PATCH/...` assets for the current
   stable release, or `releases/latest/download/...` only after verifying the
@@ -675,19 +687,23 @@ node --import tsx scripts/openclaw-npm-postpublish-verify.ts <published-version>
     where npm did not publish the beta version, delete/recreate the same beta
     tag and any accidental draft/incomplete prerelease at the fixed commit
     instead of skipping a prerelease number.
-22. Start `.github/workflows/openclaw-npm-release.yml` from the same branch with
+22. Start `.github/workflows/openclaw-release-publish.yml` from the same branch with
     the same tag for the real publish, choose `npm_dist_tag` (`beta` default,
     `latest` only when you intentionally want direct stable publish), keep it
     the same as the preflight run, and pass the successful npm
-    `preflight_run_id`.
+    `preflight_run_id` plus the successful `full_release_validation_run_id`.
+    For stable publish, also pass the exact non-prerelease
+    `openclaw/openclaw-windows-node` tag as `windows_node_tag` and its
+    candidate-approved installer digest map as `windows_node_installer_digests`.
 23. Wait for `npm-release` approval from `@openclaw/openclaw-release-managers`.
 24. Wait for the real publish workflow to run postpublish verification,
     create or update the GitHub release as a draft, upload dependency evidence,
+    promote and verify the required Windows Hub assets for stable releases,
     append release verification proof, and only then undraft/publish it. If a
-    waited plugin publish fails after OpenClaw npm succeeds, the workflow keeps
-    the release draft with OpenClaw npm evidence and exits red; do not undraft
-    until the plugin publish gap is repaired. The standalone verifier command
-    remains the recovery probe:
+    waited plugin publish or Windows Hub promotion fails after OpenClaw npm
+    succeeds, the workflow keeps the release draft with OpenClaw npm evidence
+    and exits red; do not undraft until the gap is repaired. The standalone
+    verifier command remains the recovery probe:
     `node --import tsx scripts/openclaw-npm-postpublish-verify.ts <published-version>`.
 25. Run the post-published beta verification roster. First scan current `main`
     for critical fixes that landed after the release branch cut; backport only

.github/workflows/ci.yml

@@ -1358,6 +1358,8 @@ jobs:
           - check_name: check-additional-boundaries-bcd
             group: boundaries
             boundary_shard: 2/4,3/4,4/4
+          - check_name: check-session-accessor-boundary
+            group: session-accessor-boundary
           - check_name: check-additional-extension-channels
             group: extension-channels
           - check_name: check-additional-extension-bundled
@@ -1504,6 +1506,15 @@ jobs:
             boundaries)
               node scripts/run-additional-boundary-checks.mjs
               ;;
+            session-accessor-boundary)
+              if [ ! -f scripts/check-session-accessor-boundary.mjs ]; then
+                echo "[skip] session accessor boundary check is not present in this checkout"
+              elif ! node -e 'const pkg = require("./package.json"); process.exit(pkg.scripts?.["lint:tmp:session-accessor-boundary"] ? 0 : 1);'; then
+                echo "[skip] session accessor boundary script is not present in package.json"
+              else
+                run_check "lint:tmp:session-accessor-boundary" pnpm run lint:tmp:session-accessor-boundary
+              fi
+              ;;
             extension-channels)
               run_check "lint:extensions:channels" pnpm run lint:extensions:channels
               ;;

.github/workflows/full-release-validation.yml

@@ -783,7 +783,7 @@ jobs:
           fi
 
           args=(
-            -f ref="$TARGET_SHA"
+            -f ref="$TARGET_REF"
             -f expected_sha="$TARGET_SHA"
             -f provider="$PROVIDER"
             -f mode="$MODE"

.github/workflows/mantis-telegram-live.yml

@@ -379,7 +379,6 @@ jobs:
           OPENCLAW_QA_CONVEX_SECRET_CI: ${{ secrets.OPENCLAW_QA_CONVEX_SECRET_CI }}
           OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS: "1800000"
           OPENCLAW_QA_REDACT_PUBLIC_METADATA: "1"
-          OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT: "1"
           CRABBOX_COORDINATOR: ${{ secrets.CRABBOX_COORDINATOR }}
           CRABBOX_COORDINATOR_TOKEN: ${{ secrets.CRABBOX_COORDINATOR_TOKEN }}
           OPENCLAW_QA_MANTIS_CRABBOX_COORDINATOR: ${{ secrets.OPENCLAW_QA_MANTIS_CRABBOX_COORDINATOR }}

.github/workflows/npm-telegram-beta-e2e.yml

@@ -220,7 +220,6 @@ jobs:
           OPENCLAW_QA_CONVEX_SECRET_CI: ${{ secrets.OPENCLAW_QA_CONVEX_SECRET_CI }}
           OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS: "1800000"
           OPENCLAW_QA_REDACT_PUBLIC_METADATA: "1"
-          OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT: "1"
           INPUT_SCENARIO: ${{ inputs.scenario }}
           PACKAGE_ARTIFACT_NAME: ${{ inputs.package_artifact_name || '' }}
         run: |

.github/workflows/openclaw-release-checks.yml

@@ -1181,7 +1181,7 @@ jobs:
   runtime_tool_coverage_release_checks:
     name: Enforce QA Lab runtime tool coverage
     needs: [resolve_target, qa_lab_runtime_parity_release_checks]
-    if: always() && contains(fromJSON('["all","qa","qa-parity"]'), needs.resolve_target.outputs.rerun_group)
+    if: contains(fromJSON('["all","qa","qa-parity"]'), needs.resolve_target.outputs.rerun_group)
     runs-on: ubuntu-24.04
     timeout-minutes: 15
     permissions:
@@ -1204,13 +1204,35 @@ jobs:
           node-version: ${{ env.NODE_VERSION }}
           install-bun: "true"
 
+      - name: Download runtime parity status
+        uses: actions/download-artifact@v8
+        with:
+          name: release-check-status-qa-runtime-parity-${{ needs.resolve_target.outputs.revision }}
+          path: .artifacts/release-check-status/
+
+      - name: Verify runtime parity producer status
+        id: verify_runtime_parity_status
+        shell: bash
+        run: |
+          set -euo pipefail
+          status_path=".artifacts/release-check-status/qa_lab_runtime_parity_release_checks.env"
+          status="$(sed -n 's/^status=//p' "$status_path" | tail -n 1)"
+          if [[ "$status" != "success" ]]; then
+            echo "Runtime parity producer status is ${status:-missing}; skipping coverage artifact consumer."
+            echo "ready=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          echo "ready=true" >> "$GITHUB_OUTPUT"
+
       - name: Download runtime parity artifacts
+        if: steps.verify_runtime_parity_status.outputs.ready == 'true'
         uses: actions/download-artifact@v8
         with:
           name: release-qa-runtime-parity-${{ needs.resolve_target.outputs.revision }}
           path: .artifacts/qa-e2e/
 
       - name: Enforce standard runtime tool coverage
+        if: steps.verify_runtime_parity_status.outputs.ready == 'true'
         run: |
           set -euo pipefail
           pnpm openclaw qa coverage \
@@ -1412,7 +1434,6 @@ jobs:
           OPENCLAW_QA_CONVEX_SECRET_CI: ${{ secrets.OPENCLAW_QA_CONVEX_SECRET_CI }}
           OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS: "1800000"
           OPENCLAW_QA_REDACT_PUBLIC_METADATA: "1"
-          OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT: "1"
         run: |
           set -euo pipefail
 

.github/workflows/openclaw-release-publish.yml

@@ -15,6 +15,14 @@ on:
         description: Successful Full Release Validation run id for this tag/SHA, required when publish_openclaw_npm=true
         required: false
         type: string
+      windows_node_tag:
+        description: Exact openclaw-windows-node release tag, required for stable OpenClaw publish
+        required: false
+        type: string
+      windows_node_installer_digests:
+        description: Candidate-approved compact JSON map of Windows installer names to pinned sha256 digests
+        required: false
+        type: string
       npm_telegram_run_id:
         description: Optional successful NPM Telegram Beta E2E run id to include in final release evidence
         required: false
@@ -81,12 +89,15 @@ jobs:
     outputs:
       sha: ${{ steps.manifest.outputs.sha || steps.ref.outputs.sha }}
       preflight_artifact_name: ${{ steps.preflight_artifact.outputs.name }}
+      windows_node_installer_digests: ${{ steps.windows_source.outputs.installer_digests }}
     steps:
       - name: Validate inputs
         env:
           RELEASE_TAG: ${{ inputs.tag }}
           PREFLIGHT_RUN_ID: ${{ inputs.preflight_run_id }}
           FULL_RELEASE_VALIDATION_RUN_ID: ${{ inputs.full_release_validation_run_id }}
+          WINDOWS_NODE_TAG: ${{ inputs.windows_node_tag }}
+          WINDOWS_NODE_INSTALLER_DIGESTS: ${{ inputs.windows_node_installer_digests }}
           PUBLISH_OPENCLAW_NPM: ${{ inputs.publish_openclaw_npm && 'true' || 'false' }}
           PLUGIN_PUBLISH_SCOPE: ${{ inputs.plugin_publish_scope }}
           PLUGINS: ${{ inputs.plugins }}
@@ -115,6 +126,22 @@ jobs:
             echo "publish_openclaw_npm=true requires full_release_validation_run_id." >&2
             exit 1
           fi
+          stable_release=true
+          if [[ "${RELEASE_TAG}" == *"-alpha."* || "${RELEASE_TAG}" == *"-beta."* ]]; then
+            stable_release=false
+          fi
+          if [[ -n "${WINDOWS_NODE_TAG}" && ! "${WINDOWS_NODE_TAG}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+([-.][0-9A-Za-z]+([.-][0-9A-Za-z]+)*)?$ ]]; then
+            echo "windows_node_tag must be an explicit openclaw-windows-node release tag, not latest: ${WINDOWS_NODE_TAG}" >&2
+            exit 1
+          fi
+          if [[ "${PUBLISH_OPENCLAW_NPM}" == "true" && "${stable_release}" == "true" && -z "${WINDOWS_NODE_TAG}" ]]; then
+            echo "Stable OpenClaw publish requires an explicit windows_node_tag." >&2
+            exit 1
+          fi
+          if [[ "${PUBLISH_OPENCLAW_NPM}" == "true" && "${stable_release}" == "true" && -z "${WINDOWS_NODE_INSTALLER_DIGESTS}" ]]; then
+            echo "Stable OpenClaw publish requires candidate-approved windows_node_installer_digests." >&2
+            exit 1
+          fi
           tideclaw_alpha_publish=false
           if [[ "${RELEASE_TAG}" == *"-alpha."* && "${RELEASE_NPM_DIST_TAG}" == "alpha" && "${WORKFLOW_REF}" =~ ^refs/heads/tideclaw/alpha/[0-9]{4}-[0-9]{2}-[0-9]{2}-[0-9]{4}Z$ ]]; then
             tideclaw_alpha_publish=true
@@ -143,6 +170,73 @@ jobs:
               ;;
           esac
 
+      - name: Validate stable Windows source release
+        id: windows_source
+        if: ${{ inputs.publish_openclaw_npm }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ inputs.tag }}
+          WINDOWS_NODE_TAG: ${{ inputs.windows_node_tag }}
+          APPROVED_INSTALLER_DIGESTS: ${{ inputs.windows_node_installer_digests }}
+        run: |
+          set -euo pipefail
+          if [[ "${RELEASE_TAG}" == *"-alpha."* || "${RELEASE_TAG}" == *"-beta."* ]]; then
+            exit 0
+          fi
+
+          source_json="$(gh release view "${WINDOWS_NODE_TAG}" \
+            --repo openclaw/openclaw-windows-node \
+            --json tagName,isDraft,isPrerelease,assets,url)"
+          if [[ "$(printf '%s' "${source_json}" | jq -r '.tagName')" != "${WINDOWS_NODE_TAG}" ]]; then
+            echo "Windows source release tag does not match ${WINDOWS_NODE_TAG}." >&2
+            exit 1
+          fi
+          if [[ "$(printf '%s' "${source_json}" | jq -r '.isDraft')" == "true" ]]; then
+            echo "Stable OpenClaw publish requires a published Windows source release." >&2
+            exit 1
+          fi
+          if [[ "$(printf '%s' "${source_json}" | jq -r '.isPrerelease')" == "true" ]]; then
+            echo "Stable OpenClaw publish requires a non-prerelease Windows source release." >&2
+            exit 1
+          fi
+
+          required_assets=(
+            "OpenClawCompanion-Setup-x64.exe"
+            "OpenClawCompanion-Setup-arm64.exe"
+          )
+          required_assets_json="$(printf '%s\n' "${required_assets[@]}" | jq -R . | jq -sc .)"
+          if ! approved_installer_digests="$(printf '%s' "${APPROVED_INSTALLER_DIGESTS}" | jq -ce --argjson names "${required_assets_json}" '
+            if type == "object" and
+              (keys | sort) == ($names | sort) and
+              all(.[]; type == "string" and test("^sha256:[a-f0-9]{64}$"))
+            then .
+            else error("invalid candidate-approved Windows installer digest map")
+            end
+          ')"; then
+            echo "windows_node_installer_digests must contain exactly the candidate-approved current installer asset contract." >&2
+            exit 1
+          fi
+          for asset_name in "${required_assets[@]}"; do
+            asset_matches="$(printf '%s' "${source_json}" | jq -c --arg name "${asset_name}" '[.assets[]? | select(.name == $name)]')"
+            asset_match_count="$(printf '%s' "${asset_matches}" | jq 'length')"
+            if [[ "${asset_match_count}" != "1" ]]; then
+              echo "Windows source release ${WINDOWS_NODE_TAG} must contain exactly one required asset ${asset_name}; found ${asset_match_count}." >&2
+              exit 1
+            fi
+            asset_digest="$(printf '%s' "${asset_matches}" | jq -r '.[0].digest // empty')"
+            if [[ ! "${asset_digest}" =~ ^sha256:[a-f0-9]{64}$ ]]; then
+              echo "Windows source release ${WINDOWS_NODE_TAG} asset ${asset_name} is missing its immutable SHA-256 digest." >&2
+              exit 1
+            fi
+            approved_digest="$(printf '%s' "${approved_installer_digests}" | jq -r --arg name "${asset_name}" '.[$name]')"
+            if [[ "${asset_digest}" != "${approved_digest}" ]]; then
+              echo "Windows source release ${WINDOWS_NODE_TAG} asset ${asset_name} no longer matches its candidate-approved digest." >&2
+              exit 1
+            fi
+          done
+          echo "installer_digests=${approved_installer_digests}" >> "$GITHUB_OUTPUT"
+          echo "- Windows Node source release: prevalidated \`${WINDOWS_NODE_TAG}\`" >> "$GITHUB_STEP_SUMMARY"
+
       - name: Download OpenClaw npm preflight manifest
         id: preflight_artifact
         if: ${{ inputs.publish_openclaw_npm }}
@@ -337,6 +431,7 @@ jobs:
           TARGET_SHA: ${{ steps.manifest.outputs.sha || steps.ref.outputs.sha }}
           RELEASE_PROFILE: ${{ steps.full_manifest.outputs.release_profile || inputs.release_profile }}
           FULL_RELEASE_VALIDATION_RUN_ID: ${{ inputs.full_release_validation_run_id }}
+          WINDOWS_NODE_TAG: ${{ inputs.windows_node_tag }}
         run: |
           {
             echo "### Release target"
@@ -347,13 +442,16 @@ jobs:
             if [[ -n "${FULL_RELEASE_VALIDATION_RUN_ID// }" ]]; then
               echo "- Full release validation: \`${FULL_RELEASE_VALIDATION_RUN_ID}\`"
             fi
+            if [[ -n "${WINDOWS_NODE_TAG// }" ]]; then
+              echo "- Windows Node source release: \`${WINDOWS_NODE_TAG}\`"
+            fi
           } >> "$GITHUB_STEP_SUMMARY"
 
   publish:
     name: Publish plugins, then OpenClaw
     needs: [resolve_release_target]
     runs-on: ubuntu-latest
-    timeout-minutes: 60
+    timeout-minutes: 120
     environment: npm-release
     steps:
       - name: Checkout release SHA
@@ -383,10 +481,16 @@ jobs:
           WAIT_FOR_CLAWHUB: ${{ inputs.wait_for_clawhub && 'true' || 'false' }}
           PREFLIGHT_ARTIFACT_NAME: ${{ needs.resolve_release_target.outputs.preflight_artifact_name }}
           NPM_TELEGRAM_RUN_ID: ${{ inputs.npm_telegram_run_id }}
+          WINDOWS_NODE_TAG: ${{ inputs.windows_node_tag }}
+          WINDOWS_NODE_INSTALLER_DIGESTS: ${{ needs.resolve_release_target.outputs.windows_node_installer_digests }}
           POSTPUBLISH_EVIDENCE_DIR: ${{ runner.temp }}/openclaw-release-postpublish-evidence
         run: |
           set -euo pipefail
 
+          is_stable_release() {
+            [[ "${RELEASE_TAG}" != *"-alpha."* && "${RELEASE_TAG}" != *"-beta."* ]]
+          }
+
           dispatch_workflow_at_ref() {
             local workflow_ref="$1"
             shift
@@ -836,10 +940,105 @@ jobs:
           }
 
           publish_github_release() {
+            if is_stable_release; then
+              verify_windows_release_asset_contract
+            fi
             gh release edit "${RELEASE_TAG}" --repo "$GITHUB_REPOSITORY" --draft=false
             echo "- GitHub release: https://github.com/${GITHUB_REPOSITORY}/releases/tag/${RELEASE_TAG}" >> "$GITHUB_STEP_SUMMARY"
           }
 
+          verify_windows_release_asset_contract() {
+            local actual_companion_assets actual_digest asset_name expected_companion_assets expected_digest expected_hash expected_installer_names manifest_dir manifest_json manifest_path release_json
+            # Add future promoted installer names, such as MSIX x64/ARM64, here.
+            local -a installer_assets=(
+              "OpenClawCompanion-Setup-x64.exe"
+              "OpenClawCompanion-Setup-arm64.exe"
+            )
+            local -a required_assets=(
+              "${installer_assets[@]}"
+              "OpenClawCompanion-SHA256SUMS.txt"
+            )
+
+            release_json="$(gh release view "${RELEASE_TAG}" --repo "$GITHUB_REPOSITORY" --json assets,url)"
+            expected_companion_assets="$(printf '%s\n' "${required_assets[@]}" | jq -R . | jq -sc 'sort')"
+            actual_companion_assets="$(printf '%s' "${release_json}" | jq -c '
+              [.assets[]? | select(.name | startswith("OpenClawCompanion-")) | .name] | sort
+            ')"
+            if [[ "${actual_companion_assets}" != "${expected_companion_assets}" ]]; then
+              echo "Stable release OpenClawCompanion asset names do not exactly match the current contract." >&2
+              return 1
+            fi
+            for asset_name in "${required_assets[@]}"; do
+              if ! printf '%s' "${release_json}" | jq -e --arg name "${asset_name}" 'any(.assets[]?; .name == $name)' >/dev/null; then
+                echo "Stable release is missing required Windows asset ${asset_name}." >&2
+                return 1
+              fi
+            done
+
+            manifest_dir="${RUNNER_TEMP}/openclaw-windows-release-contract"
+            manifest_path="${manifest_dir}/OpenClawCompanion-SHA256SUMS.txt"
+            rm -rf "${manifest_dir}"
+            mkdir -p "${manifest_dir}"
+            gh release download "${RELEASE_TAG}" \
+              --repo "$GITHUB_REPOSITORY" \
+              --pattern "OpenClawCompanion-SHA256SUMS.txt" \
+              --dir "${manifest_dir}"
+            if ! manifest_json="$(jq -Rsc '
+              split("\n") as $lines |
+              (if $lines[-1] == "" then $lines[0:-1] else $lines end) |
+              map(sub("\r$"; "")) |
+              if all(.[]; test("^(?<hash>[a-f0-9]{64})  (?<name>[^/\\\\]+)$"))
+              then map(capture("^(?<hash>[a-f0-9]{64})  (?<name>[^/\\\\]+)$"))
+              else error("malformed Windows checksum manifest entry")
+              end
+            ' "${manifest_path}")"; then
+              echo "Stable release Windows checksum manifest contains malformed entries." >&2
+              return 1
+            fi
+            expected_installer_names="$(printf '%s\n' "${installer_assets[@]}" | jq -R . | jq -sc 'sort')"
+            if ! printf '%s' "${manifest_json}" | jq -e --argjson expected "${expected_installer_names}" '
+              length == ($expected | length) and
+              ([.[].name] | sort) == $expected and
+              ([.[].name] | unique | length) == length
+            ' >/dev/null; then
+              echo "Stable release Windows checksum manifest does not exactly match the installer asset contract." >&2
+              return 1
+            fi
+            for asset_name in "${installer_assets[@]}"; do
+              expected_digest="$(printf '%s' "${WINDOWS_NODE_INSTALLER_DIGESTS}" | jq -r --arg name "${asset_name}" '.[$name] // empty')"
+              actual_digest="$(printf '%s' "${release_json}" | jq -r --arg name "${asset_name}" '.assets[]? | select(.name == $name) | .digest // empty')"
+              if [[ -z "${expected_digest}" || "${actual_digest}" != "${expected_digest}" ]]; then
+                echo "Stable release Windows asset ${asset_name} does not match its pinned digest." >&2
+                return 1
+              fi
+              expected_hash="${expected_digest#sha256:}"
+              if ! printf '%s' "${manifest_json}" | jq -e --arg name "${asset_name}" --arg hash "${expected_hash}" '
+                any(.[]; .name == $name and .hash == $hash)
+              ' >/dev/null; then
+                echo "Stable release Windows checksum manifest does not match pinned digest for ${asset_name}." >&2
+                return 1
+              fi
+            done
+            echo "- Windows Hub asset contract: verified" >> "$GITHUB_STEP_SUMMARY"
+          }
+
+          promote_windows_release_assets() {
+            if ! is_stable_release; then
+              return 0
+            fi
+            if [[ -z "${WINDOWS_NODE_INSTALLER_DIGESTS// }" ]]; then
+              echo "Stable release is missing prevalidated Windows installer digests." >&2
+              return 1
+            fi
+
+            windows_node_run_id="$(dispatch_workflow windows-node-release.yml \
+              -f tag="${RELEASE_TAG}" \
+              -f windows_node_tag="${WINDOWS_NODE_TAG}" \
+              -f expected_installer_digests="${WINDOWS_NODE_INSTALLER_DIGESTS}")"
+            echo "- Windows Node release run ID: \`${windows_node_run_id}\`" >> "$GITHUB_STEP_SUMMARY"
+            wait_for_run windows-node-release.yml "${windows_node_run_id}"
+          }
+
           upload_dependency_evidence_release_asset() {
             local release_version download_dir asset_path asset_name artifact_name
             release_version="${RELEASE_TAG#v}"
@@ -913,7 +1112,7 @@ jobs:
           }
 
           append_release_proof_to_github_release() {
-            local release_version body_file notes_file tarball integrity telegram_line clawhub_line clawhub_bootstrap_line clawhub_runtime_state_path
+            local release_version body_file notes_file tarball integrity telegram_line clawhub_line clawhub_bootstrap_line clawhub_runtime_state_path windows_line
 
             release_version="${RELEASE_TAG#v}"
             body_file="${RUNNER_TEMP}/release-body.md"
@@ -931,6 +1130,10 @@ jobs:
             write_clawhub_runtime_state false "${clawhub_runtime_state_path}"
             clawhub_line="$(jq -r '.proofLines.normal' "${clawhub_runtime_state_path}")"
             clawhub_bootstrap_line="$(jq -r '.proofLines.bootstrap' "${clawhub_runtime_state_path}")"
+            windows_line=""
+            if [[ -n "${windows_node_run_id// }" ]]; then
+              windows_line="- Windows Hub promotion: https://github.com/${GITHUB_REPOSITORY}/actions/runs/${windows_node_run_id} from openclaw/openclaw-windows-node@${WINDOWS_NODE_TAG}"
+            fi
 
             RELEASE_BODY_FILE="${body_file}" \
               RELEASE_NOTES_FILE="${notes_file}" \
@@ -948,6 +1151,7 @@ jobs:
               CLAWHUB_LINE="${clawhub_line}" \
               CLAWHUB_BOOTSTRAP_LINE="${clawhub_bootstrap_line}" \
               TELEGRAM_LINE="${telegram_line}" \
+              WINDOWS_LINE="${windows_line}" \
               node --input-type=module <<'NODE'
           import { readFileSync, writeFileSync } from "node:fs";
 
@@ -974,6 +1178,7 @@ jobs:
             process.env.CLAWHUB_BOOTSTRAP_LINE,
             `- OpenClaw npm publish: https://github.com/${process.env.RELEASE_REPO}/actions/runs/${process.env.OPENCLAW_NPM_RUN_ID}`,
             process.env.TELEGRAM_LINE,
+            ...(process.env.WINDOWS_LINE ? [process.env.WINDOWS_LINE] : []),
           ].join("\n");
 
           const withoutOldProof = body.replace(/\n?### Release verification\n[\s\S]*?(?=\n### |\n## |$)/, "");
@@ -998,6 +1203,9 @@ jobs:
             else
               echo "- OpenClaw npm publish: skipped by input"
             fi
+            if is_stable_release && [[ "${PUBLISH_OPENCLAW_NPM}" == "true" ]]; then
+              echo "- Windows Hub promotion: required before the GitHub release can be published"
+            fi
             if [[ "${WAIT_FOR_CLAWHUB}" == "true" ]]; then
               echo "- Workflow completion waits for ClawHub"
             else
@@ -1142,6 +1350,7 @@ jobs:
 
           failed=0
           openclaw_failed=0
+          windows_node_run_id=""
           if [[ -n "${openclaw_pid}" ]] && ! wait "${openclaw_pid}"; then
             failed=1
             openclaw_failed=1
@@ -1172,6 +1381,9 @@ jobs:
             fi
             create_or_update_github_release
             upload_dependency_evidence_release_asset
+            if ! promote_windows_release_assets; then
+              failed=1
+            fi
             append_release_proof_to_github_release
             if [[ "${failed}" == "0" ]]; then
               publish_github_release

.github/workflows/qa-live-transports-convex.yml

@@ -532,7 +532,6 @@ jobs:
           OPENCLAW_QA_CONVEX_SECRET_CI: ${{ secrets.OPENCLAW_QA_CONVEX_SECRET_CI }}
           OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS: "1800000"
           OPENCLAW_QA_REDACT_PUBLIC_METADATA: "1"
-          OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT: "1"
           INPUT_SCENARIO: ${{ github.event_name == 'workflow_dispatch' && inputs.scenario || '' }}
         run: |
           set -euo pipefail

.github/workflows/stale.yml

@@ -68,7 +68,7 @@ jobs:
           days-before-pr-close: 7
           stale-issue-label: stale
           stale-pr-label: stale
-          exempt-issue-labels: enhancement,maintainer,pinned,security,no-stale,bad-barnacle
+          exempt-issue-labels: enhancement,maintainer,pinned,security,no-stale,bad-barnacle,clawsweeper:queueable-fix,clawsweeper:source-repro,clawsweeper:fix-shape-clear
           exempt-pr-labels: maintainer,no-stale,bad-barnacle
           operations-per-run: 2000
           ascending: true
@@ -100,7 +100,7 @@ jobs:
           days-before-pr-stale: -1
           days-before-pr-close: -1
           stale-issue-label: stale
-          exempt-issue-labels: enhancement,maintainer,pinned,security,no-stale,bad-barnacle
+          exempt-issue-labels: enhancement,maintainer,pinned,security,no-stale,bad-barnacle,clawsweeper:queueable-fix,clawsweeper:source-repro,clawsweeper:fix-shape-clear
           operations-per-run: 2000
           ascending: true
           include-only-assigned: true
@@ -172,7 +172,7 @@ jobs:
           days-before-pr-close: 7
           stale-issue-label: stale
           stale-pr-label: stale
-          exempt-issue-labels: enhancement,maintainer,pinned,security,no-stale,bad-barnacle
+          exempt-issue-labels: enhancement,maintainer,pinned,security,no-stale,bad-barnacle,clawsweeper:queueable-fix,clawsweeper:source-repro,clawsweeper:fix-shape-clear
           exempt-pr-labels: maintainer,no-stale,bad-barnacle
           operations-per-run: 2000
           ascending: true
@@ -203,7 +203,7 @@ jobs:
           days-before-pr-stale: -1
           days-before-pr-close: -1
           stale-issue-label: stale
-          exempt-issue-labels: enhancement,maintainer,pinned,security,no-stale,bad-barnacle
+          exempt-issue-labels: enhancement,maintainer,pinned,security,no-stale,bad-barnacle,clawsweeper:queueable-fix,clawsweeper:source-repro,clawsweeper:fix-shape-clear
           operations-per-run: 2000
           ascending: true
           include-only-assigned: true
@@ -277,6 +277,9 @@ jobs:
               "security",
               "no-stale",
               "bad-barnacle",
+              "clawsweeper:queueable-fix",
+              "clawsweeper:source-repro",
+              "clawsweeper:fix-shape-clear",
             ]);
             const prExemptLabels = new Set(["maintainer", "no-stale", "bad-barnacle"]);
             const maintainerAssociations = new Set(["OWNER", "MEMBER", "COLLABORATOR"]);

.github/workflows/windows-node-release.yml

@@ -8,9 +8,12 @@ on:
         required: true
         type: string
       windows_node_tag:
-        description: openclaw-windows-node release tag to promote, or latest
+        description: Exact openclaw-windows-node release tag to promote, for example v0.6.3
+        required: true
+        type: string
+      expected_installer_digests:
+        description: Compact JSON map of installer asset names to pinned source sha256 digests
         required: true
-        default: latest
         type: string
 
 permissions:
@@ -31,46 +34,129 @@ jobs:
         env:
           RELEASE_TAG: ${{ inputs.tag }}
           WINDOWS_NODE_TAG: ${{ inputs.windows_node_tag }}
+          EXPECTED_INSTALLER_DIGESTS: ${{ inputs.expected_installer_digests }}
           GH_TOKEN: ${{ github.token }}
         run: |
           if ($env:RELEASE_TAG -notmatch '^v[0-9]{4}\.[1-9][0-9]*\.[1-9][0-9]*((-(alpha|beta)\.[1-9][0-9]*)|(-[1-9][0-9]*))?$') {
             throw "Invalid OpenClaw release tag: $env:RELEASE_TAG"
           }
-          if ($env:WINDOWS_NODE_TAG -ne "latest" -and $env:WINDOWS_NODE_TAG -notmatch '^v[0-9]+\.[0-9]+\.[0-9]+([-.][0-9A-Za-z.-]+)?$') {
-            throw "Invalid openclaw-windows-node release tag: $env:WINDOWS_NODE_TAG"
+          $stableRelease = -not (
+            $env:RELEASE_TAG.Contains("-alpha.") -or
+            $env:RELEASE_TAG.Contains("-beta.")
+          )
+          if ($env:WINDOWS_NODE_TAG -notmatch '^v[0-9]+\.[0-9]+\.[0-9]+([-.][0-9A-Za-z]+([.-][0-9A-Za-z]+)*)?$') {
+            throw "windows_node_tag must be an explicit openclaw-windows-node release tag, not latest: $env:WINDOWS_NODE_TAG"
+          }
+
+          try {
+            $expectedDigests = $env:EXPECTED_INSTALLER_DIGESTS | ConvertFrom-Json -AsHashtable
+          } catch {
+            throw "expected_installer_digests must be a JSON object: $_"
+          }
+          # Add future signed installer names, such as MSIX x64/ARM64, here.
+          $requiredInstallerNames = @(
+            "OpenClawCompanion-Setup-x64.exe",
+            "OpenClawCompanion-Setup-arm64.exe"
+          )
+          $allowedTargetCompanionAssetNames = @(
+            $requiredInstallerNames
+            "OpenClawCompanion-SHA256SUMS.txt"
+          )
+          if ($expectedDigests.Count -ne $requiredInstallerNames.Count) {
+            throw "expected_installer_digests must contain exactly the current installer asset contract."
+          }
+          foreach ($name in $requiredInstallerNames) {
+            $digest = [string]$expectedDigests[$name]
+            if ($digest -notmatch '^sha256:[A-Fa-f0-9]{64}$') {
+              throw "expected_installer_digests is missing a valid pinned digest for $name."
+            }
+          }
+
+          $targetRelease = gh release view $env:RELEASE_TAG --repo $env:GITHUB_REPOSITORY --json tagName,isDraft,isPrerelease,assets,url | ConvertFrom-Json
+          if ($targetRelease.tagName -ne $env:RELEASE_TAG) {
+            throw "OpenClaw release tag mismatch: expected $env:RELEASE_TAG, got $($targetRelease.tagName)"
+          }
+          $unexpectedTargetCompanionAssets = @(
+            $targetRelease.assets |
+              Where-Object {
+                $_.name.StartsWith("OpenClawCompanion-") -and
+                $_.name -notin $allowedTargetCompanionAssetNames
+              } |
+              ForEach-Object name |
+              Sort-Object
+          )
+          if ($unexpectedTargetCompanionAssets.Count -ne 0) {
+            throw "Target OpenClaw release contains unexpected OpenClawCompanion assets before upload: $($unexpectedTargetCompanionAssets -join ', ')"
+          }
+
+          $sourceRelease = gh release view $env:WINDOWS_NODE_TAG --repo openclaw/openclaw-windows-node --json tagName,isDraft,isPrerelease,assets,url | ConvertFrom-Json
+          if ($sourceRelease.tagName -ne $env:WINDOWS_NODE_TAG) {
+            throw "Windows source release tag mismatch: expected $env:WINDOWS_NODE_TAG, got $($sourceRelease.tagName)"
+          }
+          if ($sourceRelease.isDraft) {
+            throw "Windows source release must be published: $($sourceRelease.url)"
+          }
+          if ($stableRelease -and $sourceRelease.isPrerelease) {
+            throw "Stable OpenClaw releases require a non-prerelease Windows source release: $($sourceRelease.url)"
+          }
+          foreach ($name in $requiredInstallerNames) {
+            $sourceAssets = @($sourceRelease.assets | Where-Object name -eq $name)
+            if ($sourceAssets.Count -ne 1) {
+              throw "Windows source release must contain exactly one required asset $name; found $($sourceAssets.Count)."
+            }
+            if ([string]$sourceAssets[0].digest -ne [string]$expectedDigests[$name]) {
+              throw "Windows source release asset digest does not match the pinned digest: $name"
+            }
           }
-          gh release view $env:RELEASE_TAG --repo $env:GITHUB_REPOSITORY | Out-Null
 
       - name: Download Windows Hub release installers
         shell: pwsh
         env:
           WINDOWS_NODE_TAG: ${{ inputs.windows_node_tag }}
+          EXPECTED_INSTALLER_DIGESTS: ${{ inputs.expected_installer_digests }}
           GH_TOKEN: ${{ github.token }}
         run: |
           New-Item -ItemType Directory -Force -Path dist | Out-Null
-          $tagArgs = @()
-          if ($env:WINDOWS_NODE_TAG -ne "latest") {
-            $tagArgs += $env:WINDOWS_NODE_TAG
-          }
-          gh release download @tagArgs `
-            --repo openclaw/openclaw-windows-node `
-            --pattern "OpenClawCompanion-Setup-*.exe" `
-            --dir dist
-
-          $expected = @(
-            "dist/OpenClawCompanion-Setup-x64.exe",
-            "dist/OpenClawCompanion-Setup-arm64.exe"
+          # Add future signed installer patterns, such as MSIX x64/ARM64, here.
+          # Every matched installer is signature-checked, checksummed, and promoted.
+          $installerPatterns = @(
+            "OpenClawCompanion-Setup-x64.exe",
+            "OpenClawCompanion-Setup-arm64.exe"
           )
-          foreach ($file in $expected) {
-            if (-not (Test-Path -LiteralPath $file)) {
-              throw "Missing expected Windows installer: $file"
+          $downloadArgs = @(
+            $env:WINDOWS_NODE_TAG,
+            "--repo", "openclaw/openclaw-windows-node",
+            "--dir", "dist"
+          )
+          foreach ($pattern in $installerPatterns) {
+            $downloadArgs += @("--pattern", $pattern)
+          }
+          gh release download @downloadArgs
+          if ($LASTEXITCODE -ne 0) {
+            throw "Failed to download Windows release assets from $env:WINDOWS_NODE_TAG."
+          }
+
+          foreach ($pattern in $installerPatterns) {
+            $patternMatches = @(Get-ChildItem -LiteralPath dist -File | Where-Object Name -Like $pattern)
+            if ($patternMatches.Count -ne 1) {
+              throw "Expected exactly one Windows installer matching '$pattern', found $($patternMatches.Count)."
+            }
+          }
+
+          $expectedDigests = $env:EXPECTED_INSTALLER_DIGESTS | ConvertFrom-Json -AsHashtable
+          foreach ($file in Get-ChildItem -LiteralPath dist -File) {
+            $expectedHash = ([string]$expectedDigests[$file.Name]) -replace '^sha256:', ''
+            $actualHash = (Get-FileHash -Algorithm SHA256 -LiteralPath $file.FullName).Hash
+            if ($actualHash -ne $expectedHash) {
+              throw "Downloaded Windows source asset does not match pinned digest: $($file.Name)"
             }
           }
 
       - name: Verify Authenticode signatures
         shell: pwsh
         run: |
-          Get-ChildItem -LiteralPath dist -Filter "OpenClawCompanion-Setup-*.exe" | ForEach-Object {
+          $expectedSignerSubject = "CN=OpenClaw Foundation, O=OpenClaw Foundation, L=Mill Valley, S=California, C=US"
+          Get-ChildItem -LiteralPath dist -File | ForEach-Object {
             $signature = Get-AuthenticodeSignature -LiteralPath $_.FullName
             if ($signature.Status -ne "Valid") {
               throw "$($_.Name) Authenticode signature was $($signature.Status)."
@@ -78,6 +164,9 @@ jobs:
             if (-not $signature.SignerCertificate) {
               throw "$($_.Name) has no signer certificate."
             }
+            if ($signature.SignerCertificate.Subject -ne $expectedSignerSubject) {
+              throw "$($_.Name) has unexpected signer subject $($signature.SignerCertificate.Subject)."
+            }
             [pscustomobject]@{
               File = $_.Name
               Signer = $signature.SignerCertificate.Subject
@@ -88,7 +177,7 @@ jobs:
       - name: Write SHA-256 manifest
         shell: pwsh
         run: |
-          Get-ChildItem -LiteralPath dist -Filter "OpenClawCompanion-Setup-*.exe" |
+          Get-ChildItem -LiteralPath dist -File |
             Sort-Object Name |
             ForEach-Object {
               $hash = Get-FileHash -Algorithm SHA256 -LiteralPath $_.FullName
@@ -101,12 +190,81 @@ jobs:
           RELEASE_TAG: ${{ inputs.tag }}
           GH_TOKEN: ${{ github.token }}
         run: |
-          gh release upload $env:RELEASE_TAG `
-            dist/OpenClawCompanion-Setup-x64.exe `
-            dist/OpenClawCompanion-Setup-arm64.exe `
-            dist/OpenClawCompanion-SHA256SUMS.txt `
-            --repo $env:GITHUB_REPOSITORY `
-            --clobber
+          $releaseAssets = @(Get-ChildItem -LiteralPath dist -File | Sort-Object Name | ForEach-Object FullName)
+          gh release upload $env:RELEASE_TAG @releaseAssets --repo $env:GITHUB_REPOSITORY --clobber
+          if ($LASTEXITCODE -ne 0) {
+            throw "Failed to upload Windows release assets to $env:RELEASE_TAG."
+          }
+
+      - name: Verify promoted release asset contract
+        shell: pwsh
+        env:
+          RELEASE_TAG: ${{ inputs.tag }}
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          New-Item -ItemType Directory -Force -Path verified | Out-Null
+          $expectedAssets = @(Get-ChildItem -LiteralPath dist -File | Sort-Object Name)
+          $expectedCompanionAssetNames = @($expectedAssets | ForEach-Object Name | Sort-Object)
+          $targetRelease = gh release view $env:RELEASE_TAG --repo $env:GITHUB_REPOSITORY --json assets | ConvertFrom-Json
+          $actualCompanionAssetNames = @(
+            $targetRelease.assets |
+              Where-Object { $_.name.StartsWith("OpenClawCompanion-") } |
+              ForEach-Object name |
+              Sort-Object
+          )
+          $assetContractDiff = @(
+            Compare-Object `
+              -ReferenceObject $expectedCompanionAssetNames `
+              -DifferenceObject $actualCompanionAssetNames
+          )
+          if (
+            $actualCompanionAssetNames.Count -ne $expectedCompanionAssetNames.Count -or
+            $assetContractDiff.Count -ne 0
+          ) {
+            throw "Promoted OpenClawCompanion asset names do not exactly match the current contract."
+          }
+
+          foreach ($asset in $expectedAssets) {
+            gh release download $env:RELEASE_TAG `
+              --repo $env:GITHUB_REPOSITORY `
+              --pattern $asset.Name `
+              --dir verified
+            if ($LASTEXITCODE -ne 0) {
+              throw "Failed to download promoted Windows release asset $($asset.Name)."
+            }
+          }
+
+          $manifestPath = "verified/OpenClawCompanion-SHA256SUMS.txt"
+          $manifestEntries = @(Get-Content -LiteralPath $manifestPath | ForEach-Object {
+            if ($_ -notmatch '^([A-Fa-f0-9]{64})  ([^\\/]+)$') {
+              throw "Invalid Windows SHA-256 manifest entry: $_"
+            }
+            [PSCustomObject]@{
+              Hash = $Matches[1]
+              Name = $Matches[2]
+            }
+          })
+          $expectedInstallerNames = @(
+            $expectedAssets |
+              Where-Object Name -ne "OpenClawCompanion-SHA256SUMS.txt" |
+              ForEach-Object Name
+          )
+          $manifestInstallerNames = @($manifestEntries | ForEach-Object Name | Sort-Object)
+          $contractDiff = @(
+            Compare-Object `
+              -ReferenceObject $expectedInstallerNames `
+              -DifferenceObject $manifestInstallerNames
+          )
+          if ($contractDiff.Count -ne 0) {
+            throw "Promoted Windows SHA-256 manifest does not match the installer asset contract."
+          }
+
+          foreach ($entry in $manifestEntries) {
+            $hash = (Get-FileHash -Algorithm SHA256 -LiteralPath "verified/$($entry.Name)").Hash
+            if ($hash -ne $entry.Hash) {
+              throw "Promoted Windows release asset checksum mismatch: $($entry.Name)"
+            }
+          }
 
       - name: Summary
         shell: pwsh
@@ -119,8 +277,9 @@ jobs:
 
           OpenClaw release: $env:RELEASE_TAG
           Source release: openclaw/openclaw-windows-node@$env:WINDOWS_NODE_TAG
-
-          - https://github.com/openclaw/openclaw/releases/download/$env:RELEASE_TAG/OpenClawCompanion-Setup-x64.exe
-          - https://github.com/openclaw/openclaw/releases/download/$env:RELEASE_TAG/OpenClawCompanion-Setup-arm64.exe
-          - https://github.com/openclaw/openclaw/releases/download/$env:RELEASE_TAG/OpenClawCompanion-SHA256SUMS.txt
           "@ >> $env:GITHUB_STEP_SUMMARY
+          Get-ChildItem -LiteralPath dist -File |
+            Sort-Object Name |
+            ForEach-Object {
+              "- https://github.com/openclaw/openclaw/releases/download/$env:RELEASE_TAG/$($_.Name)"
+            } >> $env:GITHUB_STEP_SUMMARY

CHANGELOG.md

@@ -24,7 +24,8 @@ Docs: https://docs.openclaw.ai
 ### Fixes
 
 - Channels and delivery: preserve account-scoped DM channel send policy, rich Telegram final replies, rich Telegram tables and lists, Telegram thread-create CLI remapping, Slack outbound `message_sent` hooks, contributed message-tool schema optionality, same-channel generated media completions, and channel chunking around surrogate pairs and Infinity limits. (#92788, #92679, #89421, #89943, #91137, #91246, #92735) Thanks @yetval, @obviyus, @spacegeologist, @rishitamrakar, @lundog, @TurboTheTurtle, and @yhterrance.
-- Agent, cron, and Gateway runtime: mark active main sessions before restart shutdown aborts, pause yielded subagent runs whose terminal also signals abort, preserve yielded media completions, de-duplicate main-session heartbeat events, expose session identity in runtime prompts, reject unknown OpenAI agent selectors, keep generated media completions in WebChat, and require admin privileges for HTTP session/model override surfaces. (#91357, #92631, #92146, #91287, #92468, #92510, #91246, #92651, #92646) Thanks @ooiuuii, @openperf, @IWhatsskill, @ZengWen-DT, @zhangguiping-xydt, and @TurboTheTurtle.
+- Discord: give generated auto-thread titles a 60-second timeout and 4,096-token reasoning-model output budget, clamped to the selected model output cap. (#64734) Thanks @hanamizuki.
+- Agent, cron, and Gateway runtime: mark active main sessions before restart shutdown aborts, pause yielded subagent runs whose terminal also signals abort, preserve yielded media completions, de-duplicate main-session heartbeat events, expose session identity in runtime prompts, reject unknown OpenAI agent selectors, keep generated media completions and slash-command block replies in WebChat, and require admin privileges for HTTP session/model override surfaces. (#91357, #92631, #92146, #91287, #92468, #92510, #91246, #92651, #92646) Thanks @ooiuuii, @openperf, @IWhatsskill, @ZengWen-DT, @zhangguiping-xydt, and @TurboTheTurtle.
 - Providers and model replay: preserve storeless OpenAI Responses replay compatibility, avoid eager tool streaming for Claude 4.5 in Copilot, honor profile auth for SecretRef model entries, bound model browsing, strip provider prefixes where runtimes need bare IDs, and surface nested embedding fetch failures. (#90706, #75393, #90686, #92247, #92627, #91218, #92628) Thanks @snowzlm, @Kailigithub, @rohitjavvadi, @samson910022, @liuhao1024, @bymle, and @mushuiyu886.
 - Memory, state, diagnostics, and config: split header-too-large embedding batches, keep QMD memory search enabled in transient mode, avoid SQLite WAL on NFS volumes, preserve recovery scheduling outside stuck-session warning backoff, and keep shell environment fallbacks contained in config write tests. (#92650, #92618, #92639, #91247, #92752) Thanks @mushuiyu886, @TurboTheTurtle, @849261680, and @gnanam1990.
 - UI/mobile/TUI: preserve dashboard session parent lineage, WebChat backscroll, reset soft command args, sidebar session picker interactivity, collapsed workspace files, resolved `/model` confirmation refs, and stale foreground iOS Gateway reconnects. (#90658, #92622, #91353, #92705, #92779, #92773, #92552) Thanks @luoyanglang, @TurboTheTurtle, @zhouhe-xydt, @NianJiuZst, @shakkernerd, @NarahariRaghava, and @Solvely-Colin.

apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift

@@ -2074,6 +2074,204 @@ public struct SessionsCompactionRestoreResult: Codable, Sendable {
     }
 }
 
+public struct SessionFileBrowserEntry: Codable, Sendable {
+    public let path: String
+    public let name: String
+    public let kind: AnyCodable
+    public let sessionkind: SessionFileRelevance?
+    public let size: Int?
+    public let updatedatms: Int?
+
+    public init(
+        path: String,
+        name: String,
+        kind: AnyCodable,
+        sessionkind: SessionFileRelevance?,
+        size: Int?,
+        updatedatms: Int?)
+    {
+        self.path = path
+        self.name = name
+        self.kind = kind
+        self.sessionkind = sessionkind
+        self.size = size
+        self.updatedatms = updatedatms
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case path
+        case name
+        case kind
+        case sessionkind = "sessionKind"
+        case size
+        case updatedatms = "updatedAtMs"
+    }
+}
+
+public struct SessionFileBrowserResult: Codable, Sendable {
+    public let path: String
+    public let parentpath: String?
+    public let search: String?
+    public let entries: [SessionFileBrowserEntry]
+    public let truncated: Bool?
+
+    public init(
+        path: String,
+        parentpath: String?,
+        search: String?,
+        entries: [SessionFileBrowserEntry],
+        truncated: Bool?)
+    {
+        self.path = path
+        self.parentpath = parentpath
+        self.search = search
+        self.entries = entries
+        self.truncated = truncated
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case path
+        case parentpath = "parentPath"
+        case search
+        case entries
+        case truncated
+    }
+}
+
+public struct SessionFileEntry: Codable, Sendable {
+    public let path: String
+    public let name: String
+    public let kind: SessionFileKind
+    public let missing: Bool
+    public let size: Int?
+    public let updatedatms: Int?
+    public let content: String?
+
+    public init(
+        path: String,
+        name: String,
+        kind: SessionFileKind,
+        missing: Bool,
+        size: Int?,
+        updatedatms: Int?,
+        content: String?)
+    {
+        self.path = path
+        self.name = name
+        self.kind = kind
+        self.missing = missing
+        self.size = size
+        self.updatedatms = updatedatms
+        self.content = content
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case path
+        case name
+        case kind
+        case missing
+        case size
+        case updatedatms = "updatedAtMs"
+        case content
+    }
+}
+
+public struct SessionsFilesListParams: Codable, Sendable {
+    public let sessionkey: String
+    public let agentid: String?
+    public let path: String?
+    public let search: String?
+
+    public init(
+        sessionkey: String,
+        agentid: String? = nil,
+        path: String?,
+        search: String?)
+    {
+        self.sessionkey = sessionkey
+        self.agentid = agentid
+        self.path = path
+        self.search = search
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case sessionkey = "sessionKey"
+        case agentid = "agentId"
+        case path
+        case search
+    }
+}
+
+public struct SessionsFilesListResult: Codable, Sendable {
+    public let sessionkey: String
+    public let root: String?
+    public let files: [SessionFileEntry]
+    public let browser: SessionFileBrowserResult?
+
+    public init(
+        sessionkey: String,
+        root: String?,
+        files: [SessionFileEntry],
+        browser: SessionFileBrowserResult?)
+    {
+        self.sessionkey = sessionkey
+        self.root = root
+        self.files = files
+        self.browser = browser
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case sessionkey = "sessionKey"
+        case root
+        case files
+        case browser
+    }
+}
+
+public struct SessionsFilesGetParams: Codable, Sendable {
+    public let sessionkey: String
+    public let path: String
+    public let agentid: String?
+
+    public init(
+        sessionkey: String,
+        path: String,
+        agentid: String? = nil)
+    {
+        self.sessionkey = sessionkey
+        self.path = path
+        self.agentid = agentid
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case sessionkey = "sessionKey"
+        case path
+        case agentid = "agentId"
+    }
+}
+
+public struct SessionsFilesGetResult: Codable, Sendable {
+    public let sessionkey: String
+    public let root: String?
+    public let file: SessionFileEntry
+
+    public init(
+        sessionkey: String,
+        root: String?,
+        file: SessionFileEntry)
+    {
+        self.sessionkey = sessionkey
+        self.root = root
+        self.file = file
+    }
+
+    private enum CodingKeys: String, CodingKey {
+        case sessionkey = "sessionKey"
+        case root
+        case file
+    }
+}
+
 public struct SessionsCreateParams: Codable, Sendable {
     public let key: String?
     public let agentid: String?

docs/.generated/config-baseline.sha256

@@ -1,4 +1,4 @@
-37b56008790612b8293930b6a29d74490e98daa90f954fca9d133fcc28645c4c  config-baseline.json
-75b64c2ea081369ba4306493313a8a4cd48b784145f92fed995e6b77a5df350d  config-baseline.core.json
-17d64c9799dfa239a49493413f1100bdd9237e9b67aaeae331a4604dbc227023  config-baseline.channel.json
-f9d1f50bfa8403891e76cd99dc1357cdece4a71e8ae18a39b190c2a14e6f97b0  config-baseline.plugin.json
+0485ba902d2afd89d2c41cde7180d0cec2900b2db6804b9f97d42b7d85cd3af5  config-baseline.json
+72bb80be618406f3337eaa2560d2559a35e49bd29576de8dd4a3aec1a6a94d92  config-baseline.core.json
+1218f5555541b61bd5ddcac6441f15061b44789e2471d4ffecbe3059777c55c1  config-baseline.channel.json
+a14ac4261e98403d1a7e047070e6f151938444e27382b860315bd0c74fda4861  config-baseline.plugin.json

docs/.generated/plugin-sdk-api-baseline.sha256

@@ -1,2 +1,2 @@
-0cca9891634edbdd08dfcebe0f29b36d7cf2729fd0c2ec3dd4615acef209a7eb  plugin-sdk-api-baseline.json
-2c763baab30411800b8931857e0a61e2710202394c2284f4c98e3e2f4231f88c  plugin-sdk-api-baseline.jsonl
+b121079a0912b3051a9fc319a675ef920da9db23364ca0c0ccd3c9f0a05a3a49  plugin-sdk-api-baseline.json
+61a0108da670e0f44ba4b861c002eb6eaa5cf63e392d4e7e7de42044cbe7d115  plugin-sdk-api-baseline.jsonl

docs/automation/tasks.md

@@ -311,7 +311,9 @@ $OPENCLAW_STATE_DIR/tasks/runs.sqlite
 
 The registry loads into memory at gateway start and syncs writes to SQLite for durability across restarts.
 The Gateway keeps the SQLite write-ahead log bounded by using SQLite's default
-autocheckpoint threshold plus periodic and shutdown `TRUNCATE` checkpoints.
+autocheckpoint threshold plus periodic `PASSIVE` checkpoints. Shutdown and
+explicit maintenance checkpoints still use `TRUNCATE` so normal closes can
+reclaim WAL space without making the background sweeper wait on active readers.
 
 ### Automatic maintenance
 

docs/channels/feishu.md

@@ -416,7 +416,9 @@ Enable `dynamicAgentCreation` to automatically create **isolated agent instances
 This is essential for public bots where you want each user to have their own private AI assistant experience.
 
 <Note>
-**Account limitation**: `dynamicAgentCreation` currently works with the **default Feishu account only**. Named/multi-account setups are not yet fully supported — dynamic bindings are created without `accountId`, so messages to named accounts may still route to `agent:main`. Track progress in [Issue #42837](https://github.com/openclaw/openclaw/issues/42837).
+Dynamic bindings include the normalized Feishu `accountId`, so default and named accounts route each sender to the correct dynamic agent.
+
+If a named account created an unscoped dynamic agent on an older release, that legacy agent still counts toward `maxAgents`. Confirm that it is not used by the default account before removing it, or temporarily increase `maxAgents`; OpenClaw cannot safely infer which account owns ambiguous legacy state.
 </Note>
 
 ### Quick setup
@@ -447,7 +449,7 @@ This is essential for public bots where you want each user to have their own pri
 
 When a new user sends their first DM:
 
-1. The channel generates a unique `agentId` = `feishu-{user_open_id}`
+1. The channel generates a unique `agentId`: `feishu-{user_open_id}` for the default account, or a bounded account-prefixed identity digest for a named account
 2. Creates a new workspace at `workspaceTemplate` path
 3. Registers the agent and creates a binding for this user
 4. The workspace helper ensures bootstrap files (`AGENTS.md`, `SOUL.md`, `USER.md`, etc.) on first access
@@ -464,22 +466,23 @@ When a new user sends their first DM:
 
 Template variables:
 
-- `{agentId}` - the generated agent ID (e.g., `feishu-ou_xxxxxx`)
+- `{agentId}` - the generated agent ID (e.g., `feishu-ou_xxxxxx` or `feishu-support-<identity_digest>`)
 - `{userId}` - the sender's Feishu open_id (e.g., `ou_xxxxxx`)
 
 ### Session scope
 
 `session.dmScope` controls how direct messages are mapped to agent sessions. This is a **global setting** that affects all channels.
 
-| Value                | Behavior                                                  | Best for                                                           |
-| -------------------- | --------------------------------------------------------- | ------------------------------------------------------------------ |
-| `"main"`             | Each user's DM maps to their agent's main session         | Single-user bots where you want `USER.md` / `SOUL.md` to auto-load |
-| `"per-channel-peer"` | Each (channel + user) combination gets a separate session | Public multi-user bots needing stronger isolation                  |
+| Value                        | Behavior                                                            | Best for                                                           |
+| ---------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| `"main"`                     | Each user's DM maps to their agent's main session                   | Single-user bots where you want `USER.md` / `SOUL.md` to auto-load |
+| `"per-channel-peer"`         | Each (channel + user) combination gets a separate session           | Public multi-user bots needing stronger isolation                  |
+| `"per-account-channel-peer"` | Each (account + channel + user) combination gets a separate session | Multi-account bots needing account-level session isolation         |
 
 **Tradeoff**: Using `"main"` enables automatic bootstrap file loading (`USER.md`, `SOUL.md`, `MEMORY.md`), but means all DMs across all channels share the same session key pattern. For public multi-user bots where isolation matters more than bootstrap auto-loading, consider `"per-channel-peer"` and manage bootstrap files manually.
 
 <Note>
-`"per-account-channel-peer"` is not recommended with `dynamicAgentCreation` because dynamic bindings are created without `accountId`. Use it only with manual bindings.
+Use `"per-account-channel-peer"` when named Feishu accounts should keep separate sessions for the same sender. Dynamic bindings preserve the account scope.
 </Note>
 
 ```json5

docs/ci.md

@@ -200,13 +200,19 @@ from `release/YYYY.M.PATCH` or `main` after the release tag exists and after the
 OpenClaw npm preflight has succeeded. It verifies `pnpm plugins:sync:check`,
 dispatches `Plugin NPM Release` for all publishable plugin packages, dispatches
 `Plugin ClawHub Release` for the same release SHA, and only then dispatches
-`OpenClaw NPM Release` with the saved `preflight_run_id`.
+`OpenClaw NPM Release` with the saved `preflight_run_id`. Stable publish also
+requires an exact `windows_node_tag`; the workflow verifies the Windows source
+release and compares its x64/ARM64 installers with the candidate-approved
+`windows_node_installer_digests` input before any publish child, then promotes
+and verifies those same pinned installer digests plus the exact companion asset
+and checksum contract before publishing the GitHub release draft.
 
 ```bash
 gh workflow run openclaw-release-publish.yml \
   --ref release/YYYY.M.PATCH \
   -f tag=vYYYY.M.PATCH-beta.N \
   -f preflight_run_id=<successful-openclaw-npm-preflight-run-id> \
+  -f full_release_validation_run_id=<successful-full-release-validation-run-id> \
   -f npm_dist_tag=beta
 ```
 

docs/cli/browser.md

@@ -174,7 +174,22 @@ Notes:
   or `--element`.
 - `existing-session` / `user` profiles support page screenshots and `--ref`
   screenshots from snapshot output, but not CSS `--element` screenshots.
-- `--labels` overlays current snapshot refs on the screenshot.
+- `--labels` overlays current snapshot refs on the screenshot. On
+  Playwright-backed profiles, it works with `--full-page` (full-page label
+  overlay), `--ref` (element-clip label overlay by ARIA ref), and `--element`
+  (element-clip label overlay by CSS selector); in element-clip modes, labels
+  are projected relative to the element. The response also includes an
+  `annotations` array with each ref's bounding box. Each item has `ref`,
+  `number`, `role`, optional `name`, and `box: {x, y, width, height}`;
+  coordinates are in the captured image's space (viewport / fullpage /
+  element-relative). The field is omitted when empty.
+  `existing-session` profiles render a chrome-mcp overlay on page screenshots
+  but do not use the Playwright projection helper and do not include
+  `annotations`; CSS `--element` screenshots are unsupported there. Without
+  Playwright or chrome-mcp, labeled screenshots are not available. Prior
+  releases ignored `--full-page`, `--ref`, and `--element` on labeled
+  Playwright screenshots and always returned a viewport capture; labeled
+  screenshots now honor those scopes.
 - `snapshot --urls` appends discovered link destinations to AI snapshots so
   agents can choose direct navigation targets instead of guessing from link
   text alone.

docs/concepts/active-memory.md

@@ -479,6 +479,9 @@ names that plugin registers. Active Memory lists those tools in the recall
 prompt and passes the same list to the embedded sub-agent. If none of the
 configured tools are available, or the memory sub-agent fails, Active Memory
 skips recall for that turn and the main reply continues without memory context.
+For custom recall tools, non-empty model-visible tool output counts as recall
+evidence unless structured result fields explicitly report an empty result or
+failure.
 `toolsAllow` only accepts concrete memory tool names. Wildcards, `group:*`
 entries, and core agent tools such as `read`, `exec`, `message`, and
 `web_search` are ignored before the hidden memory sub-agent starts.
@@ -743,7 +746,11 @@ Before v2026.5.2 the plugin silently extended your configured `timeoutMs` by an
 extra 30000 ms during cold-start so model warm-up, embedding-index load, and
 the first recall could share one larger budget. v2026.5.2 moved that grace
 behind an explicit `setupGraceTimeoutMs` config — your configured `timeoutMs`
-is now the budget by default, unless you opt in.
+is now the recall-work budget by default, unless you opt in. The blocking hook
+uses two bounded phases around that budget: up to 1500 ms for session/config
+preflight before recall starts, then a separate fixed 1500 ms for abort
+settlement and transcript recovery after recall work stops. Neither allowance
+extends model or tool execution.
 
 If you upgraded from v2026.4.x and you set `timeoutMs` to a value tuned for the
 old implicit-grace world (the recommended starter `timeoutMs: 15000` is one
@@ -765,14 +772,16 @@ outer watchdog budgets back to the pre-v5.2 effective values:
 }
 ```
 
-Per the v2026.5.2 changelog: _"use the configured recall timeout as the
-blocking prompt-build hook budget by default and move cold-start setup grace
-behind explicit `setupGraceTimeoutMs` config, so the plugin no longer silently
-extends 15000 ms configs to 45000 ms on the main lane."_
+The v2026.5.2 change removed the old implicit 30000 ms cold-start extension.
+Beyond the configured recall-work budget, the hook can use up to 1500 ms for
+preflight and another 1500 ms for post-recall completion. Its worst-case
+blocking time is therefore `timeoutMs + setupGraceTimeoutMs + 3000` ms.
 
 The embedded recall runner uses the same effective timeout budget, so
 `setupGraceTimeoutMs` covers both the outer prompt-build watchdog and the inner
-blocking recall run.
+blocking recall run. The preflight cap covers session/config checks before that
+budget begins. The post-recall allowance lets the outer hook settle abort
+cleanup and read any final transcript state.
 
 For resource-tight gateways where cold-start latency is a known trade-off,
 lower values (5000–15000 ms) work too — the trade-off is a higher chance of

docs/concepts/mantis.md

@@ -247,12 +247,13 @@ of only a bot-to-bot Slack transcript.
 evidence pipeline. It checks out the trusted candidate ref in a separate
 worktree, runs `pnpm openclaw qa telegram --credential-source convex
 --credential-role ci`, writes a `mantis-evidence.json` manifest from the
-Telegram QA summary and observed-message artifact, renders the redacted
-transcript HTML through a Crabbox desktop browser, generates a motion-trimmed GIF
-with `crabbox media preview`, and posts the inline PR evidence comment when a PR
-number is available. This lane is transcript-visual rather than logged-in
-Telegram Web proof: the Telegram Bot API gives stable live message evidence, but
-Telegram Web login state is not required for normal Mantis automation.
+Telegram QA summary, `qa-evidence.json`, and report artifacts, renders the
+redacted evidence HTML through a Crabbox desktop browser, generates a
+motion-trimmed GIF with `crabbox media preview`, and posts the inline PR
+evidence comment when a PR number is available. This lane is QA-evidence visual
+rather than logged-in Telegram Web proof: the Telegram Bot API gives stable live
+message evidence, but Telegram Web login state is not required for normal Mantis
+automation.
 
 `Mantis Telegram Desktop Proof` is the agentic native Telegram Desktop
 before/after wrapper. A maintainer can trigger it from a PR comment with
@@ -494,8 +495,8 @@ zero:
 
 - `pnpm openclaw qa discord` already runs a live Discord lane with driver and
   SUT bots.
-- The live transport runner already writes reports and observed-message
-  artifacts under `.artifacts/qa-e2e/`.
+- The live transport runner already writes reports, QA evidence, and
+  transport-specific artifacts under `.artifacts/qa-e2e/`.
 - Convex credential leases already provide exclusive access to shared live
   transport credentials.
 - The browser control service already supports screenshots, snapshots,

docs/concepts/qa-e2e-automation.md

@@ -318,17 +318,17 @@ Matrix has a [dedicated page](/concepts/qa-matrix) because of its scenario count
 
 These lanes register through `extensions/qa-lab/src/live-transports/shared/live-transport-cli.ts` and accept the same flags:
 
-| Flag                                  | Default                                            | Description                                                                                                           |
-| ------------------------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| `--scenario <id>`                     | -                                                  | Run only this scenario. Repeatable.                                                                                   |
-| `--output-dir <path>`                 | `<repo>/.artifacts/qa-e2e/<transport>-<timestamp>` | Where reports/summary/observed messages and the output log are written. Relative paths resolve against `--repo-root`. |
-| `--repo-root <path>`                  | `process.cwd()`                                    | Repository root when invoking from a neutral cwd.                                                                     |
-| `--sut-account <id>`                  | `sut`                                              | Temporary account id inside the QA gateway config.                                                                    |
-| `--provider-mode <mode>`              | `live-frontier`                                    | `mock-openai` or `live-frontier` (legacy `live-openai` still works).                                                  |
-| `--model <ref>` / `--alt-model <ref>` | provider default                                   | Primary/alternate model refs.                                                                                         |
-| `--fast`                              | off                                                | Provider fast mode where supported.                                                                                   |
-| `--credential-source <env\|convex>`   | `env`                                              | See [Convex credential pool](#convex-credential-pool).                                                                |
-| `--credential-role <maintainer\|ci>`  | `ci` in CI, `maintainer` otherwise                 | Role used when `--credential-source convex`.                                                                          |
+| Flag                                  | Default                                            | Description                                                                                                                                     |
+| ------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--scenario <id>`                     | -                                                  | Run only this scenario. Repeatable.                                                                                                             |
+| `--output-dir <path>`                 | `<repo>/.artifacts/qa-e2e/<transport>-<timestamp>` | Where reports, summaries, evidence, transport-specific artifacts, and the output log are written. Relative paths resolve against `--repo-root`. |
+| `--repo-root <path>`                  | `process.cwd()`                                    | Repository root when invoking from a neutral cwd.                                                                                               |
+| `--sut-account <id>`                  | `sut`                                              | Temporary account id inside the QA gateway config.                                                                                              |
+| `--provider-mode <mode>`              | `live-frontier`                                    | `mock-openai` or `live-frontier` (legacy `live-openai` still works).                                                                            |
+| `--model <ref>` / `--alt-model <ref>` | provider default                                   | Primary/alternate model refs.                                                                                                                   |
+| `--fast`                              | off                                                | Provider fast mode where supported.                                                                                                             |
+| `--credential-source <env\|convex>`   | `env`                                              | See [Convex credential pool](#convex-credential-pool).                                                                                          |
+| `--credential-role <maintainer\|ci>`  | `ci` in CI, `maintainer` otherwise                 | Role used when `--credential-source convex`.                                                                                                    |
 
 Each lane exits non-zero on any failed scenario. `--allow-failures` writes artifacts without setting a failing exit code.
 
@@ -346,10 +346,6 @@ Required env when `--credential-source env`:
 - `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN`
 - `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`
 
-Optional:
-
-- `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1` keeps message bodies in observed-message artifacts (default redacts).
-
 Scenarios (`extensions/qa-lab/src/live-transports/telegram/telegram-live.runtime.ts`):
 
 - `telegram-canary`
@@ -375,26 +371,26 @@ Output artifacts:
 
 - `telegram-qa-report.md`
 - `qa-evidence.json` - evidence entries for the live transport checks, including profile, coverage, provider, channel, artifacts, result, and RTT fields.
-- `telegram-qa-observed-messages.json` - bodies redacted unless `OPENCLAW_QA_TELEGRAM_CAPTURE_CONTENT=1`.
 
-Package RTT comparison uses the same Telegram credential contract while keeping
-its RTT sample controls on the RTT harness path:
+Package Telegram runs use the same Telegram credential contract. Repeated RTT
+measurement is part of the normal package Telegram live lane; the RTT
+distribution is folded into `qa-evidence.json` under `result.timing` for the
+selected RTT check.
 
 ```bash
-pnpm rtt openclaw@beta \
-  --credential-source convex \
-  --credential-role maintainer \
-  --samples 20 \
-  --sample-timeout-ms 30000
+OPENCLAW_QA_CREDENTIAL_SOURCE=convex \
+pnpm test:docker:npm-telegram-live
 ```
 
-When `--credential-source convex` is set, the RTT Docker wrapper leases a
-`kind: "telegram"` credential, exports the leased group/driver/SUT bot env into
-the installed-package run, heartbeats the lease, and releases it on shutdown.
-`--samples` and `--sample-timeout-ms` still feed
-`OPENCLAW_NPM_TELEGRAM_WARM_SAMPLES` and
-`OPENCLAW_NPM_TELEGRAM_SAMPLE_TIMEOUT_MS`, so `result.json` remains comparable
-across env-backed and Convex-backed RTT runs.
+When `OPENCLAW_QA_CREDENTIAL_SOURCE=convex` is set, the package live wrapper
+leases a `kind: "telegram"` credential, exports the leased group/driver/SUT bot
+env into the installed-package run, heartbeats the lease, and releases it on
+shutdown. The package wrapper defaults to 20 RTT checks of
+`telegram-mentioned-message-reply`, a 30s RTT timeout, and Convex role
+`maintainer` outside CI when Convex is selected. Override
+`OPENCLAW_NPM_TELEGRAM_RTT_SAMPLES`, `OPENCLAW_NPM_TELEGRAM_RTT_TIMEOUT_MS`,
+or `OPENCLAW_NPM_TELEGRAM_RTT_MAX_FAILURES` to tune RTT measurement without
+creating a separate RTT command or Telegram-specific summary format.
 
 ### Discord QA
 

docs/help/testing.md

@@ -218,17 +218,27 @@ inside every shard.
     `OPENCLAW_NPM_TELEGRAM_PACKAGE_TGZ=/path/to/openclaw-current.tgz` or
     `OPENCLAW_CURRENT_PACKAGE_TGZ` to test a resolved local tarball instead of
     installing from the registry.
+  - Emits repeated RTT timing in `qa-evidence.json` by default with
+    `OPENCLAW_NPM_TELEGRAM_RTT_SAMPLES=20`. Override
+    `OPENCLAW_NPM_TELEGRAM_RTT_SAMPLES`,
+    `OPENCLAW_NPM_TELEGRAM_RTT_TIMEOUT_MS`, or
+    `OPENCLAW_NPM_TELEGRAM_RTT_MAX_FAILURES` to tune the RTT run.
+    `OPENCLAW_NPM_TELEGRAM_RTT_CHECKS` accepts a comma-separated list of
+    Telegram QA check IDs to sample; when unset, the default RTT-capable check
+    is `telegram-mentioned-message-reply`.
   - Uses the same Telegram env credentials or Convex credential source as
     `pnpm openclaw qa telegram`. For CI/release automation, set
     `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex` plus
-    `OPENCLAW_QA_CONVEX_SITE_URL` and the role secret. If
+    `OPENCLAW_QA_CONVEX_SITE_URL` and a role secret. If
     `OPENCLAW_QA_CONVEX_SITE_URL` and a Convex role secret are present in CI,
     the Docker wrapper selects Convex automatically.
   - The wrapper validates Telegram or Convex credential env on the host before
     Docker build/install work. Set `OPENCLAW_NPM_TELEGRAM_SKIP_CREDENTIAL_PREFLIGHT=1`
     only when deliberately debugging pre-credential setup.
   - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` overrides the shared
-    `OPENCLAW_QA_CREDENTIAL_ROLE` for this lane only.
+    `OPENCLAW_QA_CREDENTIAL_ROLE` for this lane only. When Convex credentials
+    are selected and no role is set, the wrapper uses `ci` in CI and
+    `maintainer` outside CI.
   - GitHub Actions exposes this lane as the manual maintainer workflow
     `NPM Telegram Beta E2E`. It does not run on merge. The workflow uses the
     `qa-live-shared` environment and Convex CI credential leases.
@@ -344,11 +354,11 @@ gh workflow run package-acceptance.yml --ref main \
     want artifacts without a failing exit code.
   - Requires two distinct bots in the same private group, with the SUT bot exposing a Telegram username.
   - For stable bot-to-bot observation, enable Bot-to-Bot Communication Mode in `@BotFather` for both bots and ensure the driver bot can observe group bot traffic.
-  - Writes a Telegram QA report, summary, and observed-messages artifact under `.artifacts/qa-e2e/...`. Replying scenarios include RTT from driver send request to observed SUT reply.
+  - Writes a Telegram QA report, summary, and `qa-evidence.json` under `.artifacts/qa-e2e/...`. Replying scenarios include RTT from driver send request to observed SUT reply.
 
 `Mantis Telegram Live` is the PR-evidence wrapper around this lane. It runs the
-candidate ref with Convex-leased Telegram credentials, renders the redacted
-observed-message transcript in a Crabbox desktop browser, records MP4 evidence,
+candidate ref with Convex-leased Telegram credentials, renders the redacted QA
+report/evidence bundle in a Crabbox desktop browser, records MP4 evidence,
 generates a motion-trimmed GIF, uploads the artifact bundle, and posts inline PR
 evidence through the Mantis GitHub App when `pr_number` is set. Maintainers can
 start it from the Actions UI through `Mantis Scenario` (`scenario_id:

docs/plugins/codex-harness.md

@@ -143,12 +143,39 @@ The native Codex app-server harness supports context engines that require
 pre-prompt assembly. Generic CLI backends, including `codex-cli`, do not provide
 that host capability.
 
+Codex thread bindings live in OpenClaw's SQLite plugin state and use the stable
+agent-scoped OpenClaw session key, or an opaque conversation-binding id, as
+their owner. Physical session ids fence delayed cleanup but may rotate without
+losing the Codex thread. Context-engine compaction adopts the successor id
+before continuing native Codex compaction. The bounded store rejects a new
+binding at its safety limit instead of evicting an existing thread's continuity
+record.
+Conversation binds create or resume their Codex thread on the first bound
+message after channel approval; an abandoned approval consumes no thread row.
+That first message carries the prepared thread directly into its turn.
+Subsequent messages use a metadata-only resume to subscribe the shared client,
+then unsubscribe after the turn completes.
+The runtime does not poll transcript-adjacent binding files. Upgrades from
+releases that used `*.jsonl.codex-app-server.json` sidecars migrate them during
+normal startup preflight. `openclaw doctor --fix` can run the same migration
+manually.
+Successfully matched sidecars are archived before the new runtime resumes their
+threads. Migration imports durable thread ownership only; it does not infer
+Codex context usage from OpenClaw counters or crawl Codex rollout files. For
+agent-session harness bindings, the next resume attempts to restore a cached
+native snapshot when Codex has one, and ongoing turns persist the current-context
+usage reported by app-server notifications, not the cumulative thread lifetime
+total. Conversation bindings
+keep metadata-only resumes and leave continuity and compaction with the native
+Codex thread. Conflicting or ambiguous sidecars stay in place with a warning for
+operator review.
+
 For Codex-backed agents, `/compact` starts native Codex app-server compaction on
-the bound thread. OpenClaw does not wait for completion, impose an OpenClaw
-timeout, restart the shared app-server, or fall back to a context-engine or
-public OpenAI summarizer. If the native Codex thread binding is missing or
-stale, the command fails closed so the operator sees the real runtime boundary
-instead of silently switching compaction backends.
+the bound thread. OpenClaw bounds the request-acceptance RPC but does not wait
+for compaction completion, restart the shared app-server, or fall back to a
+context-engine or public OpenAI summarizer. If the native Codex thread binding
+is missing or stale, the command fails closed so the operator sees the real
+runtime boundary instead of silently switching compaction backends.
 
 ```json5
 {

docs/plugins/sdk-provider-plugins.md

@@ -515,6 +515,7 @@ API key auth, and dynamic model resolution.
 
       - `openclaw/plugin-sdk/provider-model-shared` - `ProviderReplayFamily`, `buildProviderReplayFamilyHooks(...)`, and the raw replay builders (`buildOpenAICompatibleReplayPolicy`, `buildAnthropicReplayPolicyForModel`, `buildGoogleGeminiReplayPolicy`, `buildHybridAnthropicOrOpenAIReplayPolicy`). Also exports Gemini replay helpers (`sanitizeGoogleGeminiReplayHistory`, `resolveTaggedReasoningOutputMode`) and endpoint/model helpers (`resolveProviderEndpoint`, `normalizeProviderId`, `normalizeGooglePreviewModelId`).
       - `openclaw/plugin-sdk/provider-stream` - `ProviderStreamFamily`, `buildProviderStreamFamilyHooks(...)`, `composeProviderStreamWrappers(...)`, plus the shared OpenAI/Codex wrappers (`createOpenAIAttributionHeadersWrapper`, `createOpenAIFastModeWrapper`, `createOpenAIServiceTierWrapper`, `createOpenAIResponsesContextManagementWrapper`, `createCodexNativeWebSearchWrapper`), DeepSeek V4 OpenAI-compatible wrapper (`createDeepSeekV4OpenAICompatibleThinkingWrapper`), Anthropic Messages thinking prefill cleanup (`createAnthropicThinkingPrefillPayloadWrapper`), plain-text tool-call compat (`createPlainTextToolCallCompatWrapper`), and shared proxy/provider wrappers (`createOpenRouterWrapper`, `createToolStreamWrapper`, `createMinimaxFastModeWrapper`).
+      - `openclaw/plugin-sdk/provider-stream-shared` - lightweight payload and event wrappers for hot provider paths, including `createOpenAICompatibleCompletionsThinkingOffWrapper`, `createPayloadPatchStreamWrapper`, and `createPlainTextToolCallCompatWrapper`.
       - `openclaw/plugin-sdk/provider-tools` - `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks("deepseek" | "gemini" | "openai")`, and underlying provider schema helpers.
 
       For Gemini-family providers, keep the reasoning-output mode aligned with

docs/plugins/sdk-subpaths.md

@@ -164,7 +164,7 @@ and pairing-path families.
     | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, and DeepSeek/Gemini/OpenAI schema cleanup + diagnostics |
     | `plugin-sdk/provider-usage` | Provider usage snapshot types, shared usage fetch helpers, and provider fetchers such as `fetchClaudeUsage` |
     | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, stream wrapper types, plain-text tool-call compat, and shared Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot wrapper helpers |
-    | `plugin-sdk/provider-stream-shared` | Public shared provider stream wrapper helpers including `composeProviderStreamWrappers`, `createPlainTextToolCallCompatWrapper`, `createPayloadPatchStreamWrapper`, `createToolStreamWrapper`, and Anthropic/DeepSeek/OpenAI-compatible stream utilities |
+    | `plugin-sdk/provider-stream-shared` | Public shared provider stream wrapper helpers including `composeProviderStreamWrappers`, `createOpenAICompatibleCompletionsThinkingOffWrapper`, `createPlainTextToolCallCompatWrapper`, `createPayloadPatchStreamWrapper`, `createToolStreamWrapper`, and Anthropic/DeepSeek/OpenAI-compatible stream utilities |
     | `plugin-sdk/provider-transport-runtime` | Native provider transport helpers such as guarded fetch, transport message transforms, and writable transport event streams |
     | `plugin-sdk/provider-onboard` | Onboarding config patch helpers |
     | `plugin-sdk/global-singleton` | Process-local singleton/map/cache helpers |
@@ -236,6 +236,7 @@ usage endpoint failed or returned no usable usage data.
     | `plugin-sdk/config-contracts` | Focused type-only config surface for plugin config shapes such as `OpenClawConfig` and channel/provider config types |
     | `plugin-sdk/plugin-config-runtime` | Runtime plugin-config lookup helpers such as `requireRuntimeConfig`, `resolvePluginConfigObject`, and `resolveLivePluginConfigObject` |
     | `plugin-sdk/config-mutation` | Transactional config mutation helpers such as `mutateConfigFile`, `replaceConfigFile`, and `logConfigUpdated` |
+    | `plugin-sdk/message-tool-delivery-hints` | Shared message-tool delivery metadata hint strings |
     | `plugin-sdk/runtime-config-snapshot` | Current process config snapshot helpers such as `getRuntimeConfig`, `getRuntimeConfigSnapshot`, and test snapshot setters |
     | `plugin-sdk/telegram-command-config` | Telegram command-name/description normalization and duplicate/conflict checks, even when the bundled Telegram contract surface is unavailable |
     | `plugin-sdk/text-autolink-runtime` | File-reference autolink detection without the broad text barrel |

docs/reference/RELEASING.md

@@ -99,10 +99,14 @@ the maintainer-only release runbook.
    file, lane, workflow job, package profile, provider, or model allowlist that
    proves the fix. Rerun the full umbrella only when the changed surface makes
    prior evidence stale.
-9. For beta, tag `vYYYY.M.PATCH-beta.N`, then run `pnpm release:candidate -- --tag
-vYYYY.M.PATCH-beta.N` from the matching `release/YYYY.M.PATCH` branch. The helper runs
-   the local generated-release checks, dispatches or verifies the full release
-   validation and npm preflight evidence, runs Parallels and Telegram package
+9. For a tagged beta candidate, run
+   `pnpm release:candidate -- --tag vYYYY.M.PATCH-beta.N` from the matching
+   `release/YYYY.M.PATCH` branch. For stable, pass the required Windows source
+   release too:
+   `pnpm release:candidate -- --tag vYYYY.M.PATCH --windows-node-tag vX.Y.Z`.
+   The helper runs the local generated-release checks, dispatches or verifies
+   the full release validation and npm preflight evidence, runs Parallels
+   fresh/update proof against the exact prepared tarball plus Telegram package
    proof, records plugin npm and ClawHub plans, and prints the exact
    `OpenClaw Release Publish` command only after the evidence bundle is green.
    `OpenClaw Release Publish` dispatches the selected or all-publishable plugin
@@ -142,9 +146,12 @@ vYYYY.M.PATCH-beta.N` from the matching `release/YYYY.M.PATCH` branch. The helpe
     direct push, it opens or updates an appcast PR. Stable Windows Hub
     readiness requires the signed `OpenClawCompanion-Setup-x64.exe`,
     `OpenClawCompanion-Setup-arm64.exe`, and
-    `OpenClawCompanion-SHA256SUMS.txt` assets on the OpenClaw GitHub release;
-    promote them with the `Windows Node Release` workflow after the matching
-    `openclaw/openclaw-windows-node` release has passed its signing workflow.
+    `OpenClawCompanion-SHA256SUMS.txt` assets on the OpenClaw GitHub release.
+    Pass the exact signed `openclaw/openclaw-windows-node` release tag as
+    `windows_node_tag` and its candidate-approved installer digest map as
+    `windows_node_installer_digests`; `OpenClaw Release Publish` keeps the
+    release draft, dispatches `Windows Node Release`, and verifies all three
+    assets before publication.
 11. After publish, run the npm post-publish verifier, optional standalone
     published-npm Telegram E2E when you need post-publish channel proof,
     dist-tag promotion when needed, verify the generated GitHub release page,
@@ -253,21 +260,36 @@ vYYYY.M.PATCH-beta.N` from the matching `release/YYYY.M.PATCH` branch. The helpe
   to the GitHub release as `openclaw-<version>-dependency-evidence.zip`.
 - Run `OpenClaw Release Publish` for the mutating publish sequence after the
   tag exists. Dispatch it from `release/YYYY.M.PATCH` (or `main` when publishing a
-  main-reachable tag), pass the release tag and successful OpenClaw npm
-  `preflight_run_id`, and keep the default plugin publish scope
-  `all-publishable` unless you are deliberately running a focused repair. The
-  workflow serializes plugin npm publish, plugin ClawHub publish, and OpenClaw
-  npm publish so the core package is not published before its externalized
-  plugins.
-- Run the manual `Windows Node Release` workflow for stable releases after the
-  matching `openclaw/openclaw-windows-node` release exists. It downloads the
-  signed Windows Hub installers from the companion repo, verifies their
-  Authenticode signatures on a Windows runner, writes a SHA-256 manifest, and
-  uploads the installers plus manifest onto the canonical OpenClaw GitHub
-  release. Website download links should target exact OpenClaw release asset
-  URLs for the current stable release, or `releases/latest/download/...` only
-  after verifying GitHub's latest redirect points at that same release; do not
-  link only to the companion repo release page.
+  main-reachable tag), pass the release tag, successful OpenClaw npm
+  `preflight_run_id`, and successful `full_release_validation_run_id`, and keep
+  the default plugin publish scope `all-publishable` unless you are deliberately
+  running a focused repair. The workflow serializes plugin npm publish, plugin
+  ClawHub publish, and OpenClaw npm publish so the core package is not published
+  before its externalized plugins.
+- Stable `OpenClaw Release Publish` requires an exact `windows_node_tag` after
+  the matching non-prerelease `openclaw/openclaw-windows-node` release exists.
+  It also requires the candidate-approved `windows_node_installer_digests` map.
+  Before dispatching any publish child, it verifies that source release is
+  published, non-prerelease, contains the required x64/ARM64 installers, and
+  still matches that approved map. It then dispatches `Windows Node Release`
+  while the OpenClaw release is still a draft, carrying the pinned installer
+  digest map unchanged. The child
+  workflow downloads the signed Windows Hub installers from that exact tag,
+  matches them against the pinned digests, verifies their Authenticode
+  signatures use the expected OpenClaw Foundation signer on a Windows runner,
+  writes a SHA-256 manifest, and uploads the installers plus manifest onto the
+  canonical OpenClaw GitHub release, then re-downloads the promoted assets and
+  verifies the manifest membership and hashes. The parent verifies the current
+  x64, ARM64, and checksum asset contract before publication. Direct recovery
+  rejects unexpected `OpenClawCompanion-*` asset names before replacing the
+  expected contract assets with the pinned source bytes. Manually dispatch
+  `Windows Node Release` only for recovery, and always pass an exact tag, never
+  `latest`, plus the explicit `expected_installer_digests` JSON map from the
+  approved source release. Website download links should target exact OpenClaw
+  release asset URLs for the current stable release, or
+  `releases/latest/download/...` only after verifying GitHub's latest redirect
+  points at that same release; do not link only to the companion repo release
+  page.
 - Release checks now run in a separate manual workflow:
   `OpenClaw Release Checks`
 - `OpenClaw Release Checks` also runs the QA Lab mock parity lane plus the fast
@@ -697,7 +719,12 @@ orchestrates the trusted-publisher workflows in the order the release needs:
    `ref=<release-sha>`.
 5. Dispatch `Plugin ClawHub Release` with the same scope and SHA.
 6. Dispatch `OpenClaw NPM Release` with the release tag, npm dist-tag, and
-   saved `preflight_run_id`.
+   saved `preflight_run_id` after verifying the saved
+   `full_release_validation_run_id`.
+7. For stable releases, create or update the GitHub release as a draft, dispatch
+   `Windows Node Release` with the explicit `windows_node_tag` and
+   candidate-approved `windows_node_installer_digests`, and verify the canonical
+   installer/checksum assets before publishing the draft.
 
 Beta publish example:
 
@@ -706,6 +733,7 @@ gh workflow run openclaw-release-publish.yml \
   --ref release/YYYY.M.PATCH \
   -f tag=vYYYY.M.PATCH-beta.N \
   -f preflight_run_id=<successful-openclaw-npm-preflight-run-id> \
+  -f full_release_validation_run_id=<successful-full-release-validation-run-id> \
   -f npm_dist_tag=beta
 ```
 
@@ -715,7 +743,10 @@ Stable publish to the default beta dist-tag:
 gh workflow run openclaw-release-publish.yml \
   --ref release/YYYY.M.PATCH \
   -f tag=vYYYY.M.PATCH \
+  -f windows_node_tag=vX.Y.Z \
+  -f windows_node_installer_digests='{"OpenClawCompanion-Setup-x64.exe":"sha256:<approved-x64-sha256>","OpenClawCompanion-Setup-arm64.exe":"sha256:<approved-arm64-sha256>"}' \
   -f preflight_run_id=<successful-openclaw-npm-preflight-run-id> \
+  -f full_release_validation_run_id=<successful-full-release-validation-run-id> \
   -f npm_dist_tag=beta
 ```
 
@@ -725,7 +756,10 @@ Stable promotion directly to `latest` is explicit:
 gh workflow run openclaw-release-publish.yml \
   --ref release/YYYY.M.PATCH \
   -f tag=vYYYY.M.PATCH \
+  -f windows_node_tag=vX.Y.Z \
+  -f windows_node_installer_digests='{"OpenClawCompanion-Setup-x64.exe":"sha256:<approved-x64-sha256>","OpenClawCompanion-Setup-arm64.exe":"sha256:<approved-arm64-sha256>"}' \
   -f preflight_run_id=<successful-openclaw-npm-preflight-run-id> \
+  -f full_release_validation_run_id=<successful-full-release-validation-run-id> \
   -f npm_dist_tag=latest
 ```
 
@@ -755,6 +789,13 @@ package cannot ship without every publishable official plugin, including
 - `tag`: required release tag; must already exist
 - `preflight_run_id`: successful `OpenClaw NPM Release` preflight run id;
   required when `publish_openclaw_npm=true`
+- `full_release_validation_run_id`: successful `Full Release Validation` run
+  id; required when `publish_openclaw_npm=true`
+- `windows_node_tag`: exact non-prerelease `openclaw/openclaw-windows-node`
+  release tag; required for stable OpenClaw publish
+- `windows_node_installer_digests`: candidate-approved compact JSON map of the
+  current Windows installer names to their pinned `sha256:` digests; required
+  for stable OpenClaw publish
 - `npm_dist_tag`: npm target tag for the OpenClaw package
 - `plugin_publish_scope`: defaults to `all-publishable`; use `selected` only
   for focused plugin-only repair work with `publish_openclaw_npm=false`
@@ -800,14 +841,21 @@ When cutting a stable npm release:
    Matrix, and Telegram coverage from one manual workflow
 4. If you intentionally only need the deterministic normal test graph, run the
    manual `CI` workflow on the release ref instead
-5. Save the successful `preflight_run_id`
-6. Run `OpenClaw Release Publish` with the same `tag`, the same `npm_dist_tag`,
-   and the saved `preflight_run_id`; it publishes externalized plugins to npm
-   and ClawHub before promoting the OpenClaw npm package
-7. If the release landed on `beta`, use the
+5. Select the exact non-prerelease `openclaw/openclaw-windows-node` release tag
+   whose signed x64 and ARM64 installers should ship. Save it as
+   `windows_node_tag`, and save their validated digest map as
+   `windows_node_installer_digests`. The release-candidate helper records both
+   and includes them in its generated publish command.
+6. Save the successful `preflight_run_id` and `full_release_validation_run_id`
+7. Run `OpenClaw Release Publish` with the same `tag`, the same `npm_dist_tag`,
+   the selected `windows_node_tag`, its saved `windows_node_installer_digests`,
+   the saved `preflight_run_id`, and the saved `full_release_validation_run_id`;
+   it publishes externalized plugins to npm and ClawHub before promoting the
+   OpenClaw npm package
+8. If the release landed on `beta`, use the
    `openclaw/releases/.github/workflows/openclaw-npm-dist-tags.yml`
    workflow to promote that stable version from `beta` to `latest`
-8. If the release intentionally published directly to `latest` and `beta`
+9. If the release intentionally published directly to `latest` and `beta`
    should follow the same stable build immediately, use that same release
    workflow to point both dist-tags at the stable version, or let its scheduled
    self-healing sync move `beta` later

docs/reference/transcript-hygiene.md

@@ -20,6 +20,7 @@ Scope includes:
 - Thinking signature cleanup
 - Image payload sanitization
 - Blank text-block cleanup before provider replay
+- Incomplete reasoning-only length-turn cleanup before provider replay
 - User-input provenance tagging (for inter-session routed prompts)
 - Empty assistant error-turn repair for Bedrock Converse replay
 
@@ -91,6 +92,21 @@ Implementation:
 
 ---
 
+## Global rule: incomplete reasoning-only turns
+
+Assistant turns that hit the provider output limit with only thinking or
+redacted-thinking content are omitted from the in-memory replay copy. Such turns
+contain incomplete provider state and may carry a partial thinking signature.
+
+Empty length turns remain unchanged, as do length turns with visible text, tool
+calls, or unknown content blocks. Stored transcripts are not rewritten.
+
+Implementation:
+
+- `normalizeAssistantReplayContent` in `src/agents/embedded-agent-runner/replay-history.ts`
+
+---
+
 ## Global rule: inter-session input provenance
 
 When an agent sends a prompt into another session via `sessions_send` (including

docs/tools/browser-control.md

@@ -13,7 +13,12 @@ CLI, and scripting patterns (snapshots, refs, waits, debug flows).
 
 ## Control API (optional)
 
-For local integrations only, the Gateway exposes a small loopback HTTP API:
+For local integrations only, the Gateway exposes a small loopback HTTP API.
+This standalone server is opt-in — set the environment variable
+`OPENCLAW_EAGER_BROWSER_CONTROL_SERVER=1` in the gateway service environment
+and restart the gateway before the HTTP endpoints become available. Without
+this variable the browser control runtime still works through the CLI and
+agent tools, but nothing listens on the loopback control port.
 
 - Status/start/stop: `GET /`, `POST /start`, `POST /stop`
 - Tabs: `GET /tabs`, `POST /tabs/open`, `POST /tabs/focus`, `DELETE /tabs/:targetId`
@@ -258,7 +263,14 @@ Snapshot flags at a glance:
 - `--format aria`: accessibility tree with `axN` refs. When Playwright is available, OpenClaw binds refs with backend DOM ids to the live page so follow-up actions can use them; otherwise treat the output as inspection-only.
 - `--efficient` (or `--mode efficient`): compact role snapshot preset. Set `browser.snapshotDefaults.mode: "efficient"` to make this the default (see [Gateway configuration](/gateway/configuration-reference#browser)).
 - `--interactive`, `--compact`, `--depth`, `--selector` force a role snapshot with `ref=e12` refs. `--frame "<iframe>"` scopes role snapshots to an iframe.
-- `--labels` adds a viewport-only screenshot with overlayed ref labels and prints the saved path.
+- With Playwright, `--labels` adds a screenshot with overlayed ref labels
+  (prints `MEDIA:<path>`) plus an `annotations` array with each ref's bounding
+  box. On `screenshot`, Playwright-backed labels work with `--full-page`,
+  `--ref`, and `--element`; on `snapshot`, the accompanying screenshot remains
+  viewport-only. Existing-session/chrome-mcp profiles render overlay labels on
+  page screenshots but do not return `annotations` or use the Playwright
+  full-page/ref/element projection helper. Without Playwright or chrome-mcp,
+  labeled screenshots are not available.
 - `--urls` appends discovered link destinations to AI snapshots.
 
 ## Snapshots and refs
@@ -274,7 +286,9 @@ OpenClaw supports two "snapshot" styles:
   - Output: a role-based list/tree with `[ref=e12]` (and optional `[nth=1]`).
   - Actions: `openclaw browser click e12`, `openclaw browser highlight e12`.
   - Internally, the ref is resolved via `getByRole(...)` (plus `nth()` for duplicates).
-  - Add `--labels` to include a viewport screenshot with overlayed `e12` labels.
+  - Add `--labels` to include a screenshot with overlayed `e12` labels. On
+    Playwright-backed profiles this also returns per-ref bounding-box metadata
+    (`annotations[]`).
   - Add `--urls` when link text is ambiguous and the agent needs concrete
     navigation targets.
 

docs/tools/tool-search.md

@@ -16,9 +16,9 @@ search or dynamic-tools surface. Codex-native code mode, tool search, deferred
 dynamic tools, and nested tool calls are stable Codex harness surfaces and do
 not depend on `tools.toolSearch`.
 
-When enabled for OpenClaw runs, the model receives one `tool_search_code` tool by default.
-That tool runs a short JavaScript body in an isolated Node subprocess with an
-`openclaw.tools` bridge:
+When enabled for OpenClaw runs, the model receives one `tool_search_code` tool
+by default. That tool runs a short JavaScript body in an isolated Node
+subprocess with an `openclaw.tools` bridge:
 
 ```js
 const hits = await openclaw.tools.search("create a GitHub issue");
@@ -49,8 +49,8 @@ run:
 3. List eligible MCP tools through the session MCP runtime.
 4. Add eligible client tools supplied for the current run.
 5. Index compact descriptors for search.
-6. Expose either the OpenClaw code bridge or the structured fallback tools to the
-   model.
+6. Expose the OpenClaw code bridge, the structured fallback tools, or the
+   compact directory surface to the model.
 
 At execution time every real tool call returns to OpenClaw. The isolated Node
 runtime does not hold plugin implementations, MCP client objects, or secrets.
@@ -59,18 +59,26 @@ normal policy, approval, hook, logging, and result handling still apply.
 
 ## Modes
 
-`tools.toolSearch` has two model-facing modes:
+`tools.toolSearch` has three model-facing modes:
 
 - `code`: exposes `tool_search_code`, the default compact JavaScript bridge.
 - `tools`: exposes `tool_search`, `tool_describe`, and `tool_call` as plain
   structured tools for providers that should not receive code.
+- `directory`: exposes `tool_search`, `tool_describe`, and `tool_call` plus a
+  bounded prompt directory of available tool names and descriptions for
+  providers that should see tool names without every full schema. OpenClaw can
+  also expose a small bounded set of likely or required tool schemas directly
+  for the current turn.
 
-Both modes use the same catalog and execution path. The only difference is the
-shape the model sees. If the current runtime cannot launch the isolated Node
-code-mode child process, the default `code` mode falls back to `tools` before
-catalog compaction.
+All modes use the same policy-filtered catalog and normal OpenClaw execution
+path. If the current runtime cannot launch the isolated Node code-mode child
+process, the default `code` mode falls back to `tools` before catalog
+compaction. In `directory` mode, client-provided tools stay directly visible
+for the current run while OpenClaw tools, plugin tools, and MCP tools can be
+compacted behind the directory catalog. A direct call to an exact hidden
+directory name is hydrated from that same authorized catalog before execution.
 
-Both modes are experimental. Prefer direct tool exposure for small OpenClaw tool
+All modes are experimental. Prefer direct tool exposure for small OpenClaw tool
 catalogs, and prefer the Codex-native stable surfaces for Codex harness runs.
 
 There is no separate source-selection config. When Tool Search is enabled, the
@@ -90,7 +98,10 @@ Tool Search changes the shape:
   contract
 - Tool Search tools mode: the model sees three compact structured fallback
   tools
-- during the turn: the model loads only the tool schemas it actually needs
+- Tool Search directory mode: the model sees a bounded directory plus
+  search/describe/call controls and a small bounded set of likely or required
+  schemas
+- during the turn: the model can load remaining schemas as needed
 
 Direct tool exposure is still the right default for small catalogs. Tool Search
 is best when one run can see many tools, especially from MCP servers or
@@ -132,6 +143,20 @@ The structured fallback mode exposes the same operations as tools:
 - `tool_describe`
 - `tool_call`
 
+Directory mode exposes:
+
+- `tool_search`
+- `tool_describe`
+- `tool_call`
+
+It also keeps client-provided tools directly visible and may expose a small
+bounded set of likely or required catalog tool schemas directly for the current
+turn. If the bounded directory omits entries, use `tool_search` to find them. If
+the model requests an exact hidden directory tool name directly, OpenClaw
+hydrates it from the authorized catalog before normal execution.
+Directory-mode client tool names must not collide with OpenClaw, plugin, or MCP
+tool names because exact deferred dispatch uses those names.
+
 ## Runtime boundary
 
 The code bridge runs in a short-lived Node subprocess. The subprocess starts
@@ -186,6 +211,18 @@ Use the structured fallback tools instead for OpenClaw runs:
 }
 ```
 
+Use the compact directory surface instead for OpenClaw runs:
+
+```json5
+{
+  tools: {
+    toolSearch: {
+      mode: "directory",
+    },
+  },
+}
+```
+
 Tune code-mode timeout and search result limits:
 
 ```json5

extensions/active-memory/openclaw.plugin.json

@@ -123,11 +123,12 @@
       "help": "Optional explicit denylist of chat/user IDs. Sessions whose resolved conversation id matches the list are skipped even when the chat type is allowed. Applied after allowedChatIds."
     },
     "timeoutMs": {
-      "label": "Timeout (ms)"
+      "label": "Timeout (ms)",
+      "help": "Recall work budget on the main lane. Before recall, the hook allows up to 1500 ms for session/config preflight. After recall starts, it reserves another fixed 1500 ms only for abort settlement and transcript recovery."
     },
     "setupGraceTimeoutMs": {
       "label": "Setup Grace Timeout (ms)",
-      "help": "Advanced: extra blocking budget for cold embedded-run setup before the recall timeout is considered exhausted. Defaults to 0 so timeoutMs remains the main-lane hook budget unless you opt in."
+      "help": "Advanced: extra recall-work budget for cold embedded-run setup. Defaults to 0. The separate 1500 ms preflight cap and 1500 ms post-recall completion allowance still apply."
     },
     "queryMode": {
       "label": "Query Mode",

extensions/browser/skills/browser-automation/SKILL.md

@@ -25,7 +25,7 @@ Use this skill when you need the `browser` tool for anything beyond a single pag
    - Use the same `targetId` for follow-up actions so refs stay on the same tab.
    - For durable Playwright refs, request `refs="aria"` when supported. If you receive `axN` refs from `snapshotFormat="aria"`, use them only after that same snapshot call; stale or unbound `axN` refs fail fast and need a fresh snapshot.
    - Use `urls=true` when link text is ambiguous or a direct navigation target would avoid brittle clicks.
-   - Use `labels=true` on snapshot or screenshot when visual position matters.
+   - Use `labels=true` on snapshot or screenshot when visual position matters. On Playwright-backed profiles, the response includes an `annotations` array (`{ref, number, role, name?, box}`) with each ref's bounding box in the captured image's coordinate space, so you can reason about position without re-snapshotting; screenshot labels can also combine with `fullPage=true` (CLI: `--full-page`) to label the whole document, or `ref` / `element` to clip to one element. `profile="user"` and other existing-session (chrome-mcp) profiles render an overlay into page screenshots but do not attach `annotations` or use the Playwright full-page/ref/element projection helper, so read positions from the labeled image itself on those profiles. The raw-CDP fallback (no Playwright) does not support labeled screenshots at all and returns a 501, so only request `labels` when Playwright is available.
 4. Act narrowly:
    - Prefer `action="act"` with a ref from the latest snapshot.
    - After navigation, modal changes, or form submission, snapshot again before the next action.

extensions/browser/src/browser-tool.actions.ts

@@ -486,6 +486,7 @@ export async function executeSnapshotAction(params: {
       labels: snapshot.labels,
       labelsCount: snapshot.labelsCount,
       labelsSkipped: snapshot.labelsSkipped,
+      annotations: snapshot.annotations,
       imagePath: snapshot.imagePath,
       imageType: snapshot.imageType,
       refsFallback,

extensions/browser/src/browser/client-actions-types.ts

@@ -1,6 +1,8 @@
 /**
  * Shared result types for browser client action helpers.
  */
+import type { AnnotationItem } from "./screenshot-annotate.js";
+
 /** Generic success result for action endpoints. */
 export type BrowserActionOk = { ok: true };
 
@@ -20,4 +22,10 @@ export type BrowserActionPathResult = {
   labels?: boolean;
   labelsCount?: number;
   labelsSkipped?: number;
+  /**
+   * Per-ref bounding boxes when labels=true. Coordinates are in the
+   * captured image's space (viewport / fullpage / element-relative).
+   * Omitted when empty.
+   */
+  annotations?: AnnotationItem[];
 };

extensions/browser/src/browser/client.ts

@@ -18,6 +18,7 @@ import type {
 } from "./client.types.js";
 import { DEFAULT_BROWSER_SNAPSHOT_TIMEOUT_MS } from "./constants.js";
 import type { BrowserDoctorReport } from "./doctor.js";
+import type { AnnotationItem } from "./screenshot-annotate.js";
 
 export type { BrowserStatus, BrowserTab, BrowserTransport } from "./client.types.js";
 export type { BrowserDoctorCheck, BrowserDoctorReport } from "./doctor.js";
@@ -124,6 +125,11 @@ export type SnapshotResult =
       labels?: boolean;
       labelsCount?: number;
       labelsSkipped?: number;
+      /**
+       * Per-ref bounding boxes when labels=true. Coordinates are in the
+       * captured image's space. Omitted when empty.
+       */
+      annotations?: AnnotationItem[];
       imagePath?: string;
       imageType?: "png" | "jpeg";
       blockedByDialog?: boolean;

extensions/browser/src/browser/pw-tools-core.annotate.test.ts

@@ -0,0 +1,205 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  installPwToolsCoreTestHooks,
+  setPwToolsCoreCurrentPage,
+  setPwToolsCoreCurrentRefLocator,
+} from "./pw-tools-core.test-harness.js";
+
+installPwToolsCoreTestHooks();
+const mod = await import("./pw-tools-core.js");
+
+type EvaluateArg = unknown;
+
+function evaluateMockReturning(view: { x: number; y: number; width?: number; height?: number }) {
+  // Caller reads { x, y, width, height } in one evaluate; default to a normal
+  // desktop viewport so refs near the top stay in-viewport unless a test puts
+  // them out of range explicitly.
+  const result = { width: 1280, height: 720, ...view };
+  return vi.fn(async (arg: EvaluateArg) => {
+    if (typeof arg === "function") {
+      return result;
+    }
+    return true;
+  });
+}
+
+describe("screenshotWithLabelsViaPlaywright (viewport)", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("calls page.screenshot without fullPage and returns annotations", async () => {
+    const evaluate = evaluateMockReturning({ x: 0, y: 100 });
+    const screenshot = vi.fn(async () => Buffer.from("PNG"));
+    setPwToolsCoreCurrentPage({ evaluate, screenshot, url: () => "https://example.com" });
+    setPwToolsCoreCurrentRefLocator({
+      boundingBox: async () => ({ x: 10, y: 200, width: 50, height: 20 }),
+    });
+
+    const result = await mod.screenshotWithLabelsViaPlaywright({
+      cdpUrl: "http://127.0.0.1:18792",
+      targetId: "T1",
+      refs: { e1: { role: "button", name: "Submit" } },
+      type: "png",
+    });
+
+    expect(screenshot).toHaveBeenCalledWith(expect.objectContaining({ type: "png" }));
+    expect(screenshot).not.toHaveBeenCalledWith(expect.objectContaining({ fullPage: true }));
+
+    expect(result.annotations).toHaveLength(1);
+    expect(result.annotations[0]).toMatchObject({
+      ref: "e1",
+      number: 1,
+      role: "button",
+      name: "Submit",
+    });
+    // viewport-mode box = doc(box.x + scroll.x, box.y + scroll.y) - scroll = bbox
+    expect(result.annotations[0]?.box).toEqual({ x: 10, y: 200, width: 50, height: 20 });
+    expect(result.skipped).toBe(0);
+  });
+
+  it("runs the clear script even when screenshot throws", async () => {
+    const evaluate = evaluateMockReturning({ x: 0, y: 0 });
+    const screenshot = vi.fn(async () => {
+      throw new Error("boom");
+    });
+    setPwToolsCoreCurrentPage({ evaluate, screenshot });
+    setPwToolsCoreCurrentRefLocator({
+      boundingBox: async () => ({ x: 0, y: 0, width: 1, height: 1 }),
+    });
+
+    await expect(
+      mod.screenshotWithLabelsViaPlaywright({
+        cdpUrl: "http://127.0.0.1:18792",
+        targetId: "T1",
+        refs: { e1: { role: "button" } },
+      }),
+    ).rejects.toThrow(/boom/);
+
+    // The clear script must have run (string evaluate calls include the overlay attr)
+    const clearCalls = evaluate.mock.calls.filter(
+      ([arg]) => typeof arg === "string" && arg.includes("data-openclaw-labels"),
+    );
+    // inject + clear = at least 2 string evaluations
+    expect(clearCalls.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it("counts off-viewport refs as skipped but still surfaces them in annotations", async () => {
+    const evaluate = evaluateMockReturning({ x: 0, y: 0, width: 1280, height: 720 });
+    const screenshot = vi.fn(async () => Buffer.from("PNG"));
+    setPwToolsCoreCurrentPage({ evaluate, screenshot });
+    // bbox is far below the viewport (y: 5000): not drawn, but still reported
+    // so callers keep the position and a non-zero skipped count.
+    setPwToolsCoreCurrentRefLocator({
+      boundingBox: async () => ({ x: 0, y: 5000, width: 50, height: 20 }),
+    });
+
+    const result = await mod.screenshotWithLabelsViaPlaywright({
+      cdpUrl: "http://127.0.0.1:18792",
+      targetId: "T1",
+      refs: { e1: { role: "button" } },
+    });
+
+    expect(result.skipped).toBe(1);
+    expect(result.labels).toBe(0);
+    expect(result.annotations).toHaveLength(1);
+    expect(result.annotations[0]?.ref).toBe("e1");
+  });
+});
+
+describe("screenshotWithLabelsViaPlaywright (fullpage)", () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it("forwards fullPage:true to page.screenshot and uses doc-space annotations", async () => {
+    const evaluate = evaluateMockReturning({ x: 0, y: 1000 });
+    const screenshot = vi.fn(async () => Buffer.from("FULL"));
+    setPwToolsCoreCurrentPage({ evaluate, screenshot });
+    setPwToolsCoreCurrentRefLocator({
+      boundingBox: async () => ({ x: 10, y: 200, width: 50, height: 20 }),
+    });
+
+    const result = await mod.screenshotWithLabelsViaPlaywright({
+      cdpUrl: "http://127.0.0.1:18792",
+      targetId: "T1",
+      refs: { e1: { role: "button" } },
+      fullPage: true,
+    });
+
+    expect(screenshot).toHaveBeenCalledWith(expect.objectContaining({ fullPage: true }));
+    // doc-space: scroll y=1000 + bbox y=200 = 1200
+    expect(result.annotations[0]?.box.y).toBe(1200);
+    expect(result.annotations[0]?.box.x).toBe(10);
+  });
+});
+
+describe("screenshotWithLabelsViaPlaywright (element/ref)", () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it("uses refLocator.screenshot for ref mode and projects relative to element", async () => {
+    const evaluate = evaluateMockReturning({ x: 0, y: 0 });
+    // First call resolves the element rect (container), second resolves e1 annotation bbox.
+    const boundingBox = vi
+      .fn<() => Promise<{ x: number; y: number; width: number; height: number } | null>>()
+      .mockResolvedValueOnce({ x: 50, y: 100, width: 200, height: 300 })
+      .mockResolvedValueOnce({ x: 60, y: 110, width: 30, height: 20 });
+    const elementScreenshot = vi.fn(async () => Buffer.from("ELEM"));
+    setPwToolsCoreCurrentPage({ evaluate, screenshot: vi.fn() });
+    setPwToolsCoreCurrentRefLocator({ boundingBox, screenshot: elementScreenshot });
+
+    const result = await mod.screenshotWithLabelsViaPlaywright({
+      cdpUrl: "http://127.0.0.1:18792",
+      targetId: "T1",
+      refs: { e1: { role: "button" } },
+      ref: "container",
+    });
+
+    expect(elementScreenshot).toHaveBeenCalledTimes(1);
+    // Element-relative: doc(60,110) - elementRect(50,100) = (10,10)
+    expect(result.annotations).toHaveLength(1);
+    expect(result.annotations[0]?.box).toEqual({ x: 10, y: 10, width: 30, height: 20 });
+  });
+
+  it("throws when ref/element cannot be resolved", async () => {
+    const evaluate = evaluateMockReturning({ x: 0, y: 0 });
+    setPwToolsCoreCurrentPage({ evaluate, screenshot: vi.fn() });
+    setPwToolsCoreCurrentRefLocator({
+      boundingBox: async () => null,
+      screenshot: vi.fn(),
+    });
+
+    await expect(
+      mod.screenshotWithLabelsViaPlaywright({
+        cdpUrl: "http://127.0.0.1:18792",
+        targetId: "T1",
+        refs: { e1: { role: "button" } },
+        ref: "missing",
+      }),
+    ).rejects.toThrow(/element not found/i);
+  });
+});
+
+describe("screenshotWithLabelsViaPlaywright (skipped accounting)", () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it("counts refs whose boundingBox is null toward skipped", async () => {
+    const evaluate = evaluateMockReturning({ x: 0, y: 0 });
+    const screenshot = vi.fn(async () => Buffer.from("PNG"));
+    setPwToolsCoreCurrentPage({ evaluate, screenshot });
+    // Two refs: first returns a box, second returns null (e.g. element detached).
+    const boundingBox = vi
+      .fn<() => Promise<{ x: number; y: number; width: number; height: number } | null>>()
+      .mockResolvedValueOnce({ x: 10, y: 20, width: 30, height: 40 })
+      .mockResolvedValueOnce(null);
+    setPwToolsCoreCurrentRefLocator({ boundingBox });
+
+    const result = await mod.screenshotWithLabelsViaPlaywright({
+      cdpUrl: "http://127.0.0.1:18792",
+      targetId: "T1",
+      refs: { e1: { role: "button" }, e2: { role: "link" } },
+    });
+
+    expect(result.annotations).toHaveLength(1);
+    expect(result.annotations[0]?.ref).toBe("e1");
+    expect(result.skipped).toBe(1);
+  });
+});

extensions/browser/src/browser/pw-tools-core.interactions.ts

@@ -41,6 +41,15 @@ import {
   toAIFriendlyError,
 } from "./pw-tools-core.shared.js";
 import { closePageViaPlaywright, resizeViewportViaPlaywright } from "./pw-tools-core.snapshot.js";
+import {
+  ANNOTATION_MAX_LABELS_DEFAULT,
+  type AnnotationItem,
+  buildOverlayClearScript,
+  buildOverlayInjectionScript,
+  type CoordinateSpace,
+  planAnnotations,
+  type RawAnnotationInput,
+} from "./screenshot-annotate.js";
 
 type TargetOpts = {
   cdpUrl: string;
@@ -1287,7 +1296,15 @@ export async function screenshotWithLabelsViaPlaywright(opts: {
   maxLabels?: number;
   type?: "png" | "jpeg";
   timeoutMs?: number;
-}): Promise<{ buffer: Buffer; labels: number; skipped: number }> {
+  fullPage?: boolean;
+  ref?: string;
+  element?: string;
+}): Promise<{
+  buffer: Buffer;
+  labels: number;
+  skipped: number;
+  annotations: AnnotationItem[];
+}> {
   const page = await getPageForTargetId(opts);
   ensurePageState(page);
   restoreRoleRefsForTarget({ cdpUrl: opts.cdpUrl, targetId: opts.targetId, page });
@@ -1295,119 +1312,151 @@ export async function screenshotWithLabelsViaPlaywright(opts: {
   const maxLabels =
     typeof opts.maxLabels === "number" && Number.isFinite(opts.maxLabels)
       ? Math.max(1, Math.floor(opts.maxLabels))
-      : 150;
+      : ANNOTATION_MAX_LABELS_DEFAULT;
 
-  const viewport = await page.evaluate(() => ({
-    scrollX: window.scrollX || 0,
-    scrollY: window.scrollY || 0,
+  const refKey = normalizeOptionalString(opts.ref) ?? undefined;
+  const elementSelector = normalizeOptionalString(opts.element) ?? undefined;
+  const space: CoordinateSpace = opts.fullPage
+    ? "fullpage"
+    : refKey || elementSelector
+      ? "element"
+      : "viewport";
+
+  // Read scroll + viewport size. Scroll converts Playwright's viewport-space
+  // boundingBoxes into document-space inputs; the viewport size lets the helper
+  // restore the shipped `labelsSkipped` semantics by counting off-viewport refs
+  // as skipped (in viewport capture mode).
+  const view = await page.evaluate(() => ({
+    x: window.scrollX || 0,
+    y: window.scrollY || 0,
     width: window.innerWidth || 0,
     height: window.innerHeight || 0,
   }));
+  const scroll = { x: view.x, y: view.y };
 
-  const refs = Object.keys(opts.refs ?? {});
-  const boxes: Array<{ ref: string; x: number; y: number; w: number; h: number }> = [];
-  let skipped = 0;
+  let elementRect: { x: number; y: number; width: number; height: number } | undefined;
+  if (space === "element") {
+    const box = await resolveElementBoundingBoxForLabels(page, refKey, elementSelector);
+    if (!box) {
+      throw new Error(
+        `screenshotWithLabelsViaPlaywright: element not found for ${
+          refKey ? `ref="${refKey}"` : `selector="${elementSelector ?? ""}"`
+        }`,
+      );
+    }
+    // Convert viewport-space bbox to document space.
+    elementRect = {
+      x: box.x + scroll.x,
+      y: box.y + scroll.y,
+      width: box.width,
+      height: box.height,
+    };
+  }
 
-  for (const ref of refs) {
-    if (boxes.length >= maxLabels) {
-      skipped += 1;
+  const refKeys = Object.keys(opts.refs ?? {});
+  const inputs: RawAnnotationInput[] = [];
+  let bboxFailures = 0;
+  for (const ref of refKeys) {
+    const box = await refLocator(page, ref)
+      .boundingBox()
+      .catch(() => null);
+    if (!box) {
+      bboxFailures += 1;
       continue;
     }
-    try {
-      const box = await refLocator(page, ref).boundingBox();
-      if (!box) {
-        skipped += 1;
-        continue;
-      }
-      const x0 = box.x;
-      const y0 = box.y;
-      const x1 = box.x + box.width;
-      const y1 = box.y + box.height;
-      const vx0 = viewport.scrollX;
-      const vy0 = viewport.scrollY;
-      const vx1 = viewport.scrollX + viewport.width;
-      const vy1 = viewport.scrollY + viewport.height;
-      if (x1 < vx0 || x0 > vx1 || y1 < vy0 || y0 > vy1) {
-        skipped += 1;
-        continue;
-      }
-      boxes.push({
-        ref,
-        x: x0 - viewport.scrollX,
-        y: y0 - viewport.scrollY,
-        w: Math.max(1, box.width),
-        h: Math.max(1, box.height),
-      });
-    } catch {
-      skipped += 1;
-    }
+    inputs.push({
+      ref,
+      role: opts.refs[ref].role,
+      name: opts.refs[ref].name,
+      doc: {
+        x: box.x + scroll.x,
+        y: box.y + scroll.y,
+        width: box.width,
+        height: box.height,
+      },
+    });
   }
 
+  const plan = planAnnotations({
+    inputs,
+    space,
+    scroll,
+    viewport: { width: view.width, height: view.height },
+    elementRect,
+    maxLabels,
+  });
+
   try {
-    if (boxes.length > 0) {
-      await page.evaluate((labels) => {
-        const existing = document.querySelectorAll("[data-openclaw-labels]");
-        existing.forEach((el) => el.remove());
-
-        const root = document.createElement("div");
-        root.setAttribute("data-openclaw-labels", "1");
-        root.style.position = "fixed";
-        root.style.left = "0";
-        root.style.top = "0";
-        root.style.zIndex = "2147483647";
-        root.style.pointerEvents = "none";
-        root.style.fontFamily =
-          '"SF Mono","SFMono-Regular",Menlo,Monaco,Consolas,"Liberation Mono","Courier New",monospace';
-
-        const clamp = (value: number, min: number, max: number) =>
-          Math.min(max, Math.max(min, value));
-
-        for (const label of labels) {
-          const box = document.createElement("div");
-          box.setAttribute("data-openclaw-labels", "1");
-          box.style.position = "absolute";
-          box.style.left = `${label.x}px`;
-          box.style.top = `${label.y}px`;
-          box.style.width = `${label.w}px`;
-          box.style.height = `${label.h}px`;
-          box.style.border = "2px solid #ffb020";
-          box.style.boxSizing = "border-box";
-
-          const tag = document.createElement("div");
-          tag.setAttribute("data-openclaw-labels", "1");
-          tag.textContent = label.ref;
-          tag.style.position = "absolute";
-          tag.style.left = `${label.x}px`;
-          tag.style.top = `${clamp(label.y - 18, 0, 20000)}px`;
-          tag.style.background = "#ffb020";
-          tag.style.color = "#1a1a1a";
-          tag.style.fontSize = "12px";
-          tag.style.lineHeight = "14px";
-          tag.style.padding = "1px 4px";
-          tag.style.borderRadius = "3px";
-          tag.style.boxShadow = "0 1px 2px rgba(0,0,0,0.35)";
-          tag.style.whiteSpace = "nowrap";
-
-          root.appendChild(box);
-          root.appendChild(tag);
-        }
-
-        document.documentElement.appendChild(root);
-      }, boxes);
+    if (plan.overlayItems.length > 0) {
+      const captureY = space === "element" ? elementRect?.y : space === "viewport" ? scroll.y : 0;
+      await page.evaluate(buildOverlayInjectionScript({ items: plan.overlayItems, captureY }));
     }
-
-    const buffer = await page.screenshot({ type, timeout: opts.timeoutMs });
-    return { buffer, labels: boxes.length, skipped };
+    const buffer =
+      space === "element"
+        ? await captureElementScreenshotForLabels(
+            page,
+            refKey,
+            elementSelector,
+            type,
+            opts.timeoutMs,
+          )
+        : await page.screenshot({
+            type,
+            fullPage: Boolean(opts.fullPage),
+            timeout: opts.timeoutMs,
+          });
+    return {
+      // `labels` reports overlay boxes actually drawn on the captured image
+      // (in-viewport, within budget); off-viewport refs are surfaced via
+      // `annotations` but not drawn, and are reflected in `skipped`.
+      buffer,
+      labels: plan.overlayItems.length,
+      skipped: plan.skipped + bboxFailures,
+      annotations: plan.annotations,
+    };
   } finally {
-    await page
-      .evaluate(() => {
-        const existing = document.querySelectorAll("[data-openclaw-labels]");
-        existing.forEach((el) => el.remove());
-      })
-      .catch(() => {});
+    await page.evaluate(buildOverlayClearScript()).catch(() => {});
   }
 }
 
+async function resolveElementBoundingBoxForLabels(
+  page: Page,
+  refKey: string | undefined,
+  cssSelector: string | undefined,
+): Promise<{ x: number; y: number; width: number; height: number } | null> {
+  if (refKey) {
+    try {
+      return await refLocator(page, refKey).boundingBox();
+    } catch {
+      return null;
+    }
+  }
+  if (cssSelector) {
+    try {
+      return await page.locator(cssSelector).first().boundingBox();
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+async function captureElementScreenshotForLabels(
+  page: Page,
+  refKey: string | undefined,
+  cssSelector: string | undefined,
+  type: "png" | "jpeg",
+  timeoutMs: number | undefined,
+): Promise<Buffer> {
+  if (refKey) {
+    return await refLocator(page, refKey).screenshot({ type, timeout: timeoutMs });
+  }
+  if (cssSelector) {
+    return await page.locator(cssSelector).first().screenshot({ type, timeout: timeoutMs });
+  }
+  throw new Error("captureElementScreenshotForLabels: requires refKey or cssSelector");
+}
+
 /** Sets file inputs for a role ref or selector with strict existing-path checks. */
 export async function setInputFilesViaPlaywright(opts: {
   cdpUrl: string;

extensions/browser/src/browser/routes/agent.snapshot.ts

@@ -5,6 +5,7 @@
  * navigation policy checks, media storage, and screenshot normalization.
  */
 import path from "node:path";
+import { getImageMetadata } from "../../media/media-services.js";
 import { ensureMediaDir, saveMediaBuffer } from "../../media/store.js";
 import { captureScreenshot, snapshotAria, snapshotRoleViaCdp } from "../cdp.js";
 import {
@@ -24,6 +25,8 @@ import {
   assertBrowserNavigationResultAllowed,
 } from "../navigation-guard.js";
 import { getBrowserProfileCapabilities } from "../profile-capabilities.js";
+import type { AnnotationItem } from "../screenshot-annotate.js";
+import { scaleAnnotations } from "../screenshot-annotate.js";
 import {
   DEFAULT_BROWSER_SCREENSHOT_MAX_BYTES,
   DEFAULT_BROWSER_SCREENSHOT_MAX_SIDE,
@@ -192,11 +195,24 @@ async function saveNormalizedScreenshotResponse(params: {
   labels?: boolean;
   labelsCount?: number;
   labelsSkipped?: number;
+  annotations?: AnnotationItem[];
 }) {
+  // Measure original dimensions BEFORE normalization so we can rescale
+  // annotation coordinates if the response pipeline shrinks the image
+  // (longest-side or byte-budget cap). Annotation boxes are in the captured
+  // image's pixel space, so they would otherwise drift from the saved media.
+  const originalMeta = params.annotations?.length
+    ? ((await getImageMetadata(params.buffer)) ?? undefined)
+    : undefined;
   const normalized = await normalizeBrowserScreenshot(params.buffer, {
     maxSide: DEFAULT_BROWSER_SCREENSHOT_MAX_SIDE,
     maxBytes: DEFAULT_BROWSER_SCREENSHOT_MAX_BYTES,
   });
+  const annotations = await rescaleAnnotationsForNormalization({
+    annotations: params.annotations,
+    originalMeta,
+    normalizedBuffer: normalized.buffer,
+  });
   await saveBrowserMediaResponse({
     res: params.res,
     buffer: normalized.buffer,
@@ -207,9 +223,39 @@ async function saveNormalizedScreenshotResponse(params: {
     labels: params.labels,
     labelsCount: params.labelsCount,
     labelsSkipped: params.labelsSkipped,
+    annotations,
   });
 }
 
+/**
+ * Keep annotation coordinates aligned with the saved media after
+ * normalizeBrowserScreenshot. Returns the original annotations unchanged
+ * when normalization did not change the image dimensions, or when image
+ * metadata is unavailable (best-effort: better to ship pre-resize coords
+ * than to drop the field entirely).
+ */
+async function rescaleAnnotationsForNormalization(params: {
+  annotations?: AnnotationItem[];
+  originalMeta?: { width?: number; height?: number };
+  normalizedBuffer: Buffer;
+}): Promise<AnnotationItem[] | undefined> {
+  if (!params.annotations || params.annotations.length === 0) {
+    return params.annotations;
+  }
+  const orig = params.originalMeta;
+  if (!orig?.width || !orig?.height) {
+    return params.annotations;
+  }
+  const next = await getImageMetadata(params.normalizedBuffer);
+  if (!next?.width || !next?.height) {
+    return params.annotations;
+  }
+  if (next.width === orig.width && next.height === orig.height) {
+    return params.annotations;
+  }
+  return scaleAnnotations(params.annotations, next.width / orig.width, next.height / orig.height);
+}
+
 async function saveBrowserMediaResponse(params: {
   res: BrowserResponse;
   buffer: Buffer;
@@ -220,6 +266,7 @@ async function saveBrowserMediaResponse(params: {
   labels?: boolean;
   labelsCount?: number;
   labelsSkipped?: number;
+  annotations?: AnnotationItem[];
 }) {
   await ensureMediaDir();
   const saved = await saveMediaBuffer(
@@ -236,6 +283,9 @@ async function saveBrowserMediaResponse(params: {
     ...(params.labels ? { labels: true } : {}),
     ...(typeof params.labelsCount === "number" ? { labelsCount: params.labelsCount } : {}),
     ...(typeof params.labelsSkipped === "number" ? { labelsSkipped: params.labelsSkipped } : {}),
+    ...(params.annotations && params.annotations.length > 0
+      ? { annotations: params.annotations }
+      : {}),
   });
 }
 
@@ -478,6 +528,9 @@ export function registerBrowserAgentSnapshotRoutes(
                 refs: snap.refs,
                 type,
                 timeoutMs,
+                fullPage,
+                ref,
+                element,
               });
               await saveNormalizedScreenshotResponse({
                 res,
@@ -488,6 +541,7 @@ export function registerBrowserAgentSnapshotRoutes(
                 labels: true,
                 labelsCount: labeled.labels,
                 labelsSkipped: labeled.skipped,
+                annotations: labeled.annotations,
               });
               return;
             }
@@ -743,10 +797,18 @@ export function registerBrowserAgentSnapshotRoutes(
               type: "png",
               timeoutMs: plan.timeoutMs,
             });
+            const originalMeta = labeled.annotations.length
+              ? ((await getImageMetadata(labeled.buffer)) ?? undefined)
+              : undefined;
             const normalized = await normalizeBrowserScreenshot(labeled.buffer, {
               maxSide: DEFAULT_BROWSER_SCREENSHOT_MAX_SIDE,
               maxBytes: DEFAULT_BROWSER_SCREENSHOT_MAX_BYTES,
             });
+            const scaledAnnotations = await rescaleAnnotationsForNormalization({
+              annotations: labeled.annotations,
+              originalMeta,
+              normalizedBuffer: normalized.buffer,
+            });
             await ensureMediaDir();
             const saved = await saveMediaBuffer(
               normalized.buffer,
@@ -764,6 +826,9 @@ export function registerBrowserAgentSnapshotRoutes(
               labels: true,
               labelsCount: labeled.labels,
               labelsSkipped: labeled.skipped,
+              ...(scaledAnnotations && scaledAnnotations.length > 0
+                ? { annotations: scaledAnnotations }
+                : {}),
               imagePath: path.resolve(saved.path),
               imageType,
               ...snap,

extensions/browser/src/browser/screenshot-annotate.test.ts

@@ -0,0 +1,345 @@
+import { describe, expect, it } from "vitest";
+import {
+  ANNOTATION_OVERLAY_ATTR,
+  type AnnotationItem,
+  buildOverlayClearScript,
+  buildOverlayInjectionScript,
+  planAnnotations,
+  type RawAnnotationInput,
+  refToNumber,
+  scaleAnnotations,
+} from "./screenshot-annotate.js";
+
+const sampleInputs: RawAnnotationInput[] = [
+  {
+    ref: "e1",
+    role: "button",
+    name: "Submit",
+    doc: { x: 100, y: 200, width: 50, height: 20 },
+  },
+  {
+    ref: "e2",
+    role: "link",
+    doc: { x: 300, y: 1500, width: 80, height: 18 },
+  },
+];
+
+describe("refToNumber", () => {
+  it("extracts number from `e<N>` form", () => {
+    expect(refToNumber("e12")).toBe(12);
+    expect(refToNumber("e0")).toBe(0);
+  });
+
+  it("extracts number from `ax<N>` form", () => {
+    expect(refToNumber("ax12")).toBe(12);
+  });
+
+  it("extracts number from bare numeric form", () => {
+    expect(refToNumber("12")).toBe(12);
+  });
+
+  it("returns 0 for non-numeric refs", () => {
+    expect(refToNumber("foo")).toBe(0);
+    expect(refToNumber("")).toBe(0);
+  });
+});
+
+describe("planAnnotations - viewport mode", () => {
+  it("subtracts scroll from doc coords", () => {
+    const plan = planAnnotations({
+      inputs: sampleInputs,
+      space: "viewport",
+      scroll: { x: 0, y: 1000 },
+    });
+
+    expect(plan.annotations).toHaveLength(2);
+    expect(plan.annotations[0]).toEqual({
+      ref: "e1",
+      number: 1,
+      role: "button",
+      name: "Submit",
+      box: { x: 100, y: -800, width: 50, height: 20 },
+    });
+    expect(plan.annotations[1]).toEqual({
+      ref: "e2",
+      number: 2,
+      role: "link",
+      box: { x: 300, y: 500, width: 80, height: 18 },
+    });
+    expect(plan.skipped).toBe(0);
+  });
+
+  it("keeps overlay items in document space regardless of mode", () => {
+    const plan = planAnnotations({
+      inputs: sampleInputs,
+      space: "viewport",
+      scroll: { x: 0, y: 1000 },
+    });
+    expect(plan.overlayItems).toEqual([
+      { ref: "e1", x: 100, y: 200, w: 50, h: 20 },
+      { ref: "e2", x: 300, y: 1500, w: 80, h: 18 },
+    ]);
+  });
+
+  it("omits empty name field", () => {
+    const plan = planAnnotations({
+      inputs: [{ ref: "e1", role: "button", name: "", doc: { x: 0, y: 0, width: 1, height: 1 } }],
+      space: "viewport",
+      scroll: { x: 0, y: 0 },
+    });
+    expect(plan.annotations[0]).not.toHaveProperty("name");
+  });
+
+  it("throws when scroll missing in viewport mode", () => {
+    expect(() => planAnnotations({ inputs: sampleInputs, space: "viewport" })).toThrow(/scroll/);
+  });
+});
+
+describe("planAnnotations - viewport off-screen accounting", () => {
+  it("counts off-viewport refs as skipped but keeps them in annotations when viewport size is given", () => {
+    const plan = planAnnotations({
+      inputs: [
+        { ref: "e1", role: "button", doc: { x: 10, y: 50, width: 40, height: 20 } }, // in viewport
+        { ref: "e2", role: "link", doc: { x: 10, y: 5000, width: 40, height: 20 } }, // below viewport
+      ],
+      space: "viewport",
+      scroll: { x: 0, y: 0 },
+      viewport: { width: 1280, height: 720 },
+    });
+
+    // Only the in-viewport ref is drawn.
+    expect(plan.overlayItems.map((o) => o.ref)).toEqual(["e1"]);
+    // Both refs are surfaced for callers (off-viewport box can be out of image).
+    expect(plan.annotations.map((a) => a.ref)).toEqual(["e1", "e2"]);
+    // The off-viewport ref raises skipped, preserving the shipped contract.
+    expect(plan.skipped).toBe(1);
+  });
+
+  it("does not count off-viewport refs when viewport size is omitted", () => {
+    const plan = planAnnotations({
+      inputs: [{ ref: "e2", role: "link", doc: { x: 10, y: 5000, width: 40, height: 20 } }],
+      space: "viewport",
+      scroll: { x: 0, y: 0 },
+    });
+
+    expect(plan.skipped).toBe(0);
+    expect(plan.overlayItems).toHaveLength(1);
+    expect(plan.annotations).toHaveLength(1);
+  });
+});
+
+describe("planAnnotations - fullpage mode", () => {
+  it("returns box equal to doc (document coordinates)", () => {
+    const plan = planAnnotations({ inputs: sampleInputs, space: "fullpage" });
+    expect(plan.annotations[0].box).toEqual({ x: 100, y: 200, width: 50, height: 20 });
+    expect(plan.annotations[1].box).toEqual({ x: 300, y: 1500, width: 80, height: 18 });
+  });
+
+  it("does not require scroll", () => {
+    expect(() => planAnnotations({ inputs: sampleInputs, space: "fullpage" })).not.toThrow();
+  });
+});
+
+describe("planAnnotations - element mode", () => {
+  const elementRect = { x: 50, y: 100, width: 200, height: 300 };
+
+  it("projects box relative to element top-left", () => {
+    const plan = planAnnotations({
+      inputs: [{ ref: "e1", role: "button", doc: { x: 60, y: 110, width: 40, height: 20 } }],
+      space: "element",
+      elementRect,
+    });
+    expect(plan.annotations[0].box).toEqual({ x: 10, y: 10, width: 40, height: 20 });
+  });
+
+  it("filters out inputs that do not overlap element rect", () => {
+    const plan = planAnnotations({
+      inputs: [
+        { ref: "e1", role: "button", doc: { x: 60, y: 110, width: 40, height: 20 } }, // inside
+        { ref: "e2", role: "link", doc: { x: 500, y: 500, width: 40, height: 20 } }, // outside
+      ],
+      space: "element",
+      elementRect,
+    });
+    expect(plan.annotations).toHaveLength(1);
+    expect(plan.annotations[0].ref).toBe("e1");
+    expect(plan.overlayItems).toHaveLength(1);
+  });
+
+  it("throws when elementRect missing", () => {
+    expect(() => planAnnotations({ inputs: [], space: "element" })).toThrow(/elementRect/);
+  });
+});
+
+describe("planAnnotations - maxLabels", () => {
+  it("truncates to maxLabels and reports skipped", () => {
+    const inputs = Array.from({ length: 5 }, (_, i) => ({
+      ref: `e${i + 1}`,
+      role: "button",
+      doc: { x: 0, y: i * 10, width: 5, height: 5 },
+    }));
+    const plan = planAnnotations({ inputs, space: "fullpage", maxLabels: 2 });
+    expect(plan.annotations).toHaveLength(2);
+    expect(plan.overlayItems).toHaveLength(2);
+    expect(plan.skipped).toBe(3);
+  });
+
+  it("uses ANNOTATION_MAX_LABELS_DEFAULT when not specified", () => {
+    const inputs = Array.from({ length: 200 }, (_, i) => ({
+      ref: `e${i + 1}`,
+      role: "button",
+      doc: { x: 0, y: i, width: 5, height: 5 },
+    }));
+    const plan = planAnnotations({ inputs, space: "fullpage" });
+    expect(plan.annotations).toHaveLength(150);
+    expect(plan.skipped).toBe(50);
+  });
+});
+
+describe("buildOverlayInjectionScript", () => {
+  it("returns a self-contained IIFE", () => {
+    const script = buildOverlayInjectionScript({
+      items: [{ ref: "e1", x: 100, y: 200, w: 50, h: 20 }],
+    });
+    expect(script).toMatch(/^\(\s*\(\s*\)\s*=>\s*\{/);
+    expect(script).toMatch(/\}\s*\)\s*\(\s*\)\s*;?\s*$/);
+  });
+
+  it("embeds the overlay attr", () => {
+    const script = buildOverlayInjectionScript({ items: [] });
+    expect(script).toContain(ANNOTATION_OVERLAY_ATTR);
+  });
+
+  it("embeds each item's ref text and coordinates", () => {
+    const script = buildOverlayInjectionScript({
+      items: [
+        { ref: "e1", x: 100, y: 200, w: 50, h: 20 },
+        { ref: "ax42", x: 999, y: 1500, w: 80, h: 18 },
+      ],
+    });
+    expect(script).toMatch(/"ref":\s*"e1"/);
+    expect(script).toMatch(/"ref":\s*"ax42"/);
+    expect(script).toMatch(/"x":\s*100/);
+    expect(script).toMatch(/"x":\s*999/);
+  });
+
+  it("handles empty items without throwing", () => {
+    expect(() => buildOverlayInjectionScript({ items: [] })).not.toThrow();
+  });
+
+  it("rounds coordinates to integers", () => {
+    const script = buildOverlayInjectionScript({
+      items: [{ ref: "e1", x: 100.7, y: 200.4, w: 50.6, h: 20.1 }],
+    });
+    expect(script).toMatch(/"x":\s*101/); // 100.7 -> 101
+    expect(script).toMatch(/"y":\s*200/); // 200.4 -> 200
+  });
+
+  it("clamps zero/negative-size boxes to 1px so they remain visible", () => {
+    const script = buildOverlayInjectionScript({
+      items: [{ ref: "e1", x: 10, y: 10, w: 0, h: 0 }],
+    });
+    expect(script).toMatch(/"w":\s*1/);
+    expect(script).toMatch(/"h":\s*1/);
+  });
+
+  it("escapes hostile ref characters via JSON.stringify (no breakout)", () => {
+    const hostile = 'e1");alert(1);//';
+    const script = buildOverlayInjectionScript({
+      items: [{ ref: hostile, x: 0, y: 0, w: 1, h: 1 }],
+    });
+    // The hostile `"` MUST be escaped as `\"` inside the JSON literal.
+    expect(script).toContain('"e1\\");alert(1);//"');
+    // The unescaped breakout MUST NOT appear anywhere in the script as a
+    // bare statement that would terminate the JSON literal early.
+    expect(script).not.toContain('e1");alert(1);');
+  });
+
+  it("flips label below the box when y < 14 (no headroom)", () => {
+    const script = buildOverlayInjectionScript({
+      items: [{ ref: "e1", x: 0, y: 5, w: 10, h: 10 }],
+    });
+    // labelTop = relativeY < 14 ? it.y + 2 : it.y - 14
+    // The expression literal `relativeY < 14 ? (it.y + 2) : (it.y - 14)` is in the script.
+    expect(script).toContain("relativeY < 14 ? (it.y + 2) : (it.y - 14)");
+  });
+
+  it("uses capture-relative y when deciding whether to flip labels below boxes", () => {
+    const script = buildOverlayInjectionScript({
+      items: [{ ref: "e1", x: 0, y: 1005, w: 10, h: 10 }],
+      captureY: 1000,
+    });
+
+    expect(script).toContain("var captureY = 1000;");
+    expect(script).toContain("var relativeY = it.y - captureY;");
+    expect(script).toContain("relativeY < 14 ? (it.y + 2) : (it.y - 14)");
+  });
+});
+
+describe("buildOverlayClearScript", () => {
+  it("returns an IIFE selecting overlay attr", () => {
+    const script = buildOverlayClearScript();
+    expect(script).toContain(`[${ANNOTATION_OVERLAY_ATTR}]`);
+    expect(script).toMatch(/^\(\s*\(\s*\)\s*=>\s*\{/);
+  });
+});
+
+describe("scaleAnnotations", () => {
+  const sample: AnnotationItem[] = [
+    {
+      ref: "e1",
+      number: 1,
+      role: "button",
+      name: "Submit",
+      box: { x: 100, y: 200, width: 50, height: 20 },
+    },
+  ];
+
+  it("returns identity (structural copy) when both factors are 1", () => {
+    const out = scaleAnnotations(sample, 1, 1);
+    expect(out[0]).toEqual(sample[0]);
+    expect(out[0]).not.toBe(sample[0]);
+    expect(out[0]?.box).not.toBe(sample[0]?.box);
+  });
+
+  it("scales box dimensions by independent x/y factors", () => {
+    const out = scaleAnnotations(sample, 0.5, 0.485);
+    expect(out[0]?.box).toEqual({
+      x: 50,
+      y: 97,
+      width: 25,
+      height: 10,
+    });
+  });
+
+  it("clamps width/height to a minimum of 1 to avoid disappearing labels", () => {
+    const tiny: AnnotationItem[] = [
+      {
+        ref: "e1",
+        number: 1,
+        role: "button",
+        box: { x: 0, y: 0, width: 1, height: 1 },
+      },
+    ];
+    const out = scaleAnnotations(tiny, 0.1, 0.1);
+    expect(out[0]?.box.width).toBeGreaterThanOrEqual(1);
+    expect(out[0]?.box.height).toBeGreaterThanOrEqual(1);
+  });
+
+  it("returns identity (structural copy) for invalid factors", () => {
+    const out = scaleAnnotations(sample, Number.NaN, 0.5);
+    expect(out[0]?.box).toEqual(sample[0]?.box);
+    const out2 = scaleAnnotations(sample, 0, 0.5);
+    expect(out2[0]?.box).toEqual(sample[0]?.box);
+    const out3 = scaleAnnotations(sample, -1, 1);
+    expect(out3[0]?.box).toEqual(sample[0]?.box);
+  });
+
+  it("preserves ref/number/role/name fields verbatim", () => {
+    const out = scaleAnnotations(sample, 0.5, 0.5);
+    expect(out[0]?.ref).toBe("e1");
+    expect(out[0]?.number).toBe(1);
+    expect(out[0]?.role).toBe("button");
+    expect(out[0]?.name).toBe("Submit");
+  });
+});

extensions/browser/src/browser/screenshot-annotate.ts

@@ -0,0 +1,282 @@
+// extensions/browser/src/browser/screenshot-annotate.ts
+//
+// Pure helper module for screenshot label annotations.
+// Has no Playwright / CDP / page dependency: takes document-space inputs,
+// returns coordinate-projected annotations + IIFE strings the caller can
+// hand to page.evaluate / Runtime.evaluate.
+//
+// Used by:
+//   - pw-tools-core.interactions.ts (Playwright path, M1.2-a)
+//   - planned: raw-CDP path in M1.2-b
+//
+// chrome-mcp path keeps its own inline overlay (renderChromeMcpLabels) for now.
+
+export const ANNOTATION_OVERLAY_ATTR = "data-openclaw-labels";
+export const ANNOTATION_OVERLAY_ROOT_ID = "__openclaw-annotations__";
+export const ANNOTATION_MAX_LABELS_DEFAULT = 150;
+
+export type CoordinateSpace = "viewport" | "fullpage" | "element";
+
+export interface RawAnnotationInput {
+  ref: string;
+  role: string;
+  name?: string;
+  /** Bounding box in document coordinates (viewport top-left + scroll). */
+  doc: { x: number; y: number; width: number; height: number };
+}
+
+export interface AnnotationBox {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface AnnotationItem {
+  ref: string;
+  number: number;
+  role: string;
+  name?: string;
+  box: AnnotationBox;
+}
+
+export interface OverlayItem {
+  ref: string;
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+export interface AnnotationPlan {
+  /** Always document-space items, fed to buildOverlayInjectionScript. */
+  overlayItems: OverlayItem[];
+  /** Items projected into the capture mode's image-space coordinates. */
+  annotations: AnnotationItem[];
+  /** Refs dropped because of maxLabels truncation. */
+  skipped: number;
+}
+
+export interface PlanAnnotationsParams {
+  inputs: RawAnnotationInput[];
+  space: CoordinateSpace;
+  /** Required when space === "viewport". */
+  scroll?: { x: number; y: number };
+  /**
+   * Viewport size (CSS px). Only meaningful when space === "viewport". When
+   * provided, refs whose document box falls outside the current viewport rect
+   * (`scroll` + this size) are counted as skipped instead of drawn, preserving
+   * the shipped `labelsSkipped` contract. Omit it to disable that accounting.
+   */
+  viewport?: { width: number; height: number };
+  /** Required when space === "element". */
+  elementRect?: { x: number; y: number; width: number; height: number };
+  maxLabels?: number;
+}
+
+export function refToNumber(ref: string): number {
+  const match = ref.match(/(\d+)/);
+  if (!match) {
+    return 0;
+  }
+  const n = Number(match[1]);
+  return Number.isFinite(n) ? n : 0;
+}
+
+export function planAnnotations(params: PlanAnnotationsParams): AnnotationPlan {
+  const maxLabels = params.maxLabels ?? ANNOTATION_MAX_LABELS_DEFAULT;
+
+  if (params.space === "viewport" && !params.scroll) {
+    throw new Error("planAnnotations: scroll is required when space is 'viewport'");
+  }
+  if (params.space === "element" && !params.elementRect) {
+    throw new Error("planAnnotations: elementRect is required when space is 'element'");
+  }
+
+  // Element-mode filter: discard inputs that do not overlap the element rect.
+  let kept = params.inputs;
+  if (params.space === "element" && params.elementRect) {
+    const er = params.elementRect;
+    kept = params.inputs.filter((input) => rectsOverlap(input.doc, er));
+  }
+
+  // Viewport capture only shows refs inside the current viewport rect. An
+  // off-viewport ref is still surfaced in `annotations` (with its real,
+  // possibly out-of-image box) so callers can locate it, but it is not drawn
+  // and is counted as skipped. This keeps the shipped `labelsSkipped` meaning
+  // ("refs not present in the captured viewport image") instead of silently
+  // narrowing it. Only applied when the caller supplies the viewport size;
+  // without it we cannot decide off-screen state and skip nothing.
+  const viewportRect =
+    params.space === "viewport" && params.scroll && params.viewport
+      ? {
+          x: params.scroll.x,
+          y: params.scroll.y,
+          width: params.viewport.width,
+          height: params.viewport.height,
+        }
+      : undefined;
+
+  const overlayItems: OverlayItem[] = [];
+  const annotations: AnnotationItem[] = [];
+  let skipped = 0;
+
+  for (const input of kept) {
+    if (viewportRect && !rectsOverlap(input.doc, viewportRect)) {
+      // Outside the captured viewport: count as skipped (compat) but still
+      // report the annotation; do not draw it or consume the label budget.
+      skipped += 1;
+      annotations.push(toAnnotation(input, params));
+      continue;
+    }
+    if (overlayItems.length >= maxLabels) {
+      skipped += 1;
+      continue;
+    }
+    overlayItems.push({
+      ref: input.ref,
+      x: input.doc.x,
+      y: input.doc.y,
+      w: input.doc.width,
+      h: input.doc.height,
+    });
+    annotations.push(toAnnotation(input, params));
+  }
+
+  return { overlayItems, annotations, skipped };
+}
+
+function toAnnotation(input: RawAnnotationInput, params: PlanAnnotationsParams): AnnotationItem {
+  return {
+    ref: input.ref,
+    number: refToNumber(input.ref),
+    role: input.role,
+    ...(input.name ? { name: input.name } : {}),
+    box: projectBox(input.doc, params),
+  };
+}
+
+function projectBox(
+  doc: { x: number; y: number; width: number; height: number },
+  params: PlanAnnotationsParams,
+): AnnotationBox {
+  if (params.space === "viewport") {
+    const scroll = params.scroll!;
+    return {
+      x: doc.x - scroll.x,
+      y: doc.y - scroll.y,
+      width: doc.width,
+      height: doc.height,
+    };
+  }
+  if (params.space === "element") {
+    const er = params.elementRect!;
+    // NOTE: width/height pass through unchanged even when the input rect
+    // partially extends past the element. The capture backend (e.g.
+    // locator.screenshot) is responsible for clipping; the box may have
+    // negative x/y or extend past elementRect width/height for partial overlaps.
+    return {
+      x: doc.x - er.x,
+      y: doc.y - er.y,
+      width: doc.width,
+      height: doc.height,
+    };
+  }
+  // fullpage: document coordinates as-is
+  return { x: doc.x, y: doc.y, width: doc.width, height: doc.height };
+}
+
+function rectsOverlap(
+  a: { x: number; y: number; width: number; height: number },
+  b: { x: number; y: number; width: number; height: number },
+): boolean {
+  return a.x < b.x + b.width && a.x + a.width > b.x && a.y < b.y + b.height && a.y + a.height > b.y;
+}
+
+export function buildOverlayInjectionScript(params: {
+  items: OverlayItem[];
+  captureY?: number;
+}): string {
+  const itemsJson = JSON.stringify(
+    params.items.map((it) => ({
+      ref: it.ref,
+      x: round(it.x),
+      y: round(it.y),
+      w: Math.max(1, round(it.w)),
+      h: Math.max(1, round(it.h)),
+    })),
+  );
+  const attr = ANNOTATION_OVERLAY_ATTR;
+  const rootId = ANNOTATION_OVERLAY_ROOT_ID;
+  const captureY = Number.isFinite(params.captureY) ? round(params.captureY ?? 0) : 0;
+  return `(() => {
+  var items = ${itemsJson};
+  var captureY = ${captureY};
+  var existing = document.querySelectorAll("[${attr}]");
+  for (var k = 0; k < existing.length; k++) existing[k].remove();
+  var root = document.createElement("div");
+  root.id = ${JSON.stringify(rootId)};
+  root.setAttribute("${attr}", "1");
+  root.style.cssText = "position:absolute;top:0;left:0;width:0;height:0;pointer-events:none;z-index:2147483647;font-family:'SF Mono','SFMono-Regular',Menlo,Monaco,Consolas,'Liberation Mono','Courier New',monospace;";
+  for (var i = 0; i < items.length; i++) {
+    var it = items[i];
+    var box = document.createElement("div");
+    box.setAttribute("${attr}", "1");
+    box.style.cssText = "position:absolute;left:" + it.x + "px;top:" + it.y + "px;width:" + it.w + "px;height:" + it.h + "px;border:2px solid #ffb020;box-sizing:border-box;pointer-events:none;";
+    var tag = document.createElement("div");
+    tag.setAttribute("${attr}", "1");
+    tag.textContent = String(it.ref);
+    var relativeY = it.y - captureY;
+    var labelTop = relativeY < 14 ? (it.y + 2) : (it.y - 14);
+    tag.style.cssText = "position:absolute;left:" + it.x + "px;top:" + labelTop + "px;background:#ffb020;color:#1a1a1a;font:bold 11px/14px monospace;padding:0 4px;border-radius:2px;white-space:nowrap;pointer-events:none;";
+    root.appendChild(box);
+    root.appendChild(tag);
+  }
+  document.documentElement.appendChild(root);
+  return true;
+})();`;
+}
+
+export function buildOverlayClearScript(): string {
+  const attr = ANNOTATION_OVERLAY_ATTR;
+  return `(() => {
+  var existing = document.querySelectorAll("[${attr}]");
+  for (var k = 0; k < existing.length; k++) existing[k].remove();
+  return true;
+})();`;
+}
+
+/**
+ * Scale annotation boxes by independent x/y factors. Used to keep annotation
+ * coordinates aligned with the saved image after the response pipeline
+ * resizes the screenshot (e.g. via normalizeBrowserScreenshot capping the
+ * longest side or the byte budget). Returns a new array; inputs are not
+ * mutated. When both factors are 1 the boxes are returned unchanged (modulo
+ * structural copy) so callers can share the same code path for resized and
+ * non-resized captures.
+ */
+export function scaleAnnotations(
+  items: AnnotationItem[],
+  scaleX: number,
+  scaleY: number,
+): AnnotationItem[] {
+  if (!Number.isFinite(scaleX) || !Number.isFinite(scaleY) || scaleX <= 0 || scaleY <= 0) {
+    return items.map((it) => ({ ...it, box: { ...it.box } }));
+  }
+  if (scaleX === 1 && scaleY === 1) {
+    return items.map((it) => ({ ...it, box: { ...it.box } }));
+  }
+  return items.map((it) => ({
+    ...it,
+    box: {
+      x: round(it.box.x * scaleX),
+      y: round(it.box.y * scaleY),
+      width: Math.max(1, round(it.box.width * scaleX)),
+      height: Math.max(1, round(it.box.height * scaleY)),
+    },
+  }));
+}
+
+function round(v: number): number {
+  return Math.round(v);
+}

extensions/browser/src/cli/browser-cli-inspect.ts

@@ -51,7 +51,11 @@ export function registerBrowserInspectCommands(
     .option("--full-page", "Capture full scrollable page", false)
     .option("--ref <ref>", "ARIA ref from ai snapshot")
     .option("--element <selector>", "CSS selector for element screenshot")
-    .option("--labels", "Overlay role refs on the screenshot", false)
+    .option(
+      "--labels",
+      "Overlay role refs on the screenshot (works with --full-page, --ref, and --element)",
+      false,
+    )
     .option("--type <png|jpeg>", "Output type (default: png)", "png")
     .action(async (targetId: string | undefined, opts, cmd) => {
       const parent = parentOpts(cmd);
@@ -98,7 +102,7 @@ export function registerBrowserInspectCommands(
     .option("--depth <n>", "Role snapshot: max depth")
     .option("--selector <sel>", "Role snapshot: scope to CSS selector")
     .option("--frame <sel>", "Role snapshot: scope to an iframe selector")
-    .option("--labels", "Include viewport label overlay screenshot", false)
+    .option("--labels", "Include label overlay screenshot with annotations", false)
     .option("--urls", "Append discovered link URLs to AI snapshots", false)
     .option("--out <path>", "Write snapshot to a file")
     .action(async (opts, cmd) => {

extensions/codex/doctor-contract-api.test.ts

@@ -1,6 +1,44 @@
 // Codex tests cover doctor contract api plugin behavior.
-import { describe, expect, it } from "vitest";
-import { legacyConfigRules, normalizeCompatibilityConfig } from "./doctor-contract-api.js";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import type { PluginStateKeyedStore } from "openclaw/plugin-sdk/plugin-state-runtime";
+import {
+  createPluginStateKeyedStoreForTests,
+  resetPluginStateStoreForTests,
+} from "openclaw/plugin-sdk/plugin-state-test-runtime";
+import type {
+  OpenKeyedStoreOptions,
+  PluginDoctorStateMigrationContext,
+} from "openclaw/plugin-sdk/runtime-doctor";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  legacyConfigRules,
+  normalizeCompatibilityConfig,
+  stateMigrations,
+} from "./doctor-contract-api.js";
+import {
+  bindingStoreKey,
+  CODEX_APP_SERVER_BINDING_MAX_ENTRIES,
+  CODEX_APP_SERVER_BINDING_NAMESPACE,
+  type StoredCodexAppServerBinding,
+} from "./src/app-server/session-binding.js";
+import { legacyCodexConversationBindingId } from "./src/conversation-binding-data.js";
+
+function createDoctorContext(env: NodeJS.ProcessEnv): PluginDoctorStateMigrationContext {
+  return {
+    openPluginStateKeyedStore<T>(options: OpenKeyedStoreOptions) {
+      return createPluginStateKeyedStoreForTests<T>("codex", {
+        ...options,
+        env: options.env ?? env,
+      });
+    },
+  };
+}
+
+afterEach(() => {
+  resetPluginStateStoreForTests();
+});
 
 describe("codex doctor contract", () => {
   it("reports the retired dynamic tools profile config key", () => {
@@ -42,4 +80,856 @@ describe("codex doctor contract", () => {
     });
     expect(original.plugins.entries.codex.config).toHaveProperty("codexDynamicToolsProfile");
   });
+
+  it("imports shipped binding sidecars under session and legacy conversation identities", async () => {
+    const stateDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-doctor-"));
+    const env = { ...process.env, OPENCLAW_STATE_DIR: stateDir };
+    const sessionsDir = path.join(stateDir, "agents", "main", "sessions");
+    const transcriptPath = path.join(sessionsDir, "session-current.jsonl");
+    const sidecarPath = `${transcriptPath}.codex-app-server.json`;
+    const legacyBinding = {
+      schemaVersion: 1,
+      threadId: "thread-1",
+      sessionFile: transcriptPath,
+      updatedAt: "2026-01-01T00:00:00.000Z",
+    };
+    await fs.mkdir(sessionsDir, { recursive: true });
+    await fs.writeFile(transcriptPath, '{"type":"session","id":"session-current"}\n', "utf8");
+    await fs.writeFile(
+      path.join(sessionsDir, "sessions.json"),
+      JSON.stringify({
+        "agent:main:session-1": {
+          sessionId: "session-current",
+          sessionFile: "session-current.jsonl",
+          totalTokens: 42_000,
+          totalTokensFresh: true,
+          contextTokens: 258_400,
+          updatedAt: Date.now(),
+        },
+      }),
+      "utf8",
+    );
+    await fs.writeFile(sidecarPath, JSON.stringify(legacyBinding), "utf8");
+    const params = {
+      config: {},
+      env,
+      stateDir,
+      oauthDir: path.join(stateDir, "oauth"),
+      context: createDoctorContext(env),
+    };
+    const migration = stateMigrations[0];
+    if (!migration) {
+      throw new Error("missing Codex binding migration");
+    }
+
+    await expect(migration.detectLegacyState(params)).resolves.toMatchObject({
+      preview: [expect.stringContaining("legacy sidecar")],
+    });
+    await expect(migration.migrateLegacyState(params)).resolves.toMatchObject({
+      changes: [expect.stringContaining("Migrated 1")],
+      warnings: [],
+    });
+
+    const store = createDoctorContext(env).openPluginStateKeyedStore<StoredCodexAppServerBinding>({
+      namespace: CODEX_APP_SERVER_BINDING_NAMESPACE,
+      maxEntries: CODEX_APP_SERVER_BINDING_MAX_ENTRIES,
+      overflowPolicy: "reject-new",
+    });
+    await expect(
+      store.lookup(
+        bindingStoreKey({
+          kind: "session",
+          agentId: "main",
+          sessionId: "session-current",
+          sessionKey: "agent:main:session-1",
+        }),
+      ),
+    ).resolves.toMatchObject({
+      state: "active",
+      sessionId: "session-current",
+      binding: { threadId: "thread-1" },
+    });
+    await expect(
+      store.lookup(
+        bindingStoreKey({
+          kind: "conversation",
+          bindingId: legacyCodexConversationBindingId(transcriptPath),
+        }),
+      ),
+    ).resolves.toMatchObject({
+      state: "active",
+      binding: {
+        threadId: "thread-1",
+        cwd: "",
+        historyCoveredThrough: expect.any(String),
+      },
+    });
+    await expect(
+      store.lookup(
+        bindingStoreKey({
+          kind: "conversation",
+          bindingId: legacyCodexConversationBindingId(transcriptPath),
+        }),
+      ),
+    ).resolves.not.toHaveProperty("binding.nativeContextUsage");
+    await expect(fs.access(`${sidecarPath}.migrated`)).resolves.toBeUndefined();
+    await expect(
+      fs.readFile(path.join(sessionsDir, "sessions.json"), "utf8").then(JSON.parse),
+    ).resolves.toMatchObject({
+      "agent:main:session-1": { sessionId: "session-current", agentHarnessId: "codex" },
+    });
+
+    await fs.rm(`${sidecarPath}.migrated`);
+    await fs.writeFile(sidecarPath, JSON.stringify(legacyBinding), "utf8");
+    await expect(migration.migrateLegacyState(params)).resolves.toMatchObject({
+      changes: [expect.stringContaining("Migrated 1")],
+      warnings: [],
+    });
+    await expect(fs.access(`${sidecarPath}.migrated`)).resolves.toBeUndefined();
+
+    const resetTranscript = path.join(sessionsDir, "session-before-reset.jsonl");
+    const resetSidecar = `${resetTranscript}.codex-app-server.json`;
+    await fs.writeFile(resetTranscript, '{"type":"session","id":"session-before-reset"}\n', "utf8");
+    await fs.writeFile(
+      resetSidecar,
+      JSON.stringify({ schemaVersion: 1, threadId: "thread-before-reset" }),
+      "utf8",
+    );
+    await expect(migration.migrateLegacyState(params)).resolves.toMatchObject({
+      changes: [expect.stringContaining("Migrated 1 safe")],
+      warnings: [expect.stringContaining("session owner could not be resolved")],
+    });
+    await expect(fs.access(resetSidecar)).resolves.toBeUndefined();
+    await fs.rm(resetSidecar);
+
+    const conflictingTranscript = path.join(sessionsDir, "session-2.jsonl");
+    const conflictingSidecar = `${conflictingTranscript}.codex-app-server.json`;
+    await fs.writeFile(conflictingTranscript, '{"type":"session","id":"session-2"}\n', "utf8");
+    await fs.writeFile(
+      conflictingSidecar,
+      JSON.stringify({ schemaVersion: 1, threadId: "legacy-thread" }),
+      "utf8",
+    );
+    await fs.writeFile(
+      path.join(sessionsDir, "sessions.json"),
+      JSON.stringify({
+        "agent:main:session-1": {
+          sessionId: "session-1",
+          sessionFile: "session-1.jsonl",
+          updatedAt: Date.now(),
+        },
+        "agent:main:session-2": {
+          sessionId: "session-2",
+          sessionFile: "session-2.jsonl",
+          updatedAt: Date.now(),
+        },
+      }),
+      "utf8",
+    );
+    const conflictingSessionKey = bindingStoreKey({
+      kind: "session",
+      agentId: "main",
+      sessionId: "session-2",
+      sessionKey: "agent:main:session-2",
+    });
+    await store.register(conflictingSessionKey, {
+      version: 1,
+      state: "active",
+      binding: {
+        threadId: "legacy-thread",
+        cwd: "/repo",
+        historyCoveredThrough: "2026-01-01T00:00:00.000Z",
+      },
+    });
+
+    await expect(migration.migrateLegacyState(params)).resolves.toMatchObject({
+      changes: [],
+      warnings: [
+        expect.stringContaining(`canonical plugin state changed at ${conflictingSessionKey}`),
+      ],
+    });
+    await expect(
+      store.lookup(
+        bindingStoreKey({
+          kind: "conversation",
+          bindingId: legacyCodexConversationBindingId(conflictingTranscript),
+        }),
+      ),
+    ).resolves.toBeUndefined();
+    await expect(fs.access(conflictingSidecar)).resolves.toBeUndefined();
+    await fs.rm(conflictingSidecar);
+
+    const inverseTranscript = path.join(sessionsDir, "session-3.jsonl");
+    const inverseSidecar = `${inverseTranscript}.codex-app-server.json`;
+    const inverseConversationKey = bindingStoreKey({
+      kind: "conversation",
+      bindingId: legacyCodexConversationBindingId(inverseTranscript),
+    });
+    await fs.writeFile(inverseTranscript, '{"type":"session","id":"session-3"}\n', "utf8");
+    await fs.writeFile(
+      path.join(sessionsDir, "sessions.json"),
+      JSON.stringify({
+        "agent:main:session-3": {
+          sessionId: "session-3",
+          sessionFile: "session-3.jsonl",
+          updatedAt: Date.now(),
+        },
+      }),
+      "utf8",
+    );
+    await fs.writeFile(
+      inverseSidecar,
+      JSON.stringify({ schemaVersion: 1, threadId: "session-thread" }),
+      "utf8",
+    );
+    await store.register(inverseConversationKey, {
+      version: 1,
+      state: "active",
+      binding: { threadId: "conversation-thread", cwd: "/repo" },
+    });
+
+    await expect(migration.migrateLegacyState(params)).resolves.toMatchObject({
+      changes: [expect.stringContaining("Migrated 1")],
+      warnings: [],
+    });
+    await expect(
+      store.lookup(
+        bindingStoreKey({
+          kind: "session",
+          agentId: "main",
+          sessionId: "session-3",
+          sessionKey: "agent:main:session-3",
+        }),
+      ),
+    ).resolves.toMatchObject({
+      state: "active",
+      sessionId: "session-3",
+      binding: { threadId: "conversation-thread" },
+    });
+    await expect(store.lookup(inverseConversationKey)).resolves.toMatchObject({
+      state: "active",
+      binding: { threadId: "conversation-thread" },
+    });
+    await expect(fs.access(`${inverseSidecar}.migrated`)).resolves.toBeUndefined();
+    await fs.rm(stateDir, { recursive: true, force: true });
+  });
+
+  it("does not publish Codex session ownership before every binding row persists", async () => {
+    const stateDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-doctor-order-"));
+    const env = { ...process.env, OPENCLAW_STATE_DIR: stateDir };
+    const sessionsDir = path.join(stateDir, "agents", "main", "sessions");
+    const transcriptPath = path.join(sessionsDir, "session-order.jsonl");
+    const sidecarPath = `${transcriptPath}.codex-app-server.json`;
+    const storePath = path.join(sessionsDir, "sessions.json");
+    await fs.mkdir(sessionsDir, { recursive: true });
+    await fs.writeFile(transcriptPath, '{"type":"session","id":"session-order"}\n', "utf8");
+    await fs.writeFile(
+      storePath,
+      JSON.stringify({
+        "agent:main:order": {
+          sessionId: "session-order",
+          sessionFile: "session-order.jsonl",
+          updatedAt: Date.now(),
+        },
+      }),
+      "utf8",
+    );
+    await fs.writeFile(
+      sidecarPath,
+      JSON.stringify({ schemaVersion: 1, threadId: "thread-order" }),
+      "utf8",
+    );
+    const store = createPluginStateKeyedStoreForTests<StoredCodexAppServerBinding>("codex", {
+      namespace: CODEX_APP_SERVER_BINDING_NAMESPACE,
+      maxEntries: CODEX_APP_SERVER_BINDING_MAX_ENTRIES,
+      overflowPolicy: "reject-new",
+      env,
+    });
+    const registerIfAbsent = store.registerIfAbsent.bind(store);
+    let registerCalls = 0;
+    const failingStore: PluginStateKeyedStore<StoredCodexAppServerBinding> = {
+      ...store,
+      async registerIfAbsent(key, value, opts) {
+        registerCalls++;
+        if (registerCalls === 2) {
+          throw new Error("injected session binding write failure");
+        }
+        return await registerIfAbsent(key, value, opts);
+      },
+    };
+    const failingContext: PluginDoctorStateMigrationContext = {
+      openPluginStateKeyedStore<T>() {
+        return failingStore as unknown as PluginStateKeyedStore<T>;
+      },
+    };
+    const migration = stateMigrations[0];
+    if (!migration) {
+      throw new Error("missing Codex binding migration");
+    }
+
+    await expect(
+      migration.migrateLegacyState({
+        config: {},
+        env,
+        stateDir,
+        oauthDir: path.join(stateDir, "oauth"),
+        context: failingContext,
+      }),
+    ).resolves.toMatchObject({
+      changes: [expect.stringContaining("Migrated 1 safe")],
+      warnings: [expect.stringContaining("injected session binding write failure")],
+    });
+    await expect(fs.readFile(storePath, "utf8").then(JSON.parse)).resolves.toMatchObject({
+      "agent:main:order": { sessionId: "session-order" },
+    });
+    expect(
+      (JSON.parse(await fs.readFile(storePath, "utf8")) as Record<string, Record<string, unknown>>)[
+        "agent:main:order"
+      ],
+    ).not.toHaveProperty("agentHarnessId");
+    await expect(
+      store.lookup(
+        bindingStoreKey({
+          kind: "session",
+          agentId: "main",
+          sessionId: "session-order",
+          sessionKey: "agent:main:order",
+        }),
+      ),
+    ).resolves.toBeUndefined();
+    await expect(fs.access(sidecarPath)).resolves.toBeUndefined();
+
+    await expect(
+      migration.migrateLegacyState({
+        config: {},
+        env,
+        stateDir,
+        oauthDir: path.join(stateDir, "oauth"),
+        context: createDoctorContext(env),
+      }),
+    ).resolves.toMatchObject({
+      changes: [expect.stringContaining("Migrated 1")],
+      warnings: [],
+    });
+    await expect(fs.readFile(storePath, "utf8").then(JSON.parse)).resolves.toMatchObject({
+      "agent:main:order": {
+        sessionId: "session-order",
+        agentHarnessId: "codex",
+      },
+    });
+    await expect(fs.access(`${sidecarPath}.migrated`)).resolves.toBeUndefined();
+    await fs.rm(stateDir, { recursive: true, force: true });
+  });
+
+  it("retains a shipped binding when its session now belongs to another harness", async () => {
+    const stateDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-doctor-owner-"));
+    const env = { ...process.env, OPENCLAW_STATE_DIR: stateDir };
+    const sessionsDir = path.join(stateDir, "agents", "main", "sessions");
+    const transcriptPath = path.join(sessionsDir, "session-foreign.jsonl");
+    const sidecarPath = `${transcriptPath}.codex-app-server.json`;
+    await fs.mkdir(sessionsDir, { recursive: true });
+    await fs.writeFile(transcriptPath, '{"type":"session","id":"session-foreign"}\n', "utf8");
+    await fs.writeFile(
+      path.join(sessionsDir, "sessions.json"),
+      JSON.stringify({
+        "agent:main:foreign": {
+          sessionId: "session-foreign",
+          sessionFile: "session-foreign.jsonl",
+          agentHarnessId: "openclaw",
+          updatedAt: Date.now(),
+        },
+      }),
+      "utf8",
+    );
+    await fs.writeFile(
+      sidecarPath,
+      JSON.stringify({
+        schemaVersion: 1,
+        threadId: "thread-foreign",
+        sessionFile: transcriptPath,
+      }),
+      "utf8",
+    );
+    const migration = stateMigrations[0];
+    if (!migration) {
+      throw new Error("missing Codex binding migration");
+    }
+
+    await expect(
+      migration.migrateLegacyState({
+        config: {},
+        env,
+        stateDir,
+        oauthDir: path.join(stateDir, "oauth"),
+        context: createDoctorContext(env),
+      }),
+    ).resolves.toMatchObject({
+      changes: [],
+      warnings: [expect.stringContaining("owned by agent harness openclaw")],
+    });
+    await expect(fs.access(sidecarPath)).resolves.toBeUndefined();
+    const store = createDoctorContext(env).openPluginStateKeyedStore<StoredCodexAppServerBinding>({
+      namespace: CODEX_APP_SERVER_BINDING_NAMESPACE,
+      maxEntries: CODEX_APP_SERVER_BINDING_MAX_ENTRIES,
+      overflowPolicy: "reject-new",
+    });
+    await expect(
+      store.lookup(
+        bindingStoreKey({
+          kind: "session",
+          agentId: "main",
+          sessionId: "session-foreign",
+          sessionKey: "agent:main:foreign",
+        }),
+      ),
+    ).resolves.toBeUndefined();
+    await fs.rm(stateDir, { recursive: true, force: true });
+  });
+
+  it("imports sidecars from the pre-agent session directory before core moves it", async () => {
+    const stateDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-doctor-legacy-"));
+    const env = { ...process.env, OPENCLAW_STATE_DIR: stateDir };
+    const sessionsDir = path.join(stateDir, "sessions");
+    const transcriptPath = path.join(sessionsDir, "legacy-session.jsonl");
+    const sidecarPath = `${transcriptPath}.codex-app-server.json`;
+    await fs.mkdir(sessionsDir, { recursive: true });
+    await fs.writeFile(transcriptPath, '{"type":"session","id":"legacy-session"}\n', "utf8");
+    await fs.writeFile(
+      path.join(sessionsDir, "sessions.json"),
+      JSON.stringify({
+        "agent:main:legacy": {
+          sessionId: "legacy-session",
+          sessionFile: "legacy-session.jsonl",
+          updatedAt: Date.now(),
+        },
+      }),
+      "utf8",
+    );
+    await fs.writeFile(
+      sidecarPath,
+      JSON.stringify({
+        schemaVersion: 1,
+        threadId: "legacy-thread",
+        sessionFile: transcriptPath,
+      }),
+      "utf8",
+    );
+    const params = {
+      config: {},
+      env,
+      stateDir,
+      oauthDir: path.join(stateDir, "oauth"),
+      context: createDoctorContext(env),
+    };
+    const migration = stateMigrations[0];
+    if (!migration) {
+      throw new Error("missing Codex binding migration");
+    }
+
+    await expect(migration.migrateLegacyState(params)).resolves.toMatchObject({ warnings: [] });
+
+    const store = createDoctorContext(env).openPluginStateKeyedStore<StoredCodexAppServerBinding>({
+      namespace: CODEX_APP_SERVER_BINDING_NAMESPACE,
+      maxEntries: CODEX_APP_SERVER_BINDING_MAX_ENTRIES,
+      overflowPolicy: "reject-new",
+    });
+    await expect(
+      store.lookup(
+        bindingStoreKey({
+          kind: "session",
+          agentId: "main",
+          sessionId: "legacy-session",
+          sessionKey: "agent:main:legacy",
+        }),
+      ),
+    ).resolves.toMatchObject({
+      state: "active",
+      sessionId: "legacy-session",
+      binding: { threadId: "legacy-thread" },
+    });
+    await expect(fs.access(`${sidecarPath}.migrated`)).resolves.toBeUndefined();
+    await expect(
+      fs.readFile(path.join(sessionsDir, "sessions.json"), "utf8").then(JSON.parse),
+    ).resolves.toMatchObject({
+      "agent:main:legacy": { sessionId: "legacy-session", agentHarnessId: "codex" },
+    });
+  });
+
+  it("uses the session index when a shipped sidecar transcript is missing", async () => {
+    const stateDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-doctor-"));
+    const env = { ...process.env, OPENCLAW_STATE_DIR: stateDir };
+    const sessionsDir = path.join(stateDir, "agents", "main", "sessions");
+    const transcriptPath = path.join(sessionsDir, "missing.jsonl");
+    const sidecarPath = `${transcriptPath}.codex-app-server.json`;
+    await fs.mkdir(sessionsDir, { recursive: true });
+    await fs.writeFile(
+      path.join(sessionsDir, "sessions.json"),
+      JSON.stringify({
+        "agent:main:missing": {
+          sessionId: "session-missing",
+          sessionFile: "missing.jsonl",
+          updatedAt: Date.now(),
+        },
+      }),
+      "utf8",
+    );
+    await fs.writeFile(
+      sidecarPath,
+      JSON.stringify({
+        schemaVersion: 1,
+        threadId: "thread-legacy-conversation",
+        sessionFile: transcriptPath,
+      }),
+      "utf8",
+    );
+    const migration = stateMigrations[0];
+    if (!migration) {
+      throw new Error("missing Codex binding migration");
+    }
+
+    await expect(
+      migration.migrateLegacyState({
+        config: {},
+        env,
+        stateDir,
+        oauthDir: path.join(stateDir, "oauth"),
+        context: createDoctorContext(env),
+      }),
+    ).resolves.toMatchObject({
+      changes: [expect.stringContaining("Migrated 1")],
+      warnings: [],
+    });
+
+    const store = createDoctorContext(env).openPluginStateKeyedStore<StoredCodexAppServerBinding>({
+      namespace: CODEX_APP_SERVER_BINDING_NAMESPACE,
+      maxEntries: CODEX_APP_SERVER_BINDING_MAX_ENTRIES,
+      overflowPolicy: "reject-new",
+    });
+    await expect(
+      store.lookup(
+        bindingStoreKey({
+          kind: "conversation",
+          bindingId: legacyCodexConversationBindingId(transcriptPath),
+        }),
+      ),
+    ).resolves.toMatchObject({
+      state: "active",
+      binding: { threadId: "thread-legacy-conversation" },
+    });
+    await expect(
+      store.lookup(
+        bindingStoreKey({
+          kind: "session",
+          agentId: "main",
+          sessionId: "session-missing",
+          sessionKey: "agent:main:missing",
+        }),
+      ),
+    ).resolves.toMatchObject({
+      state: "active",
+      sessionId: "session-missing",
+      binding: { threadId: "thread-legacy-conversation" },
+    });
+    await expect(fs.access(`${sidecarPath}.migrated`)).resolves.toBeUndefined();
+    await fs.rm(stateDir, { recursive: true, force: true });
+  });
+
+  it("imports a binding without crawling Codex rollout files", async () => {
+    const stateDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-doctor-"));
+    const env = { ...process.env, OPENCLAW_STATE_DIR: stateDir };
+    const sessionsDir = path.join(stateDir, "agents", "main", "sessions");
+    const transcriptPath = path.join(sessionsDir, "session-fresh.jsonl");
+    const sidecarPath = `${transcriptPath}.codex-app-server.json`;
+    await fs.mkdir(sessionsDir, { recursive: true });
+    await fs.writeFile(transcriptPath, '{"type":"session","id":"session-fresh"}\n', "utf8");
+    await fs.writeFile(
+      path.join(sessionsDir, "sessions.json"),
+      JSON.stringify({
+        "agent:main:fresh": {
+          sessionId: "session-fresh",
+          sessionFile: "session-fresh.jsonl",
+          updatedAt: Date.now(),
+        },
+      }),
+      "utf8",
+    );
+    await fs.writeFile(
+      sidecarPath,
+      JSON.stringify({ schemaVersion: 1, threadId: "thread-without-rollout" }),
+      "utf8",
+    );
+    const migration = stateMigrations[0];
+    if (!migration) {
+      throw new Error("missing Codex binding migration");
+    }
+
+    await expect(
+      migration.migrateLegacyState({
+        config: {},
+        env,
+        stateDir,
+        oauthDir: path.join(stateDir, "oauth"),
+        context: createDoctorContext(env),
+      }),
+    ).resolves.toEqual({
+      changes: [expect.stringContaining("Migrated 1")],
+      warnings: [],
+    });
+
+    const store = createDoctorContext(env).openPluginStateKeyedStore<StoredCodexAppServerBinding>({
+      namespace: CODEX_APP_SERVER_BINDING_NAMESPACE,
+      maxEntries: CODEX_APP_SERVER_BINDING_MAX_ENTRIES,
+      overflowPolicy: "reject-new",
+    });
+    const targetKey = bindingStoreKey({
+      kind: "conversation",
+      bindingId: legacyCodexConversationBindingId(transcriptPath),
+    });
+    await expect(
+      store.lookup(
+        bindingStoreKey({
+          kind: "session",
+          agentId: "main",
+          sessionId: "session-fresh",
+          sessionKey: "agent:main:fresh",
+        }),
+      ),
+    ).resolves.toMatchObject({
+      state: "active",
+      sessionId: "session-fresh",
+      binding: { threadId: "thread-without-rollout" },
+    });
+    await expect(store.lookup(targetKey)).resolves.toMatchObject({
+      state: "active",
+      binding: { threadId: "thread-without-rollout" },
+    });
+    await expect(fs.access(`${sidecarPath}.migrated`)).resolves.toBeUndefined();
+    await fs.rm(stateDir, { recursive: true, force: true });
+  });
+
+  it("retains an ambiguous sidecar and converges after its owner resolves", async () => {
+    const stateDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-doctor-"));
+    const env = { ...process.env, HOME: stateDir, OPENCLAW_STATE_DIR: stateDir };
+    const config = {
+      agents: { list: [{ id: "alpha" }, { id: "beta" }] },
+      session: { store: "~/shared/sessions.json" },
+    };
+    const sessionsDir = path.join(stateDir, "shared");
+    const transcriptPath = path.join(sessionsDir, "ambiguous.jsonl");
+    const sidecarPath = `${transcriptPath}.codex-app-server.json`;
+    await fs.mkdir(sessionsDir, { recursive: true });
+    await fs.writeFile(transcriptPath, '{"type":"message"}\n', "utf8");
+    await fs.writeFile(
+      sidecarPath,
+      JSON.stringify({
+        schemaVersion: 1,
+        threadId: "thread-ambiguous",
+        sessionFile: transcriptPath,
+      }),
+      "utf8",
+    );
+    const migration = stateMigrations[0];
+    if (!migration) {
+      throw new Error("missing Codex binding migration");
+    }
+
+    await expect(
+      migration.migrateLegacyState({
+        config,
+        env,
+        stateDir,
+        oauthDir: path.join(stateDir, "oauth"),
+        context: createDoctorContext(env),
+      }),
+    ).resolves.toMatchObject({
+      changes: [expect.stringContaining("Migrated 1 safe")],
+      warnings: [expect.stringContaining("session owner could not be resolved")],
+    });
+
+    const store = createDoctorContext(env).openPluginStateKeyedStore<StoredCodexAppServerBinding>({
+      namespace: CODEX_APP_SERVER_BINDING_NAMESPACE,
+      maxEntries: CODEX_APP_SERVER_BINDING_MAX_ENTRIES,
+      overflowPolicy: "reject-new",
+    });
+    await expect(
+      store.lookup(
+        bindingStoreKey({
+          kind: "conversation",
+          bindingId: legacyCodexConversationBindingId(transcriptPath),
+        }),
+      ),
+    ).resolves.toMatchObject({ state: "active", binding: { threadId: "thread-ambiguous" } });
+    await expect(fs.access(sidecarPath)).resolves.toBeUndefined();
+
+    const conversationKey = bindingStoreKey({
+      kind: "conversation",
+      bindingId: legacyCodexConversationBindingId(transcriptPath),
+    });
+    const imported = await store.lookup(conversationKey);
+    if (imported?.state !== "active") {
+      throw new Error("missing imported Codex conversation binding");
+    }
+    await store.register(conversationKey, {
+      ...imported,
+      binding: { ...imported.binding, threadId: "thread-recovered" },
+    });
+    await expect(
+      migration.migrateLegacyState({
+        config,
+        env,
+        stateDir,
+        oauthDir: path.join(stateDir, "oauth"),
+        context: createDoctorContext(env),
+      }),
+    ).resolves.toEqual({
+      changes: [],
+      warnings: [expect.stringContaining("session owner could not be resolved")],
+    });
+    await expect(store.lookup(conversationKey)).resolves.toMatchObject({
+      state: "active",
+      binding: { threadId: "thread-recovered" },
+    });
+
+    await fs.writeFile(
+      path.join(sessionsDir, "sessions.json"),
+      JSON.stringify({
+        "agent:alpha:ambiguous": {
+          sessionId: "session-ambiguous",
+          sessionFile: "ambiguous.jsonl",
+          totalTokens: 12_345,
+          totalTokensFresh: true,
+          contextTokens: 128_000,
+          updatedAt: Date.now(),
+        },
+      }),
+      "utf8",
+    );
+    await expect(
+      migration.migrateLegacyState({
+        config,
+        env,
+        stateDir,
+        oauthDir: path.join(stateDir, "oauth"),
+        context: createDoctorContext(env),
+      }),
+    ).resolves.toMatchObject({
+      changes: [expect.stringContaining("Migrated 1")],
+      warnings: [],
+    });
+    await expect(
+      store.lookup(
+        bindingStoreKey({
+          kind: "session",
+          agentId: "alpha",
+          sessionId: "session-ambiguous",
+          sessionKey: "agent:alpha:ambiguous",
+        }),
+      ),
+    ).resolves.toMatchObject({
+      state: "active",
+      sessionId: "session-ambiguous",
+      binding: { threadId: "thread-recovered" },
+    });
+    await expect(store.lookup(conversationKey)).resolves.toMatchObject({
+      state: "active",
+      binding: {
+        threadId: "thread-recovered",
+      },
+    });
+    await expect(store.lookup(conversationKey)).resolves.not.toHaveProperty(
+      "binding.nativeContextUsage",
+    );
+    await expect(fs.access(`${sidecarPath}.migrated`)).resolves.toBeUndefined();
+    await fs.rm(stateDir, { recursive: true, force: true });
+  });
+
+  it("uses canonical custom-store, agent, and nested transcript path resolution", async () => {
+    const stateDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-doctor-"));
+    const customStoreRoot = await fs.mkdtemp(
+      path.join(os.tmpdir(), "openclaw-codex-custom-store-"),
+    );
+    const env = { ...process.env, HOME: stateDir, OPENCLAW_STATE_DIR: stateDir };
+    const config = {
+      agents: { list: [{ id: "alpha" }] },
+      session: { store: path.join(customStoreRoot, "{agentId}", "sessions.json") },
+    };
+    const sessionsDir = path.join(customStoreRoot, "alpha");
+    const transcriptPath = path.join(sessionsDir, "nested", "session-custom.jsonl");
+    const sidecarPath = `${transcriptPath}.codex-app-server.json`;
+    await fs.mkdir(path.dirname(transcriptPath), { recursive: true });
+    await fs.writeFile(transcriptPath, '{"type":"session","id":"session-custom"}\n', "utf8");
+    await fs.writeFile(
+      path.join(sessionsDir, "sessions.json"),
+      JSON.stringify({
+        "agent:alpha:custom": {
+          sessionId: "session-custom",
+          sessionFile: "nested/session-custom.jsonl",
+          updatedAt: Date.now(),
+        },
+      }),
+      "utf8",
+    );
+    await fs.writeFile(
+      sidecarPath,
+      JSON.stringify({ schemaVersion: 1, threadId: "thread-custom" }),
+      "utf8",
+    );
+    const unrelatedSidecar = path.join(
+      customStoreRoot,
+      "unrelated",
+      `not-a-session.jsonl.codex-app-server.json`,
+    );
+    await fs.mkdir(path.dirname(unrelatedSidecar), { recursive: true });
+    await fs.writeFile(
+      unrelatedSidecar,
+      JSON.stringify({ schemaVersion: 1, threadId: "unrelated-thread" }),
+      "utf8",
+    );
+    const migration = stateMigrations[0];
+    if (!migration) {
+      throw new Error("missing Codex binding migration");
+    }
+
+    await migration.migrateLegacyState({
+      config,
+      env,
+      stateDir,
+      oauthDir: path.join(stateDir, "oauth"),
+      context: createDoctorContext(env),
+    });
+
+    const store = createDoctorContext(env).openPluginStateKeyedStore<StoredCodexAppServerBinding>({
+      namespace: CODEX_APP_SERVER_BINDING_NAMESPACE,
+      maxEntries: CODEX_APP_SERVER_BINDING_MAX_ENTRIES,
+      overflowPolicy: "reject-new",
+    });
+    await expect(
+      store.lookup(
+        bindingStoreKey({
+          kind: "session",
+          agentId: "alpha",
+          sessionId: "session-custom",
+          sessionKey: "agent:alpha:custom",
+        }),
+      ),
+    ).resolves.toMatchObject({
+      state: "active",
+      sessionId: "session-custom",
+      binding: { threadId: "thread-custom" },
+    });
+    await expect(
+      store.lookup(
+        bindingStoreKey({
+          kind: "conversation",
+          bindingId: legacyCodexConversationBindingId(transcriptPath),
+        }),
+      ),
+    ).resolves.toMatchObject({
+      state: "active",
+      binding: { threadId: "thread-custom" },
+    });
+    await expect(fs.access(unrelatedSidecar)).resolves.toBeUndefined();
+    await fs.rm(stateDir, { recursive: true, force: true });
+    await fs.rm(customStoreRoot, { recursive: true, force: true });
+  });
 });

extensions/codex/doctor-contract-api.ts

@@ -1,7 +1,4 @@
-/**
- * Doctor contract hooks for Codex plugin config migrations and session-route
- * ownership warnings.
- */
+/** Doctor contract hooks for Codex config, state migration, and route ownership. */
 import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
 import type { DoctorSessionRouteStateOwner } from "openclaw/plugin-sdk/runtime-doctor";
 
@@ -31,9 +28,7 @@ export const legacyConfigRules: LegacyConfigRule[] = [
   },
 ];
 
-/**
- * Removes retired Codex plugin config keys while preserving unrelated config.
- */
+/** Removes retired Codex plugin config keys while preserving unrelated config. */
 export function normalizeCompatibilityConfig({ cfg }: { cfg: OpenClawConfig }): {
   config: OpenClawConfig;
   changes: string[];
@@ -47,10 +42,9 @@ export function normalizeCompatibilityConfig({ cfg }: { cfg: OpenClawConfig }):
   const nextConfig = structuredClone(cfg) as OpenClawConfig & {
     plugins?: Record<string, unknown>;
   };
-  const nextPlugins = asRecord(nextConfig.plugins);
-  const nextEntries = asRecord(nextPlugins?.entries);
-  const nextEntry = asRecord(nextEntries?.codex);
-  const nextPluginConfig = asRecord(nextEntry?.config);
+  const nextPluginConfig = asRecord(
+    asRecord(asRecord(asRecord(nextConfig.plugins)?.entries)?.codex)?.config,
+  );
   if (!nextPluginConfig) {
     return { config: cfg, changes: [] };
   }
@@ -75,3 +69,5 @@ export const sessionRouteStateOwners: DoctorSessionRouteStateOwner[] = [
     authProfilePrefixes: ["codex:", "codex-cli:", "openai-codex:"],
   },
 ];
+
+export { stateMigrations } from "./src/migration/session-binding-sidecars.js";

extensions/codex/harness.test.ts

@@ -1,9 +1,18 @@
 // Codex tests cover harness plugin behavior.
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
 import { describe, expect, it } from "vitest";
 import { createCodexAppServerAgentHarness } from "./harness.js";
+import {
+  createCodexTestBindingStore,
+  testCodexAppServerBindingStore,
+} from "./src/app-server/session-binding.test-helpers.js";
 
 describe("Codex agent harness supports()", () => {
-  const harness = createCodexAppServerAgentHarness();
+  const harness = createCodexAppServerAgentHarness({
+    bindingStore: testCodexAppServerBindingStore,
+  });
 
   it("supports the canonical codex virtual provider", () => {
     expect(harness.supports({ provider: "codex", requestedRuntime: "codex" })).toEqual({
@@ -40,8 +49,149 @@ describe("Codex agent harness supports()", () => {
   });
 
   it("honors explicit provider id overrides", () => {
-    const narrowHarness = createCodexAppServerAgentHarness({ providerIds: ["codex"] });
+    const narrowHarness = createCodexAppServerAgentHarness({
+      bindingStore: testCodexAppServerBindingStore,
+      providerIds: ["codex"],
+    });
     const result = narrowHarness.supports({ provider: "openai", requestedRuntime: "codex" });
     expect(result.supported).toBe(false);
   });
 });
+
+describe("Codex agent harness reset", () => {
+  it("uses the host agent for global session keys", async () => {
+    const bindingStore = createCodexTestBindingStore();
+    const harness = createCodexAppServerAgentHarness({ bindingStore });
+    const identity = {
+      kind: "session" as const,
+      agentId: "work",
+      sessionId: "session-1",
+      sessionKey: "global",
+    };
+    await bindingStore.mutate(identity, {
+      kind: "set",
+      binding: { threadId: "thread-work", cwd: "/repo" },
+    });
+
+    await harness.reset?.({
+      agentId: "work",
+      sessionId: "session-1",
+      sessionKey: "global",
+      reason: "reset",
+    });
+
+    await expect(bindingStore.read(identity)).resolves.toBeUndefined();
+    await expect(
+      bindingStore.mutate(identity, {
+        kind: "set",
+        binding: { threadId: "thread-stale", cwd: "/stale" },
+      }),
+    ).resolves.toBe(false);
+    const nextIdentity = { ...identity, sessionId: "session-2" };
+    await expect(
+      bindingStore.mutate(nextIdentity, {
+        kind: "set",
+        binding: { threadId: "thread-next", cwd: "/next" },
+      }),
+    ).resolves.toBe(false);
+    await expect(
+      bindingStore.mutate(nextIdentity, {
+        kind: "reclaim-generation",
+        expectedPreviousSessionId: identity.sessionId,
+      }),
+    ).resolves.toBe(true);
+    await expect(
+      bindingStore.mutate(nextIdentity, {
+        kind: "set",
+        binding: { threadId: "thread-next", cwd: "/next" },
+      }),
+    ).resolves.toBe(true);
+    await expect(bindingStore.read(nextIdentity)).resolves.toMatchObject({
+      threadId: "thread-next",
+    });
+  });
+
+  it("accepts an absent binding but rejects a mismatched reset generation", async () => {
+    const bindingStore = createCodexTestBindingStore();
+    const harness = createCodexAppServerAgentHarness({ bindingStore });
+    const current = {
+      kind: "session" as const,
+      agentId: "main",
+      sessionId: "session-1",
+      sessionKey: "agent:main:main",
+    };
+
+    await expect(
+      harness.reset?.({
+        agentId: "main",
+        sessionId: "missing-session",
+        sessionKey: "agent:main:missing",
+        reason: "reset",
+      }),
+    ).resolves.toBeUndefined();
+
+    await bindingStore.mutate(current, {
+      kind: "set",
+      binding: { threadId: "thread-1", cwd: "/repo" },
+    });
+    await expect(
+      harness.reset?.({
+        agentId: "main",
+        sessionId: "session-2",
+        sessionKey: current.sessionKey,
+        reason: "reset",
+      }),
+    ).rejects.toThrow("binding generation changed");
+    await expect(bindingStore.read(current)).resolves.toMatchObject({ threadId: "thread-1" });
+  });
+
+  it("reclaims a stale generation left while the Codex plugin was unavailable", async () => {
+    const stateDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-reset-"));
+    const storePath = path.join(stateDir, "sessions.json");
+    const sessionKey = "agent:main:main";
+    await fs.writeFile(
+      storePath,
+      JSON.stringify({
+        [sessionKey]: {
+          sessionId: "session-2",
+          updatedAt: Date.now(),
+        },
+      }),
+      "utf8",
+    );
+    const bindingStore = createCodexTestBindingStore();
+    const harness = createCodexAppServerAgentHarness({
+      bindingStore,
+      resolveConfig: () => ({ session: { store: storePath } }),
+    });
+    const stale = {
+      kind: "session" as const,
+      agentId: "main",
+      sessionId: "session-1",
+      sessionKey,
+    };
+    await bindingStore.mutate(stale, {
+      kind: "set",
+      binding: { threadId: "thread-stale", cwd: "/repo" },
+    });
+
+    await expect(
+      harness.reset?.({
+        agentId: "main",
+        sessionId: "session-2",
+        sessionKey,
+        reason: "reset",
+      }),
+    ).resolves.toBeUndefined();
+
+    const current = { ...stale, sessionId: "session-2" };
+    await expect(bindingStore.read(current)).resolves.toBeUndefined();
+    await expect(
+      bindingStore.mutate(current, {
+        kind: "set",
+        binding: { threadId: "thread-delayed", cwd: "/repo" },
+      }),
+    ).resolves.toBe(false);
+    await fs.rm(stateDir, { recursive: true, force: true });
+  });
+});

extensions/codex/harness.ts

@@ -7,11 +7,13 @@ import type {
   AgentHarnessCompactResult,
   ContextEngineHostCapability,
 } from "openclaw/plugin-sdk/agent-harness-runtime";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
 import type {
   CodexAppServerListModelsOptions,
   CodexAppServerModel,
   CodexAppServerModelListResult,
 } from "./src/app-server/models.js";
+import type { CodexAppServerBindingStore } from "./src/app-server/session-binding.js";
 
 const DEFAULT_CODEX_HARNESS_PROVIDER_IDS = new Set(["codex", "openai"]);
 const CODEX_APP_SERVER_CONTEXT_ENGINE_HOST_CAPABILITIES = [
@@ -37,12 +39,14 @@ type CodexAppServerAgentHarness = AgentHarness & {
  * Creates the Codex app-server harness used for attempts, side questions,
  * compaction, reset, and disposal.
  */
-export function createCodexAppServerAgentHarness(options?: {
+export function createCodexAppServerAgentHarness(options: {
   id?: string;
   label?: string;
   providerIds?: Iterable<string>;
   pluginConfig?: unknown;
   resolvePluginConfig?: () => unknown;
+  resolveConfig?: () => OpenClawConfig | undefined;
+  bindingStore: CodexAppServerBindingStore;
 }): AgentHarness {
   const providerIds = new Set(
     [...(options?.providerIds ?? DEFAULT_CODEX_HARNESS_PROVIDER_IDS)].map((id) =>
@@ -71,6 +75,7 @@ export function createCodexAppServerAgentHarness(options?: {
       // cold provider catalog reads do not pull in the whole Codex runtime.
       const { runCodexAppServerAttempt } = await import("./src/app-server/run-attempt.js");
       return runCodexAppServerAttempt(params, {
+        bindingStore: options.bindingStore,
         pluginConfig: options?.resolvePluginConfig?.() ?? options?.pluginConfig,
         nativeHookRelay: { enabled: true },
       });
@@ -78,6 +83,7 @@ export function createCodexAppServerAgentHarness(options?: {
     runSideQuestion: async (params) => {
       const { runCodexAppServerSideQuestion } = await import("./src/app-server/side-question.js");
       return runCodexAppServerSideQuestion(params, {
+        bindingStore: options.bindingStore,
         pluginConfig: options?.resolvePluginConfig?.() ?? options?.pluginConfig,
         nativeHookRelay: { enabled: true },
       });
@@ -85,20 +91,43 @@ export function createCodexAppServerAgentHarness(options?: {
     compact: async (params) => {
       const { maybeCompactCodexAppServerSession } = await import("./src/app-server/compact.js");
       return maybeCompactCodexAppServerSession(params, {
+        bindingStore: options.bindingStore,
         pluginConfig: options?.resolvePluginConfig?.() ?? options?.pluginConfig,
       });
     },
     compactAfterContextEngine: async (params) => {
       const { maybeCompactCodexAppServerSession } = await import("./src/app-server/compact.js");
       return maybeCompactCodexAppServerSession(params, {
+        bindingStore: options.bindingStore,
         pluginConfig: options?.resolvePluginConfig?.() ?? options?.pluginConfig,
         allowNonManualNativeRequest: true,
       });
     },
     reset: async (params) => {
-      if (params.sessionFile) {
-        const { clearCodexAppServerBinding } = await import("./src/app-server/session-binding.js");
-        await clearCodexAppServerBinding(params.sessionFile);
+      if (params.sessionId) {
+        const { reclaimCurrentCodexSessionGeneration, sessionBindingIdentity } =
+          await import("./src/app-server/session-binding.js");
+        const identity = sessionBindingIdentity({
+          agentId: params.agentId,
+          sessionId: params.sessionId,
+          sessionKey: params.sessionKey,
+        });
+        let retired = await options.bindingStore.retireSessionGeneration(identity);
+        if (retired === "conflict") {
+          const reclaimed = await reclaimCurrentCodexSessionGeneration({
+            bindingStore: options.bindingStore,
+            identity,
+            config: options.resolveConfig?.(),
+          });
+          if (reclaimed) {
+            retired = await options.bindingStore.retireSessionGeneration(identity);
+          }
+        }
+        if (retired === "conflict") {
+          throw new Error(
+            `Codex binding generation changed before session ${params.sessionId} could reset`,
+          );
+        }
       }
     },
     dispose: async () => {

extensions/codex/index.test.ts

@@ -4,10 +4,30 @@ import { createTestPluginApi } from "openclaw/plugin-sdk/plugin-test-api";
 import { describe, expect, it, vi } from "vitest";
 import { createCodexAppServerAgentHarness } from "./harness.js";
 import plugin from "./index.js";
+import {
+  createCodexAppServerBindingStore,
+  sessionBindingIdentity,
+} from "./src/app-server/session-binding.js";
+import {
+  createCodexTestBindingStateStore,
+  testCodexAppServerBindingStore,
+} from "./src/app-server/session-binding.test-helpers.js";
 
 const runCodexAppServerAttemptMock = vi.hoisted(() => vi.fn());
 const runCodexAppServerSideQuestionMock = vi.hoisted(() => vi.fn());
 
+function createCodexTestRuntime(
+  current?: () => unknown,
+  stateStore = createCodexTestBindingStateStore(),
+) {
+  return {
+    ...(current ? { config: { current } } : {}),
+    state: {
+      openSyncKeyedStore: () => stateStore,
+    },
+  } as never;
+}
+
 vi.mock("./src/app-server/run-attempt.js", () => ({
   runCodexAppServerAttempt: runCodexAppServerAttemptMock,
 }));
@@ -39,7 +59,6 @@ describe("codex plugin", () => {
     const registerMigrationProvider = vi.fn();
     const registerProvider = vi.fn();
     const on = vi.fn();
-    const onConversationBindingResolved = vi.fn();
 
     plugin.register(
       createTestPluginApi({
@@ -48,14 +67,13 @@ describe("codex plugin", () => {
         source: "test",
         config: {},
         pluginConfig: {},
-        runtime: {} as never,
+        runtime: createCodexTestRuntime(),
         registerAgentHarness,
         registerCommand,
         registerMediaUnderstandingProvider,
         registerMigrationProvider,
         registerProvider,
         on,
-        onConversationBindingResolved,
       }),
     );
 
@@ -65,9 +83,6 @@ describe("codex plugin", () => {
       | Record<string, unknown>
       | undefined;
     const inboundClaimRegistration = mockCall(on) as [unknown, unknown] | undefined;
-    const bindingResolvedRegistration = mockCall(onConversationBindingResolved) as
-      | [unknown]
-      | undefined;
 
     expect(providerRegistration.id).toBe("codex");
     expect(providerRegistration.label).toBe("Codex");
@@ -94,33 +109,12 @@ describe("codex plugin", () => {
     expect(migrationRegistration?.label).toBe("Codex");
     expect(inboundClaimRegistration?.[0]).toBe("inbound_claim");
     expect(typeof inboundClaimRegistration?.[1]).toBe("function");
-    expect(typeof bindingResolvedRegistration?.[0]).toBe("function");
-  });
-
-  it("registers with capture APIs that do not expose conversation binding hooks yet", () => {
-    const registerProvider = vi.fn();
-    const api = createTestPluginApi({
-      id: "codex",
-      name: "Codex",
-      source: "test",
-      config: {},
-      pluginConfig: {},
-      runtime: {} as never,
-      registerAgentHarness: vi.fn(),
-      registerCommand: vi.fn(),
-      registerMediaUnderstandingProvider: vi.fn(),
-      registerProvider,
-      on: vi.fn(),
-    });
-    delete (api as { onConversationBindingResolved?: unknown }).onConversationBindingResolved;
-
-    plugin.register(api);
-    expect(registerProvider).toHaveBeenCalledTimes(1);
-    expect((mockCallArg(registerProvider) as { id?: string } | undefined)?.id).toBe("codex");
   });
 
   it("claims the Codex routing providers by default", () => {
-    const harness = createCodexAppServerAgentHarness();
+    const harness = createCodexAppServerAgentHarness({
+      bindingStore: testCodexAppServerBindingStore,
+    });
 
     expect(harness.deliveryDefaults?.sourceVisibleReplies).toBe("message_tool");
     expect(
@@ -141,8 +135,196 @@ describe("codex plugin", () => {
     expect(unsupported.supported).toBe(false);
   });
 
+  it("clears only ended session binding rows in the owning agent scope", async () => {
+    const stateStore = createCodexTestBindingStateStore();
+    const bindingStore = createCodexAppServerBindingStore(stateStore);
+    const on = vi.fn();
+    plugin.register(
+      createTestPluginApi({
+        id: "codex",
+        name: "Codex",
+        source: "test",
+        config: {},
+        pluginConfig: {},
+        runtime: createCodexTestRuntime(undefined, stateStore),
+        registerAgentHarness: vi.fn(),
+        registerCommand: vi.fn(),
+        registerMediaUnderstandingProvider: vi.fn(),
+        registerMigrationProvider: vi.fn(),
+        registerProvider: vi.fn(),
+        on,
+      }),
+    );
+    const sessionEnd = on.mock.calls.find(([name]) => name === "session_end")?.[1] as
+      | ((
+          event: { sessionId: string; sessionKey?: string; reason?: string },
+          ctx: { agentId?: string; sessionId: string; sessionKey?: string },
+        ) => Promise<void>)
+      | undefined;
+    if (!sessionEnd) {
+      throw new Error("missing Codex session_end hook");
+    }
+    const identity = sessionBindingIdentity({
+      agentId: "worker",
+      sessionId: "session-1",
+      sessionKey: "agent:worker:session-1",
+    });
+    const setBinding = () =>
+      bindingStore.mutate(identity, {
+        kind: "set",
+        binding: { threadId: "thread-1", cwd: "/repo" },
+      });
+
+    for (const reason of ["shutdown", "restart", "compaction", "unknown"] as const) {
+      await setBinding();
+      await sessionEnd(
+        { sessionId: "session-1", sessionKey: "agent:worker:session-1", reason },
+        { agentId: "worker", sessionId: "session-1" },
+      );
+      await expect(bindingStore.read(identity)).resolves.toMatchObject({
+        threadId: "thread-1",
+      });
+    }
+    for (const reason of ["new", "reset", "idle", "daily", "deleted"] as const) {
+      await setBinding();
+      await sessionEnd(
+        { sessionId: "session-1", sessionKey: "agent:worker:session-1", reason },
+        { agentId: "worker", sessionId: "session-1" },
+      );
+      await expect(bindingStore.read(identity)).resolves.toBeUndefined();
+    }
+  });
+
+  it("adopts compaction successors before delayed lifecycle cleanup", async () => {
+    const stateStore = createCodexTestBindingStateStore();
+    const bindingStore = createCodexAppServerBindingStore(stateStore);
+    const on = vi.fn();
+    plugin.register(
+      createTestPluginApi({
+        id: "codex",
+        name: "Codex",
+        source: "test",
+        config: {},
+        pluginConfig: {},
+        runtime: createCodexTestRuntime(undefined, stateStore),
+        registerAgentHarness: vi.fn(),
+        registerCommand: vi.fn(),
+        registerMediaUnderstandingProvider: vi.fn(),
+        registerMigrationProvider: vi.fn(),
+        registerProvider: vi.fn(),
+        on,
+      }),
+    );
+    const afterCompaction = on.mock.calls.find(([name]) => name === "after_compaction")?.[1] as
+      | ((
+          event: {
+            messageCount: number;
+            compactedCount: number;
+            previousSessionId?: string;
+          },
+          ctx: { agentId?: string; sessionId?: string; sessionKey?: string },
+        ) => Promise<void>)
+      | undefined;
+    const sessionEnd = on.mock.calls.find(([name]) => name === "session_end")?.[1] as
+      | ((
+          event: { sessionId: string; sessionKey?: string; reason?: string },
+          ctx: { agentId?: string; sessionId: string; sessionKey?: string },
+        ) => Promise<void>)
+      | undefined;
+    if (!afterCompaction || !sessionEnd) {
+      throw new Error("missing Codex compaction lifecycle hooks");
+    }
+    const sessionKey = "agent:worker:telegram:chat-1";
+    const previous = sessionBindingIdentity({
+      agentId: "worker",
+      sessionId: "session-1",
+      sessionKey,
+    });
+    const successor = sessionBindingIdentity({
+      agentId: "worker",
+      sessionId: "session-2",
+      sessionKey,
+    });
+    const newest = sessionBindingIdentity({
+      agentId: "worker",
+      sessionId: "session-3",
+      sessionKey,
+    });
+    await bindingStore.mutate(previous, {
+      kind: "set",
+      binding: { threadId: "thread-1", cwd: "/repo" },
+    });
+
+    await afterCompaction(
+      { messageCount: 1, compactedCount: 1, previousSessionId: "session-1" },
+      { agentId: "worker", sessionId: "session-2", sessionKey },
+    );
+    await expect(bindingStore.read(previous)).resolves.toBeUndefined();
+    await expect(bindingStore.read(successor)).resolves.toMatchObject({ threadId: "thread-1" });
+
+    await afterCompaction(
+      { messageCount: 1, compactedCount: 1, previousSessionId: "session-2" },
+      { agentId: "worker", sessionId: "session-3", sessionKey },
+    );
+    await afterCompaction(
+      { messageCount: 1, compactedCount: 1, previousSessionId: "session-1" },
+      { agentId: "worker", sessionId: "session-2", sessionKey },
+    );
+    await expect(bindingStore.read(successor)).resolves.toBeUndefined();
+    await expect(bindingStore.read(newest)).resolves.toMatchObject({ threadId: "thread-1" });
+
+    await sessionEnd(
+      { sessionId: "session-1", sessionKey, reason: "reset" },
+      { agentId: "worker", sessionId: "session-1", sessionKey },
+    );
+    await sessionEnd(
+      { sessionId: "session-2", sessionKey, reason: "compaction" },
+      { agentId: "worker", sessionId: "session-2", sessionKey },
+    );
+    await expect(bindingStore.read(newest)).resolves.toMatchObject({ threadId: "thread-1" });
+    expect(stateStore.entries()).toHaveLength(1);
+  });
+
+  it("ignores compaction for a session without a Codex binding", async () => {
+    const warn = vi.fn();
+    const on = vi.fn();
+    plugin.register(
+      createTestPluginApi({
+        id: "codex",
+        name: "Codex",
+        source: "test",
+        config: {},
+        pluginConfig: {},
+        logger: { debug: vi.fn(), info: vi.fn(), warn, error: vi.fn() },
+        runtime: createCodexTestRuntime(),
+        registerAgentHarness: vi.fn(),
+        registerCommand: vi.fn(),
+        registerMediaUnderstandingProvider: vi.fn(),
+        registerMigrationProvider: vi.fn(),
+        registerProvider: vi.fn(),
+        on,
+      }),
+    );
+    const afterCompaction = on.mock.calls.find(([name]) => name === "after_compaction")?.[1] as
+      | ((event: object, ctx: { sessionId?: string; sessionKey?: string }) => Promise<void>)
+      | undefined;
+    if (!afterCompaction) {
+      throw new Error("missing Codex after_compaction hook");
+    }
+
+    await afterCompaction(
+      { previousSessionId: "session-1" },
+      { sessionId: "session-2", sessionKey: "agent:main:main" },
+    );
+
+    expect(warn).not.toHaveBeenCalled();
+  });
+
   it("enables the native hook relay for public Codex app-server attempts", async () => {
-    const harness = createCodexAppServerAgentHarness({ pluginConfig: { appServer: {} } });
+    const harness = createCodexAppServerAgentHarness({
+      bindingStore: testCodexAppServerBindingStore,
+      pluginConfig: { appServer: {} },
+    });
     const result = { success: true };
     runCodexAppServerAttemptMock.mockResolvedValueOnce(result);
 
@@ -151,6 +333,7 @@ describe("codex plugin", () => {
     expect(runCodexAppServerAttemptMock).toHaveBeenCalledWith(
       { prompt: "hello" },
       {
+        bindingStore: testCodexAppServerBindingStore,
         pluginConfig: { appServer: {} },
         nativeHookRelay: { enabled: true },
       },
@@ -185,11 +368,7 @@ describe("codex plugin", () => {
         source: "test",
         config: {},
         pluginConfig: { codexPlugins: { enabled: false } },
-        runtime: {
-          config: {
-            current: () => liveConfig,
-          },
-        } as never,
+        runtime: createCodexTestRuntime(() => liveConfig),
         registerAgentHarness,
         registerCommand: vi.fn(),
         registerMediaUnderstandingProvider: vi.fn(),
@@ -209,14 +388,49 @@ describe("codex plugin", () => {
     expect(runCodexAppServerAttemptMock).toHaveBeenCalledWith(
       { prompt: "calendar" },
       {
+        bindingStore: expect.any(Object),
         pluginConfig: liveConfig.plugins.entries.codex.config,
         nativeHookRelay: { enabled: true },
       },
     );
   });
 
+  it("does not resurrect startup Codex config after the live entry is removed", async () => {
+    const registerAgentHarness = vi.fn();
+    plugin.register(
+      createTestPluginApi({
+        id: "codex",
+        name: "Codex",
+        source: "test",
+        config: {},
+        pluginConfig: { appServer: { mode: "yolo" } },
+        runtime: createCodexTestRuntime(() => ({ plugins: { entries: {} } })),
+        registerAgentHarness,
+        registerCommand: vi.fn(),
+        registerMediaUnderstandingProvider: vi.fn(),
+        registerMigrationProvider: vi.fn(),
+        registerProvider: vi.fn(),
+        on: vi.fn(),
+      }),
+    );
+    const harness = mockCallArg(registerAgentHarness) as ReturnType<
+      typeof createCodexAppServerAgentHarness
+    >;
+    runCodexAppServerAttemptMock.mockResolvedValueOnce({ success: true });
+
+    await harness.runAttempt({ prompt: "default policy" } as never);
+
+    expect(runCodexAppServerAttemptMock).toHaveBeenCalledWith(
+      { prompt: "default policy" },
+      expect.objectContaining({ pluginConfig: undefined }),
+    );
+  });
+
   it("enables the native hook relay for public Codex side questions", async () => {
-    const harness = createCodexAppServerAgentHarness({ pluginConfig: { appServer: {} } });
+    const harness = createCodexAppServerAgentHarness({
+      bindingStore: testCodexAppServerBindingStore,
+      pluginConfig: { appServer: {} },
+    });
     const runSideQuestion = harness["runSideQuestion"];
     const result = { text: "ok" };
     runCodexAppServerSideQuestionMock.mockResolvedValueOnce(result);
@@ -229,6 +443,7 @@ describe("codex plugin", () => {
     expect(runCodexAppServerSideQuestionMock).toHaveBeenCalledWith(
       { question: "btw" },
       {
+        bindingStore: testCodexAppServerBindingStore,
         pluginConfig: { appServer: {} },
         nativeHookRelay: { enabled: true },
       },

extensions/codex/index.ts

@@ -4,47 +4,71 @@
  */
 import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
 import { mutateConfigFile } from "openclaw/plugin-sdk/config-mutation";
-import { resolveLivePluginConfigObject } from "openclaw/plugin-sdk/plugin-config-runtime";
+import {
+  resolveLivePluginConfigObject,
+  resolvePluginConfigObject,
+} from "openclaw/plugin-sdk/plugin-config-runtime";
 import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
 import { createCodexAppServerAgentHarness } from "./harness.js";
 import { buildCodexMediaUnderstandingProvider } from "./media-understanding-provider.js";
 import { buildCodexProvider } from "./provider.js";
+import {
+  CODEX_APP_SERVER_BINDING_MAX_ENTRIES,
+  CODEX_APP_SERVER_BINDING_NAMESPACE,
+  createLazyCodexAppServerBindingStore,
+  type StoredCodexAppServerBinding,
+} from "./src/app-server/session-binding-store.js";
 import type { CodexPluginsConfigBlock } from "./src/command-plugins-management.js";
 import { createCodexCommand } from "./src/commands.js";
-import {
-  handleCodexConversationBindingResolved,
-  handleCodexConversationInboundClaim,
-} from "./src/conversation-binding.js";
 import { buildCodexMigrationProvider } from "./src/migration/provider.js";
 import {
   createCodexCliSessionNodeHostCommands,
   createCodexCliSessionNodeInvokePolicies,
-  listCodexCliSessionsOnNode,
-  resumeCodexCliSessionOnNode,
-  resolveCodexCliSessionForBindingOnNode,
-} from "./src/node-cli-sessions.js";
+} from "./src/node-cli-session-registration.js";
+
+const ENDED_SESSION_REASONS: ReadonlySet<string> = new Set([
+  "new",
+  "reset",
+  "idle",
+  "daily",
+  "deleted",
+]);
 
 export default definePluginEntry({
   id: "codex",
   name: "Codex",
   description: "Codex app-server harness and Codex-managed GPT model catalog.",
   register(api) {
-    const resolveCurrentConfig = () =>
-      api.runtime.config?.current ? (api.runtime.config.current() as OpenClawConfig) : undefined;
+    const runtimeConfigLoader = api.runtime.config?.current
+      ? () => api.runtime.config?.current() as OpenClawConfig
+      : undefined;
+    const resolveCurrentConfig = () => runtimeConfigLoader?.();
+    const loadNodeCliSessions = () => import("./src/node-cli-sessions.js");
     const resolveCurrentPluginConfig = () =>
       // Codex plugin config can change at runtime; resolve from live config for
       // harness attempts and binding claims instead of keeping startup values.
       resolveLivePluginConfigObject(
-        resolveCurrentConfig,
+        runtimeConfigLoader,
         "codex",
         api.pluginConfig as Record<string, unknown>,
-      ) ?? api.pluginConfig;
+      );
+    const bindingStore = createLazyCodexAppServerBindingStore(
+      api.runtime.state.openSyncKeyedStore<StoredCodexAppServerBinding>({
+        namespace: CODEX_APP_SERVER_BINDING_NAMESPACE,
+        maxEntries: CODEX_APP_SERVER_BINDING_MAX_ENTRIES,
+        overflowPolicy: "reject-new",
+      }),
+    );
     api.registerAgentHarness(
-      createCodexAppServerAgentHarness({ resolvePluginConfig: resolveCurrentPluginConfig }),
+      createCodexAppServerAgentHarness({
+        bindingStore,
+        resolveConfig: resolveCurrentConfig,
+        resolvePluginConfig: resolveCurrentPluginConfig,
+      }),
     );
     api.registerProvider(buildCodexProvider({ pluginConfig: api.pluginConfig }));
     api.registerMediaUnderstandingProvider(
-      buildCodexMediaUnderstandingProvider({ pluginConfig: api.pluginConfig }),
+      buildCodexMediaUnderstandingProvider({ resolvePluginConfig: resolveCurrentPluginConfig }),
     );
     api.registerMigrationProvider(buildCodexMigrationProvider({ runtime: api.runtime }));
     for (const command of createCodexCliSessionNodeHostCommands()) {
@@ -55,43 +79,43 @@ export default definePluginEntry({
     }
     api.registerCommand(
       createCodexCommand({
-        pluginConfig: api.pluginConfig,
+        resolvePluginConfig: resolveCurrentPluginConfig,
         deps: {
-          listCodexCliSessionsOnNode: (params) =>
-            listCodexCliSessionsOnNode({ runtime: api.runtime, ...params }),
-          resolveCodexCliSessionForBindingOnNode: (params) =>
-            resolveCodexCliSessionForBindingOnNode({ runtime: api.runtime, ...params }),
+          bindingStore,
+          listCodexCliSessionsOnNode: async (params) =>
+            await (
+              await loadNodeCliSessions()
+            ).listCodexCliSessionsOnNode({
+              runtime: api.runtime,
+              ...params,
+            }),
+          resolveCodexCliSessionForBindingOnNode: async (params) =>
+            await (
+              await loadNodeCliSessions()
+            ).resolveCodexCliSessionForBindingOnNode({
+              runtime: api.runtime,
+              ...params,
+            }),
           codexPluginsManagementIo: {
             readConfig: () => {
               const current = (api.runtime.config?.current?.() ?? {}) as OpenClawConfig;
-              const plugins = (current as Record<string, unknown>).plugins;
-              if (!plugins || typeof plugins !== "object") {
+              const codexPlugins = resolvePluginConfigObject(current, "codex")?.codexPlugins;
+              if (
+                !codexPlugins ||
+                typeof codexPlugins !== "object" ||
+                Array.isArray(codexPlugins)
+              ) {
                 return Promise.resolve({});
               }
-              const entries = (plugins as Record<string, unknown>).entries;
-              if (!entries || typeof entries !== "object") {
-                return Promise.resolve({});
-              }
-              const codexEntry = (entries as Record<string, unknown>).codex;
-              if (!codexEntry || typeof codexEntry !== "object") {
-                return Promise.resolve({});
-              }
-              const config = (codexEntry as Record<string, unknown>).config;
-              if (!config || typeof config !== "object") {
-                return Promise.resolve({});
-              }
-              const codexPlugins = (config as Record<string, unknown>).codexPlugins;
-              if (!codexPlugins || typeof codexPlugins !== "object") {
-                return Promise.resolve({});
-              }
-              const declared = (codexPlugins as Record<string, unknown>).plugins;
+              const block = codexPlugins as Record<string, unknown>;
+              const declared = block.plugins;
               if (!declared || typeof declared !== "object") {
                 return Promise.resolve({
-                  enabled: (codexPlugins as Record<string, unknown>).enabled === true,
+                  enabled: block.enabled === true,
                 });
               }
               return Promise.resolve({
-                enabled: (codexPlugins as Record<string, unknown>).enabled === true,
+                enabled: block.enabled === true,
                 plugins: declared as Record<string, never>,
               });
             },
@@ -101,17 +125,12 @@ export default definePluginEntry({
                   // Create the nested plugin config path on demand so codex
                   // plugin commands can enable/update Codex-managed plugins.
                   const root = draft as Record<string, unknown>;
-                  root.plugins = (root.plugins ?? {}) as Record<string, unknown>;
-                  const pluginsBlock = root.plugins as Record<string, unknown>;
-                  pluginsBlock.entries = (pluginsBlock.entries ?? {}) as Record<string, unknown>;
-                  const entries = pluginsBlock.entries as Record<string, unknown>;
-                  entries.codex = (entries.codex ?? {}) as Record<string, unknown>;
-                  const codexEntry = entries.codex as Record<string, unknown>;
-                  codexEntry.config = (codexEntry.config ?? {}) as Record<string, unknown>;
-                  const config = codexEntry.config as Record<string, unknown>;
-                  config.codexPlugins = (config.codexPlugins ?? {}) as Record<string, unknown>;
-                  const codexPlugins = config.codexPlugins as Record<string, unknown>;
-                  codexPlugins.plugins = (codexPlugins.plugins ?? {}) as Record<string, unknown>;
+                  const pluginsBlock = (root.plugins ??= {}) as Record<string, unknown>;
+                  const entries = (pluginsBlock.entries ??= {}) as Record<string, unknown>;
+                  const codexEntry = (entries.codex ??= {}) as Record<string, unknown>;
+                  const config = (codexEntry.config ??= {}) as Record<string, unknown>;
+                  const codexPlugins = (config.codexPlugins ??= {}) as Record<string, unknown>;
+                  codexPlugins.plugins ??= {};
                   update(codexPlugins as CodexPluginsConfigBlock);
                 },
               });
@@ -120,14 +139,58 @@ export default definePluginEntry({
         },
       }),
     );
-    api.on("inbound_claim", (event, ctx) =>
-      handleCodexConversationInboundClaim(event, ctx, {
+    api.on("inbound_claim", async (event, ctx) => {
+      const { handleCodexConversationInboundClaim } = await import("./src/conversation-binding.js");
+      return await handleCodexConversationInboundClaim(event, ctx, {
+        bindingStore,
         pluginConfig: resolveCurrentPluginConfig(),
         config: resolveCurrentConfig(),
-        resumeCodexCliSessionOnNode: (params) =>
-          resumeCodexCliSessionOnNode({ runtime: api.runtime, ...params }),
-      }),
-    );
-    api.onConversationBindingResolved?.(handleCodexConversationBindingResolved);
+        resumeCodexCliSessionOnNode: async (params) =>
+          await (
+            await loadNodeCliSessions()
+          ).resumeCodexCliSessionOnNode({
+            runtime: api.runtime,
+            ...params,
+          }),
+      });
+    });
+    api.on("after_compaction", async (event, ctx) => {
+      const previousSessionId = event.previousSessionId?.trim();
+      const sessionId = ctx.sessionId?.trim();
+      if (!previousSessionId || !sessionId || previousSessionId === sessionId) {
+        return;
+      }
+      const config = resolveCurrentConfig();
+      const sessionKey = ctx.sessionKey?.trim();
+      const { sessionBindingIdentity } = await import("./src/app-server/session-binding.js");
+      const identity = sessionBindingIdentity({
+        sessionId,
+        ...(sessionKey ? { sessionKey } : {}),
+        ...(ctx.agentId ? { agentId: ctx.agentId } : {}),
+        ...(config ? { config } : {}),
+      });
+      const adopted = await bindingStore.adoptSessionGeneration(identity, previousSessionId);
+      if (adopted === "conflict") {
+        api.logger.warn?.(
+          `codex: could not adopt compacted session generation ${sessionId} (${adopted}); secondary native compaction will skip`,
+        );
+      }
+    });
+    api.on("session_end", async (event, ctx) => {
+      if (!event.reason || !ENDED_SESSION_REASONS.has(event.reason)) {
+        return;
+      }
+      const sessionKey = event.sessionKey ?? ctx.sessionKey;
+      const config = resolveCurrentConfig();
+      const { sessionBindingIdentity } = await import("./src/app-server/session-binding.js");
+      await bindingStore.retireSessionGeneration(
+        sessionBindingIdentity({
+          sessionId: event.sessionId,
+          ...(sessionKey ? { sessionKey } : {}),
+          ...(ctx.agentId ? { agentId: ctx.agentId } : {}),
+          ...(config ? { config } : {}),
+        }),
+      );
+    });
   },
 });

extensions/codex/media-understanding-provider.test.ts

@@ -2,8 +2,33 @@
 import { MAX_TIMER_TIMEOUT_MS } from "openclaw/plugin-sdk/number-runtime";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { buildCodexMediaUnderstandingProvider } from "./media-understanding-provider.js";
-import type { CodexAppServerClient } from "./src/app-server/client.js";
+import { CodexAppServerRpcError, type CodexAppServerClient } from "./src/app-server/client.js";
 import type { CodexServerNotification, JsonValue } from "./src/app-server/protocol.js";
+import { adaptCodexTestClientFactory } from "./src/app-server/test-support.js";
+
+const EXPECTED_MEDIA_THREAD_CONFIG = {
+  project_doc_max_bytes: 0,
+  web_search: "disabled",
+  "tools.experimental_request_user_input.enabled": false,
+  "features.hooks": false,
+  "features.multi_agent": false,
+  "features.apps": false,
+  "features.plugins": false,
+  "features.image_generation": false,
+  "features.skill_mcp_dependency_install": false,
+  "features.memories": false,
+  "features.goals": false,
+  "features.code_mode": false,
+  "features.code_mode_only": false,
+};
+
+const sharedClientMocks = vi.hoisted(() => ({
+  createIsolatedCodexAppServerClient: vi.fn(),
+}));
+
+vi.mock("./src/app-server/shared-client.js", () => ({
+  createIsolatedCodexAppServerClient: sharedClientMocks.createIsolatedCodexAppServerClient,
+}));
 
 function codexModel(inputModalities: string[] = ["text", "image"]) {
   return {
@@ -77,13 +102,15 @@ function createFakeClient(options?: {
   inputModalities?: string[];
   completeWithItems?: boolean;
   notifyError?: string;
-  approvalRequestMethod?: string;
   responseText?: string;
+  turnStartError?: Error;
+  preBindNotificationCount?: number;
+  interruptError?: Error;
+  unsubscribeError?: Error;
 }) {
   const notifications = new Set<(notification: CodexServerNotification) => void>();
-  const requestHandlers = new Set<(request: { method: string }) => JsonValue | undefined>();
+  const closeHandlers = new Set<() => void>();
   const requests: Array<{ method: string; params?: JsonValue }> = [];
-  const approvalResponses: JsonValue[] = [];
   const request = vi.fn(async (method: string, params?: JsonValue) => {
     requests.push({ method, params });
     if (method === "model/list") {
@@ -96,51 +123,60 @@ function createFakeClient(options?: {
       return threadStartResult();
     }
     if (method === "turn/start") {
-      if (options?.approvalRequestMethod) {
-        for (const handler of requestHandlers) {
-          const response = handler({ method: options.approvalRequestMethod });
-          if (response !== undefined) {
-            approvalResponses.push(response);
+      if (options?.turnStartError) {
+        throw options.turnStartError;
+      }
+      if (options?.preBindNotificationCount) {
+        for (let index = 0; index < options.preBindNotificationCount; index += 1) {
+          for (const notify of notifications) {
+            notify({
+              method: "item/started",
+              params: { threadId: "thread-1", turnId: "turn-1" },
+            });
           }
         }
+        return turnStartResult();
       }
-      if (options?.notifyError) {
-        for (const notify of notifications) {
-          notify({
-            method: "error",
-            params: {
-              threadId: "thread-1",
-              turnId: "turn-1",
-              error: {
-                message: options.notifyError,
-                codexErrorInfo: null,
-                additionalDetails: null,
+      const emitTurnNotifications = () => {
+        if (options?.notifyError) {
+          for (const notify of notifications) {
+            notify({
+              method: "error",
+              params: {
+                threadId: "thread-1",
+                turnId: "turn-1",
+                error: {
+                  message: options.notifyError,
+                  codexErrorInfo: null,
+                  additionalDetails: null,
+                },
+                willRetry: false,
               },
-              willRetry: false,
-            },
-          });
+            });
+          }
+        } else if (!options?.completeWithItems) {
+          for (const notify of notifications) {
+            notify({
+              method: "item/agentMessage/delta",
+              params: {
+                threadId: "thread-1",
+                turnId: "turn-1",
+                itemId: "msg-1",
+                delta: options?.responseText ?? "A red square.",
+              },
+            });
+            notify({
+              method: "turn/completed",
+              params: {
+                threadId: "thread-1",
+                turnId: "turn-1",
+                turn: turnStartResult("completed").turn,
+              },
+            });
+          }
         }
-      } else if (!options?.completeWithItems) {
-        for (const notify of notifications) {
-          notify({
-            method: "item/agentMessage/delta",
-            params: {
-              threadId: "thread-1",
-              turnId: "turn-1",
-              itemId: "msg-1",
-              delta: options?.responseText ?? "A red square.",
-            },
-          });
-          notify({
-            method: "turn/completed",
-            params: {
-              threadId: "thread-1",
-              turnId: "turn-1",
-              turn: turnStartResult("completed").turn,
-            },
-          });
-        }
-      }
+      };
+      emitTurnNotifications();
       return turnStartResult(
         options?.completeWithItems ? "completed" : "inProgress",
         options?.completeWithItems
@@ -156,6 +192,12 @@ function createFakeClient(options?: {
           : [],
       );
     }
+    if (method === "turn/interrupt" && options?.interruptError) {
+      throw options.interruptError;
+    }
+    if (method === "thread/unsubscribe" && options?.unsubscribeError) {
+      throw options.unsubscribeError;
+    }
     return {};
   });
 
@@ -165,26 +207,39 @@ function createFakeClient(options?: {
       notifications.add(handler);
       return () => notifications.delete(handler);
     },
-    addRequestHandler(handler: (request: { method: string }) => JsonValue | undefined) {
-      requestHandlers.add(handler);
-      return () => requestHandlers.delete(handler);
+    addRequestHandler() {
+      return () => undefined;
     },
+    addCloseHandler(handler: () => void) {
+      closeHandlers.add(handler);
+      return () => closeHandlers.delete(handler);
+    },
+    close: vi.fn(),
   } as unknown as CodexAppServerClient;
 
-  return { client, requests, approvalResponses };
+  return { client, requests };
 }
 
 describe("codex media understanding provider", () => {
   afterEach(() => {
     vi.useRealTimers();
     vi.restoreAllMocks();
+    sharedClientMocks.createIsolatedCodexAppServerClient.mockReset();
   });
 
   it("runs image understanding through a bounded Codex app-server turn", async () => {
     const { client, requests } = createFakeClient();
+    const clientFactory = vi.fn(async () => client);
     const provider = buildCodexMediaUnderstandingProvider({
-      clientFactory: async () => client,
+      clientLeaseFactory: adaptCodexTestClientFactory(clientFactory),
     });
+    const cfg = {
+      auth: {
+        order: {
+          openai: ["openai:work"],
+        },
+      },
+    };
 
     const result = await provider.describeImage?.({
       buffer: Buffer.from("image-bytes"),
@@ -194,34 +249,38 @@ describe("codex media understanding provider", () => {
       model: "gpt-5.4",
       prompt: "Describe briefly.",
       timeoutMs: 30_000,
-      cfg: {},
+      cfg,
       agentDir: "/tmp/openclaw-agent",
     });
 
     expect(result).toEqual({ text: "A red square.", model: "gpt-5.4" });
+    expect(clientFactory).toHaveBeenCalledWith(
+      expect.any(Object),
+      undefined,
+      "/tmp/openclaw-agent",
+      cfg,
+      expect.objectContaining({ timeoutMs: 30_000 }),
+    );
     expect(requests.map((entry) => entry.method)).toEqual([
       "model/list",
       "thread/start",
       "turn/start",
+      "thread/unsubscribe",
     ]);
+    expect(requests[0]?.params).toEqual({ limit: 100, cursor: null, includeHidden: true });
     expect(requests[1]?.params).toEqual({
       model: "gpt-5.4",
       modelProvider: "openai",
-      cwd: "/tmp/openclaw-agent",
-      approvalPolicy: "on-request",
+      cwd: "/tmp/openclaw-agent/codex-media-home",
+      approvalPolicy: "never",
       sandbox: "read-only",
       serviceName: "OpenClaw",
+      personality: "none",
       developerInstructions:
         "You are OpenClaw's bounded image-understanding worker. Describe only the provided image content. Do not call tools, edit files, or ask follow-up questions.",
-      config: {
-        "features.code_mode": false,
-        "features.code_mode_only": false,
-      },
+      config: EXPECTED_MEDIA_THREAD_CONFIG,
       environments: [],
-      dynamicTools: [],
-      experimentalRawEvents: true,
       ephemeral: true,
-      persistExtendedHistory: false,
     });
     expect(requests[2]?.params).toEqual({
       threadId: "thread-1",
@@ -229,19 +288,83 @@ describe("codex media understanding provider", () => {
         { type: "text", text: "Describe briefly.", text_elements: [] },
         { type: "image", url: "data:image/png;base64,aW1hZ2UtYnl0ZXM=" },
       ],
-      cwd: "/tmp/openclaw-agent",
-      approvalPolicy: "on-request",
-      model: "gpt-5.4",
       effort: "low",
     });
   });
 
+  it("treats a blank agent directory as absent when starting the app-server", async () => {
+    const { client, requests } = createFakeClient();
+    const clientFactory = vi.fn(async () => client);
+    const provider = buildCodexMediaUnderstandingProvider({
+      clientLeaseFactory: adaptCodexTestClientFactory(clientFactory),
+    });
+    const cfg = {
+      agents: { list: [{ id: "main", agentDir: "/tmp/openclaw-default-agent" }] },
+    };
+
+    await provider.describeImage?.({
+      buffer: Buffer.from("image-bytes"),
+      fileName: "image.png",
+      mime: "image/png",
+      provider: "codex",
+      model: "gpt-5.4",
+      timeoutMs: 30_000,
+      cfg,
+      agentDir: " ",
+    });
+
+    expect(clientFactory).toHaveBeenCalledWith(
+      expect.any(Object),
+      undefined,
+      "/tmp/openclaw-default-agent",
+      cfg,
+      expect.any(Object),
+    );
+    expect(requests[1]?.params).toEqual(
+      expect.objectContaining({ cwd: "/tmp/openclaw-default-agent/codex-media-home" }),
+    );
+  });
+
+  it("passes the scoped auth store into isolated app-server startup", async () => {
+    const { client } = createFakeClient();
+    sharedClientMocks.createIsolatedCodexAppServerClient.mockResolvedValue(client);
+    const provider = buildCodexMediaUnderstandingProvider();
+    const authStore = {
+      version: 1,
+      profiles: {
+        "openai:scoped": {
+          type: "oauth" as const,
+          provider: "openai",
+          access: "scoped-access",
+          refresh: "scoped-refresh",
+          expires: Date.now() + 60_000,
+        },
+      },
+    };
+
+    await provider.describeImage?.({
+      buffer: Buffer.from("image-bytes"),
+      fileName: "image.png",
+      mime: "image/png",
+      provider: "codex",
+      model: "gpt-5.4",
+      timeoutMs: 30_000,
+      cfg: {},
+      authStore,
+      agentDir: "/tmp/openclaw-agent",
+    });
+
+    expect(sharedClientMocks.createIsolatedCodexAppServerClient).toHaveBeenCalledWith(
+      expect.objectContaining({ authProfileStore: authStore }),
+    );
+  });
+
   it("clamps oversized image understanding turn timeouts", async () => {
     const setTimeoutSpy = vi.spyOn(globalThis, "setTimeout");
     try {
       const { client } = createFakeClient();
       const provider = buildCodexMediaUnderstandingProvider({
-        clientFactory: async () => client,
+        clientLeaseFactory: adaptCodexTestClientFactory(async () => client),
       });
 
       const result = await provider.describeImage?.({
@@ -264,33 +387,97 @@ describe("codex media understanding provider", () => {
     }
   });
 
-  it("declines approval requests during image understanding", async () => {
-    const { client, approvalResponses } = createFakeClient({
-      approvalRequestMethod: "item/permissions/requestApproval",
-    });
+  it("starts the media deadline before client acquisition", async () => {
+    vi.useFakeTimers();
     const provider = buildCodexMediaUnderstandingProvider({
-      clientFactory: async () => client,
+      clientLeaseFactory: adaptCodexTestClientFactory(
+        async () => await new Promise<CodexAppServerClient>(() => {}),
+      ),
     });
-
-    await provider.describeImage?.({
+    const description = provider.describeImage?.({
       buffer: Buffer.from("image-bytes"),
       fileName: "image.png",
       mime: "image/png",
       provider: "codex",
       model: "gpt-5.4",
-      prompt: "Describe briefly.",
-      timeoutMs: 30_000,
+      timeoutMs: 100,
+      cfg: {},
+      agentDir: "/tmp/openclaw-agent",
+    });
+    const rejected = expect(description).rejects.toThrow(
+      "Codex app-server image understanding timed out",
+    );
+
+    await vi.advanceTimersByTimeAsync(100);
+
+    await rejected;
+  });
+
+  it("retires a media client lease that resolves after its deadline", async () => {
+    let resolveLease!: (lease: {
+      client: CodexAppServerClient;
+      release: () => void;
+      abandon: () => Promise<void>;
+    }) => void;
+    const pendingLease = new Promise<{
+      client: CodexAppServerClient;
+      release: () => void;
+      abandon: () => Promise<void>;
+    }>((resolve) => {
+      resolveLease = resolve;
+    });
+    const clientLeaseFactory = vi.fn(async () => await pendingLease);
+    const provider = buildCodexMediaUnderstandingProvider({ clientLeaseFactory });
+    const description = provider.describeImage?.({
+      buffer: Buffer.from("image-bytes"),
+      fileName: "image.png",
+      mime: "image/png",
+      provider: "codex",
+      model: "gpt-5.4",
+      timeoutMs: 5,
       cfg: {},
       agentDir: "/tmp/openclaw-agent",
     });
 
-    expect(approvalResponses).toEqual([{ permissions: {}, scope: "turn" }]);
+    await expect(description).rejects.toThrow("Codex app-server image understanding timed out");
+    const { client } = createFakeClient();
+    const release = vi.fn();
+    const abandon = vi.fn(async () => undefined);
+    resolveLease({ client, release, abandon });
+    await vi.waitFor(() => expect(abandon).toHaveBeenCalledOnce());
+
+    expect(release).not.toHaveBeenCalled();
+  });
+
+  it("releases the bounded route between isolated media calls", async () => {
+    const { client, requests } = createFakeClient();
+    const provider = buildCodexMediaUnderstandingProvider({
+      clientLeaseFactory: adaptCodexTestClientFactory(async () => client),
+    });
+    const request = {
+      buffer: Buffer.from("image-bytes"),
+      fileName: "image.png",
+      mime: "image/png",
+      provider: "codex",
+      model: "gpt-5.4",
+      timeoutMs: 30_000,
+      cfg: {},
+      agentDir: "/tmp/openclaw-agent",
+    };
+
+    const first = await provider.describeImage?.(request);
+    const second = await provider.describeImage?.(request);
+
+    expect(first?.text).toBe("A red square.");
+    expect(second?.text).toBe("A red square.");
+    expect(requests.filter((entry) => entry.method === "model/list")).toHaveLength(2);
+    expect(requests.filter((entry) => entry.method === "thread/start")).toHaveLength(2);
   });
 
   it("extracts text from terminal turn items", async () => {
     const { client } = createFakeClient({ completeWithItems: true });
     const provider = buildCodexMediaUnderstandingProvider({
-      clientFactory: async () => client,
+      clientLeaseFactory: adaptCodexTestClientFactory(async () => client),
     });
 
     const result = await provider.describeImages?.({
@@ -309,7 +496,7 @@ describe("codex media understanding provider", () => {
   it("rejects text-only Codex app-server models before starting a turn", async () => {
     const { client, requests } = createFakeClient({ inputModalities: ["text"] });
     const provider = buildCodexMediaUnderstandingProvider({
-      clientFactory: async () => client,
+      clientLeaseFactory: adaptCodexTestClientFactory(async () => client),
     });
 
     await expect(
@@ -330,7 +517,7 @@ describe("codex media understanding provider", () => {
   it("surfaces Codex app-server turn errors", async () => {
     const { client } = createFakeClient({ notifyError: "vision unavailable" });
     const provider = buildCodexMediaUnderstandingProvider({
-      clientFactory: async () => client,
+      clientLeaseFactory: adaptCodexTestClientFactory(async () => client),
     });
 
     await expect(
@@ -347,12 +534,107 @@ describe("codex media understanding provider", () => {
     ).rejects.toThrow("vision unavailable");
   });
 
+  it.each([
+    {
+      name: "structured rejection",
+      error: new CodexAppServerRpcError({ message: "turn rejected" }, "turn/start"),
+      abandonCount: 0,
+    },
+    {
+      name: "ambiguous timeout",
+      error: new Error("turn/start timed out"),
+      abandonCount: 1,
+    },
+  ])("handles $name with exact media lease ownership", async ({ error, abandonCount }) => {
+    const { client } = createFakeClient({ turnStartError: error });
+    const release = vi.fn();
+    const abandon = vi.fn(async () => undefined);
+    const provider = buildCodexMediaUnderstandingProvider({
+      clientLeaseFactory: async () => ({ client, release, abandon }),
+    });
+
+    await expect(
+      provider.describeImage?.({
+        buffer: Buffer.from("image-bytes"),
+        fileName: "image.png",
+        mime: "image/png",
+        provider: "codex",
+        model: "gpt-5.4",
+        timeoutMs: 30_000,
+        cfg: {},
+        agentDir: "/tmp/openclaw-agent",
+      }),
+    ).rejects.toBe(error);
+
+    expect(abandon).toHaveBeenCalledTimes(abandonCount);
+    expect(release).toHaveBeenCalledTimes(1);
+  });
+
+  it("retires the media client when thread cleanup is unconfirmed", async () => {
+    const { client } = createFakeClient({ unsubscribeError: new Error("unsubscribe failed") });
+    const release = vi.fn();
+    const abandon = vi.fn(async () => undefined);
+    const provider = buildCodexMediaUnderstandingProvider({
+      clientLeaseFactory: async () => ({ client, release, abandon }),
+    });
+
+    await expect(
+      provider.describeImage?.({
+        buffer: Buffer.from("image-bytes"),
+        fileName: "image.png",
+        mime: "image/png",
+        provider: "codex",
+        model: "gpt-5.4",
+        timeoutMs: 30_000,
+        cfg: {},
+        agentDir: "/tmp/openclaw-agent",
+      }),
+    ).resolves.toEqual({ text: "A red square.", model: "gpt-5.4" });
+
+    expect(abandon).toHaveBeenCalledOnce();
+    expect(release).not.toHaveBeenCalled();
+  });
+
+  it("retires the media client when an accepted turn cannot be interrupted", async () => {
+    const { client, requests } = createFakeClient({
+      preBindNotificationCount: 257,
+      interruptError: new Error("interrupt timeout"),
+    });
+    const release = vi.fn();
+    const abandon = vi.fn(async () => undefined);
+    const provider = buildCodexMediaUnderstandingProvider({
+      clientLeaseFactory: async () => ({ client, release, abandon }),
+    });
+
+    await expect(
+      provider.describeImage?.({
+        buffer: Buffer.from("image-bytes"),
+        fileName: "image.png",
+        mime: "image/png",
+        provider: "codex",
+        model: "gpt-5.4",
+        timeoutMs: 30_000,
+        cfg: {},
+        agentDir: "/tmp/openclaw-agent",
+      }),
+    ).rejects.toThrow("pre-bind notification buffer exceeded 256 entries");
+
+    expect(requests.map((entry) => entry.method)).toEqual([
+      "model/list",
+      "thread/start",
+      "turn/start",
+      "turn/interrupt",
+    ]);
+    expect(abandon).toHaveBeenCalledOnce();
+    expect(release).not.toHaveBeenCalled();
+  });
+
   it("runs structured extraction through the same bounded Codex app-server path", async () => {
     const { client, requests } = createFakeClient({
       responseText: '{"summary":"red square","tags":["shape"]}',
     });
     const provider = buildCodexMediaUnderstandingProvider({
-      clientFactory: async () => client,
+      clientLeaseFactory: adaptCodexTestClientFactory(async () => client),
     });
 
     const result = await provider.extractStructured?.({
@@ -393,25 +675,21 @@ describe("codex media understanding provider", () => {
       "model/list",
       "thread/start",
       "turn/start",
+      "thread/unsubscribe",
     ]);
     expect(requests[1]?.params).toEqual({
       model: "gpt-5.4",
       modelProvider: "openai",
-      cwd: "/tmp/openclaw-agent",
-      approvalPolicy: "on-request",
+      cwd: "/tmp/openclaw-agent/codex-media-home",
+      approvalPolicy: "never",
       sandbox: "read-only",
       serviceName: "OpenClaw",
+      personality: "none",
       developerInstructions:
         "You are OpenClaw's bounded structured-extraction worker. Return only the requested extraction. Do not call tools, edit files, ask follow-up questions, or include secrets.",
-      config: {
-        "features.code_mode": false,
-        "features.code_mode_only": false,
-      },
+      config: EXPECTED_MEDIA_THREAD_CONFIG,
       environments: [],
-      dynamicTools: [],
-      experimentalRawEvents: true,
       ephemeral: true,
-      persistExtendedHistory: false,
     });
     const turnParams = requests[2]?.params as
       | {
@@ -424,9 +702,9 @@ describe("codex media understanding provider", () => {
         }
       | undefined;
     expect(turnParams?.threadId).toBe("thread-1");
-    expect(turnParams?.approvalPolicy).toBe("on-request");
-    expect(turnParams?.model).toBe("gpt-5.4");
-    expect(turnParams?.cwd).toBe("/tmp/openclaw-agent");
+    expect(turnParams?.approvalPolicy).toBeUndefined();
+    expect(turnParams?.model).toBeUndefined();
+    expect(turnParams?.cwd).toBeUndefined();
     expect(turnParams?.effort).toBe("low");
     expect(turnParams?.input).toHaveLength(3);
     expect(turnParams?.input?.[0]?.type).toBe("text");
@@ -449,7 +727,7 @@ describe("codex media understanding provider", () => {
       responseText: '{"summary":"only text"}',
     });
     const provider = buildCodexMediaUnderstandingProvider({
-      clientFactory: async () => client,
+      clientLeaseFactory: adaptCodexTestClientFactory(async () => client),
     });
 
     await expect(
@@ -469,7 +747,7 @@ describe("codex media understanding provider", () => {
   it("returns a controlled error when structured JSON parsing fails", async () => {
     const { client } = createFakeClient({ responseText: "not json" });
     const provider = buildCodexMediaUnderstandingProvider({
-      clientFactory: async () => client,
+      clientLeaseFactory: adaptCodexTestClientFactory(async () => client),
     });
 
     await expect(
@@ -498,7 +776,7 @@ describe("codex media understanding provider", () => {
       responseText: '{"summary":123,"tags":["shape"]}',
     });
     const provider = buildCodexMediaUnderstandingProvider({
-      clientFactory: async () => client,
+      clientLeaseFactory: adaptCodexTestClientFactory(async () => client),
     });
 
     await expect(

extensions/codex/media-understanding-provider.ts

@@ -1,538 +1,35 @@
-/**
- * Codex-backed media understanding provider for bounded image description and
- * structured extraction turns.
- */
-import {
-  type JsonSchemaObject,
-  validateJsonSchemaValue,
-} from "openclaw/plugin-sdk/json-schema-runtime";
-import type {
-  ImagesDescriptionRequest,
-  ImagesDescriptionResult,
-  MediaUnderstandingProvider,
-  StructuredExtractionRequest,
-  StructuredExtractionResult,
-} from "openclaw/plugin-sdk/media-understanding";
-import { resolveTimerTimeoutMs } from "openclaw/plugin-sdk/number-runtime";
+/** Lazy registration facade for Codex-backed media understanding. */
+import type { MediaUnderstandingProvider } from "openclaw/plugin-sdk/media-understanding";
 import { CODEX_PROVIDER_ID, FALLBACK_CODEX_MODELS } from "./provider-catalog.js";
-import type { CodexAppServerClientFactory } from "./src/app-server/client-factory.js";
-import type { CodexAppServerClient } from "./src/app-server/client.js";
-import { resolveCodexAppServerRuntimeOptions } from "./src/app-server/config.js";
-import { readModelListResult } from "./src/app-server/models.js";
-import {
-  assertCodexThreadStartResponse,
-  assertCodexTurnStartResponse,
-  readCodexErrorNotification,
-  readCodexTurnCompletedNotification,
-} from "./src/app-server/protocol-validators.js";
-import {
-  isJsonObject,
-  type CodexServerNotification,
-  type CodexThreadItem,
-  type CodexThreadStartParams,
-  type CodexTurn,
-  type CodexTurnStartParams,
-  type CodexUserInput,
-  type JsonObject,
-  type JsonValue,
-} from "./src/app-server/protocol.js";
-import { buildCodexRuntimeThreadConfig } from "./src/app-server/thread-lifecycle.js";
+import type { CodexAppServerClientLeaseFactory } from "./src/app-server/shared-client.js";
 
 const DEFAULT_CODEX_IMAGE_MODEL =
   FALLBACK_CODEX_MODELS.find((model) => model.inputModalities.includes("image"))?.id ??
   FALLBACK_CODEX_MODELS[0]?.id;
-const DEFAULT_CODEX_IMAGE_PROMPT = "Describe the image.";
 
 /** Dependencies and plugin config for Codex media-understanding calls. */
 export type CodexMediaUnderstandingProviderOptions = {
   pluginConfig?: unknown;
-  clientFactory?: CodexAppServerClientFactory;
+  resolvePluginConfig?: () => unknown;
+  clientLeaseFactory?: CodexAppServerClientLeaseFactory;
 };
 
-/**
- * Builds the media-understanding provider that delegates image tasks to an
- * isolated Codex app-server session.
- */
+/** Builds a provider whose app-server implementation loads on first use. */
 export function buildCodexMediaUnderstandingProvider(
   options: CodexMediaUnderstandingProviderOptions = {},
 ): MediaUnderstandingProvider {
+  let runtime: Promise<typeof import("./src/media-understanding-provider.runtime.js")> | undefined;
+  const load = () => (runtime ??= import("./src/media-understanding-provider.runtime.js"));
   return {
     id: CODEX_PROVIDER_ID,
     capabilities: ["image"],
     ...(DEFAULT_CODEX_IMAGE_MODEL ? { defaultModels: { image: DEFAULT_CODEX_IMAGE_MODEL } } : {}),
-    describeImage: async (req) =>
-      describeCodexImages(
-        {
-          images: [
-            {
-              buffer: req.buffer,
-              fileName: req.fileName,
-              mime: req.mime,
-            },
-          ],
-          provider: req.provider,
-          model: req.model,
-          prompt: req.prompt,
-          maxTokens: req.maxTokens,
-          timeoutMs: req.timeoutMs,
-          profile: req.profile,
-          preferredProfile: req.preferredProfile,
-          authStore: req.authStore,
-          agentDir: req.agentDir,
-          cfg: req.cfg,
-        },
-        options,
-      ),
-    describeImages: async (req) => describeCodexImages(req, options),
-    extractStructured: async (req) => extractCodexStructured(req, options),
+    describeImage: async ({ buffer, fileName, mime, ...request }) =>
+      await (
+        await load()
+      ).describeCodexImages({ ...request, images: [{ buffer, fileName, mime }] }, options),
+    describeImages: async (request) => await (await load()).describeCodexImages(request, options),
+    extractStructured: async (request) =>
+      await (await load()).extractCodexStructured(request, options),
   };
 }
-
-async function describeCodexImages(
-  req: ImagesDescriptionRequest,
-  options: CodexMediaUnderstandingProviderOptions,
-): Promise<ImagesDescriptionResult> {
-  const model = req.model.trim();
-  if (!model) {
-    throw new Error("Codex image understanding requires model id.");
-  }
-
-  const text = await runBoundedCodexVisionTurn({
-    model,
-    profile: req.profile,
-    timeoutMs: req.timeoutMs,
-    agentDir: req.agentDir,
-    options,
-    taskLabel: "image understanding",
-    developerInstructions:
-      "You are OpenClaw's bounded image-understanding worker. Describe only the provided image content. Do not call tools, edit files, or ask follow-up questions.",
-    input: [
-      { type: "text", text: buildCodexImagePrompt(req), text_elements: [] },
-      ...req.images.map((image) => ({
-        type: "image" as const,
-        url: `data:${image.mime ?? "image/png"};base64,${image.buffer.toString("base64")}`,
-      })),
-    ],
-    requiredModalities: ["text", "image"],
-  });
-  return { text, model };
-}
-
-type BoundedCodexVisionTurnParams = {
-  model: string;
-  profile?: string;
-  timeoutMs: number;
-  agentDir?: string;
-  options: CodexMediaUnderstandingProviderOptions;
-  taskLabel: string;
-  developerInstructions: string;
-  input: CodexUserInput[];
-  requiredModalities: string[];
-};
-
-async function runBoundedCodexVisionTurn(params: BoundedCodexVisionTurnParams): Promise<string> {
-  const appServer = resolveCodexAppServerRuntimeOptions({
-    pluginConfig: params.options.pluginConfig,
-  });
-  const timeoutMs = resolveTimerTimeoutMs(params.timeoutMs, 100, 100);
-  const ownsClient = !params.options.clientFactory;
-  // Tests inject a client factory; production creates an isolated app-server
-  // client so media tasks cannot reuse the interactive attempt session.
-  const client = params.options.clientFactory
-    ? await params.options.clientFactory(appServer.start, params.profile)
-    : await import("./src/app-server/shared-client.js").then(
-        ({ createIsolatedCodexAppServerClient }) =>
-          createIsolatedCodexAppServerClient({
-            startOptions: appServer.start,
-            timeoutMs,
-            authProfileId: params.profile,
-          }),
-      );
-  const abortController = new AbortController();
-  const timeout = setTimeout(() => abortController.abort("timeout"), timeoutMs);
-  timeout.unref?.();
-
-  try {
-    await assertCodexModelSupportsInput({
-      client,
-      model: params.model,
-      requiredModalities: params.requiredModalities,
-      timeoutMs,
-      signal: abortController.signal,
-    });
-    const thread = assertCodexThreadStartResponse(
-      await client.request<unknown>(
-        "thread/start",
-        {
-          model: params.model,
-          modelProvider: "openai",
-          cwd: params.agentDir || process.cwd(),
-          approvalPolicy: "on-request",
-          sandbox: "read-only",
-          serviceName: "OpenClaw",
-          developerInstructions: params.developerInstructions,
-          // Media workers are bounded read-only turns; native code mode and
-          // dynamic tools stay disabled to avoid side effects while inspecting media.
-          config: buildCodexRuntimeThreadConfig(undefined, { nativeCodeModeEnabled: false }),
-          environments: [],
-          dynamicTools: [],
-          experimentalRawEvents: true,
-          persistExtendedHistory: false,
-          ephemeral: true,
-        } satisfies CodexThreadStartParams,
-        { timeoutMs, signal: abortController.signal },
-      ),
-    );
-    const collector = createCodexTurnCollector(thread.thread.id, params.taskLabel);
-    const cleanup = client.addNotificationHandler(collector.handleNotification);
-    const requestCleanup = client.addRequestHandler(denyCodexImageApprovalRequest);
-    try {
-      const turn = assertCodexTurnStartResponse(
-        await client.request<unknown>(
-          "turn/start",
-          {
-            threadId: thread.thread.id,
-            input: params.input,
-            cwd: params.agentDir || process.cwd(),
-            approvalPolicy: "on-request",
-            model: params.model,
-            effort: "low",
-          } satisfies CodexTurnStartParams,
-          { timeoutMs, signal: abortController.signal },
-        ),
-      );
-      const text = await collector.collect(turn.turn, {
-        timeoutMs,
-        signal: abortController.signal,
-      });
-      return text;
-    } finally {
-      requestCleanup();
-      cleanup();
-    }
-  } finally {
-    clearTimeout(timeout);
-    if (ownsClient) {
-      client.close();
-    }
-  }
-}
-
-async function extractCodexStructured(
-  req: StructuredExtractionRequest,
-  options: CodexMediaUnderstandingProviderOptions,
-): Promise<StructuredExtractionResult> {
-  const model = req.model.trim();
-  if (!model) {
-    throw new Error("Codex structured extraction requires model id.");
-  }
-  const instructions = req.instructions.trim();
-  if (!instructions) {
-    throw new Error("Codex structured extraction requires instructions.");
-  }
-  if (req.input.length === 0) {
-    throw new Error("Codex structured extraction requires at least one input.");
-  }
-  if (!req.input.some((entry) => entry.type === "image")) {
-    throw new Error("Codex structured extraction requires at least one image input.");
-  }
-
-  const text = await runBoundedCodexVisionTurn({
-    model,
-    profile: req.profile,
-    timeoutMs: req.timeoutMs,
-    agentDir: req.agentDir,
-    options,
-    taskLabel: "structured extraction",
-    developerInstructions:
-      "You are OpenClaw's bounded structured-extraction worker. Return only the requested extraction. Do not call tools, edit files, ask follow-up questions, or include secrets.",
-    input: buildCodexStructuredInput(req),
-    requiredModalities: requiredStructuredModalities(),
-  });
-  return normalizeStructuredExtractionResult({ text, model, provider: req.provider, req });
-}
-
-function denyCodexImageApprovalRequest(request: { method: string }): JsonValue | undefined {
-  if (
-    request.method === "item/commandExecution/requestApproval" ||
-    request.method === "item/fileChange/requestApproval"
-  ) {
-    return {
-      decision: "decline",
-      reason: "OpenClaw Codex image understanding does not grant tool or file approvals.",
-    };
-  }
-  if (request.method === "item/permissions/requestApproval") {
-    return { permissions: {}, scope: "turn" };
-  }
-  if (request.method.includes("requestApproval")) {
-    return {
-      decision: "decline",
-      reason: "OpenClaw Codex image understanding does not grant native approvals.",
-    };
-  }
-  if (request.method === "mcpServer/elicitation/request") {
-    return { action: "decline" };
-  }
-  return undefined;
-}
-
-async function assertCodexModelSupportsInput(params: {
-  client: CodexAppServerClient;
-  model: string;
-  requiredModalities: string[];
-  timeoutMs: number;
-  signal: AbortSignal;
-}): Promise<void> {
-  const result = await params.client.request<unknown>(
-    "model/list",
-    { limit: 100, cursor: null, includeHidden: false },
-    { timeoutMs: Math.min(params.timeoutMs, 5_000), signal: params.signal },
-  );
-  const listed = readModelListResult(result).models;
-  const match = listed.find((entry) => entry.model === params.model || entry.id === params.model);
-  if (!match) {
-    throw new Error(`Codex app-server model not found: ${params.model}`);
-  }
-  if (params.requiredModalities.includes("image") && !match.inputModalities.includes("image")) {
-    throw new Error(`Codex app-server model does not support images: ${params.model}`);
-  }
-  if (params.requiredModalities.includes("text") && !match.inputModalities.includes("text")) {
-    throw new Error(`Codex app-server model does not support text: ${params.model}`);
-  }
-}
-
-function buildCodexImagePrompt(req: ImagesDescriptionRequest): string {
-  const prompt = req.prompt?.trim() || DEFAULT_CODEX_IMAGE_PROMPT;
-  if (req.images.length <= 1) {
-    return prompt;
-  }
-  return `${prompt}\n\nAnalyze all ${req.images.length} images together.`;
-}
-
-function requiredStructuredModalities(): string[] {
-  return ["text", "image"];
-}
-
-function buildCodexStructuredInput(req: StructuredExtractionRequest): CodexUserInput[] {
-  return [
-    { type: "text", text: buildStructuredExtractionPrompt(req), text_elements: [] },
-    ...req.input.map((entry) => {
-      if (entry.type === "text") {
-        return { type: "text" as const, text: entry.text, text_elements: [] };
-      }
-      return {
-        type: "image" as const,
-        url: `data:${entry.mime ?? "image/png"};base64,${entry.buffer.toString("base64")}`,
-      };
-    }),
-  ];
-}
-
-function buildStructuredExtractionPrompt(req: StructuredExtractionRequest): string {
-  return [
-    req.instructions.trim(),
-    req.schemaName ? `Schema name: ${req.schemaName}` : undefined,
-    req.jsonSchema ? `JSON schema:\n${JSON.stringify(req.jsonSchema)}` : undefined,
-    req.jsonMode === false
-      ? "Return the extraction as concise text."
-      : "Return valid JSON only. Do not wrap the JSON in Markdown fences.",
-  ]
-    .filter((part): part is string => Boolean(part))
-    .join("\n\n");
-}
-
-function isJsonSchemaObject(value: unknown): value is JsonSchemaObject {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function normalizeStructuredExtractionResult(params: {
-  text: string;
-  model: string;
-  provider: string;
-  req: StructuredExtractionRequest;
-}): StructuredExtractionResult {
-  const result: StructuredExtractionResult = {
-    text: params.text,
-    model: params.model,
-    provider: params.provider,
-    contentType: params.req.jsonMode === false ? "text" : "json",
-  };
-  if (params.req.jsonMode !== false) {
-    try {
-      result.parsed = JSON.parse(params.text);
-    } catch {
-      throw new Error("Codex structured extraction returned invalid JSON.");
-    }
-    if (isJsonSchemaObject(params.req.jsonSchema)) {
-      const validation = validateJsonSchemaValue({
-        schema: params.req.jsonSchema,
-        cacheKey: "codex.media-understanding.extractStructured",
-        value: result.parsed,
-        cache: false,
-      });
-      if (!validation.ok) {
-        const message = validation.errors.map((error) => error.text).join("; ") || "invalid";
-        throw new Error(`Codex structured extraction JSON did not match schema: ${message}`);
-      }
-      result.parsed = validation.value;
-    }
-  }
-  return result;
-}
-
-function createCodexTurnCollector(threadId: string, taskLabel: string) {
-  let turnId: string | undefined;
-  let completedTurn: CodexTurn | undefined;
-  let promptError: string | undefined;
-  const pending: CodexServerNotification[] = [];
-  const assistantTextByItem = new Map<string, string>();
-  const assistantItemOrder: string[] = [];
-  let resolveCompletion: (() => void) | undefined;
-  const completion = new Promise<void>((resolve) => {
-    resolveCompletion = resolve;
-  });
-
-  const rememberAssistantText = (itemId: string, text: string) => {
-    if (!text) {
-      return;
-    }
-    if (!assistantTextByItem.has(itemId)) {
-      assistantItemOrder.push(itemId);
-    }
-    assistantTextByItem.set(itemId, text);
-  };
-
-  const handleNotification = (notification: CodexServerNotification): void => {
-    const params = isJsonObject(notification.params) ? notification.params : undefined;
-    if (!params || readString(params, "threadId") !== threadId) {
-      return;
-    }
-    if (!turnId) {
-      pending.push(notification);
-      return;
-    }
-    const notificationTurnId = readNotificationTurnId(params);
-    if (notificationTurnId !== turnId) {
-      return;
-    }
-    if (notification.method === "item/agentMessage/delta") {
-      const itemId = readString(params, "itemId") ?? readString(params, "id") ?? "assistant";
-      const delta = readString(params, "delta") ?? "";
-      rememberAssistantText(itemId, `${assistantTextByItem.get(itemId) ?? ""}${delta}`);
-      return;
-    }
-    if (notification.method === "turn/completed") {
-      completedTurn =
-        readCodexTurnCompletedNotification(notification.params)?.turn ?? completedTurn;
-      resolveCompletion?.();
-      return;
-    }
-    if (notification.method === "error") {
-      promptError =
-        readCodexErrorNotification(notification.params)?.error.message ??
-        `codex app-server ${taskLabel} turn failed`;
-      resolveCompletion?.();
-    }
-  };
-
-  return {
-    handleNotification,
-    async collect(
-      startedTurn: CodexTurn,
-      options: { timeoutMs: number; signal: AbortSignal },
-    ): Promise<string> {
-      turnId = startedTurn.id;
-      if (isTerminalTurn(startedTurn)) {
-        completedTurn = startedTurn;
-      }
-      for (const notification of pending.splice(0)) {
-        handleNotification(notification);
-      }
-      if (!completedTurn && !promptError) {
-        await waitForTurnCompletion({
-          completion,
-          timeoutMs: options.timeoutMs,
-          signal: options.signal,
-          taskLabel,
-        });
-      }
-      if (promptError) {
-        throw new Error(promptError);
-      }
-      if (completedTurn?.status === "failed") {
-        throw new Error(
-          completedTurn.error?.message ?? `codex app-server ${taskLabel} turn failed`,
-        );
-      }
-      const itemText = collectAssistantTextFromItems(completedTurn?.items);
-      const deltaText = assistantItemOrder
-        .map((itemId) => assistantTextByItem.get(itemId)?.trim())
-        .filter((text): text is string => Boolean(text))
-        .join("\n\n")
-        .trim();
-      const text = (itemText || deltaText).trim();
-      if (!text) {
-        throw new Error(`Codex app-server ${taskLabel} turn returned no text.`);
-      }
-      return text;
-    },
-  };
-}
-
-async function waitForTurnCompletion(params: {
-  completion: Promise<void>;
-  timeoutMs: number;
-  signal: AbortSignal;
-  taskLabel: string;
-}): Promise<void> {
-  let timeout: ReturnType<typeof setTimeout> | undefined;
-  let cleanupAbort: (() => void) | undefined;
-  try {
-    await Promise.race([
-      params.completion,
-      new Promise<never>((_, reject) => {
-        timeout = setTimeout(
-          () => reject(new Error(`codex app-server ${params.taskLabel} turn timed out`)),
-          params.timeoutMs,
-        );
-        timeout.unref?.();
-        const abortListener = () =>
-          reject(new Error(`codex app-server ${params.taskLabel} turn aborted`));
-        params.signal.addEventListener("abort", abortListener, { once: true });
-        cleanupAbort = () => params.signal.removeEventListener("abort", abortListener);
-      }),
-    ]);
-  } finally {
-    if (timeout) {
-      clearTimeout(timeout);
-    }
-    cleanupAbort?.();
-  }
-}
-
-function collectAssistantTextFromItems(items: CodexThreadItem[] | undefined): string {
-  return (items ?? [])
-    .filter((item) => item.type === "agentMessage")
-    .map((item) => item.text.trim())
-    .filter(Boolean)
-    .join("\n\n")
-    .trim();
-}
-
-function readNotificationTurnId(record: JsonObject): string | undefined {
-  const direct = readString(record, "turnId");
-  if (direct) {
-    return direct;
-  }
-  return isJsonObject(record.turn) ? readString(record.turn, "id") : undefined;
-}
-
-function readString(record: JsonObject, key: string): string | undefined {
-  const value = record[key];
-  return typeof value === "string" ? value : undefined;
-}
-
-function isTerminalTurn(turn: CodexTurn): boolean {
-  return turn.status === "completed" || turn.status === "interrupted" || turn.status === "failed";
-}

extensions/codex/provider.test.ts

@@ -4,10 +4,10 @@ import { CODEX_GPT5_BEHAVIOR_CONTRACT } from "./prompt-overlay.js";
 import { codexProviderDiscovery } from "./provider-discovery.js";
 import { buildCodexProvider, buildCodexProviderCatalog } from "./provider.js";
 import { CodexAppServerClient } from "./src/app-server/client.js";
-import type { listCodexAppServerModels } from "./src/app-server/models.js";
+import type { listAllCodexAppServerModels } from "./src/app-server/models.js";
 import {
   createIsolatedCodexAppServerClient,
-  getSharedCodexAppServerClient,
+  leaseSharedCodexAppServerClient,
   resetSharedCodexAppServerClientForTests,
 } from "./src/app-server/shared-client.js";
 
@@ -26,7 +26,8 @@ function createFakeCodexClient(): CodexAppServerClient {
   return {
     initialize: vi.fn(async () => undefined),
     request: vi.fn(async () => ({ data: [] })),
-    setActiveSharedLeaseCountProviderForUnscopedNotifications: vi.fn(),
+    addNotificationHandler: vi.fn(() => () => undefined),
+    addRequestHandler: vi.fn(() => () => undefined),
     addCloseHandler: vi.fn(() => () => undefined),
     close: vi.fn(),
   } as unknown as CodexAppServerClient;
@@ -39,7 +40,7 @@ const TEST_CODEX_APP_SERVER_CONFIG = {
 };
 
 async function listTestCodexAppServerModels(
-  options: Parameters<typeof listCodexAppServerModels>[0] = {},
+  options: Parameters<typeof listAllCodexAppServerModels>[0] = {},
 ) {
   expect(options.sharedClient).toBe(false);
   const client = await createIsolatedCodexAppServerClient({
@@ -183,45 +184,33 @@ describe("codex provider", () => {
     expect(resultProvider?.models.map((model) => model.id)).toEqual(["gpt-5.4"]);
   });
 
-  it("pages through live discovery before building the provider catalog", async () => {
-    const listModels = vi
-      .fn()
-      .mockResolvedValueOnce({
-        models: [
-          {
-            id: "gpt-5.4",
-            model: "gpt-5.4",
-            hidden: false,
-            inputModalities: ["text", "image"],
-            supportedReasoningEfforts: ["medium"],
-          },
-        ],
-        nextCursor: "page-2",
-      })
-      .mockResolvedValueOnce({
-        models: [
-          {
-            id: "gpt-5.5",
-            model: "gpt-5.5",
-            hidden: false,
-            inputModalities: ["text"],
-            supportedReasoningEfforts: [],
-          },
-        ],
-      });
+  it("delegates all-page discovery to one model lister call", async () => {
+    const listModels = vi.fn(async () => ({
+      models: [
+        {
+          id: "gpt-5.4",
+          model: "gpt-5.4",
+          hidden: false,
+          inputModalities: ["text", "image"],
+          supportedReasoningEfforts: ["medium"],
+        },
+        {
+          id: "gpt-5.5",
+          model: "gpt-5.5",
+          hidden: false,
+          inputModalities: ["text"],
+          supportedReasoningEfforts: [],
+        },
+      ],
+    }));
 
     const result = await buildCodexProviderCatalog({
       env: {},
       listModels,
     });
 
+    expect(listModels).toHaveBeenCalledTimes(1);
     expectRecordFields(mockCallArg(listModels, 0), {
-      cursor: undefined,
-      limit: 100,
-      sharedClient: false,
-    });
-    expectRecordFields(mockCallArg(listModels, 1), {
-      cursor: "page-2",
       limit: 100,
       sharedClient: false,
     });
@@ -277,7 +266,7 @@ describe("codex provider", () => {
       .mockReturnValueOnce(activeClient)
       .mockReturnValueOnce(discoveryClient);
 
-    await getSharedCodexAppServerClient({
+    await leaseSharedCodexAppServerClient({
       startOptions: {
         transport: "stdio",
         command: "/tmp/openclaw-test-codex",

extensions/codex/provider.ts

@@ -18,16 +18,11 @@ import {
   CODEX_PROVIDER_ID,
   FALLBACK_CODEX_MODELS,
 } from "./provider-catalog.js";
-import {
-  type CodexAppServerStartOptions,
-  readCodexPluginConfig,
-  resolveCodexAppServerRuntimeOptions,
-} from "./src/app-server/config.js";
+import type { CodexAppServerStartOptions } from "./src/app-server/config.js";
 import type {
   CodexAppServerModel,
   CodexAppServerModelListResult,
 } from "./src/app-server/models.js";
-import { buildCodexAppServerUsageSnapshot } from "./src/app-server/rate-limits.js";
 
 const DEFAULT_DISCOVERY_TIMEOUT_MS = 2500;
 const LIVE_DISCOVERY_ENV = "OPENCLAW_CODEX_DISCOVERY_LIVE";
@@ -39,7 +34,6 @@ const codexCatalogLog = createSubsystemLogger("codex/catalog");
 type CodexModelLister = (options: {
   timeoutMs: number;
   limit?: number;
-  cursor?: string;
   startOptions?: CodexAppServerStartOptions;
   sharedClient?: boolean;
 }) => Promise<CodexAppServerModelListResult>;
@@ -123,6 +117,11 @@ export function buildCodexProvider(options: BuildCodexProviderOptions = {}): Pro
       }
       const runtimePluginConfig = resolvePluginConfigObject(ctx.config, CODEX_PROVIDER_ID);
       const pluginConfig = runtimePluginConfig ?? (ctx.config ? undefined : options.pluginConfig);
+      const [{ resolveCodexAppServerRuntimeOptions }, { buildCodexAppServerUsageSnapshot }] =
+        await Promise.all([
+          import("./src/app-server/config.js"),
+          import("./src/app-server/rate-limits.js"),
+        ]);
       const appServer = resolveCodexAppServerRuntimeOptions({ pluginConfig });
       const rateLimits = await (options.readRateLimits ?? requestCodexAppServerRateLimitsLazy)({
         timeoutMs: ctx.timeoutMs,
@@ -156,13 +155,15 @@ export function buildCodexProvider(options: BuildCodexProviderOptions = {}): Pro
 export async function buildCodexProviderCatalog(
   options: BuildCatalogOptions = {},
 ): Promise<{ provider: ModelProviderConfig }> {
+  const { readCodexPluginConfig, resolveCodexAppServerRuntimeOptions } =
+    await import("./src/app-server/config.js");
   const config = readCodexPluginConfig(options.pluginConfig);
   const appServer = resolveCodexAppServerRuntimeOptions({ pluginConfig: options.pluginConfig });
   const timeoutMs = normalizeTimeoutMs(config.discovery?.timeoutMs);
   let discovered: CodexAppServerModel[] = [];
   if (config.discovery?.enabled !== false && !shouldSkipLiveDiscovery(options.env)) {
     discovered = await listModelsBestEffort({
-      listModels: options.listModels ?? listCodexAppServerModelsLazy,
+      listModels: options.listModels ?? listAllCodexAppServerModelsLazy,
       timeoutMs,
       startOptions: appServer.start,
       onDiscoveryFailure: options.onDiscoveryFailure,
@@ -200,22 +201,14 @@ async function listModelsBestEffort(params: {
   onDiscoveryFailure?: (error: unknown) => void;
 }): Promise<CodexAppServerModel[]> {
   try {
-    const models: CodexAppServerModel[] = [];
-    let cursor: string | undefined;
-    do {
-      // App-server model listing is paginated; collect every visible model so
-      // aliases and picker rows match the current Codex account.
-      const result = await params.listModels({
-        timeoutMs: params.timeoutMs,
-        limit: MODEL_DISCOVERY_PAGE_LIMIT,
-        cursor,
-        startOptions: params.startOptions,
-        sharedClient: false,
-      });
-      models.push(...result.models.filter((model) => !model.hidden));
-      cursor = result.nextCursor;
-    } while (cursor);
-    return models;
+    // The all-pages helper keeps one app-server client alive across pagination.
+    const result = await params.listModels({
+      timeoutMs: params.timeoutMs,
+      limit: MODEL_DISCOVERY_PAGE_LIMIT,
+      startOptions: params.startOptions,
+      sharedClient: false,
+    });
+    return result.models.filter((model) => !model.hidden);
   } catch (error) {
     params.onDiscoveryFailure?.(error);
     codexCatalogLog.debug("codex model discovery failed; using fallback catalog", {
@@ -225,15 +218,14 @@ async function listModelsBestEffort(params: {
   }
 }
 
-async function listCodexAppServerModelsLazy(options: {
+async function listAllCodexAppServerModelsLazy(options: {
   timeoutMs: number;
   limit?: number;
-  cursor?: string;
   startOptions?: CodexAppServerStartOptions;
   sharedClient?: boolean;
 }): Promise<CodexAppServerModelListResult> {
-  const { listCodexAppServerModels } = await import("./src/app-server/models.js");
-  return listCodexAppServerModels(options);
+  const { listAllCodexAppServerModels } = await import("./src/app-server/models.js");
+  return listAllCodexAppServerModels(options);
 }
 
 async function requestCodexAppServerRateLimitsLazy(options: {

extensions/codex/src/app-server/app-server-policy.test.ts

@@ -1,9 +1,6 @@
 // Codex tests cover app server policy plugin behavior.
 import { describe, expect, it } from "vitest";
-import {
-  resolveCodexAppServerForModelProvider,
-  resolveCodexAppServerForOpenClawToolPolicy,
-} from "./app-server-policy.js";
+import { resolveCodexAppServerForOpenClawToolPolicy } from "./app-server-policy.js";
 import { readCodexPluginConfig, resolveCodexAppServerRuntimeOptions } from "./config.js";
 
 describe("Codex app-server policy", () => {
@@ -69,143 +66,4 @@ describe("Codex app-server policy", () => {
     expect(explicitEnv.approvalPolicy).toBe("never");
     expect(explicitRequirements.approvalPolicy).toBe("never");
   });
-
-  it("keeps model-backed reviewers for explicit OpenAI model providers", () => {
-    const appServer = resolveCodexAppServerRuntimeOptions({
-      env: {},
-      requirementsToml: null,
-      execMode: "auto",
-      modelProvider: "openai",
-    });
-
-    expect(
-      resolveCodexAppServerForModelProvider({
-        appServer,
-        provider: "codex",
-        model: "openai/gpt-5.5",
-      }).approvalsReviewer,
-    ).toBe("auto_review");
-    expect(
-      resolveCodexAppServerForModelProvider({
-        appServer,
-        provider: "codex",
-        model: "gpt-5.5",
-      }).approvalsReviewer,
-    ).toBe("user");
-    expect(
-      resolveCodexAppServerForModelProvider({ appServer, provider: "openai" }).approvalsReviewer,
-    ).toBe("auto_review");
-  });
-
-  it("uses human approval for OpenAI-compatible custom endpoints", () => {
-    const appServer = resolveCodexAppServerRuntimeOptions({
-      env: {},
-      requirementsToml: null,
-      execMode: "auto",
-      modelProvider: "openai",
-      model: "gpt-5.5",
-      config: {
-        models: {
-          providers: {
-            openai: {
-              baseUrl: "http://localhost:8080/v1",
-              models: [],
-            },
-          },
-        },
-      },
-    });
-
-    expect(appServer.approvalsReviewer).toBe("user");
-    expect(
-      resolveCodexAppServerForModelProvider({
-        appServer,
-        provider: "openai",
-        model: "gpt-5.5",
-        config: {
-          models: {
-            providers: {
-              openai: {
-                baseUrl: "http://localhost:8080/v1",
-                models: [],
-              },
-            },
-          },
-        },
-      }).approvalsReviewer,
-    ).toBe("user");
-  });
-
-  it("uses human approval instead of Codex Guardian for custom model providers", () => {
-    const appServer = resolveCodexAppServerRuntimeOptions({
-      env: {},
-      requirementsToml: null,
-      execMode: "auto",
-      modelProvider: "openai",
-    });
-
-    const resolved = resolveCodexAppServerForModelProvider({
-      appServer,
-      provider: "lmstudio",
-    });
-    const vendorPrefixedModel = resolveCodexAppServerForModelProvider({
-      appServer,
-      provider: "openrouter",
-      model: "openai/gpt-5.5",
-    });
-
-    expect(appServer.approvalsReviewer).toBe("auto_review");
-    expect(resolved.approvalPolicy).toBe("on-request");
-    expect(resolved.sandbox).toBe("workspace-write");
-    expect(resolved.approvalsReviewer).toBe("user");
-    expect(vendorPrefixedModel.approvalsReviewer).toBe("user");
-  });
-
-  it("infers custom providers from provider-qualified model refs", () => {
-    const appServer = resolveCodexAppServerRuntimeOptions({
-      env: {},
-      requirementsToml: null,
-      execMode: "auto",
-    });
-
-    expect(
-      resolveCodexAppServerForModelProvider({
-        appServer,
-        model: "lmstudio/local-model",
-      }).approvalsReviewer,
-    ).toBe("user");
-  });
-
-  it("uses provider-qualified model refs to override broad native provider wrappers", () => {
-    const appServer = resolveCodexAppServerRuntimeOptions({
-      env: {},
-      requirementsToml: null,
-      execMode: "auto",
-    });
-
-    expect(
-      resolveCodexAppServerForModelProvider({
-        appServer,
-        provider: "codex",
-        model: "lmstudio/local-model",
-      }).approvalsReviewer,
-    ).toBe("user");
-  });
-
-  it("downgrades legacy guardian_subagent for custom model providers", () => {
-    const appServer = resolveCodexAppServerRuntimeOptions({
-      env: {},
-      requirementsToml: null,
-      pluginConfig: {
-        appServer: {
-          mode: "guardian",
-          approvalsReviewer: "guardian_subagent",
-        },
-      },
-    });
-
-    expect(
-      resolveCodexAppServerForModelProvider({ appServer, provider: "local" }).approvalsReviewer,
-    ).toBe("user");
-  });
 });

extensions/codex/src/app-server/app-server-policy.ts

@@ -2,11 +2,10 @@
  * Policy promotion for Codex app-server runs that can safely use OpenClaw tool
  * approvals.
  */
-import {
-  canUseCodexModelBackedApprovalsReviewerForModel,
-  type CodexAppServerRuntimeOptions,
-  type CodexPluginConfig,
-  type OpenClawExecPolicyForCodexAppServer,
+import type {
+  CodexAppServerRuntimeOptions,
+  CodexPluginConfig,
+  OpenClawExecPolicyForCodexAppServer,
 } from "./config.js";
 
 /**
@@ -45,35 +44,6 @@ export function resolveCodexAppServerForOpenClawToolPolicy(params: {
   };
 }
 
-export function resolveCodexAppServerForModelProvider(params: {
-  appServer: CodexAppServerRuntimeOptions;
-  provider?: string;
-  model?: string;
-  config?: Parameters<typeof canUseCodexModelBackedApprovalsReviewerForModel>[0]["config"];
-  env?: NodeJS.ProcessEnv;
-  agentDir?: string;
-  codexConfigToml?: string | null;
-}): CodexAppServerRuntimeOptions {
-  const explicitProvider = normalizeModelBackedReviewerProvider(params.provider);
-  if (
-    !isCodexModelBackedApprovalsReviewer(params.appServer.approvalsReviewer) ||
-    canUseCodexModelBackedApprovalsReviewerForModel({
-      modelProvider: explicitProvider,
-      model: params.model,
-      config: params.config,
-      env: params.env,
-      agentDir: params.agentDir,
-      codexConfigToml: params.codexConfigToml,
-    })
-  ) {
-    return params.appServer;
-  }
-  return {
-    ...params.appServer,
-    approvalsReviewer: "user",
-  };
-}
-
 function isCodexAppServerPolicyMode(value: unknown): boolean {
   return value === "guardian" || value === "yolo";
 }
@@ -83,12 +53,3 @@ function isCodexAppServerApprovalPolicy(value: unknown): boolean {
     value === "never" || value === "on-request" || value === "on-failure" || value === "untrusted"
   );
 }
-
-function isCodexModelBackedApprovalsReviewer(value: string): boolean {
-  return value === "auto_review" || value === "guardian_subagent";
-}
-
-function normalizeModelBackedReviewerProvider(provider: string | undefined): string | undefined {
-  const normalized = provider?.trim().toLowerCase();
-  return normalized || undefined;
-}

extensions/codex/src/app-server/approval-bridge.ts

@@ -285,8 +285,7 @@ function matchesCurrentTurn(
   if (!requestParams) {
     return false;
   }
-  const requestThreadId =
-    readString(requestParams, "threadId") ?? readString(requestParams, "conversationId");
+  const requestThreadId = readString(requestParams, "threadId");
   const requestTurnId = readString(requestParams, "turnId");
   return requestThreadId === threadId && requestTurnId === turnId;
 }

extensions/codex/src/app-server/attempt-client-cleanup.test.ts

@@ -2,10 +2,41 @@
 import { describe, expect, it, vi } from "vitest";
 import {
   interruptCodexTurnBestEffort,
+  runCodexTurnStartWithLease,
+  settleCodexAppServerClientLease,
   unsubscribeCodexThreadBestEffort,
+  validateCodexThreadCreationResponse,
 } from "./attempt-client-cleanup.js";
+import { CodexAppServerRpcError } from "./client.js";
 
 describe("Codex app-server attempt client cleanup", () => {
+  it("keeps the client lease after a structured turn-start rejection", async () => {
+    const abandon = vi.fn(async () => undefined);
+    const error = new CodexAppServerRpcError({ message: "turn rejected" }, "turn/start");
+
+    await expect(
+      runCodexTurnStartWithLease({ abandon } as never, async () => {
+        throw error;
+      }),
+    ).rejects.toBe(error);
+
+    expect(abandon).not.toHaveBeenCalled();
+  });
+
+  it("abandons only the exact client lease after an ambiguous turn-start timeout", async () => {
+    const abandon = vi.fn(async () => undefined);
+    const otherAbandon = vi.fn(async () => undefined);
+
+    await expect(
+      runCodexTurnStartWithLease({ abandon } as never, async () => {
+        throw new Error("turn/start timed out");
+      }),
+    ).rejects.toThrow("turn/start timed out");
+
+    expect(abandon).toHaveBeenCalledTimes(1);
+    expect(otherAbandon).not.toHaveBeenCalled();
+  });
+
   it("interrupts turns with optional request timeout", () => {
     const request = vi.fn(async () => ({}));
 
@@ -22,7 +53,58 @@ describe("Codex app-server attempt client cleanup", () => {
     );
   });
 
-  it("swallows unsubscribe cleanup failures", async () => {
+  it("unsubscribes a retained thread when its create response is malformed", async () => {
+    const request = vi.fn(async () => ({}));
+    const abandon = vi.fn(async () => undefined);
+    const invalidResponse = { thread: { id: "thread-1" } };
+
+    await expect(
+      validateCodexThreadCreationResponse(
+        { client: { request } as never, abandon },
+        invalidResponse,
+        () => {
+          throw new Error("invalid thread/start response");
+        },
+      ),
+    ).rejects.toThrow("invalid thread/start response");
+
+    expect(request).toHaveBeenCalledWith(
+      "thread/unsubscribe",
+      { threadId: "thread-1" },
+      { timeoutMs: 5_000 },
+    );
+    expect(abandon).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ["omits the retained thread id", {}, vi.fn(async () => ({}))],
+    [
+      "cannot confirm unsubscribe",
+      { thread: { id: "thread-1" } },
+      vi.fn(async () => {
+        throw new Error("connection lost");
+      }),
+    ],
+  ])(
+    "retires the client when a malformed create response %s",
+    async (_label, response, request) => {
+      const abandon = vi.fn(async () => undefined);
+
+      await expect(
+        validateCodexThreadCreationResponse(
+          { client: { request } as never, abandon },
+          response,
+          () => {
+            throw new Error("invalid thread/start response");
+          },
+        ),
+      ).rejects.toThrow("subscription could not be released");
+
+      expect(abandon).toHaveBeenCalledOnce();
+    },
+  );
+
+  it("reports unsubscribe cleanup failures", async () => {
     const request = vi.fn(async () => {
       throw new Error("already gone");
     });
@@ -32,7 +114,7 @@ describe("Codex app-server attempt client cleanup", () => {
         threadId: "thread-1",
         timeoutMs: 123,
       }),
-    ).resolves.toBeUndefined();
+    ).resolves.toBe(false);
 
     expect(request).toHaveBeenCalledWith(
       "thread/unsubscribe",
@@ -40,4 +122,31 @@ describe("Codex app-server attempt client cleanup", () => {
       { timeoutMs: 123 },
     );
   });
+
+  it("returns leases only after thread cleanup is confirmed", async () => {
+    const release = vi.fn();
+    const abandon = vi.fn(async () => undefined);
+    await settleCodexAppServerClientLease(
+      { client: { request: vi.fn(async () => ({})) }, release, abandon } as never,
+      { threadId: "thread-ok", timeoutMs: 123 },
+    );
+    expect(release).toHaveBeenCalledOnce();
+    expect(abandon).not.toHaveBeenCalled();
+
+    release.mockClear();
+    await settleCodexAppServerClientLease(
+      {
+        client: {
+          request: vi.fn(async () => {
+            throw new Error("unsubscribe failed");
+          }),
+        },
+        release,
+        abandon,
+      } as never,
+      { threadId: "thread-stale", timeoutMs: 123 },
+    );
+    expect(release).not.toHaveBeenCalled();
+    expect(abandon).toHaveBeenCalledOnce();
+  });
 });

extensions/codex/src/app-server/attempt-client-cleanup.ts

@@ -2,14 +2,126 @@
  * Best-effort cleanup helpers for timed-out or aborted Codex app-server turns.
  */
 import { embeddedAgentLog } from "openclaw/plugin-sdk/agent-harness-runtime";
-import type { CodexAppServerClient } from "./client.js";
-import { retireSharedCodexAppServerClientIfCurrent } from "./shared-client.js";
+import { CodexAppServerRpcError, type CodexAppServerClient } from "./client.js";
+import { isJsonObject, readCodexThreadCreationResponseId } from "./protocol.js";
+import type { CodexAppServerClientLease } from "./shared-client.js";
 
 /** Timeout for best-effort app-server turn interruption during cleanup. */
 export const CODEX_APP_SERVER_INTERRUPT_TIMEOUT_MS = 5_000;
 /** Timeout for best-effort thread unsubscribe during cleanup. */
 export const CODEX_APP_SERVER_UNSUBSCRIBE_TIMEOUT_MS = 5_000;
 
+/** The connection's thread-subscription ownership can no longer be proven. */
+export class CodexAppServerUnsafeSubscriptionError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "CodexAppServerUnsafeSubscriptionError";
+  }
+}
+
+export function isCodexAppServerUnsafeSubscriptionError(
+  error: unknown,
+): error is CodexAppServerUnsafeSubscriptionError {
+  return error instanceof CodexAppServerUnsafeSubscriptionError;
+}
+
+/** A resume response may only describe the thread this connection retained. */
+export function assertCodexThreadResumeSubscription(
+  requestedThreadId: string,
+  returnedThreadId: string,
+): void {
+  if (returnedThreadId !== requestedThreadId) {
+    throw new CodexAppServerUnsafeSubscriptionError(
+      `Codex thread/resume returned ${returnedThreadId} for ${requestedThreadId}`,
+    );
+  }
+}
+
+/** Retires the exact client lease when turn acceptance is ambiguous. */
+export async function runCodexTurnStartWithLease<T>(
+  lease: CodexAppServerClientLease,
+  startTurn: () => Promise<T>,
+): Promise<T> {
+  try {
+    return await startTurn();
+  } catch (error) {
+    // Structured RPC rejection happens before Codex accepts the turn. Transport,
+    // timeout, and abort failures may hide an accepted turn with an unknown id.
+    if (!(error instanceof CodexAppServerRpcError)) {
+      await lease.abandon();
+    }
+    throw error;
+  }
+}
+
+/** Retries once when native work wins the race immediately before turn/start. */
+export async function runCodexTurnStartWithNativeTurnRetry<T>(params: {
+  startTurn: () => Promise<T>;
+  waitForActiveTurnCompletion: () => Promise<boolean>;
+  afterActiveTurnCompletion?: () => Promise<void>;
+  onRetry?: () => void;
+}): Promise<T> {
+  try {
+    return await params.startTurn();
+  } catch (error) {
+    if (!isCodexActiveTurnNotSteerableError(error)) {
+      throw error;
+    }
+    params.onRetry?.();
+    if (!(await params.waitForActiveTurnCompletion())) {
+      throw error;
+    }
+    await params.afterActiveTurnCompletion?.();
+    return await params.startTurn();
+  }
+}
+
+/** True for Codex's structured rejection when native work already owns the thread. */
+export function isCodexActiveTurnNotSteerableError(error: unknown): boolean {
+  if (!(error instanceof CodexAppServerRpcError) || !isJsonObject(error.data)) {
+    return false;
+  }
+  const info = error.data.codexErrorInfo;
+  return isJsonObject(info) && isJsonObject(info.activeTurnNotSteerable);
+}
+
+/** Validates a create response and retires the client unless cleanup is confirmed. */
+export async function validateCodexThreadCreationResponse<T>(
+  owner: {
+    client: CodexAppServerClient;
+    abandon: () => Promise<void>;
+  },
+  response: unknown,
+  validate: (value: unknown) => T,
+): Promise<T> {
+  try {
+    return validate(response);
+  } catch (error) {
+    const threadId = readCodexThreadCreationResponseId(response);
+    const released = threadId
+      ? await unsubscribeCodexThreadBestEffort(owner.client, {
+          threadId,
+          timeoutMs: CODEX_APP_SERVER_UNSUBSCRIBE_TIMEOUT_MS,
+        })
+      : false;
+    if (released) {
+      throw error;
+    }
+    try {
+      await owner.abandon();
+    } catch (abandonError) {
+      throw new CodexAppServerUnsafeSubscriptionError(
+        "Codex thread creation response was invalid and its client could not be retired",
+        { cause: abandonError },
+      );
+    }
+    throw new CodexAppServerUnsafeSubscriptionError(
+      "Codex thread creation response was invalid and its subscription could not be released",
+      { cause: error },
+    );
+  }
+}
+
 /** Sends a turn interrupt without blocking abort cleanup on app-server errors. */
 export function interruptCodexTurnBestEffort(
   client: CodexAppServerClient,
@@ -36,28 +148,56 @@ export function interruptCodexTurnBestEffort(
   }
 }
 
-/** Unsubscribes from a thread while swallowing cleanup-only failures. */
+/** Unsubscribes from a thread and reports whether wire cleanup was confirmed. */
 export async function unsubscribeCodexThreadBestEffort(
   client: CodexAppServerClient,
   params: {
     threadId: string;
     timeoutMs: number;
   },
-): Promise<void> {
+): Promise<boolean> {
   try {
     await client.request(
       "thread/unsubscribe",
       { threadId: params.threadId },
       { timeoutMs: params.timeoutMs },
     );
+    return true;
   } catch (error) {
     embeddedAgentLog.debug("codex app-server thread unsubscribe cleanup failed", {
       threadId: params.threadId,
       error,
     });
+    return false;
   }
 }
 
+/** Returns one exact client lease to the pool only after subscription cleanup succeeds. */
+export async function settleCodexAppServerClientLease(
+  lease: CodexAppServerClientLease,
+  params: {
+    threadId?: string;
+    timeoutMs: number;
+    abandon?: boolean;
+  },
+): Promise<void> {
+  if (params.abandon) {
+    await lease.abandon();
+    return;
+  }
+  if (
+    params.threadId &&
+    !(await unsubscribeCodexThreadBestEffort(lease.client, {
+      threadId: params.threadId,
+      timeoutMs: params.timeoutMs,
+    }))
+  ) {
+    await lease.abandon();
+    return;
+  }
+  lease.release();
+}
+
 /**
  * Retires the shared client after a timed-out turn so later runs do not reuse a
  * potentially wedged app-server connection.
@@ -68,10 +208,9 @@ export async function retireCodexAppServerClientAfterTimedOutTurn(
     threadId: string;
     turnId: string;
     reason: string;
+    abandonClientLease: () => Promise<void>;
   },
 ): Promise<void> {
-  const retiredSharedClient = retireSharedCodexAppServerClientIfCurrent(client);
-  const detachedSharedClient = Boolean(retiredSharedClient);
   interruptCodexTurnBestEffort(client, {
     threadId: params.threadId,
     turnId: params.turnId,
@@ -81,28 +220,10 @@ export async function retireCodexAppServerClientAfterTimedOutTurn(
     threadId: params.threadId,
     timeoutMs: CODEX_APP_SERVER_UNSUBSCRIBE_TIMEOUT_MS,
   });
-  let closedClient = retiredSharedClient?.closed ?? false;
-  if (!detachedSharedClient) {
-    const close = (client as { close?: () => void }).close;
-    if (typeof close === "function") {
-      try {
-        close.call(client);
-        closedClient = true;
-      } catch (error) {
-        embeddedAgentLog.debug("codex app-server client close failed during timeout cleanup", {
-          threadId: params.threadId,
-          turnId: params.turnId,
-          error,
-        });
-      }
-    }
-  }
+  await params.abandonClientLease();
   embeddedAgentLog.warn("codex app-server client retired after timed-out turn", {
     threadId: params.threadId,
     turnId: params.turnId,
     reason: params.reason,
-    detachedSharedClient,
-    closedClient,
-    activeSharedClientLeases: retiredSharedClient?.activeLeases ?? 0,
   });
 }

extensions/codex/src/app-server/attempt-context.ts

@@ -16,6 +16,7 @@ import {
 } from "openclaw/plugin-sdk/agent-harness-runtime";
 import { resolveAgentWorkspaceDir } from "openclaw/plugin-sdk/agent-runtime";
 import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core";
+import { MESSAGE_TOOL_DELIVERY_HINTS } from "openclaw/plugin-sdk/message-tool-delivery-hints";
 import type { CodexDynamicToolSpec, JsonValue } from "./protocol.js";
 import { isJsonObject } from "./protocol.js";
 import type { CodexAppServerThreadBinding } from "./session-binding.js";
@@ -584,17 +585,12 @@ export function prependCodexOpenClawPromptContext(
   return [context?.trim(), deliverySection, promptSection].filter(Boolean).join("\n\n");
 }
 
-const CODEX_DELIVERY_HINT_LINES = [
-  "Delivery: to send a message, use the `message` tool.",
-  "Delivery: Final assistant text is not automatically delivered in this run. Use the `message` tool to send user-visible output.",
-] as const;
-
 function splitLeadingCodexDeliveryHint(prompt: string): {
   deliveryHint?: string;
   prompt: string;
 } {
   const trimmedStart = prompt.trimStart();
-  const matchedHint = CODEX_DELIVERY_HINT_LINES.find((hint) => trimmedStart.startsWith(hint));
+  const matchedHint = MESSAGE_TOOL_DELIVERY_HINTS.find((hint) => trimmedStart.startsWith(hint));
   if (!matchedHint) {
     return { prompt };
   }

extensions/codex/src/app-server/attempt-notification-state.ts

@@ -9,7 +9,6 @@ import {
   isFileChangePatchUpdatedNotification,
   isAssistantCommentaryCompletionNotification,
   isNativeToolProgressNotification,
-  isNativeResponseStreamDeltaNotification,
   isPendingOpenClawDynamicToolCompletionNotification,
   isRawAssistantProgressNotification,
   isRawReasoningCompletionNotification,
@@ -17,7 +16,6 @@ import {
   isReasoningProgressNotification,
   isReasoningItemCompletionNotification,
   isRetryableErrorNotification,
-  isTurnNotification,
   readCodexNotificationItem,
   readNotificationItemId,
   shouldDisarmAssistantCompletionIdleWatch,
@@ -25,6 +23,7 @@ import {
 } from "./attempt-notifications.js";
 import { CODEX_POST_REASONING_REPLY_IDLE_TIMEOUT_MS } from "./attempt-timeouts.js";
 import type { CodexAttemptTurnWatchController } from "./attempt-turn-watches.js";
+import { isCodexNotificationForTurn } from "./notification-correlation.js";
 import type { CodexServerNotification } from "./protocol.js";
 
 type CodexExecutionPhase =
@@ -70,7 +69,7 @@ export function isTerminalCodexTurnNotificationForTurn(params: {
   turnId: string;
   currentPromptTexts: string[];
 }): boolean {
-  if (!isTurnNotification(params.notification.params, params.threadId, params.turnId)) {
+  if (!isCodexNotificationForTurn(params.notification.params, params.threadId, params.turnId)) {
     return false;
   }
   return (
@@ -105,16 +104,15 @@ export function applyCodexTurnNotificationState(params: {
   turnCrossedToolHandoff: boolean;
 } {
   const { notification, turnWatches } = params;
-  const isCurrentTurnNotification = isTurnNotification(
+  const isCurrentTurnNotification = isCodexNotificationForTurn(
     notification.params,
     params.threadId,
     params.turnId,
   );
   const isTurnCompletion = notification.method === "turn/completed" && isCurrentTurnNotification;
-  const isNativeResponseStreamDelta = isNativeResponseStreamDeltaNotification(notification);
   let turnCrossedToolHandoff = params.turnCrossedToolHandoff;
 
-  if (isCurrentTurnNotification && !isNativeResponseStreamDelta) {
+  if (isCurrentTurnNotification) {
     turnWatches.touchActivity(`notification:${notification.method}`, {
       details: describeNotificationActivity(notification),
       attemptProgress: true,
@@ -250,7 +248,6 @@ export function applyCodexTurnNotificationState(params: {
     !turnWatches.isCompletionIdleWatchPinnedByTerminalError() &&
     notification.method !== "turn/completed" &&
     isCurrentTurnNotification &&
-    !isNativeResponseStreamDelta &&
     !trackedDynamicToolCompletion &&
     !rawToolOutputCompletion &&
     !postToolProgressNeedsTerminalGuard &&

extensions/codex/src/app-server/attempt-notifications.ts

@@ -1,11 +1,6 @@
 /**
  * Predicates and readers for Codex app-server notification envelopes.
  */
-import { asBoolean } from "openclaw/plugin-sdk/string-coerce-runtime";
-import {
-  describeCodexNotificationCorrelation,
-  isCodexNotificationForTurn,
-} from "./notification-correlation.js";
 import {
   isJsonObject,
   type CodexServerNotification,
@@ -216,13 +211,6 @@ export function isNativeToolProgressNotification(notification: CodexServerNotifi
   }
 }
 
-/** Returns true for raw native response stream delta events. */
-export function isNativeResponseStreamDeltaNotification(
-  notification: CodexServerNotification,
-): boolean {
-  return notification.method.startsWith("response.") && notification.method.endsWith(".delta");
-}
-
 /** Returns true for file-change patch update notifications. */
 export function isFileChangePatchUpdatedNotification(
   notification: CodexServerNotification,
@@ -277,74 +265,9 @@ function readRawAssistantTextPreview(item: JsonObject): string | undefined {
   return text.length > 240 ? `${text.slice(0, 237)}...` : text;
 }
 
-/** Returns true when notification params correlate to a specific thread/turn. */
-export function isTurnNotification(
-  value: JsonValue | undefined,
-  threadId: string,
-  turnId: string,
-): boolean {
-  return isCodexNotificationForTurn(value, threadId, turnId);
-}
-
-/** Returns true when a correlated notification belongs to another active run. */
-export function isCodexNotificationOutsideActiveRun(
-  correlation: ReturnType<typeof describeCodexNotificationCorrelation>,
-): boolean {
-  const hasThreadScope = Boolean(correlation.threadId || correlation.nestedTurnThreadId);
-  if (!hasThreadScope) {
-    return false;
-  }
-  if (!correlation.matchesActiveThread) {
-    return true;
-  }
-  const hasTurnScope = Boolean(correlation.turnId || correlation.nestedTurnId);
-  return hasTurnScope && correlation.matchesActiveTurn === false;
-}
-
-/** Checks request params that must contain the current thread and turn ids. */
-export function isCurrentThreadTurnRequestParams(
-  value: JsonValue | undefined,
-  threadId: string,
-  turnId: string,
-): boolean {
-  if (!isJsonObject(value)) {
-    return false;
-  }
-  return readString(value, "threadId") === threadId && readString(value, "turnId") === turnId;
-}
-
-/** Checks approval request params, accepting `conversationId` as thread id. */
-export function isCurrentApprovalTurnRequestParams(
-  value: JsonValue | undefined,
-  threadId: string,
-  turnId: string,
-): boolean {
-  if (!isJsonObject(value)) {
-    return false;
-  }
-  const requestThreadId = readString(value, "threadId") ?? readString(value, "conversationId");
-  return requestThreadId === threadId && readString(value, "turnId") === turnId;
-}
-
-/** Checks request params where `turnId` may be omitted or null for the thread. */
-export function isCurrentThreadOptionalTurnRequestParams(
-  value: JsonValue | undefined,
-  threadId: string,
-  turnId: string,
-): boolean {
-  if (!isJsonObject(value) || readString(value, "threadId") !== threadId) {
-    return false;
-  }
-  const requestTurnId = value.turnId;
-  return requestTurnId === null || requestTurnId === undefined || requestTurnId === turnId;
-}
-
 /** Returns true for app-server error notifications that will retry. */
 export function isRetryableErrorNotification(value: JsonValue | undefined): boolean {
-  if (!isJsonObject(value)) {
-    return false;
-  }
-  return readBoolean(value, "willRetry") === true || readBoolean(value, "will_retry") === true;
+  return isJsonObject(value) && value.willRetry === true;
 }
 
 /** Returns true for terminal app-server thread status strings. */
@@ -419,10 +342,6 @@ function readString(record: JsonObject, key: string): string | undefined {
   return typeof value === "string" ? value : undefined;
 }
 
-function readBoolean(record: JsonObject, key: string): boolean | undefined {
-  return asBoolean(record[key]);
-}
-
 /** Reads a typed Codex item from notification params when id/type are present. */
 export function readCodexNotificationItem(
   params: JsonValue | undefined,

extensions/codex/src/app-server/attempt-startup.test.ts

@@ -9,13 +9,16 @@ import type {
 } from "openclaw/plugin-sdk/agent-harness-runtime";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { startCodexAttemptThread } from "./attempt-startup.js";
-import { defaultLeasedCodexAppServerClientFactory } from "./client-factory.js";
 import { CodexAppServerClient } from "./client.js";
 import { type CodexPluginConfig, resolveCodexAppServerRuntimeOptions } from "./config.js";
+import { threadStartResult } from "./run-attempt-test-harness.js";
 import {
-  clearSharedCodexAppServerClient,
-  getLeasedSharedCodexAppServerClient,
-  releaseLeasedSharedCodexAppServerClient,
+  resetCodexTestBindingStore,
+  testCodexAppServerBindingStore,
+} from "./session-binding.test-helpers.js";
+import {
+  leaseSharedCodexAppServerClient,
+  resetSharedCodexAppServerClientForTests,
 } from "./shared-client.js";
 import { createClientHarness, createCodexTestModel } from "./test-support.js";
 
@@ -85,12 +88,10 @@ function startThreadWithHarness(
   signal = new AbortController().signal,
   overrides?: {
     pluginConfig?: CodexPluginConfig;
-    attemptClientFactory?: (
-      harness: ClientHarness,
-    ) => Parameters<typeof startCodexAttemptThread>[0]["attemptClientFactory"];
     harness?: ClientHarness;
     paths?: AttemptPaths;
     skipStartSpy?: boolean;
+    onThreadReserved?: Parameters<typeof startCodexAttemptThread>[0]["onThreadReserved"];
   },
 ) {
   const harness = overrides?.harness ?? createClientHarness();
@@ -101,8 +102,7 @@ function startThreadWithHarness(
   const effectivePluginConfig = overrides?.pluginConfig ?? pluginConfig;
 
   const run = startCodexAttemptThread({
-    attemptClientFactory:
-      overrides?.attemptClientFactory?.(harness) ?? defaultLeasedCodexAppServerClientFactory,
+    bindingStore: testCodexAppServerBindingStore,
     appServer: resolveCodexAppServerRuntimeOptions({ pluginConfig: effectivePluginConfig }),
     pluginConfig: effectivePluginConfig,
     computerUseConfig: effectivePluginConfig.computerUse ?? { enabled: false },
@@ -123,10 +123,11 @@ function startThreadWithHarness(
     sandboxExecServerEnabled: false,
     sandbox: null,
     contextEngineProjection: undefined,
+    startupTokenGuard: {},
     startupTimeoutMs,
     signal,
     onStartupTimeout: vi.fn(),
-    spawnedBy: undefined,
+    onThreadReserved: overrides?.onThreadReserved,
   });
 
   return { harness, run };
@@ -168,12 +169,13 @@ describe("startCodexAttemptThread", () => {
     vi.useRealTimers();
     vi.stubEnv("CODEX_API_KEY", "");
     vi.stubEnv("OPENAI_API_KEY", "");
-    clearSharedCodexAppServerClient();
+    resetCodexTestBindingStore();
+    resetSharedCodexAppServerClientForTests();
   });
 
   afterEach(async () => {
     vi.useRealTimers();
-    clearSharedCodexAppServerClient();
+    resetSharedCodexAppServerClientForTests();
     vi.restoreAllMocks();
     vi.unstubAllEnvs();
     for (const root of tempRoots) {
@@ -182,7 +184,7 @@ describe("startCodexAttemptThread", () => {
     tempRoots.clear();
   });
 
-  it("clears the shared app-server when top-level thread startup fails with an app error", async () => {
+  it("keeps the shared app-server reusable after a structured startup rejection", async () => {
     const { harness, run } = startThreadWithHarness(5_000);
     await answerInitialize(harness);
     const threadStart = await waitForThreadStart(harness);
@@ -192,25 +194,57 @@ describe("startCodexAttemptThread", () => {
     });
 
     await expect(run).rejects.toThrow("Invalid bearer token");
+    expect(harness.process.stdin.destroyed).toBe(false);
+  });
+
+  it("retires the client when malformed startup cleanup cannot be confirmed", async () => {
+    const { harness, run } = startThreadWithHarness(5_000);
+    await answerInitialize(harness);
+    const threadStart = await waitForThreadStart(harness);
+    harness.send({ id: threadStart.id, result: { thread: { id: "thread-malformed" } } });
+    const unsubscribe = await waitForRequest(harness, "thread/unsubscribe");
+    harness.send({
+      id: unsubscribe.id,
+      error: { code: -32000, message: "unsubscribe failed" },
+    });
+
+    await expect(run).rejects.toThrow("subscription could not be released");
     expect(harness.process.stdin.destroyed).toBe(true);
   });
 
-  it("retires a failed startup client after another active lease releases", async () => {
+  it("retires the client when route cleanup cannot release the subscription", async () => {
+    const { harness, run } = startThreadWithHarness(5_000, undefined, {
+      onThreadReserved: () => {
+        throw new Error("route integration failed");
+      },
+    });
+    await answerInitialize(harness);
+    const threadStart = await waitForThreadStart(harness);
+    harness.send({ id: threadStart.id, result: threadStartResult("thread-route-failed") });
+    const unsubscribe = await waitForRequest(harness, "thread/unsubscribe");
+    harness.send({
+      id: unsubscribe.id,
+      error: { code: -32000, message: "unsubscribe failed" },
+    });
+
+    await expect(run).rejects.toThrow("Codex startup subscription cleanup failed");
+    expect(harness.process.stdin.destroyed).toBe(true);
+  });
+
+  it("does not retire a peer-owned client after a structured startup rejection", async () => {
     const retained = createClientHarness();
-    const replacement = createClientHarness();
-    const startSpy = vi
-      .spyOn(CodexAppServerClient, "start")
-      .mockReturnValueOnce(retained.client)
-      .mockReturnValueOnce(replacement.client);
+    const startSpy = vi.spyOn(CodexAppServerClient, "start").mockReturnValue(retained.client);
     const appServer = resolveCodexAppServerRuntimeOptions({ pluginConfig });
     const paths = createAttemptPaths();
 
-    const retainedLease = getLeasedSharedCodexAppServerClient({
+    const retainedLeasePromise = leaseSharedCodexAppServerClient({
       startOptions: appServer.start,
       agentDir: paths.agentDir,
+      preparedAuth: {},
     });
     await answerInitialize(retained);
-    await expect(retainedLease).resolves.toBe(retained.client);
+    const retainedLease = await retainedLeasePromise;
+    expect(retainedLease.client).toBe(retained.client);
 
     const { run } = startThreadWithHarness(5_000, new AbortController().signal, {
       harness: retained,
@@ -226,17 +260,16 @@ describe("startCodexAttemptThread", () => {
     await expect(run).rejects.toThrow("Invalid bearer token");
     expect(retained.process.stdin.destroyed).toBe(false);
 
-    expect(releaseLeasedSharedCodexAppServerClient(retained.client)).toBe(true);
-    await vi.waitFor(() => expect(retained.process.stdin.destroyed).toBe(true));
-
-    const replacementLease = getLeasedSharedCodexAppServerClient({
+    retainedLease.release();
+    const nextLeasePromise = leaseSharedCodexAppServerClient({
       startOptions: appServer.start,
       agentDir: paths.agentDir,
+      preparedAuth: {},
     });
-    await answerInitialize(replacement);
-    await expect(replacementLease).resolves.toBe(replacement.client);
-    expect(startSpy).toHaveBeenCalledTimes(2);
-    expect(releaseLeasedSharedCodexAppServerClient(replacement.client)).toBe(true);
+    const nextLease = await nextLeasePromise;
+    expect(nextLease.client).toBe(retained.client);
+    expect(startSpy).toHaveBeenCalledTimes(1);
+    nextLease.release();
   });
 
   it("clears the shared app-server when startup abandons an in-flight thread request", async () => {
@@ -258,18 +291,20 @@ describe("startCodexAttemptThread", () => {
     expect(harness.stdinDestroyed).toBe(true);
   });
 
-  it("aborts abandoned thread startup when another lease keeps the shared app-server alive", async () => {
+  it("retires abandoned thread startup even when another lease shares the client", async () => {
     const retained = createClientHarness();
     vi.spyOn(CodexAppServerClient, "start").mockReturnValue(retained.client);
     const appServer = resolveCodexAppServerRuntimeOptions({ pluginConfig });
     const paths = createAttemptPaths();
 
-    const retainedLease = getLeasedSharedCodexAppServerClient({
+    const retainedLeasePromise = leaseSharedCodexAppServerClient({
       startOptions: appServer.start,
       agentDir: paths.agentDir,
+      preparedAuth: {},
     });
     await answerInitialize(retained);
-    await expect(retainedLease).resolves.toBe(retained.client);
+    const retainedLease = await retainedLeasePromise;
+    expect(retainedLease.client).toBe(retained.client);
 
     const { run } = startThreadWithHarness(100, new AbortController().signal, {
       harness: retained,
@@ -280,11 +315,9 @@ describe("startCodexAttemptThread", () => {
     const threadStart = await waitForThreadStart(retained);
 
     await rejected;
-    expect(retained.process.stdin.destroyed).toBe(false);
-
-    retained.send({ id: threadStart.id, result: { threadId: "late-thread" } });
-    expect(releaseLeasedSharedCodexAppServerClient(retained.client)).toBe(true);
-    await vi.waitFor(() => expect(retained.process.stdin.destroyed).toBe(true));
+    expect(threadStart.id).toBeDefined();
+    expect(retained.process.stdin.destroyed).toBe(true);
+    retainedLease.release();
   });
 
   it("closes the shared app-server when startup times out during initialize", async () => {
@@ -309,45 +342,37 @@ describe("startCodexAttemptThread", () => {
     ).toBe(false);
   });
 
-  it("closes a startup client that arrives after startup timeout", async () => {
-    let observedFactoryOptions:
-      | {
-          onStartedClient?: (client: CodexAppServerClient) => void;
-          abandonSignal?: AbortSignal;
-        }
-      | undefined;
-    let resolveFactoryDone: () => void = () => undefined;
-    const factoryDone = new Promise<void>((resolve) => {
-      resolveFactoryDone = resolve;
+  it("releases a late startup lease without retiring a peer-owned initializing client", async () => {
+    const harness = createClientHarness();
+    const startSpy = vi.spyOn(CodexAppServerClient, "start").mockReturnValue(harness.client);
+    const paths = createAttemptPaths();
+    const appServer = resolveCodexAppServerRuntimeOptions({ pluginConfig });
+    const peerPromise = leaseSharedCodexAppServerClient({
+      startOptions: appServer.start,
+      agentDir: paths.agentDir,
+      preparedAuth: {},
     });
-    const { harness, run } = startThreadWithHarness(100, new AbortController().signal, {
-      attemptClientFactory:
-        (factoryHarness) => async (_startOptions, _authProfileId, _agentDir, _config, options) => {
-          try {
-            observedFactoryOptions = options;
-            await new Promise<void>((resolve) => {
-              setTimeout(resolve, 250);
-            });
-            options?.onStartedClient?.(factoryHarness.client);
-            return factoryHarness.client;
-          } finally {
-            resolveFactoryDone();
-          }
-        },
+    const { run } = startThreadWithHarness(100, new AbortController().signal, {
+      harness,
+      paths,
+      skipStartSpy: true,
     });
-    const rejected = expect(run).rejects.toThrow("codex app-server startup timed out");
 
-    await rejected;
-    await factoryDone;
-    await vi.waitFor(() => expect(harness.stdinDestroyed).toBe(true), {
-      interval: 1,
-      timeout: 2_000,
+    await expect(run).rejects.toThrow("codex app-server startup timed out");
+    expect(harness.stdinDestroyed).toBe(false);
+    await answerInitialize(harness);
+    const peer = await peerPromise;
+    expect(peer.client).toBe(harness.client);
+    await new Promise<void>((resolve) => {
+      setImmediate(resolve);
     });
+
+    expect(startSpy).toHaveBeenCalledTimes(1);
     expect(
       readHarnessMessages(harness.writes).some((write) => write.method === "thread/start"),
     ).toBe(false);
-    expect(observedFactoryOptions?.onStartedClient).toBeTypeOf("function");
-    expect(observedFactoryOptions?.abandonSignal?.aborted).toBe(true);
+    await peer.abandon();
+    expect(harness.stdinDestroyed).toBe(true);
   });
 
   it("clears the shared app-server when cancellation abandons an in-flight thread request", async () => {

extensions/codex/src/app-server/attempt-startup.ts

@@ -11,9 +11,15 @@ import {
   type resolveSandboxContext,
 } from "openclaw/plugin-sdk/agent-harness-runtime";
 import { defaultCodexAppInventoryCache } from "./app-inventory-cache.js";
+import {
+  CODEX_APP_SERVER_UNSUBSCRIBE_TIMEOUT_MS,
+  CodexAppServerUnsafeSubscriptionError,
+  isCodexAppServerUnsafeSubscriptionError,
+  unsubscribeCodexThreadBestEffort,
+} from "./attempt-client-cleanup.js";
 import { buildCodexPluginThreadConfigEligibilityLogData } from "./attempt-diagnostics.js";
 import { withCodexStartupTimeout } from "./attempt-timeouts.js";
-import type { CodexAppServerClientFactory } from "./client-factory.js";
+import { ensureCodexAppServerClientRuntime } from "./client-runtime.js";
 import { isCodexAppServerConnectionClosedError, type CodexAppServerClient } from "./client.js";
 import { ensureCodexComputerUse } from "./computer-use.js";
 import {
@@ -48,17 +54,23 @@ import {
   releaseCodexSandboxExecServerEnvironment,
   type CodexSandboxExecEnvironment,
 } from "./sandbox-exec-server.js";
+import type { CodexAppServerBindingStore } from "./session-binding.js";
 import {
-  clearSharedCodexAppServerClientIfCurrentAndUnclaimed,
-  clearSharedCodexAppServerClientIfCurrent,
-  releaseLeasedSharedCodexAppServerClient,
-  retireSharedCodexAppServerClientIfCurrent,
+  leaseSharedCodexAppServerClient,
+  type CodexAppServerClientLease,
+  type CodexAppServerClientLeaseFactory,
 } from "./shared-client.js";
+import type { CodexAppServerStartupTokenGuard } from "./startup-binding.js";
 import {
   startOrResumeThread,
   type CodexAppServerThreadLifecycleBinding,
   type CodexContextEngineThreadBootstrapProjection,
 } from "./thread-lifecycle.js";
+import {
+  getCodexAppServerTurnRouter,
+  type CodexAppServerTurnRouter,
+  type CodexThreadRouteReservation,
+} from "./turn-router.js";
 
 const CODEX_APP_SERVER_STARTUP_CONNECTION_CLOSE_MAX_ATTEMPTS = 3;
 
@@ -66,14 +78,15 @@ type CodexSandboxContext = Awaited<ReturnType<typeof resolveSandboxContext>>;
 
 /** Resources and bindings returned after a Codex attempt thread starts. */
 export type StartCodexAttemptThreadResult = {
-  client: CodexAppServerClient;
+  turnRouter: CodexAppServerTurnRouter;
+  turnRoute: CodexThreadRouteReservation;
   thread: CodexAppServerThreadLifecycleBinding;
-  pluginAppServer: CodexAppServerRuntimeOptions;
   sandboxEnvironment: CodexSandboxExecEnvironment | undefined;
   environmentSelection: CodexTurnEnvironmentParams[] | undefined;
   executionCwd: string;
   sandboxPolicy: CodexSandboxPolicy | undefined;
-  releaseSharedClientLease: () => void;
+  clientLease: CodexAppServerClientLease;
+  mcpElicitationDelegationRequired: boolean;
   restartContextEngineCodexThread: () => Promise<CodexAppServerThreadLifecycleBinding>;
 };
 
@@ -82,7 +95,8 @@ export type StartCodexAttemptThreadResult = {
  * run loop must later release.
  */
 export async function startCodexAttemptThread(params: {
-  attemptClientFactory: CodexAppServerClientFactory;
+  bindingStore: CodexAppServerBindingStore;
+  clientLeaseFactory?: CodexAppServerClientLeaseFactory;
   appServer: CodexAppServerRuntimeOptions;
   pluginConfig: CodexPluginConfig;
   computerUseConfig: CodexComputerUseConfig;
@@ -105,18 +119,26 @@ export async function startCodexAttemptThread(params: {
   sandboxExecServerEnabled: boolean;
   sandbox: CodexSandboxContext;
   contextEngineProjection: CodexContextEngineThreadBootstrapProjection | undefined;
+  expectedResumeThreadId?: string;
+  startupTokenGuard: CodexAppServerStartupTokenGuard;
   startupTimeoutMs: number;
   signal: AbortSignal;
   onStartupTimeout: () => void | Promise<void>;
-  spawnedBy: EmbeddedRunAttemptParams["spawnedBy"];
+  onThreadReserved?: (client: CodexAppServerClient, threadId: string) => () => void;
 }): Promise<StartCodexAttemptThreadResult> {
-  let pluginAppServer = params.appServer;
-  let releaseSharedClientLease: (() => void) | undefined;
-  let startupClientForAbandonedRequestCleanup: CodexAppServerClient | undefined;
+  let mcpElicitationDelegationRequired = false;
+  let sharedClientLease: CodexAppServerClientLease | undefined;
   let releaseStartupResourcesOnTimeout: (() => Promise<void>) | undefined;
   let startupAbandoned = false;
   const startupAbandonController = new AbortController();
   const abandonStartupAcquire = () => startupAbandonController.abort();
+  const abandonStartupClient = async () => {
+    const lease = sharedClientLease;
+    sharedClientLease = undefined;
+    if (lease) {
+      await lease.abandon();
+    }
+  };
   params.signal.addEventListener("abort", abandonStartupAcquire, { once: true });
   try {
     const startupResult = await withCodexStartupTimeout({
@@ -127,10 +149,7 @@ export async function startCodexAttemptThread(params: {
         startupAbandonController.abort();
         await params.onStartupTimeout();
         await releaseStartupResourcesOnTimeout?.();
-        releaseSharedClientLease?.();
-        releaseSharedClientLease = undefined;
-        await closeAbandonedStartupClient(startupClientForAbandonedRequestCleanup);
-        startupClientForAbandonedRequestCleanup = undefined;
+        await abandonStartupClient();
       },
       operation: async () => {
         const threadConfig = mergeCodexThreadConfigs(
@@ -161,8 +180,9 @@ export async function startCodexAttemptThread(params: {
         const resolvedPluginPolicy = pluginThreadConfigRequired
           ? resolveCodexPluginsPolicy(pluginThreadConfigPluginConfig)
           : undefined;
-        const computerUseMcpElicitationDelegationRequired = params.computerUseConfig.enabled;
-        const mcpElicitationDelegationRequired =
+        const computerUseMcpElicitationDelegationRequired =
+          params.computerUseConfig.enabled === true;
+        mcpElicitationDelegationRequired =
           resolvedPluginPolicy?.enabled === true || computerUseMcpElicitationDelegationRequired;
         const enabledPluginConfigKeys = resolvedPluginPolicy
           ? resolvedPluginPolicy.pluginPolicies
@@ -184,55 +204,48 @@ export async function startCodexAttemptThread(params: {
             appServer: params.appServer,
           }),
         );
-        pluginAppServer = mcpElicitationDelegationRequired
+        const pluginAppServer = mcpElicitationDelegationRequired
           ? {
               ...params.appServer,
               approvalPolicy: withMcpElicitationsApprovalPolicy(params.appServer.approvalPolicy),
             }
           : params.appServer;
 
-        let attemptedClient: CodexAppServerClient | undefined;
+        let attemptedClientAbandoned = false;
         const startupAttempt = async () => {
-          let startupClientLease: (() => void) | undefined;
-          let startupClient: CodexAppServerClient | undefined;
-          let startupAttemptError: unknown;
-          let startupAttemptSucceeded = false;
+          let startupClientLease: CodexAppServerClientLease | undefined;
+          let clientWorkStarted = false;
+          attemptedClientAbandoned = false;
           try {
-            startupClient = await params.attemptClientFactory(
-              params.appServer.start,
-              params.startupAuthProfileId,
-              params.agentDir,
-              params.config,
-              {
-                onStartedClient: (client) => {
-                  // Timeout cleanup may fire before the client factory resolves;
-                  // close any late-arriving client instead of leaking a lease.
-                  startupClientForAbandonedRequestCleanup = client;
-                  if (startupAbandoned || startupAbandonController.signal.aborted) {
-                    void closeAbandonedStartupClient(client);
-                  }
-                },
-                abandonSignal: startupAbandonController.signal,
+            startupClientLease = await (
+              params.clientLeaseFactory ?? leaseSharedCodexAppServerClient
+            )({
+              startOptions: params.appServer.start,
+              authProfileId: params.startupAuthProfileId,
+              agentDir: params.agentDir,
+              config: params.config,
+              preparedAuth: {
+                profileId: params.startupAuthProfileId,
+                cacheKey: params.startupAuthAccountCacheKey ?? params.startupEnvApiKeyCacheKey,
               },
-            );
-            const activeStartupClient = startupClient;
-            let startupClientLeaseReleased = false;
-            startupClientLease = () => {
-              if (startupClientLeaseReleased) {
-                return;
-              }
-              startupClientLeaseReleased = true;
-              releaseLeasedSharedCodexAppServerClient(activeStartupClient);
-            };
-            releaseSharedClientLease = startupClientLease;
-            attemptedClient = activeStartupClient;
-            startupClientForAbandonedRequestCleanup = activeStartupClient;
+              abandonSignal: startupAbandonController.signal,
+            });
+            const activeStartupLease = startupClientLease;
+            const activeStartupClient = activeStartupLease.client;
+            sharedClientLease = startupClientLease;
             if (startupAbandoned) {
               throw new Error("codex app-server startup timed out");
             }
             if (startupAbandonController.signal.aborted) {
               throw new Error("codex app-server startup aborted");
             }
+            clientWorkStarted = true;
+            ensureCodexAppServerClientRuntime(activeStartupClient, {
+              agentDir: params.agentDir,
+              authProfileId: params.startupAuthProfileId,
+              config: params.config,
+            });
+            const turnRouter = getCodexAppServerTurnRouter(activeStartupClient);
             await ensureCodexComputerUse({
               client: activeStartupClient,
               pluginConfig: params.pluginConfig,
@@ -264,7 +277,6 @@ export async function startCodexAttemptThread(params: {
                 : undefined;
               startupSandboxEnvironmentAcquired = Boolean(startupSandboxEnvironment);
               if (startupAbandonController.signal.aborted) {
-                await releaseStartupSandboxEnvironment();
                 throw new Error("codex app-server startup aborted");
               }
               if (
@@ -293,9 +305,57 @@ export async function startCodexAttemptThread(params: {
             const startupSandboxPolicy = startupSandboxEnvironment
               ? resolveCodexExternalSandboxPolicyForOpenClawSandbox(params.sandbox)
               : undefined;
-            const buildThreadLifecycleParams = (signal: AbortSignal) =>
+            let startupReservation:
+              | { route: CodexThreadRouteReservation; release: () => void }
+              | undefined;
+            const reserveStartupThread = (threadId: string) => {
+              if (startupReservation) {
+                if (startupReservation.route.threadId !== threadId) {
+                  throw new Error(
+                    `codex app-server reserved ${startupReservation.route.threadId} but started ${threadId}`,
+                  );
+                }
+                return { release: startupReservation.release };
+              }
+              const route = turnRouter.reserveThread({
+                threadId,
+                releaseOn: params.signal,
+              });
+              let releaseIntegration: (() => void) | undefined;
+              try {
+                releaseIntegration = params.onThreadReserved?.(activeStartupClient, threadId);
+              } catch (error) {
+                route.release();
+                throw error;
+              }
+              let released = false;
+              const release = () => {
+                if (released) {
+                  return;
+                }
+                released = true;
+                if (startupReservation?.route === route) {
+                  startupReservation = undefined;
+                }
+                route.release();
+                releaseIntegration?.();
+              };
+              startupReservation = { route, release };
+              return { release };
+            };
+            const releaseStartupResources = async () => {
+              startupReservation?.release();
+              await releaseStartupSandboxEnvironment();
+            };
+            releaseStartupResourcesOnTimeout = releaseStartupResources;
+            const buildThreadLifecycleParams = (
+              signal: AbortSignal,
+              options: { freshStartOnly?: boolean } = {},
+            ) =>
               ({
                 client: activeStartupClient,
+                abandonClient: activeStartupLease.abandon,
+                bindingStore: params.bindingStore,
                 params: params.buildAttemptParams(),
                 agentId: params.sessionAgentId,
                 cwd: startupExecutionCwd,
@@ -313,7 +373,13 @@ export async function startCodexAttemptThread(params: {
                 mcpServersFingerprintEvaluated: params.bundleMcpThreadConfig.evaluated,
                 environmentSelection: startupEnvironmentSelection,
                 contextEngineProjection: params.contextEngineProjection,
+                freshStartOnly: options.freshStartOnly,
+                expectedResumeThreadId: options.freshStartOnly
+                  ? undefined
+                  : params.expectedResumeThreadId,
                 signal,
+                reserveResumeThread: options.freshStartOnly ? undefined : reserveStartupThread,
+                startupTokenGuard: params.startupTokenGuard,
                 pluginThreadConfig: pluginThreadConfigRequired
                   ? {
                       enabled: true,
@@ -337,57 +403,65 @@ export async function startCodexAttemptThread(params: {
               const startupThread = await startOrResumeThread(
                 buildThreadLifecycleParams(startupAbandonController.signal),
               );
+              try {
+                reserveStartupThread(startupThread.threadId);
+              } catch (error) {
+                const unsubscribed = await unsubscribeCodexThreadBestEffort(activeStartupClient, {
+                  threadId: startupThread.threadId,
+                  timeoutMs: CODEX_APP_SERVER_UNSUBSCRIBE_TIMEOUT_MS,
+                });
+                if (!unsubscribed) {
+                  throw new CodexAppServerUnsafeSubscriptionError(
+                    "Codex startup subscription cleanup failed",
+                    { cause: error },
+                  );
+                }
+                throw error;
+              }
               if (startupAbandonController.signal.aborted) {
-                await releaseStartupSandboxEnvironment();
                 throw new Error("codex app-server startup aborted");
               }
+              if (!startupReservation) {
+                throw new Error("codex app-server startup did not reserve its thread route");
+              }
               startupSandboxEnvironmentAcquired = false;
-              startupAttemptSucceeded = true;
               return {
-                client: activeStartupClient,
+                turnRouter,
+                turnRoute: startupReservation.route,
                 thread: startupThread,
                 sandboxEnvironment: startupSandboxEnvironment,
                 environmentSelection: startupEnvironmentSelection,
                 executionCwd: startupExecutionCwd,
                 sandboxPolicy: startupSandboxPolicy,
                 restartContextEngineCodexThread: () =>
-                  startOrResumeThread(buildThreadLifecycleParams(params.signal)),
+                  startOrResumeThread(
+                    buildThreadLifecycleParams(params.signal, { freshStartOnly: true }),
+                  ),
               };
             } catch (error) {
-              await releaseStartupSandboxEnvironment();
+              await releaseStartupResources();
               throw error;
             } finally {
-              if (releaseStartupResourcesOnTimeout === releaseStartupSandboxEnvironment) {
+              if (releaseStartupResourcesOnTimeout === releaseStartupResources) {
                 releaseStartupResourcesOnTimeout = undefined;
               }
             }
           } catch (error) {
-            startupAttemptError = error;
-            throw error;
-          } finally {
-            if (!startupAttemptSucceeded) {
-              if (releaseSharedClientLease === startupClientLease) {
-                releaseSharedClientLease = undefined;
-              }
-              startupClientLease?.();
-              if (startupAbandoned || params.signal.aborted) {
-                if (startupClientForAbandonedRequestCleanup === startupClient) {
-                  startupClientForAbandonedRequestCleanup = undefined;
-                }
-                await closeAbandonedStartupClient(startupClient);
-              } else if (
-                shouldClearSharedClientAfterStartupRace(startupAttemptError) ||
-                shouldClearSharedClientAfterStartupFailure({
-                  error: startupAttemptError,
-                  spawnedBy: params.spawnedBy,
-                })
-              ) {
-                if (startupClientForAbandonedRequestCleanup === startupClient) {
-                  startupClientForAbandonedRequestCleanup = undefined;
-                }
-                await evictFailedStartupClient(startupClient);
-              }
+            if (sharedClientLease === startupClientLease) {
+              sharedClientLease = undefined;
             }
+            const shouldAbandonStartupClient =
+              clientWorkStarted &&
+              (startupAbandoned ||
+                params.signal.aborted ||
+                isIndeterminateCodexStartupFailure(error));
+            if (shouldAbandonStartupClient) {
+              attemptedClientAbandoned = true;
+              await startupClientLease?.abandon();
+            } else {
+              startupClientLease?.release();
+            }
+            throw error;
           }
         };
 
@@ -402,18 +476,13 @@ export async function startCodexAttemptThread(params: {
             if (params.signal.aborted || !isCodexAppServerConnectionClosedError(error)) {
               throw error;
             }
-            const failedClient = attemptedClient;
-            const clearedSharedClient = clearSharedCodexAppServerClientIfCurrent(failedClient);
-            if (startupClientForAbandonedRequestCleanup === failedClient) {
-              startupClientForAbandonedRequestCleanup = undefined;
-            }
             if (attempt >= CODEX_APP_SERVER_STARTUP_CONNECTION_CLOSE_MAX_ATTEMPTS) {
               embeddedAgentLog.warn(
                 "codex app-server connection closed during startup; retries exhausted",
                 {
                   attempt,
                   maxAttempts: CODEX_APP_SERVER_STARTUP_CONNECTION_CLOSE_MAX_ATTEMPTS,
-                  clearedSharedClient,
+                  abandonedSharedClient: attemptedClientAbandoned,
                   error: formatErrorMessage(error),
                 },
               );
@@ -425,7 +494,7 @@ export async function startCodexAttemptThread(params: {
                 attempt,
                 nextAttempt: attempt + 1,
                 maxAttempts: CODEX_APP_SERVER_STARTUP_CONNECTION_CLOSE_MAX_ATTEMPTS,
-                clearedSharedClient,
+                abandonedSharedClient: attemptedClientAbandoned,
                 error: formatErrorMessage(error),
               },
             );
@@ -434,32 +503,21 @@ export async function startCodexAttemptThread(params: {
         throw new Error("codex app-server startup retry loop exited unexpectedly");
       },
     });
-    startupClientForAbandonedRequestCleanup = undefined;
-    if (!releaseSharedClientLease) {
+    const completedSharedClientLease = sharedClientLease;
+    if (!completedSharedClientLease) {
       throw new Error("codex app-server startup succeeded without a shared client lease");
     }
+    sharedClientLease = undefined;
     return {
       ...startupResult,
-      pluginAppServer,
-      releaseSharedClientLease,
+      mcpElicitationDelegationRequired,
+      clientLease: completedSharedClientLease,
     };
   } catch (error) {
-    if (params.signal.aborted || shouldClearSharedClientAfterStartupAbandon(error)) {
-      releaseSharedClientLease?.();
-      releaseSharedClientLease = undefined;
-      await closeAbandonedStartupClient(startupClientForAbandonedRequestCleanup);
-      startupClientForAbandonedRequestCleanup = undefined;
-    } else if (
-      shouldClearSharedClientAfterStartupRace(error) ||
-      shouldClearSharedClientAfterStartupFailure({
-        error,
-        spawnedBy: params.spawnedBy,
-      })
-    ) {
-      releaseSharedClientLease?.();
-      releaseSharedClientLease = undefined;
-      await evictFailedStartupClient(startupClientForAbandonedRequestCleanup);
-      startupClientForAbandonedRequestCleanup = undefined;
+    const shouldAbandonStartupClient =
+      params.signal.aborted || isIndeterminateCodexStartupFailure(error);
+    if (shouldAbandonStartupClient) {
+      await abandonStartupClient();
     }
     throw error;
   } finally {
@@ -467,104 +525,13 @@ export async function startCodexAttemptThread(params: {
   }
 }
 
-async function closeAbandonedStartupClient(
-  client: CodexAppServerClient | undefined,
-): Promise<void> {
-  if (!client) {
-    return;
-  }
-  const unclaimedSharedClient = clearSharedCodexAppServerClientIfCurrentAndUnclaimed(client);
-  if (unclaimedSharedClient.closed) {
-    await closeClientAndWaitIfAvailable(client);
-    return;
-  }
-  if (unclaimedSharedClient.found) {
-    const retired = retireSharedCodexAppServerClientIfCurrent(client);
-    if (retired?.closed) {
-      await closeClientAndWaitIfAvailable(client);
-    }
-    return;
-  }
-  const retiredSharedClient = retireSharedCodexAppServerClientIfCurrent(client);
-  if (retiredSharedClient) {
-    if (retiredSharedClient.closed) {
-      await closeClientAndWaitIfAvailable(client);
-    }
-    return;
-  }
-  if (clearSharedCodexAppServerClientIfCurrent(client)) {
-    await closeClientAndWaitIfAvailable(client);
-    return;
-  }
-  await closeClientAndWaitIfAvailable(client);
-}
-
-async function closeClientAndWaitIfAvailable(client: CodexAppServerClient): Promise<void> {
-  const closeable = client as {
-    close?: CodexAppServerClient["close"];
-    closeAndWait?: CodexAppServerClient["closeAndWait"];
-  };
-  if (typeof closeable.closeAndWait === "function") {
-    await closeable.closeAndWait();
-    return;
-  }
-  closeable.close?.();
-}
-
-async function evictFailedStartupClient(client: CodexAppServerClient | undefined): Promise<void> {
-  if (!client) {
-    return;
-  }
-  const unclaimedSharedClient = clearSharedCodexAppServerClientIfCurrentAndUnclaimed(client);
-  if (unclaimedSharedClient.closed) {
-    await closeClientAndWaitIfAvailable(client);
-    return;
-  }
-  if (unclaimedSharedClient.found) {
-    const retired = retireSharedCodexAppServerClientIfCurrent(client);
-    if (retired?.closed) {
-      await closeClientAndWaitIfAvailable(client);
-    }
-    return;
-  }
-  const retiredSharedClient = retireSharedCodexAppServerClientIfCurrent(client);
-  if (retiredSharedClient) {
-    if (retiredSharedClient.closed) {
-      await closeClientAndWaitIfAvailable(client);
-    }
-    return;
-  }
-  if (clearSharedCodexAppServerClientIfCurrent(client)) {
-    await closeClientAndWaitIfAvailable(client);
-    return;
-  }
-  await closeClientAndWaitIfAvailable(client);
-}
-
-function shouldClearSharedClientAfterStartupAbandon(error: unknown): boolean {
+function isIndeterminateCodexStartupFailure(error: unknown): boolean {
   return (
-    error instanceof Error &&
-    (error.message === "codex app-server startup timed out" ||
-      error.message === "codex app-server startup aborted")
+    isCodexAppServerUnsafeSubscriptionError(error) ||
+    isCodexAppServerConnectionClosedError(error) ||
+    (error instanceof Error &&
+      (error.message.endsWith(" timed out") ||
+        error.message.endsWith(" aborted") ||
+        error.message.includes("write EPIPE")))
   );
 }
-
-function shouldClearSharedClientAfterStartupRace(error: unknown): boolean {
-  return (
-    error instanceof Error &&
-    (shouldClearSharedClientAfterStartupAbandon(error) || error.message.endsWith(" timed out"))
-  );
-}
-
-function shouldClearSharedClientAfterStartupFailure(params: {
-  error: unknown;
-  spawnedBy: EmbeddedRunAttemptParams["spawnedBy"];
-}): boolean {
-  if (!(params.error instanceof Error)) {
-    return !params.spawnedBy;
-  }
-  if (params.error.message.includes("write EPIPE")) {
-    return true;
-  }
-  return !params.spawnedBy;
-}

extensions/codex/src/app-server/attempt-timeouts.test.ts

@@ -159,6 +159,39 @@ describe("Codex app-server attempt timeouts", () => {
     expect(events).toEqual(["cleanup-start", "cleanup-done"]);
   });
 
+  it("keeps the timeout result when startup resolves during timeout cleanup", async () => {
+    vi.useFakeTimers();
+    const events: string[] = [];
+    let resolveOperation!: (value: string) => void;
+    let finishCleanup!: () => void;
+    const run = withCodexStartupTimeout({
+      timeoutMs: 10,
+      signal: new AbortController().signal,
+      onTimeout: async () => {
+        events.push("cleanup-start");
+        await new Promise<void>((resolve) => {
+          finishCleanup = resolve;
+        });
+        events.push("cleanup-done");
+      },
+      operation: () =>
+        new Promise<string>((resolve) => {
+          resolveOperation = resolve;
+        }),
+    });
+    const rejected = expect(run).rejects.toThrow("codex app-server startup timed out");
+
+    await vi.advanceTimersByTimeAsync(10);
+    expect(events).toEqual(["cleanup-start"]);
+    resolveOperation("late-ready");
+    await Promise.resolve();
+    expect(events).toEqual(["cleanup-start"]);
+    finishCleanup();
+
+    await rejected;
+    expect(events).toEqual(["cleanup-start", "cleanup-done"]);
+  });
+
   it("rejects startup timeout when aborted before completion", async () => {
     vi.useFakeTimers();
     const controller = new AbortController();

extensions/codex/src/app-server/attempt-timeouts.ts

@@ -52,13 +52,13 @@ export async function withCodexStartupTimeout<T>(params: {
         };
         timeout = setTimeout(() => {
           timeoutError = new Error("codex app-server startup timed out");
-          timeoutCleanup = Promise.resolve(params.onTimeout?.()).then(
-            () => undefined,
-            () => undefined,
-          );
-          void timeoutCleanup.finally(() => {
-            rejectOnce(timeoutError!);
-          });
+          rejectOnce(timeoutError);
+          timeoutCleanup = Promise.resolve()
+            .then(() => params.onTimeout?.())
+            .then(
+              () => undefined,
+              () => undefined,
+            );
         }, params.timeoutMs);
         const abortListener = () => rejectOnce(new Error("codex app-server startup aborted"));
         params.signal.addEventListener("abort", abortListener, { once: true });

extensions/codex/src/app-server/attempt-turn-watches.test.ts

@@ -29,7 +29,7 @@ describe("Codex app-server attempt turn watches", () => {
     const progress: string[] = [];
     const diagnostics: string[] = [];
     const controller = createCodexAttemptTurnWatchController({
-      threadId: "thread-1",
+      getThreadId: () => "thread-1",
       signal: abortController.signal,
       getTurnId: () => "turn-1",
       isCompleted: () => completed,

extensions/codex/src/app-server/attempt-turn-watches.ts

@@ -29,7 +29,7 @@ export type CodexAttemptTurnWatchController = ReturnType<
  * notifications and tool handoffs progress.
  */
 export function createCodexAttemptTurnWatchController(params: {
-  threadId: string;
+  getThreadId: () => string;
   signal: AbortSignal;
   getTurnId: () => string | undefined;
   isCompleted: () => boolean;
@@ -79,6 +79,7 @@ export function createCodexAttemptTurnWatchController(params: {
   const turnTerminalIdleTimeoutMs = resolveTimerTimeoutMs(params.turnTerminalIdleTimeoutMs, 1);
   const interruptTimeoutMs = resolveTimerTimeoutMs(params.interruptTimeoutMs, 1);
   const resolveWatchTimeoutMs = (timeoutMs: number) => resolveTimerTimeoutMs(timeoutMs, 1);
+  const currentThreadId = () => params.getThreadId();
 
   const clearCompletionIdleTimer = () => {
     if (completionIdleTimer) {
@@ -227,7 +228,7 @@ export function createCodexAttemptTurnWatchController(params: {
     clearTerminalIdleTimer();
     const turnId = params.getTurnId();
     params.onRecordEvent("turn.assistant_completion_idle_release", {
-      threadId: params.threadId,
+      threadId: currentThreadId(),
       turnId,
       idleMs,
       timeoutMs: turnAssistantCompletionIdleTimeoutMs,
@@ -236,7 +237,7 @@ export function createCodexAttemptTurnWatchController(params: {
     embeddedAgentLog.warn(
       "codex app-server turn released after completed assistant item without terminal event",
       {
-        threadId: params.threadId,
+        threadId: currentThreadId(),
         turnId,
         idleMs,
         timeoutMs: turnAssistantCompletionIdleTimeoutMs,
@@ -245,7 +246,7 @@ export function createCodexAttemptTurnWatchController(params: {
     );
     if (turnId) {
       params.onInterruptTurn({
-        threadId: params.threadId,
+        threadId: currentThreadId(),
         turnId,
         timeoutMs: interruptTimeoutMs,
       });
@@ -278,7 +279,7 @@ export function createCodexAttemptTurnWatchController(params: {
     params.onTimeout(timeout);
     params.onMarkTimedOut();
     params.onRecordEvent("turn.progress_idle_timeout", {
-      threadId: params.threadId,
+      threadId: currentThreadId(),
       turnId: params.getTurnId(),
       idleMs,
       timeoutMs: timeout.timeoutMs,
@@ -286,7 +287,7 @@ export function createCodexAttemptTurnWatchController(params: {
       ...timeout.details,
     });
     embeddedAgentLog.warn("codex app-server turn idle timed out waiting for progress", {
-      threadId: params.threadId,
+      threadId: currentThreadId(),
       turnId: params.getTurnId(),
       idleMs,
       timeoutMs: timeout.timeoutMs,
@@ -331,7 +332,7 @@ export function createCodexAttemptTurnWatchController(params: {
     params.onTimeout(timeout);
     params.onMarkTimedOut();
     params.onRecordEvent("turn.completion_idle_timeout", {
-      threadId: params.threadId,
+      threadId: currentThreadId(),
       turnId: params.getTurnId(),
       idleMs,
       timeoutMs,
@@ -339,7 +340,7 @@ export function createCodexAttemptTurnWatchController(params: {
       ...timeout.details,
     });
     embeddedAgentLog.warn("codex app-server turn idle timed out waiting for completion", {
-      threadId: params.threadId,
+      threadId: currentThreadId(),
       turnId: params.getTurnId(),
       idleMs,
       timeoutMs,
@@ -374,7 +375,7 @@ export function createCodexAttemptTurnWatchController(params: {
     params.onTimeout(timeout);
     params.onMarkTimedOut();
     params.onRecordEvent("turn.terminal_idle_timeout", {
-      threadId: params.threadId,
+      threadId: currentThreadId(),
       turnId: params.getTurnId(),
       idleMs,
       timeoutMs: timeout.timeoutMs,
@@ -382,7 +383,7 @@ export function createCodexAttemptTurnWatchController(params: {
       ...timeout.details,
     });
     embeddedAgentLog.warn("codex app-server turn idle timed out waiting for terminal event", {
-      threadId: params.threadId,
+      threadId: currentThreadId(),
       turnId: params.getTurnId(),
       idleMs,
       timeoutMs: timeout.timeoutMs,
@@ -457,9 +458,11 @@ export function createCodexAttemptTurnWatchController(params: {
         details?: Record<string, unknown>;
         attemptProgress?: boolean;
         attemptTimeoutMs?: number;
+        receivedAtMs?: number;
       },
     ) => {
-      completionLastActivityAt = Date.now();
+      const now = Date.now();
+      completionLastActivityAt = Math.min(now, options?.receivedAtMs ?? now);
       completionLastActivityReason = `notification:${method}`;
       if (options?.details !== undefined) {
         completionLastActivityDetails = options.details;

extensions/codex/src/app-server/auth-bridge.test.ts

@@ -5,6 +5,7 @@ import path from "node:path";
 import {
   clearRuntimeAuthProfileStoreSnapshots,
   loadAuthProfileStoreForSecretsRuntime,
+  replaceRuntimeAuthProfileStoreSnapshots,
 } from "openclaw/plugin-sdk/agent-runtime";
 import { upsertAuthProfile } from "openclaw/plugin-sdk/provider-auth";
 import { afterEach, describe, expect, it, vi } from "vitest";
@@ -14,6 +15,7 @@ import {
   refreshCodexAppServerAuthTokens,
   resolveCodexAppServerAuthAccountCacheKey,
   resolveCodexAppServerAuthProfileId,
+  resolveCodexAppServerAuthProfileStore,
   resolveCodexAppServerFallbackApiKeyCacheKey,
   resolveCodexAppServerHomeDir,
   resolveCodexAppServerNativeHomeDir,
@@ -179,6 +181,39 @@ async function writeCodexCliApiKeyAuthFile(codexHome: string): Promise<void> {
 }
 
 describe("bridgeCodexAppServerStartOptions", () => {
+  it("preserves persisted provenance when preparing a supplied base store", async () => {
+    const agentDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-app-server-"));
+    const authProfileStore = { version: 1, profiles: {} };
+    try {
+      upsertAuthProfile({
+        agentDir,
+        profileId: "openai:work",
+        credential: {
+          type: "oauth",
+          provider: "openai",
+          access: "persisted-access",
+          refresh: "persisted-refresh",
+          expires: Date.now() + 60_000,
+        },
+      });
+
+      const prepared = resolveCodexAppServerAuthProfileStore({
+        agentDir,
+        authProfileId: "openai:work",
+        authProfileStore,
+      });
+
+      expect(prepared).not.toBe(authProfileStore);
+      expect(prepared.runtimePersistedProfileIds).toContain("openai:work");
+      expect(prepared.profiles["openai:work"]).toMatchObject({
+        access: "persisted-access",
+        refresh: "persisted-refresh",
+      });
+    } finally {
+      await fs.rm(agentDir, { recursive: true, force: true });
+    }
+  });
+
   it("sets agent-owned CODEX_HOME without overriding HOME for local app-server launches", async () => {
     const agentDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-app-server-"));
     const startOptions = createStartOptions();
@@ -576,6 +611,603 @@ describe("bridgeCodexAppServerStartOptions", () => {
     }
   });
 
+  it("applies a supplied scoped OAuth profile instead of persisted credentials", async () => {
+    const agentDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-app-server-"));
+    const request = vi.fn(async () => ({ type: "chatgptAuthTokens" }));
+    try {
+      upsertAuthProfile({
+        agentDir,
+        profileId: "openai:work",
+        credential: {
+          type: "oauth",
+          provider: "openai",
+          access: "persisted-access",
+          refresh: "persisted-refresh",
+          expires: Date.now() + 24 * 60 * 60_000,
+          accountId: "persisted-account",
+        },
+      });
+      const authProfileStore: AuthProfileStore = {
+        version: 1,
+        profiles: {
+          "openai:work": {
+            type: "oauth",
+            provider: "openai",
+            access: "scoped-access",
+            refresh: "scoped-refresh",
+            expires: Date.now() + 24 * 60 * 60_000,
+            accountId: "scoped-account",
+          },
+        },
+      };
+
+      await applyCodexAppServerAuthProfile({
+        client: { request } as never,
+        agentDir,
+        authProfileId: "openai:work",
+        authProfileStore,
+      });
+
+      expect(request).toHaveBeenCalledWith("account/login/start", {
+        type: "chatgptAuthTokens",
+        accessToken: "scoped-access",
+        chatgptAccountId: "scoped-account",
+        chatgptPlanType: null,
+      });
+    } finally {
+      await fs.rm(agentDir, { recursive: true, force: true });
+    }
+  });
+
+  it.each([
+    { name: "without persisted same-id credentials", persistSameId: false },
+    { name: "with persisted same-id credentials", persistSameId: true },
+  ])("refreshes an expired scoped OAuth profile $name", async ({ persistSameId }) => {
+    const agentDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-app-server-"));
+    const request = vi.fn(async () => ({ type: "chatgptAuthTokens" }));
+    oauthMocks.refreshOpenAICodexToken.mockResolvedValueOnce({
+      access: "scoped-refreshed-access",
+      refresh: "scoped-refreshed-refresh",
+      expires: Date.now() + 60_000,
+      accountId: "scoped-refreshed-account",
+    });
+    try {
+      if (persistSameId) {
+        upsertAuthProfile({
+          agentDir,
+          profileId: "openai:work",
+          credential: {
+            type: "oauth",
+            provider: "openai",
+            access: "persisted-access",
+            refresh: "persisted-refresh",
+            expires: Date.now() + 24 * 60 * 60_000,
+            accountId: "persisted-account",
+          },
+        });
+      }
+      const authProfileStore: AuthProfileStore = {
+        version: 1,
+        profiles: {
+          "openai:work": {
+            type: "oauth",
+            provider: "openai",
+            access: "scoped-expired-access",
+            refresh: "scoped-refresh",
+            expires: Date.now() - 60_000,
+            accountId: "scoped-account",
+          },
+        },
+      };
+
+      await applyCodexAppServerAuthProfile({
+        client: { request } as never,
+        agentDir,
+        authProfileId: "openai:work",
+        authProfileStore,
+      });
+
+      expect(oauthMocks.refreshOpenAICodexToken).toHaveBeenCalledWith("scoped-refresh");
+      expect(request).toHaveBeenCalledWith("account/login/start", {
+        type: "chatgptAuthTokens",
+        accessToken: "scoped-refreshed-access",
+        chatgptAccountId: "scoped-refreshed-account",
+        chatgptPlanType: null,
+      });
+      expect(authProfileStore.profiles["openai:work"]).toMatchObject({
+        access: "scoped-refreshed-access",
+        accountId: "scoped-refreshed-account",
+      });
+      if (persistSameId) {
+        expect(
+          loadAuthProfileStoreForSecretsRuntime(agentDir).profiles["openai:work"],
+        ).toMatchObject({
+          access: "persisted-access",
+          accountId: "persisted-account",
+        });
+      }
+    } finally {
+      await fs.rm(agentDir, { recursive: true, force: true });
+    }
+  });
+
+  it("routes a supplied persisted OAuth clone through canonical refresh", async () => {
+    const agentDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-app-server-"));
+    const request = vi.fn(async () => ({ type: "chatgptAuthTokens" }));
+    oauthMocks.refreshOpenAICodexToken.mockResolvedValueOnce({
+      access: "persisted-refreshed-access",
+      refresh: "persisted-refreshed-refresh",
+      expires: Date.now() + 60_000,
+      accountId: "persisted-account",
+    });
+    try {
+      upsertAuthProfile({
+        agentDir,
+        profileId: "openai:work",
+        credential: {
+          type: "oauth",
+          provider: "openai",
+          access: "persisted-expired-access",
+          refresh: "persisted-refresh",
+          expires: Date.now() - 60_000,
+          accountId: "persisted-account",
+        },
+      });
+      const authProfileStore = loadAuthProfileStoreForSecretsRuntime(agentDir);
+      expect(authProfileStore.runtimePersistedProfileIds).toContain("openai:work");
+
+      await applyCodexAppServerAuthProfile({
+        client: { request } as never,
+        agentDir,
+        authProfileId: "openai:work",
+        authProfileStore,
+      });
+
+      expect(oauthMocks.refreshOpenAICodexToken).toHaveBeenCalledWith("persisted-refresh");
+      expect(request).toHaveBeenCalledWith("account/login/start", {
+        type: "chatgptAuthTokens",
+        accessToken: "persisted-refreshed-access",
+        chatgptAccountId: "persisted-account",
+        chatgptPlanType: null,
+      });
+      expect(loadAuthProfileStoreForSecretsRuntime(agentDir).profiles["openai:work"]).toMatchObject(
+        {
+          access: "persisted-refreshed-access",
+          refresh: "persisted-refreshed-refresh",
+          accountId: "persisted-account",
+        },
+      );
+    } finally {
+      await fs.rm(agentDir, { recursive: true, force: true });
+    }
+  });
+
+  it("keeps a prepared persisted store aligned across rotating refresh tokens", async () => {
+    const agentDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-app-server-"));
+    oauthMocks.refreshOpenAICodexToken
+      .mockResolvedValueOnce({
+        access: "first-rotated-access",
+        refresh: "first-rotated-refresh",
+        expires: Date.now() + 60_000,
+      })
+      .mockResolvedValueOnce({
+        access: "second-rotated-access",
+        refresh: "second-rotated-refresh",
+        expires: Date.now() + 60_000,
+      });
+    try {
+      upsertAuthProfile({
+        agentDir,
+        profileId: "openai:work",
+        credential: {
+          type: "oauth",
+          provider: "openai",
+          access: "initial-access",
+          refresh: "initial-refresh",
+          expires: Date.now() + 60_000,
+        },
+      });
+      const authProfileStore = resolveCodexAppServerAuthProfileStore({
+        agentDir,
+        authProfileId: "openai:work",
+        authProfileStore: { version: 1, profiles: {} },
+      });
+
+      await refreshCodexAppServerAuthTokens({
+        agentDir,
+        authProfileId: "openai:work",
+        authProfileStore,
+      });
+      await refreshCodexAppServerAuthTokens({
+        agentDir,
+        authProfileId: "openai:work",
+        authProfileStore,
+      });
+
+      expect(oauthMocks.refreshOpenAICodexToken.mock.calls).toEqual([
+        ["initial-refresh"],
+        ["first-rotated-refresh"],
+      ]);
+      expect(authProfileStore.profiles["openai:work"]).toMatchObject({
+        access: "second-rotated-access",
+        refresh: "second-rotated-refresh",
+      });
+    } finally {
+      await fs.rm(agentDir, { recursive: true, force: true });
+    }
+  });
+
+  it("does not replace a prepared persisted store changed during refresh", async () => {
+    const agentDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-app-server-"));
+    let resolveRefresh:
+      | ((value: { access: string; refresh: string; expires: number }) => void)
+      | undefined;
+    oauthMocks.refreshOpenAICodexToken.mockImplementationOnce(
+      () =>
+        new Promise((resolve) => {
+          resolveRefresh = resolve;
+        }),
+    );
+    try {
+      upsertAuthProfile({
+        agentDir,
+        profileId: "openai:work",
+        credential: {
+          type: "oauth",
+          provider: "openai",
+          access: "initial-access",
+          refresh: "initial-refresh",
+          expires: Date.now() + 60_000,
+        },
+      });
+      const authProfileStore = resolveCodexAppServerAuthProfileStore({
+        agentDir,
+        authProfileId: "openai:work",
+        authProfileStore: { version: 1, profiles: {} },
+      });
+
+      const refresh = refreshCodexAppServerAuthTokens({
+        agentDir,
+        authProfileId: "openai:work",
+        authProfileStore,
+      });
+      await vi.waitFor(() => expect(oauthMocks.refreshOpenAICodexToken).toHaveBeenCalledTimes(1));
+      authProfileStore.profiles["openai:work"] = {
+        type: "oauth",
+        provider: "openai",
+        access: "replacement-access",
+        refresh: "replacement-refresh",
+        expires: Date.now() + 60_000,
+        accountId: "replacement-account",
+      };
+      resolveRefresh?.({
+        access: "rotated-access",
+        refresh: "rotated-refresh",
+        expires: Date.now() + 60_000,
+      });
+
+      await refresh;
+      expect(authProfileStore.profiles["openai:work"]).toMatchObject({
+        access: "replacement-access",
+        refresh: "replacement-refresh",
+        accountId: "replacement-account",
+      });
+    } finally {
+      await fs.rm(agentDir, { recursive: true, force: true });
+    }
+  });
+
+  it("keeps a runtime-external same-account OAuth profile scoped", async () => {
+    const agentDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-app-server-"));
+    const request = vi.fn(async () => ({ type: "chatgptAuthTokens" }));
+    oauthMocks.refreshOpenAICodexToken.mockResolvedValueOnce({
+      access: "scoped-refreshed-access",
+      refresh: "scoped-refreshed-refresh",
+      expires: Date.now() + 60_000,
+      accountId: "shared-account",
+    });
+    try {
+      upsertAuthProfile({
+        agentDir,
+        profileId: "openai:work",
+        credential: {
+          type: "oauth",
+          provider: "openai",
+          access: "persisted-access",
+          refresh: "persisted-refresh",
+          expires: Date.now() + 24 * 60 * 60_000,
+          accountId: "shared-account",
+        },
+      });
+      const authProfileStore: AuthProfileStore = {
+        version: 1,
+        runtimeExternalProfileIds: ["openai:work"],
+        runtimeExternalProfileIdsAuthoritative: true,
+        profiles: {
+          "openai:work": {
+            type: "oauth",
+            provider: "openai",
+            access: "scoped-expired-access",
+            refresh: "scoped-refresh",
+            expires: Date.now() - 60_000,
+            accountId: "shared-account",
+          },
+        },
+      };
+
+      await applyCodexAppServerAuthProfile({
+        client: { request } as never,
+        agentDir,
+        authProfileId: "openai:work",
+        authProfileStore,
+      });
+
+      expect(oauthMocks.refreshOpenAICodexToken).toHaveBeenCalledWith("scoped-refresh");
+      expect(request).toHaveBeenCalledWith("account/login/start", {
+        type: "chatgptAuthTokens",
+        accessToken: "scoped-refreshed-access",
+        chatgptAccountId: "shared-account",
+        chatgptPlanType: null,
+      });
+      expect(loadAuthProfileStoreForSecretsRuntime(agentDir).profiles["openai:work"]).toMatchObject(
+        {
+          access: "persisted-access",
+          refresh: "persisted-refresh",
+          accountId: "shared-account",
+        },
+      );
+    } finally {
+      await fs.rm(agentDir, { recursive: true, force: true });
+    }
+  });
+
+  it("keeps an ambiguous supplied OAuth identity scoped", async () => {
+    const agentDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-app-server-"));
+    const request = vi.fn(async () => ({ type: "chatgptAuthTokens" }));
+    oauthMocks.refreshOpenAICodexToken.mockResolvedValueOnce({
+      access: "scoped-refreshed-access",
+      refresh: "scoped-refreshed-refresh",
+      expires: Date.now() + 60_000,
+    });
+    try {
+      upsertAuthProfile({
+        agentDir,
+        profileId: "openai:work",
+        credential: {
+          type: "oauth",
+          provider: "openai",
+          access: "persisted-access",
+          refresh: "persisted-refresh",
+          expires: Date.now() + 24 * 60 * 60_000,
+          accountId: "persisted-account",
+        },
+      });
+      const authProfileStore: AuthProfileStore = {
+        version: 1,
+        profiles: {
+          "openai:work": {
+            type: "oauth",
+            provider: "openai",
+            access: "scoped-expired-access",
+            refresh: "scoped-refresh",
+            expires: Date.now() - 60_000,
+          },
+        },
+      };
+
+      await applyCodexAppServerAuthProfile({
+        client: { request } as never,
+        agentDir,
+        authProfileId: "openai:work",
+        authProfileStore,
+      });
+
+      expect(oauthMocks.refreshOpenAICodexToken).toHaveBeenCalledWith("scoped-refresh");
+      expect(request).toHaveBeenCalledWith("account/login/start", {
+        type: "chatgptAuthTokens",
+        accessToken: "scoped-refreshed-access",
+        chatgptAccountId: "openai:work",
+        chatgptPlanType: null,
+      });
+      expect(loadAuthProfileStoreForSecretsRuntime(agentDir).profiles["openai:work"]).toMatchObject(
+        {
+          access: "persisted-access",
+          refresh: "persisted-refresh",
+          accountId: "persisted-account",
+        },
+      );
+    } finally {
+      await fs.rm(agentDir, { recursive: true, force: true });
+    }
+  });
+
+  it("routes a same-identity stale persisted clone through canonical persisted auth", async () => {
+    const agentDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-app-server-"));
+    const request = vi.fn(async () => ({ type: "chatgptAuthTokens" }));
+    try {
+      upsertAuthProfile({
+        agentDir,
+        profileId: "openai:work",
+        credential: {
+          type: "oauth",
+          provider: "openai",
+          access: "stale-access",
+          refresh: "stale-refresh",
+          expires: Date.now() - 60_000,
+          accountId: "persisted-account",
+        },
+      });
+      const authProfileStore = loadAuthProfileStoreForSecretsRuntime(agentDir);
+      expect(authProfileStore.runtimePersistedProfileIds).toContain("openai:work");
+      upsertAuthProfile({
+        agentDir,
+        profileId: "openai:work",
+        credential: {
+          type: "oauth",
+          provider: "openai",
+          access: "current-access",
+          refresh: "current-refresh",
+          expires: Date.now() + 24 * 60 * 60_000,
+          accountId: "persisted-account",
+        },
+      });
+
+      await applyCodexAppServerAuthProfile({
+        client: { request } as never,
+        agentDir,
+        authProfileId: "openai:work",
+        authProfileStore,
+      });
+
+      expect(oauthMocks.refreshOpenAICodexToken).not.toHaveBeenCalled();
+      expect(request).toHaveBeenCalledWith("account/login/start", {
+        type: "chatgptAuthTokens",
+        accessToken: "current-access",
+        chatgptAccountId: "persisted-account",
+        chatgptPlanType: null,
+      });
+    } finally {
+      await fs.rm(agentDir, { recursive: true, force: true });
+    }
+  });
+
+  it("keeps a changed-identity persisted clone scoped", async () => {
+    const agentDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-app-server-"));
+    const request = vi.fn(async () => ({ type: "chatgptAuthTokens" }));
+    oauthMocks.refreshOpenAICodexToken.mockResolvedValueOnce({
+      access: "account-a-refreshed-access",
+      refresh: "account-a-refreshed-refresh",
+      expires: Date.now() + 60_000,
+      accountId: "account-a",
+    });
+    try {
+      upsertAuthProfile({
+        agentDir,
+        profileId: "openai:work",
+        credential: {
+          type: "oauth",
+          provider: "openai",
+          access: "account-a-expired-access",
+          refresh: "account-a-refresh",
+          expires: Date.now() - 60_000,
+          accountId: "account-a",
+        },
+      });
+      const authProfileStore = loadAuthProfileStoreForSecretsRuntime(agentDir);
+      expect(authProfileStore.runtimePersistedProfileIds).toContain("openai:work");
+      upsertAuthProfile({
+        agentDir,
+        profileId: "openai:work",
+        credential: {
+          type: "oauth",
+          provider: "openai",
+          access: "account-b-access",
+          refresh: "account-b-refresh",
+          expires: Date.now() + 24 * 60 * 60_000,
+          accountId: "account-b",
+        },
+      });
+      replaceRuntimeAuthProfileStoreSnapshots([{ agentDir, store: authProfileStore }]);
+
+      await applyCodexAppServerAuthProfile({
+        client: { request } as never,
+        agentDir,
+        authProfileId: "openai:work",
+        authProfileStore,
+      });
+
+      expect(oauthMocks.refreshOpenAICodexToken).toHaveBeenCalledWith("account-a-refresh");
+      expect(request).toHaveBeenCalledWith("account/login/start", {
+        type: "chatgptAuthTokens",
+        accessToken: "account-a-refreshed-access",
+        chatgptAccountId: "account-a",
+        chatgptPlanType: null,
+      });
+      expect(loadAuthProfileStoreForSecretsRuntime(agentDir).profiles["openai:work"]).toMatchObject(
+        {
+          access: "account-b-access",
+          refresh: "account-b-refresh",
+          accountId: "account-b",
+        },
+      );
+    } finally {
+      await fs.rm(agentDir, { recursive: true, force: true });
+    }
+  });
+
+  it("serializes concurrent refreshes of the same scoped OAuth profile", async () => {
+    const agentDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-app-server-"));
+    const request = vi.fn(async () => ({ type: "chatgptAuthTokens" }));
+    let resolveRefresh:
+      | ((value: { access: string; refresh: string; expires: number; accountId: string }) => void)
+      | undefined;
+    oauthMocks.refreshOpenAICodexToken.mockImplementationOnce(
+      () =>
+        new Promise((resolve) => {
+          resolveRefresh = resolve;
+        }),
+    );
+    const authProfileStore: AuthProfileStore = {
+      version: 1,
+      profiles: {
+        "openai:work": {
+          type: "oauth",
+          provider: "openai",
+          access: "scoped-expired-access",
+          refresh: "scoped-refresh",
+          expires: Date.now() - 60_000,
+          accountId: "scoped-account",
+        },
+      },
+    };
+    try {
+      const first = applyCodexAppServerAuthProfile({
+        client: { request } as never,
+        agentDir,
+        authProfileId: "openai:work",
+        authProfileStore,
+      });
+      const second = applyCodexAppServerAuthProfile({
+        client: { request } as never,
+        agentDir,
+        authProfileId: "openai:work",
+        authProfileStore,
+      });
+      await vi.waitFor(() => expect(oauthMocks.refreshOpenAICodexToken).toHaveBeenCalledTimes(1));
+
+      resolveRefresh?.({
+        access: "scoped-refreshed-access",
+        refresh: "scoped-refreshed-refresh",
+        expires: Date.now() + 60_000,
+        accountId: "scoped-refreshed-account",
+      });
+      await Promise.all([first, second]);
+
+      expect(oauthMocks.refreshOpenAICodexToken).toHaveBeenCalledTimes(1);
+      expect(request).toHaveBeenCalledTimes(2);
+      expect(request).toHaveBeenNthCalledWith(1, "account/login/start", {
+        type: "chatgptAuthTokens",
+        accessToken: "scoped-refreshed-access",
+        chatgptAccountId: "scoped-refreshed-account",
+        chatgptPlanType: null,
+      });
+      expect(request).toHaveBeenNthCalledWith(2, "account/login/start", {
+        type: "chatgptAuthTokens",
+        accessToken: "scoped-refreshed-access",
+        chatgptAccountId: "scoped-refreshed-account",
+        chatgptPlanType: null,
+      });
+    } finally {
+      resolveRefresh?.({
+        access: "cleanup-access",
+        refresh: "cleanup-refresh",
+        expires: Date.now() + 60_000,
+        accountId: "cleanup-account",
+      });
+      await fs.rm(agentDir, { recursive: true, force: true });
+    }
+  });
+
   it("leaves native app-server auth untouched when auth bridging is disabled", async () => {
     const agentDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-app-server-"));
     const request = vi.fn(async () => ({ requiresOpenaiAuth: true }));

extensions/codex/src/app-server/auth-bridge.ts

@@ -4,9 +4,10 @@ import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
 import {
   ensureAuthProfileStore,
-  ensureAuthProfileStoreWithoutExternalProfiles,
+  findPersistedAuthProfileCredential,
   loadAuthProfileStoreForSecretsRuntime,
   refreshOAuthCredentialForRuntime,
   resolveAuthProfileOrder,
@@ -18,6 +19,7 @@ import {
   type AuthProfileStore,
   type OAuthCredential,
 } from "openclaw/plugin-sdk/agent-runtime";
+import { hasUsableOAuthCredential } from "openclaw/plugin-sdk/provider-auth";
 import type { CodexAppServerClient } from "./client.js";
 import type { CodexAppServerStartOptions } from "./config.js";
 import type {
@@ -48,11 +50,16 @@ const CODEX_AUTH_JSON_FILENAME = "auth.json";
 const CODEX_HOME_DIRNAME = ".codex";
 
 type AuthProfileOrderConfig = Parameters<typeof resolveAuthProfileOrder>[0]["cfg"];
+const scopedOAuthRefreshQueues = new WeakMap<
+  AuthProfileStore,
+  Map<string, Promise<OAuthCredential>>
+>();
 
 export async function bridgeCodexAppServerStartOptions(params: {
   startOptions: CodexAppServerStartOptions;
   agentDir: string;
   authProfileId?: string | null;
+  authProfileStore?: AuthProfileStore;
   config?: AuthProfileOrderConfig;
 }): Promise<CodexAppServerStartOptions> {
   if (params.startOptions.transport !== "stdio") {
@@ -65,9 +72,10 @@ export async function bridgeCodexAppServerStartOptions(params: {
   if (params.authProfileId === null) {
     return isolatedStartOptions;
   }
-  const store = ensureCodexAppServerAuthProfileStore({
+  const store = resolveCodexAppServerAuthProfileStore({
     agentDir: params.agentDir,
     authProfileId: params.authProfileId,
+    authProfileStore: params.authProfileStore,
     config: params.config,
   });
   const authProfileId = resolveCodexAppServerAuthProfileId({
@@ -103,13 +111,15 @@ export function resolveCodexAppServerAuthProfileId(params: {
 
 export function resolveCodexAppServerAuthProfileIdForAgent(params: {
   authProfileId?: string;
+  authProfileStore?: AuthProfileStore;
   agentDir?: string;
   config?: AuthProfileOrderConfig;
 }): string | undefined {
   const agentDir = params.agentDir?.trim() || resolveDefaultAgentDir(params.config ?? {});
-  const store = ensureCodexAppServerAuthProfileStore({
+  const store = resolveCodexAppServerAuthProfileStore({
     agentDir,
     authProfileId: params.authProfileId,
+    authProfileStore: params.authProfileStore,
     config: params.config,
   });
   return resolveCodexAppServerAuthProfileId({
@@ -132,7 +142,7 @@ function ensureCodexAppServerAuthProfileStore(params: {
   });
 }
 
-function resolveCodexAppServerAuthProfileStore(params: {
+export function resolveCodexAppServerAuthProfileStore(params: {
   agentDir?: string;
   authProfileId?: string;
   authProfileStore?: AuthProfileStore;
@@ -163,13 +173,41 @@ function resolveCodexAppServerAuthProfileStore(params: {
           ...params.authProfileStore.order,
         }
       : undefined;
+  const profiles = {
+    ...overlaidStore.profiles,
+    ...params.authProfileStore.profiles,
+  };
+  const suppliedProfileIds = new Set(Object.keys(params.authProfileStore.profiles));
+  const mergeRuntimeProfileIds = (overlaidIds?: string[], suppliedIds?: string[]) => [
+    ...(overlaidIds ?? []).filter((profileId) => !suppliedProfileIds.has(profileId)),
+    ...(suppliedIds ?? []),
+  ];
+  const runtimePersistedProfileIds = mergeRuntimeProfileIds(
+    overlaidStore.runtimePersistedProfileIds,
+    params.authProfileStore.runtimePersistedProfileIds,
+  ).filter((profileId) => profiles[profileId]);
+  const runtimeExternalProfileIds = mergeRuntimeProfileIds(
+    overlaidStore.runtimeExternalProfileIds,
+    params.authProfileStore.runtimeExternalProfileIds,
+  ).filter((profileId) => profiles[profileId]);
+  const runtimeExternalProfileIdsAuthoritative =
+    overlaidStore.runtimeExternalProfileIdsAuthoritative === true ||
+    params.authProfileStore.runtimeExternalProfileIdsAuthoritative === true;
   return {
     ...params.authProfileStore,
     ...(order ? { order } : {}),
-    profiles: {
-      ...overlaidStore.profiles,
-      ...params.authProfileStore.profiles,
-    },
+    profiles,
+    ...(runtimePersistedProfileIds.length > 0
+      ? { runtimePersistedProfileIds: [...new Set(runtimePersistedProfileIds)] }
+      : {}),
+    ...(runtimeExternalProfileIds.length > 0 || runtimeExternalProfileIdsAuthoritative
+      ? {
+          runtimeExternalProfileIds: [...new Set(runtimeExternalProfileIds)],
+          ...(runtimeExternalProfileIdsAuthoritative
+            ? { runtimeExternalProfileIdsAuthoritative: true }
+            : {}),
+        }
+      : {}),
   };
 }
 
@@ -339,6 +377,7 @@ export async function applyCodexAppServerAuthProfile(params: {
   client: CodexAppServerClient;
   agentDir: string;
   authProfileId?: string | null;
+  authProfileStore?: AuthProfileStore;
   startOptions?: CodexAppServerStartOptions;
   config?: AuthProfileOrderConfig;
 }): Promise<void> {
@@ -348,6 +387,7 @@ export async function applyCodexAppServerAuthProfile(params: {
   const loginParams = await resolveCodexAppServerAuthProfileLoginParams({
     agentDir: params.agentDir,
     authProfileId: params.authProfileId,
+    authProfileStore: params.authProfileStore,
     config: params.config,
   });
   if (!loginParams) {
@@ -371,6 +411,7 @@ export async function applyCodexAppServerAuthProfile(params: {
 function resolveCodexAppServerAuthProfileLoginParams(params: {
   agentDir: string;
   authProfileId?: string;
+  authProfileStore?: AuthProfileStore;
   config?: AuthProfileOrderConfig;
 }): Promise<CodexLoginAccountParams | undefined> {
   return resolveCodexAppServerAuthProfileLoginParamsInternal(params);
@@ -379,6 +420,7 @@ function resolveCodexAppServerAuthProfileLoginParams(params: {
 export async function refreshCodexAppServerAuthTokens(params: {
   agentDir: string;
   authProfileId?: string;
+  authProfileStore?: AuthProfileStore;
   config?: AuthProfileOrderConfig;
 }): Promise<CodexChatgptAuthTokensRefreshResponse> {
   const loginParams = await resolveCodexAppServerAuthProfileLoginParamsInternal({
@@ -398,12 +440,14 @@ export async function refreshCodexAppServerAuthTokens(params: {
 async function resolveCodexAppServerAuthProfileLoginParamsInternal(params: {
   agentDir: string;
   authProfileId?: string;
+  authProfileStore?: AuthProfileStore;
   forceOAuthRefresh?: boolean;
   config?: AuthProfileOrderConfig;
 }): Promise<CodexLoginAccountParams | undefined> {
-  const store = ensureCodexAppServerAuthProfileStore({
+  const store = resolveCodexAppServerAuthProfileStore({
     agentDir: params.agentDir,
     authProfileId: params.authProfileId,
+    authProfileStore: params.authProfileStore,
     config: params.config,
   });
   const profileId = resolveCodexAppServerAuthProfileId({
@@ -425,6 +469,8 @@ async function resolveCodexAppServerAuthProfileLoginParamsInternal(params: {
   }
   const loginParams = await resolveLoginParamsForCredential(profileId, credential, {
     agentDir: params.agentDir,
+    store,
+    preferStoreCredential: Boolean(params.authProfileStore?.profiles[profileId]),
     forceOAuthRefresh: params.forceOAuthRefresh === true,
     config: params.config,
   });
@@ -509,14 +555,22 @@ function resolveCodexCliAuthFileApiKeyCacheKey(env: NodeJS.ProcessEnv): string |
 async function resolveLoginParamsForCredential(
   profileId: string,
   credential: AuthProfileCredential,
-  params: { agentDir: string; forceOAuthRefresh: boolean; config?: AuthProfileOrderConfig },
+  params: {
+    agentDir: string;
+    store: AuthProfileStore;
+    preferStoreCredential: boolean;
+    forceOAuthRefresh: boolean;
+    config?: AuthProfileOrderConfig;
+  },
 ): Promise<CodexLoginAccountParams | undefined> {
   // Runtime honors the persisted auth profile type. Shape-based remediation
   // belongs at credential entry time so request handling does not preemptively
   // reject opaque provider credentials.
   if (credential.type === "api_key") {
     const resolved = await resolveApiKeyForProfile({
-      store: ensureAuthProfileStore(params.agentDir, { allowKeychainPrompt: false }),
+      store: params.preferStoreCredential
+        ? params.store
+        : ensureAuthProfileStore(params.agentDir, { allowKeychainPrompt: false }),
       profileId,
       agentDir: params.agentDir,
     });
@@ -525,7 +579,9 @@ async function resolveLoginParamsForCredential(
   }
   if (credential.type === "token") {
     const resolved = await resolveApiKeyForProfile({
-      store: ensureAuthProfileStore(params.agentDir, { allowKeychainPrompt: false }),
+      store: params.preferStoreCredential
+        ? params.store
+        : ensureAuthProfileStore(params.agentDir, { allowKeychainPrompt: false }),
       profileId,
       agentDir: params.agentDir,
     });
@@ -539,6 +595,8 @@ async function resolveLoginParamsForCredential(
   }
   const resolvedCredential = await resolveOAuthCredentialForCodexAppServer(profileId, credential, {
     agentDir: params.agentDir,
+    store: params.store,
+    preferStoreCredential: params.preferStoreCredential,
     forceRefresh: params.forceOAuthRefresh,
     config: params.config,
   });
@@ -551,22 +609,40 @@ async function resolveLoginParamsForCredential(
 async function resolveOAuthCredentialForCodexAppServer(
   profileId: string,
   credential: OAuthCredential,
-  params: { agentDir: string; forceRefresh: boolean; config?: AuthProfileOrderConfig },
+  params: {
+    agentDir: string;
+    store: AuthProfileStore;
+    preferStoreCredential: boolean;
+    forceRefresh: boolean;
+    config?: AuthProfileOrderConfig;
+  },
 ): Promise<OAuthCredential> {
   const ownerAgentDir = resolvePersistedAuthProfileOwnerAgentDir({
     agentDir: params.agentDir,
     profileId,
   });
-  const store = ensureCodexAppServerAuthProfileStore({
+  const persistedCredential = findPersistedAuthProfileCredential({
     agentDir: ownerAgentDir,
-    authProfileId: profileId,
-    config: params.config,
+    profileId,
   });
-  const persistedStore = ensureAuthProfileStoreWithoutExternalProfiles(ownerAgentDir, {
-    allowKeychainPrompt: false,
-  });
-  const persistedCredential = persistedStore.profiles[profileId];
+  const useScopedCredential =
+    params.preferStoreCredential &&
+    shouldUseScopedOAuthCredential({
+      store: params.store,
+      profileId,
+      persistedCredential,
+      suppliedCredential: credential,
+      config: params.config,
+    });
+  const store = useScopedCredential
+    ? params.store
+    : ensureCodexAppServerAuthProfileStore({
+        agentDir: ownerAgentDir,
+        authProfileId: profileId,
+        config: params.config,
+      });
   const persistedOAuthCredential =
+    !useScopedCredential &&
     persistedCredential?.type === "oauth" &&
     isCodexAppServerAuthProvider(persistedCredential.provider, params.config)
       ? persistedCredential
@@ -577,6 +653,14 @@ async function resolveOAuthCredentialForCodexAppServer(
     isCodexAppServerAuthProvider(ownerCredential.provider, params.config)
       ? ownerCredential
       : undefined;
+  if (useScopedCredential && overlaidOAuthCredential) {
+    return await resolveScopedOAuthCredential({
+      store,
+      profileId,
+      credential: overlaidOAuthCredential,
+      forceRefresh: params.forceRefresh,
+    });
+  }
   if (params.forceRefresh && !persistedOAuthCredential && overlaidOAuthCredential) {
     const refreshedRuntimeCredential = await refreshOAuthCredentialForRuntime({
       credential: overlaidOAuthCredential,
@@ -593,18 +677,111 @@ async function resolveOAuthCredentialForCodexAppServer(
     agentDir: ownerAgentDir,
     forceRefresh: params.forceRefresh && Boolean(persistedOAuthCredential),
   });
-  const refreshed = loadAuthProfileStoreForSecretsRuntime(ownerAgentDir).profiles[profileId];
-  const storedCredential = store.profiles[profileId];
-  const candidate =
+  const refreshed = useScopedCredential
+    ? undefined
+    : loadAuthProfileStoreForSecretsRuntime(ownerAgentDir).profiles[profileId];
+  const refreshedOAuthCredential =
     refreshed?.type === "oauth" && isCodexAppServerAuthProvider(refreshed.provider, params.config)
       ? refreshed
-      : storedCredential?.type === "oauth" &&
-          isCodexAppServerAuthProvider(storedCredential.provider, params.config)
-        ? storedCredential
-        : credential;
+      : undefined;
+  if (refreshedOAuthCredential && isDeepStrictEqual(params.store.profiles[profileId], credential)) {
+    // Persisted refreshes rotate refresh tokens. Keep an isolated prepared
+    // store aligned without reverting a concurrent caller-owned replacement.
+    params.store.profiles[profileId] = refreshedOAuthCredential;
+  }
+  const storedCredential = store.profiles[profileId];
+  const candidate = refreshedOAuthCredential
+    ? refreshedOAuthCredential
+    : storedCredential?.type === "oauth" &&
+        isCodexAppServerAuthProvider(storedCredential.provider, params.config)
+      ? storedCredential
+      : credential;
   return resolved?.apiKey ? { ...candidate, access: resolved.apiKey } : candidate;
 }
 
+function shouldUseScopedOAuthCredential(params: {
+  store: AuthProfileStore;
+  profileId: string;
+  persistedCredential: AuthProfileCredential | undefined;
+  suppliedCredential: OAuthCredential;
+  config?: AuthProfileOrderConfig;
+}): boolean {
+  if (!params.store.runtimePersistedProfileIds?.includes(params.profileId)) {
+    return true;
+  }
+  const persisted = params.persistedCredential;
+  if (persisted?.type !== "oauth") {
+    return true;
+  }
+  if (
+    resolveProviderIdForAuth(persisted.provider, { config: params.config }) !==
+    resolveProviderIdForAuth(params.suppliedCredential.provider, { config: params.config })
+  ) {
+    return true;
+  }
+  return (
+    !isDeepStrictEqual(persisted, params.suppliedCredential) &&
+    !hasMatchingOAuthIdentity(persisted, params.suppliedCredential)
+  );
+}
+
+function hasMatchingOAuthIdentity(persisted: OAuthCredential, supplied: OAuthCredential): boolean {
+  const persistedAccountId = persisted.accountId?.trim();
+  const suppliedAccountId = supplied.accountId?.trim();
+  if (persistedAccountId && suppliedAccountId) {
+    return persistedAccountId === suppliedAccountId;
+  }
+  const persistedEmail = persisted.email?.trim().toLowerCase();
+  const suppliedEmail = supplied.email?.trim().toLowerCase();
+  return Boolean(persistedEmail && suppliedEmail && persistedEmail === suppliedEmail);
+}
+
+async function resolveScopedOAuthCredential(params: {
+  store: AuthProfileStore;
+  profileId: string;
+  credential: OAuthCredential;
+  forceRefresh: boolean;
+}): Promise<OAuthCredential> {
+  const existingRefresh = scopedOAuthRefreshQueues.get(params.store)?.get(params.profileId);
+  if (existingRefresh) {
+    return await existingRefresh;
+  }
+  if (!params.forceRefresh && hasUsableOAuthCredential(params.credential)) {
+    return params.credential;
+  }
+
+  const storeRefreshes = scopedOAuthRefreshQueues.get(params.store) ?? new Map();
+  scopedOAuthRefreshQueues.set(params.store, storeRefreshes);
+  const refresh = (async () => {
+    const current = params.store.profiles[params.profileId];
+    const credential = current?.type === "oauth" ? current : params.credential;
+    if (!params.forceRefresh && hasUsableOAuthCredential(credential)) {
+      return credential;
+    }
+    const refreshed = await refreshOAuthCredentialForRuntime({ credential });
+    if (!refreshed?.access?.trim()) {
+      throw new Error(`Codex app-server auth profile "${params.profileId}" could not refresh.`);
+    }
+    if (!isDeepStrictEqual(params.store.profiles[params.profileId], credential)) {
+      throw new Error(
+        `Codex app-server auth profile "${params.profileId}" changed while refreshing.`,
+      );
+    }
+    params.store.profiles[params.profileId] = refreshed;
+    return refreshed;
+  })();
+  storeRefreshes.set(params.profileId, refresh);
+  try {
+    return await refresh;
+  } finally {
+    // Scoped stores are process-local; serialize their rotating refresh token
+    // and release the queue entry with the refresh that owns it.
+    if (storeRefreshes.get(params.profileId) === refresh) {
+      storeRefreshes.delete(params.profileId);
+    }
+  }
+}
+
 function isCodexAppServerAuthProvider(provider: string, config?: AuthProfileOrderConfig): boolean {
   const resolvedProvider = resolveProviderIdForAuth(provider, { config });
   return (

extensions/codex/src/app-server/auth-profile-runtime-contract.test.ts

@@ -8,37 +8,56 @@ import {
 } from "openclaw/plugin-sdk/agent-harness";
 import { AUTH_PROFILE_RUNTIME_CONTRACT } from "openclaw/plugin-sdk/agent-runtime-test-contracts";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import type { CodexAppServerClientFactory } from "./client-factory.js";
 import { runCodexAppServerAttempt as runCodexAppServerAttemptImpl } from "./run-attempt.js";
-import { readCodexAppServerBinding, writeCodexAppServerBinding } from "./session-binding.js";
-import { createCodexTestModel } from "./test-support.js";
+import {
+  readCodexAppServerBinding,
+  registerCodexTestSessionIdentity,
+  resetCodexTestBindingStore,
+  testCodexAppServerBindingStore,
+  writeCodexAppServerBinding,
+} from "./session-binding.test-helpers.js";
+import type { CodexAppServerClientLeaseFactory } from "./shared-client.js";
+import {
+  adaptCodexTestClientFactory,
+  createCodexTestModel,
+  type CodexTestAppServerClientFactory,
+} from "./test-support.js";
 
-let codexAppServerClientFactoryForTest: CodexAppServerClientFactory | undefined;
+let codexAppServerClientLeaseFactoryForTest: CodexAppServerClientLeaseFactory | undefined;
 
-type RunCodexAppServerAttemptOptions = NonNullable<
+type RunCodexAppServerAttemptImplOptions = NonNullable<
   Parameters<typeof runCodexAppServerAttemptImpl>[1]
 >;
+type RunCodexAppServerAttemptOptions = Omit<RunCodexAppServerAttemptImplOptions, "bindingStore"> & {
+  bindingStore?: RunCodexAppServerAttemptImplOptions["bindingStore"];
+};
 
-function setCodexAppServerClientFactoryForTest(factory: CodexAppServerClientFactory): void {
-  codexAppServerClientFactoryForTest = factory;
+function setCodexAppServerClientFactoryForTest(factory: CodexTestAppServerClientFactory): void {
+  codexAppServerClientLeaseFactoryForTest = adaptCodexTestClientFactory(factory);
 }
 
 function resetCodexAppServerClientFactoryForTest(): void {
-  codexAppServerClientFactoryForTest = undefined;
+  codexAppServerClientLeaseFactoryForTest = undefined;
 }
 
 function runCodexAppServerAttempt(
   params: EmbeddedRunAttemptParams,
   options: RunCodexAppServerAttemptOptions = {},
 ) {
-  const clientFactory = options.clientFactory ?? codexAppServerClientFactoryForTest;
-  return runCodexAppServerAttemptImpl(
-    params,
-    clientFactory ? { ...options, clientFactory } : options,
-  );
+  const clientLeaseFactory = options.clientLeaseFactory ?? codexAppServerClientLeaseFactoryForTest;
+  return runCodexAppServerAttemptImpl(params, {
+    ...options,
+    bindingStore: options.bindingStore ?? testCodexAppServerBindingStore,
+    ...(clientLeaseFactory ? { clientLeaseFactory } : {}),
+  });
 }
 
 function createParams(sessionFile: string, workspaceDir: string): EmbeddedRunAttemptParams {
+  registerCodexTestSessionIdentity(
+    sessionFile,
+    AUTH_PROFILE_RUNTIME_CONTRACT.sessionId,
+    AUTH_PROFILE_RUNTIME_CONTRACT.sessionKey,
+  );
   return {
     prompt: AUTH_PROFILE_RUNTIME_CONTRACT.workspacePrompt,
     sessionId: AUTH_PROFILE_RUNTIME_CONTRACT.sessionId,
@@ -111,7 +130,8 @@ function createCodexAuthProfileHarness(params: { startMethod: "thread/start" | "
   const seenAuthProfileIds: Array<string | undefined> = [];
   const seenAgentDirs: Array<string | undefined> = [];
   const requests: Array<{ method: string; params: unknown }> = [];
-  let notify: (notification: unknown) => Promise<void> = async () => undefined;
+  const notificationHandlers = new Set<(notification: unknown) => Promise<void> | void>();
+  const requestHandlers = new Set<(request: unknown) => unknown>();
   setCodexAppServerClientFactoryForTest(async (_startOptions, authProfileId, agentDir) => {
     seenAuthProfileIds.push(authProfileId);
     seenAgentDirs.push(agentDir);
@@ -126,13 +146,22 @@ function createCodexAuthProfileHarness(params: { startMethod: "thread/start" | "
         }
         throw new Error(`unexpected method: ${method}`);
       }),
-      addNotificationHandler: (handler: (notification: unknown) => Promise<void>) => {
-        notify = handler;
-        return () => undefined;
+      addNotificationHandler: (handler: (notification: unknown) => Promise<void> | void) => {
+        notificationHandlers.add(handler);
+        return () => notificationHandlers.delete(handler);
       },
-      addRequestHandler: () => () => undefined,
+      addRequestHandler: (handler: (request: unknown) => unknown) => {
+        requestHandlers.add(handler);
+        return () => requestHandlers.delete(handler);
+      },
+      addCloseHandler: () => () => undefined,
     } as never;
   });
+  const notify = async (notification: unknown) => {
+    await Promise.all(
+      [...notificationHandlers].map((handler) => Promise.resolve(handler(notification))),
+    );
+  };
   return {
     seenAuthProfileIds,
     seenAgentDirs,
@@ -158,6 +187,7 @@ describe("Auth profile runtime contract - Codex app-server adapter", () => {
   let tmpDir: string;
 
   beforeEach(async () => {
+    resetCodexTestBindingStore();
     vi.useRealTimers();
     tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-auth-contract-"));
   });
@@ -193,6 +223,7 @@ describe("Auth profile runtime contract - Codex app-server adapter", () => {
   it("reuses a bound OpenAI Codex auth profile when resume params omit authProfileId", async () => {
     const harness = createCodexAuthProfileHarness({ startMethod: "thread/resume" });
     const sessionFile = path.join(tmpDir, "session.jsonl");
+    const params = createParams(sessionFile, tmpDir);
     await writeCodexAppServerBinding(sessionFile, {
       threadId: "thread-auth-contract",
       cwd: tmpDir,
@@ -200,7 +231,6 @@ describe("Auth profile runtime contract - Codex app-server adapter", () => {
       dynamicToolsFingerprint: "[]",
     });
     // authProfileId is intentionally omitted to exercise the resume-bound profile path.
-    const params = createParams(sessionFile, tmpDir);
 
     const run = runCodexAppServerAttempt(params);
     await vi.waitFor(
@@ -218,13 +248,13 @@ describe("Auth profile runtime contract - Codex app-server adapter", () => {
   it("prefers an explicit runtime auth profile over a stale persisted binding", async () => {
     const harness = createCodexAuthProfileHarness({ startMethod: "thread/resume" });
     const sessionFile = path.join(tmpDir, "session.jsonl");
+    const params = createParams(sessionFile, tmpDir);
     await writeCodexAppServerBinding(sessionFile, {
       threadId: "thread-auth-contract",
       cwd: tmpDir,
       authProfileId: "openai:stale",
       dynamicToolsFingerprint: "[]",
     });
-    const params = createParams(sessionFile, tmpDir);
     params.authProfileId = AUTH_PROFILE_RUNTIME_CONTRACT.openAiCodexProfileId;
 
     const run = runCodexAppServerAttempt(params);

extensions/codex/src/app-server/client-factory.ts

@@ -1,67 +0,0 @@
-/**
- * Lazy factories for shared and leased Codex app-server clients.
- */
-import type { resolveCodexAppServerAuthProfileIdForAgent } from "./auth-bridge.js";
-import type { CodexAppServerClient } from "./client.js";
-import type { CodexAppServerStartOptions } from "./config.js";
-
-type AuthProfileOrderConfig = Parameters<
-  typeof resolveCodexAppServerAuthProfileIdForAgent
->[0]["config"];
-
-/** Factory signature used by Codex attempt startup to acquire a client. */
-export type CodexAppServerClientFactory = (
-  startOptions?: CodexAppServerStartOptions,
-  authProfileId?: string,
-  agentDir?: string,
-  config?: AuthProfileOrderConfig,
-  options?: {
-    onStartedClient?: (client: CodexAppServerClient) => void;
-    abandonSignal?: AbortSignal;
-  },
-) => Promise<CodexAppServerClient>;
-
-let sharedClientModulePromise: Promise<typeof import("./shared-client.js")> | null = null;
-
-const loadSharedClientModule = async () => {
-  sharedClientModulePromise ??= import("./shared-client.js");
-  return await sharedClientModulePromise;
-};
-
-/** Returns the process-shared app-server client for normal attempt reuse. */
-export const defaultCodexAppServerClientFactory: CodexAppServerClientFactory = (
-  startOptions,
-  authProfileId,
-  agentDir,
-  config,
-  options,
-) =>
-  loadSharedClientModule().then(({ getSharedCodexAppServerClient }) =>
-    getSharedCodexAppServerClient({
-      startOptions,
-      authProfileId,
-      agentDir,
-      config,
-      onStartedClient: options?.onStartedClient,
-      abandonSignal: options?.abandonSignal,
-    }),
-  );
-
-/** Returns a leased shared client so startup can release ownership explicitly. */
-export const defaultLeasedCodexAppServerClientFactory: CodexAppServerClientFactory = (
-  startOptions,
-  authProfileId,
-  agentDir,
-  config,
-  options,
-) =>
-  loadSharedClientModule().then(({ getLeasedSharedCodexAppServerClient }) =>
-    getLeasedSharedCodexAppServerClient({
-      startOptions,
-      authProfileId,
-      agentDir,
-      config,
-      onStartedClient: options?.onStartedClient,
-      abandonSignal: options?.abandonSignal,
-    }),
-  );

extensions/codex/src/app-server/client-runtime.test.ts

@@ -0,0 +1,78 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { CodexAppServerClient } from "./client.js";
+import { createClientHarness } from "./test-support.js";
+
+const mocks = vi.hoisted(() => ({
+  refreshAuth: vi.fn(async () => ({ accessToken: "refreshed", chatgptAccountId: "account" })),
+  mergeRateLimitUpdate: vi.fn(),
+}));
+
+vi.mock("./auth-bridge.js", () => ({
+  refreshCodexAppServerAuthTokens: mocks.refreshAuth,
+}));
+
+vi.mock("./rate-limit-cache.js", () => ({
+  mergeCodexRateLimitsUpdate: mocks.mergeRateLimitUpdate,
+}));
+
+const { ensureCodexAppServerClientRuntime } = await import("./client-runtime.js");
+
+describe("Codex app-server client runtime", () => {
+  const clients: CodexAppServerClient[] = [];
+
+  afterEach(() => {
+    for (const client of clients) {
+      client.close();
+    }
+    clients.length = 0;
+    mocks.refreshAuth.mockClear();
+    mocks.mergeRateLimitUpdate.mockClear();
+  });
+
+  it("installs shared handlers once per physical client", async () => {
+    const harness = createClientHarness();
+    clients.push(harness.client);
+    const context = {
+      agentDir: "/tmp/agent",
+      authProfileId: "openai:default",
+      config: {},
+    };
+    const updatedContext = {
+      ...context,
+      authProfileStore: { version: 1 as const, profiles: {} },
+      config: { models: { mode: "merge" as const } },
+    };
+    const addNotificationHandler = vi.spyOn(harness.client, "addNotificationHandler");
+    const addRequestHandler = vi.spyOn(harness.client, "addRequestHandler");
+    const addCloseHandler = vi.spyOn(harness.client, "addCloseHandler");
+
+    ensureCodexAppServerClientRuntime(harness.client, context);
+    ensureCodexAppServerClientRuntime(harness.client, updatedContext);
+
+    expect(addNotificationHandler).toHaveBeenCalledTimes(1);
+    expect(addRequestHandler).toHaveBeenCalledTimes(1);
+    expect(addCloseHandler).not.toHaveBeenCalled();
+    harness.send({
+      method: "account/rateLimits/updated",
+      params: { rateLimits: { primary: { usedPercent: 12 } } },
+    });
+    harness.send({
+      id: "refresh-1",
+      method: "account/chatgptAuthTokens/refresh",
+      params: { reason: "expired" },
+    });
+
+    await vi.waitFor(() => expect(mocks.mergeRateLimitUpdate).toHaveBeenCalledTimes(1));
+    await vi.waitFor(() => expect(mocks.refreshAuth).toHaveBeenCalledTimes(1));
+    expect(mocks.refreshAuth).toHaveBeenCalledWith(updatedContext);
+    expect(mocks.mergeRateLimitUpdate).toHaveBeenCalledWith(harness.client, {
+      rateLimits: { primary: { usedPercent: 12 } },
+    });
+    await vi.waitFor(() =>
+      expect(harness.writes.map((line) => JSON.parse(line) as unknown)).toContainEqual({
+        id: "refresh-1",
+        result: { accessToken: "refreshed", chatgptAccountId: "account" },
+      }),
+    );
+  });
+});

extensions/codex/src/app-server/client-runtime.ts

@@ -0,0 +1,50 @@
+/** Client-scoped Codex auth and account observers. */
+import { refreshCodexAppServerAuthTokens } from "./auth-bridge.js";
+import type { CodexAppServerClient } from "./client.js";
+import type { JsonValue } from "./protocol.js";
+import { mergeCodexRateLimitsUpdate } from "./rate-limit-cache.js";
+import type { CodexAppServerAuthProfileLookup } from "./session-binding.js";
+
+type ClientRuntimeContext = Omit<CodexAppServerAuthProfileLookup, "agentDir"> & {
+  agentDir: string;
+};
+
+type ClientRuntime = {
+  context: ClientRuntimeContext;
+};
+
+const configuredClients = new WeakMap<CodexAppServerClient, ClientRuntime>();
+
+/** Installs one auth-refresh handler and one rate-limit observer per physical client. */
+export function ensureCodexAppServerClientRuntime(
+  client: CodexAppServerClient,
+  context: ClientRuntimeContext,
+): void {
+  const existing = configuredClients.get(client);
+  if (existing) {
+    // Shared-client keys already isolate agent/auth identity. Keep config fresh
+    // without installing another physical-client handler set.
+    existing.context = context;
+    return;
+  }
+  const runtime: ClientRuntime = { context };
+  configuredClients.set(client, runtime);
+  client.addRequestHandler(async (request) => {
+    if (request.method !== "account/chatgptAuthTokens/refresh") {
+      return undefined;
+    }
+    return (await refreshCodexAppServerAuthTokens({
+      agentDir: runtime.context.agentDir,
+      authProfileId: runtime.context.authProfileId,
+      ...(runtime.context.authProfileStore
+        ? { authProfileStore: runtime.context.authProfileStore }
+        : {}),
+      config: runtime.context.config,
+    })) as unknown as JsonValue;
+  });
+  client.addNotificationHandler((notification) => {
+    if (notification.method === "account/rateLimits/updated") {
+      mergeCodexRateLimitsUpdate(client, notification.params);
+    }
+  });
+}

extensions/codex/src/app-server/client.test.ts

@@ -50,6 +50,78 @@ describe("CodexAppServerClient", () => {
     expect(outbound.method).toBe("model/list");
   });
 
+  it("keeps a shared thread subscribed until every local owner releases it", async () => {
+    const harness = createClientHarness();
+    clients.push(harness.client);
+
+    const firstResume = harness.client.request("thread/resume", { threadId: "thread-1" });
+    const secondResume = harness.client.request("thread/resume", { threadId: "thread-1" });
+    const [firstRequest, secondRequest] = harness.writes.map((line) => JSON.parse(line)) as Array<{
+      id: number;
+    }>;
+    const resumeResult = {
+      thread: { id: "thread-1", cwd: "/tmp", status: { type: "idle" } },
+      model: "gpt-5.5",
+    };
+    harness.send({ id: firstRequest?.id, result: resumeResult });
+    harness.send({ id: secondRequest?.id, result: resumeResult });
+    await Promise.all([firstResume, secondResume]);
+
+    await expect(
+      harness.client.request("thread/unsubscribe", { threadId: "thread-1" }),
+    ).resolves.toEqual({ status: "unsubscribed" });
+    expect(harness.writes).toHaveLength(2);
+
+    const finalRelease = harness.client.request("thread/unsubscribe", {
+      threadId: "thread-1",
+    });
+    const releaseRequest = JSON.parse(harness.writes[2] ?? "{}") as { id?: number };
+    harness.send({ id: releaseRequest.id, result: { status: "unsubscribed" } });
+    await expect(finalRelease).resolves.toEqual({ status: "unsubscribed" });
+    expect(harness.writes).toHaveLength(3);
+  });
+
+  it("pairs written resume failures without retaining pre-aborted requests", async () => {
+    const harness = createClientHarness();
+    clients.push(harness.client);
+
+    const firstResume = harness.client.request("thread/resume", { threadId: "thread-1" });
+    const firstRequest = JSON.parse(harness.writes[0] ?? "{}") as { id?: number };
+    harness.send({
+      id: firstRequest.id,
+      result: {
+        thread: { id: "thread-1", cwd: "/tmp", status: { type: "idle" } },
+        model: "gpt-5.5",
+      },
+    });
+    await firstResume;
+
+    const failedResume = harness.client.request("thread/resume", { threadId: "thread-1" });
+    const failedRequest = JSON.parse(harness.writes[1] ?? "{}") as { id?: number };
+    harness.send({ id: failedRequest.id, error: { code: -32000, message: "resume failed" } });
+    await expect(failedResume).rejects.toThrow("resume failed");
+
+    await expect(
+      harness.client.request("thread/unsubscribe", { threadId: "thread-1" }),
+    ).resolves.toEqual({ status: "unsubscribed" });
+    expect(harness.writes).toHaveLength(2);
+
+    const controller = new AbortController();
+    controller.abort();
+    await expect(
+      harness.client.request(
+        "thread/resume",
+        { threadId: "thread-1" },
+        { signal: controller.signal },
+      ),
+    ).rejects.toThrow("thread/resume aborted");
+    const unsubscribe = harness.client.request("thread/unsubscribe", { threadId: "thread-1" });
+    expect(harness.writes).toHaveLength(3);
+    const unsubscribeRequest = JSON.parse(harness.writes[2] ?? "{}") as { id?: number };
+    harness.send({ id: unsubscribeRequest.id, result: { status: "unsubscribed" } });
+    await expect(unsubscribe).resolves.toEqual({ status: "unsubscribed" });
+  });
+
   it("removes unpaired surrogate code units from outbound JSON-RPC strings", async () => {
     const harness = createClientHarness();
     clients.push(harness.client);
@@ -70,9 +142,9 @@ describe("CodexAppServerClient", () => {
     expect(outbound.params?.nested).toEqual(["lowend", "emoji 🙈 ok"]);
     harness.send({
       id: JSON.parse(harness.writes[0] ?? "{}").id,
-      result: { threadId: "thread-1" },
+      result: { thread: { id: "thread-1" } },
     });
-    await expect(request).resolves.toEqual({ threadId: "thread-1" });
+    await expect(request).resolves.toEqual({ thread: { id: "thread-1" } });
   });
 
   it("logs a redacted preview for malformed app-server messages", async () => {
@@ -140,6 +212,30 @@ describe("CodexAppServerClient", () => {
     expect(warn).not.toHaveBeenCalled();
   });
 
+  it("contains synchronous notification handler failures and continues fanout", async () => {
+    const warn = vi.spyOn(embeddedAgentLog, "warn").mockImplementation(() => undefined);
+    const harness = createClientHarness();
+    clients.push(harness.client);
+    const laterHandler = vi.fn();
+    harness.client.addNotificationHandler(() => {
+      throw new Error("handler exploded");
+    });
+    harness.client.addNotificationHandler(laterHandler);
+
+    expect(() =>
+      harness.send({
+        method: "item/commandExecution/outputDelta",
+        params: { delta: "still routed" },
+      }),
+    ).not.toThrow();
+
+    await vi.waitFor(() => expect(laterHandler).toHaveBeenCalledTimes(1));
+    expect(warn).toHaveBeenCalledWith(
+      "codex app-server notification handler failed",
+      expect.objectContaining({ error: expect.any(Error) }),
+    );
+  });
+
   it("preserves JSON-RPC error codes", async () => {
     const harness = createClientHarness();
     clients.push(harness.client);
@@ -220,6 +316,95 @@ describe("CodexAppServerClient", () => {
     expect(harness.writes).toHaveLength(1);
   });
 
+  it.each([
+    {
+      method: "thread/start" as const,
+      params: {},
+      abandonment: "timeout" as const,
+      expectedError: "thread/start timed out",
+    },
+    {
+      method: "thread/fork" as const,
+      params: { threadId: "parent-thread" },
+      abandonment: "abort" as const,
+      expectedError: "thread/fork aborted",
+    },
+  ])("unsubscribes a late successful $method after local $abandonment", async (testCase) => {
+    vi.useFakeTimers();
+    const harness = createClientHarness();
+    clients.push(harness.client);
+    const controller = new AbortController();
+    const options =
+      testCase.abandonment === "timeout" ? { timeoutMs: 1 } : { signal: controller.signal };
+    const request = harness.client.request(testCase.method, testCase.params, options);
+    const outbound = JSON.parse(harness.writes[0] ?? "{}") as { id?: number };
+    const rejected = expect(request).rejects.toThrow(testCase.expectedError);
+
+    if (testCase.abandonment === "timeout") {
+      await vi.advanceTimersByTimeAsync(100);
+    } else {
+      controller.abort();
+    }
+    await rejected;
+
+    harness.send({ id: outbound.id, result: { thread: { id: "late-thread" } } });
+    expect(JSON.parse(harness.writes[1] ?? "{}")).toEqual({
+      id: expect.any(Number),
+      method: "thread/unsubscribe",
+      params: { threadId: "late-thread" },
+    });
+  });
+
+  it("closes when a late thread creation subscription cannot be released", async () => {
+    const harness = createClientHarness();
+    clients.push(harness.client);
+    const controller = new AbortController();
+    const request = harness.client.request("thread/start", {}, { signal: controller.signal });
+    const outbound = JSON.parse(harness.writes[0] ?? "{}") as { id?: number };
+    const rejected = expect(request).rejects.toThrow("thread/start aborted");
+
+    controller.abort();
+    await rejected;
+    harness.send({ id: outbound.id, result: { thread: { id: "late-thread" } } });
+    const unsubscribe = JSON.parse(harness.writes[1] ?? "{}") as { id?: number };
+    harness.send({
+      id: unsubscribe.id,
+      error: { code: -32_000, message: "unsubscribe failed" },
+    });
+
+    await vi.waitFor(() => expect(harness.stdinDestroyed).toBe(true));
+  });
+
+  it("does not unsubscribe a late rejected thread creation", async () => {
+    const harness = createClientHarness();
+    clients.push(harness.client);
+    const controller = new AbortController();
+    const request = harness.client.request("thread/start", {}, { signal: controller.signal });
+    const outbound = JSON.parse(harness.writes[0] ?? "{}") as { id?: number };
+    const rejected = expect(request).rejects.toThrow("thread/start aborted");
+
+    controller.abort();
+    await rejected;
+    harness.send({ id: outbound.id, error: { code: -32000, message: "start failed" } });
+
+    expect(harness.writes).toHaveLength(1);
+  });
+
+  it("closes after the bounded late-creation cleanup ledger fills", async () => {
+    const harness = createClientHarness();
+    clients.push(harness.client);
+
+    for (let index = 0; index < 129; index += 1) {
+      const controller = new AbortController();
+      const request = harness.client.request("thread/start", {}, { signal: controller.signal });
+      const rejected = expect(request).rejects.toThrow("thread/start aborted");
+      controller.abort();
+      await rejected;
+    }
+
+    expect(harness.stdinDestroyed).toBe(true);
+  });
+
   it("initializes with the required client version", async () => {
     const { harness, initializing, outbound } = startInitialize();
     harness.send({
@@ -516,6 +701,26 @@ describe("CodexAppServerClient", () => {
     });
   });
 
+  it.each(["execCommandApproval", "applyPatchApproval"])(
+    "fails closed for unhandled legacy %s requests",
+    async (method) => {
+      const harness = createClientHarness();
+      clients.push(harness.client);
+
+      harness.send({
+        id: "legacy-approval-1",
+        method,
+        params: { conversationId: "thread-1" },
+      });
+      await vi.waitFor(() => expect(harness.writes.length).toBe(1));
+
+      expect(JSON.parse(harness.writes[0] ?? "{}")).toEqual({
+        id: "legacy-approval-1",
+        result: { decision: "denied" },
+      });
+    },
+  );
+
   it("fails closed for unhandled native app-server approvals", async () => {
     const harness = createClientHarness();
     clients.push(harness.client);
@@ -533,6 +738,41 @@ describe("CodexAppServerClient", () => {
     });
   });
 
+  it.each([
+    [
+      "item/tool/call",
+      {
+        contentItems: [
+          {
+            type: "inputText",
+            text: "OpenClaw did not register a handler for this app-server tool call.",
+          },
+        ],
+        success: false,
+      },
+    ],
+    ["item/permissions/requestApproval", { permissions: {}, scope: "turn" }],
+    ["mcpServer/elicitation/request", { action: "decline" }],
+    [
+      "item/future/requestApproval",
+      {
+        decision: "decline",
+        reason: "OpenClaw codex app-server bridge does not grant unknown native approvals.",
+      },
+    ],
+  ])("fails closed for an unhandled %s request", async (method, expected) => {
+    const harness = createClientHarness();
+    clients.push(harness.client);
+
+    harness.send({ id: "unhandled-1", method, params: { threadId: "thread-1" } });
+    await vi.waitFor(() => expect(harness.writes.length).toBe(1));
+
+    expect(JSON.parse(harness.writes[0] ?? "{}")).toEqual({
+      id: "unhandled-1",
+      result: expected,
+    });
+  });
+
   it("only treats known Codex app-server approval methods as approvals", () => {
     expect(isCodexAppServerApprovalRequest("item/commandExecution/requestApproval")).toBe(true);
     expect(isCodexAppServerApprovalRequest("item/fileChange/requestApproval")).toBe(true);

extensions/codex/src/app-server/client.ts

@@ -12,6 +12,7 @@ import {
   type CodexInitializeParams,
   type CodexInitializeResponse,
   isRpcResponse,
+  readCodexThreadCreationResponseId,
   type CodexServerNotification,
   type JsonValue,
   type RpcMessage,
@@ -34,6 +35,8 @@ const CODEX_APP_SERVER_PARSE_BUFFER_MAX = 1_000_000;
 const CODEX_APP_SERVER_PARSE_BUFFER_MAX_LINES = 1_000;
 const CODEX_DYNAMIC_TOOL_SERVER_REQUEST_TIMEOUT_MS = 600_000;
 const CODEX_APP_SERVER_STDERR_TAIL_MAX = 2_000;
+const CODEX_APP_SERVER_ABANDONED_THREAD_CREATION_MAX = 128;
+const CODEX_APP_SERVER_LATE_THREAD_CLEANUP_TIMEOUT_MS = 5_000;
 const UNPAIRED_SURROGATE_RE =
   /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;
 
@@ -111,7 +114,10 @@ export class CodexAppServerClient {
   private readonly requestHandlers = new Set<CodexServerRequestHandler>();
   private readonly notificationHandlers = new Set<CodexServerNotificationHandler>();
   private readonly closeHandlers = new Set<(client: CodexAppServerClient) => void>();
-  private activeSharedLeaseCountProvider: (() => number | undefined) | undefined;
+  private readonly threadSubscriptionOwners = new Map<string, number>();
+  // Codex may finish a locally abandoned create request. Remember its RPC id
+  // until response/close so the unknown thread subscription can be released.
+  private readonly abandonedThreadCreationRequestIds = new Set<number | string>();
   private nextId = 1;
   private initialized = false;
   private closed = false;
@@ -225,11 +231,27 @@ export class CodexAppServerClient {
     if (options.signal?.aborted) {
       return Promise.reject(new Error(`${method} aborted`));
     }
+    const requestedThreadId = readRequestThreadId(params);
+    if (
+      method === "thread/unsubscribe" &&
+      requestedThreadId &&
+      this.releaseThreadSubscriptionOwner(requestedThreadId)
+    ) {
+      // Codex subscriptions are connection-wide sets. A logical owner can
+      // release without silencing another turn on the same physical client.
+      return Promise.resolve({ status: "unsubscribed" } as unknown as T);
+    }
+    if (method === "thread/resume" && requestedThreadId) {
+      // Every resume attempt owns one release, even if the response times out
+      // or aborts: Codex may have subscribed before OpenClaw saw the outcome.
+      this.retainThreadSubscriptionOwner(requestedThreadId);
+    }
     const id = this.nextId++;
     const message: RpcRequest = { id, method, params: params as JsonValue | undefined };
     return new Promise<T>((resolve, reject) => {
       let timeout: ReturnType<typeof setTimeout> | undefined;
       let cleanupAbort: (() => void) | undefined;
+      let requestWritten = false;
       const cleanup = () => {
         if (timeout) {
           clearTimeout(timeout);
@@ -238,23 +260,37 @@ export class CodexAppServerClient {
         cleanupAbort?.();
         cleanupAbort = undefined;
       };
-      const rejectPending = (error: Error) => {
+      const rejectPending = (error: Error, rememberLateThreadCreation = false) => {
         if (!this.pending.has(id)) {
           return;
         }
         this.pending.delete(id);
+        if (rememberLateThreadCreation && isThreadCreationRequest(method)) {
+          if (
+            this.abandonedThreadCreationRequestIds.size >=
+            CODEX_APP_SERVER_ABANDONED_THREAD_CREATION_MAX
+          ) {
+            // Lost create responses can hide server subscriptions. Once the
+            // bounded cleanup ledger fills, closing is the only safe release.
+            this.closeWithError(
+              new Error("codex app-server abandoned thread creation limit exceeded"),
+            );
+          } else {
+            this.abandonedThreadCreationRequestIds.add(id);
+          }
+        }
         cleanup();
         reject(error);
       };
       if (options.timeoutMs && Number.isFinite(options.timeoutMs) && options.timeoutMs > 0) {
         timeout = setTimeout(
-          () => rejectPending(new Error(`${method} timed out`)),
+          () => rejectPending(new Error(`${method} timed out`), true),
           Math.max(100, options.timeoutMs),
         );
         timeout.unref?.();
       }
       if (options.signal) {
-        const abortListener = () => rejectPending(new Error(`${method} aborted`));
+        const abortListener = () => rejectPending(new Error(`${method} aborted`), requestWritten);
         options.signal.addEventListener("abort", abortListener, { once: true });
         cleanupAbort = () => options.signal?.removeEventListener("abort", abortListener);
       }
@@ -262,6 +298,12 @@ export class CodexAppServerClient {
         method,
         resolve: (value) => {
           cleanup();
+          if (method === "thread/start" || method === "thread/fork") {
+            const threadId = readCodexThreadCreationResponseId(value);
+            if (threadId) {
+              this.retainThreadSubscriptionOwner(threadId);
+            }
+          }
           resolve(value as T);
         },
         reject: (error) => {
@@ -275,6 +317,7 @@ export class CodexAppServerClient {
         return;
       }
       try {
+        requestWritten = true;
         this.writeMessage(message, (error) => rejectPending(error));
       } catch (error) {
         rejectPending(error instanceof Error ? error : new Error(String(error)));
@@ -299,18 +342,6 @@ export class CodexAppServerClient {
     return () => this.notificationHandlers.delete(handler);
   }
 
-  /** Installs a lease-count provider used to route unscoped notifications. */
-  setActiveSharedLeaseCountProviderForUnscopedNotifications(
-    provider: (() => number | undefined) | undefined,
-  ): void {
-    this.activeSharedLeaseCountProvider = provider;
-  }
-
-  /** Reads the active shared-client lease count when available. */
-  getActiveSharedLeaseCountForUnscopedNotifications(): number | undefined {
-    return this.activeSharedLeaseCountProvider?.();
-  }
-
   /** Registers a close handler and returns its disposer. */
   addCloseHandler(handler: (client: CodexAppServerClient) => void): () => void {
     this.closeHandlers.add(handler);
@@ -429,6 +460,15 @@ export class CodexAppServerClient {
   }
 
   private handleResponse(response: RpcResponse): void {
+    if (this.abandonedThreadCreationRequestIds.delete(response.id)) {
+      if (!response.error) {
+        const threadId = readCodexThreadCreationResponseId(response.result);
+        if (threadId) {
+          this.unsubscribeLateThreadCreation(threadId);
+        }
+      }
+      return;
+    }
     const pending = this.pending.get(response.id);
     if (!pending) {
       return;
@@ -506,7 +546,14 @@ export class CodexAppServerClient {
 
   private handleNotification(notification: CodexServerNotification): void {
     for (const handler of this.notificationHandlers) {
-      Promise.resolve(handler(notification)).catch((error: unknown) => {
+      let result: Promise<void> | void;
+      try {
+        result = handler(notification);
+      } catch (error) {
+        embeddedAgentLog.warn("codex app-server notification handler failed", { error });
+        continue;
+      }
+      Promise.resolve(result).catch((error: unknown) => {
         embeddedAgentLog.warn("codex app-server notification handler failed", { error });
       });
     }
@@ -524,11 +571,54 @@ export class CodexAppServerClient {
     }
     this.closed = true;
     this.closeError = error;
+    this.threadSubscriptionOwners.clear();
+    this.abandonedThreadCreationRequestIds.clear();
     this.lines.close();
     this.rejectPendingRequests(error);
     return true;
   }
 
+  private unsubscribeLateThreadCreation(threadId: string): void {
+    // This late response never registered a local owner. Track the wire
+    // release anyway; an unconfirmed cleanup makes this client unsafe to pool.
+    void this.request(
+      "thread/unsubscribe",
+      { threadId },
+      { timeoutMs: CODEX_APP_SERVER_LATE_THREAD_CLEANUP_TIMEOUT_MS },
+    ).catch((error: unknown) => {
+      embeddedAgentLog.debug("codex app-server late thread unsubscribe failed", {
+        threadId,
+        error,
+      });
+      this.closeWithError(
+        new Error(`Codex late thread subscription could not be released: ${threadId}`, {
+          cause: error,
+        }),
+      );
+    });
+  }
+
+  private retainThreadSubscriptionOwner(threadId: string): void {
+    this.threadSubscriptionOwners.set(
+      threadId,
+      (this.threadSubscriptionOwners.get(threadId) ?? 0) + 1,
+    );
+  }
+
+  /** Returns true when another local owner still needs the wire subscription. */
+  private releaseThreadSubscriptionOwner(threadId: string): boolean {
+    const owners = this.threadSubscriptionOwners.get(threadId);
+    if (owners === undefined) {
+      return false;
+    }
+    if (owners > 1) {
+      this.threadSubscriptionOwners.set(threadId, owners - 1);
+      return true;
+    }
+    this.threadSubscriptionOwners.delete(threadId);
+    return false;
+  }
+
   private rejectPendingRequests(error: Error): void {
     for (const pending of this.pending.values()) {
       pending.cleanup();
@@ -541,6 +631,17 @@ export class CodexAppServerClient {
   }
 }
 
+function readRequestThreadId(value: unknown): string | undefined {
+  if (!isJsonObject(value) || typeof value.threadId !== "string") {
+    return undefined;
+  }
+  return value.threadId.trim() || undefined;
+}
+
+function isThreadCreationRequest(method: string): boolean {
+  return method === "thread/start" || method === "thread/fork";
+}
+
 function defaultServerRequestResponse(
   request: Required<Pick<RpcRequest, "id" | "method">> & { params?: JsonValue },
 ): JsonValue {
@@ -555,6 +656,9 @@ function defaultServerRequestResponse(
       success: false,
     };
   }
+  if (request.method === "execCommandApproval" || request.method === "applyPatchApproval") {
+    return { decision: "denied" };
+  }
   if (
     request.method === "item/commandExecution/requestApproval" ||
     request.method === "item/fileChange/requestApproval"
@@ -570,6 +674,12 @@ function defaultServerRequestResponse(
       reason: "OpenClaw codex app-server bridge does not grant native approvals yet.",
     };
   }
+  if (request.method.includes("requestApproval")) {
+    return {
+      decision: "decline",
+      reason: "OpenClaw codex app-server bridge does not grant unknown native approvals.",
+    };
+  }
   if (request.method === "item/tool/requestUserInput") {
     return {
       answers: {},

extensions/codex/src/app-server/compact.ts

@@ -7,145 +7,396 @@ import {
   type EmbeddedAgentCompactResult,
 } from "openclaw/plugin-sdk/agent-harness-runtime";
 import {
-  defaultLeasedCodexAppServerClientFactory,
-  type CodexAppServerClientFactory,
-} from "./client-factory.js";
+  CODEX_APP_SERVER_UNSUBSCRIBE_TIMEOUT_MS,
+  isCodexAppServerUnsafeSubscriptionError,
+  settleCodexAppServerClientLease,
+} from "./attempt-client-cleanup.js";
+import { readCodexNotificationItem } from "./attempt-notifications.js";
+import { resolveCodexTurnTerminalIdleTimeoutMs } from "./attempt-timeouts.js";
+import { CodexAppServerRpcError } from "./client.js";
 import { resolveCodexAppServerRuntimeOptions } from "./config.js";
-import type { JsonObject } from "./protocol.js";
+import { isJsonObject, type JsonObject, type JsonValue } from "./protocol.js";
 import { resolveCodexNativeExecutionBlock } from "./sandbox-guard.js";
 import {
   CODEX_APP_SERVER_BINDING_GUARDED_REQUEST_TIMEOUT_MS,
-  readCodexAppServerBinding,
-  withCodexAppServerBindingLock,
-  writeCodexAppServerBinding,
+  sessionBindingIdentity,
+  type CodexAppServerBindingIdentity,
+  type CodexAppServerBindingStore,
   type CodexAppServerThreadBinding,
 } from "./session-binding.js";
-import { releaseLeasedSharedCodexAppServerClient } from "./shared-client.js";
+import {
+  leaseSharedCodexAppServerClient,
+  type CodexAppServerClientLease,
+  type CodexAppServerClientLeaseFactory,
+  type CodexAppServerClientOptions,
+} from "./shared-client.js";
+import { resumeCodexAppServerThread } from "./thread-resume.js";
+import { withTimeout } from "./timeout.js";
+import {
+  getCodexAppServerTurnRouter,
+  isCodexTerminalTurnNotification,
+  type CodexNativeTurnCompletionWatch,
+  type CodexThreadRouteReservation,
+} from "./turn-router.js";
 
-const warnedIgnoredCompactionOverrides = new Set<string>();
 type CodexAppServerCompactOptions = {
+  bindingStore: CodexAppServerBindingStore;
   pluginConfig?: unknown;
-  clientFactory?: CodexAppServerClientFactory;
+  clientLeaseFactory?: CodexAppServerClientLeaseFactory;
   allowNonManualNativeRequest?: boolean;
 };
 
+class CodexNativeTurnBindingChangedError extends Error {}
+
+type CodexNativeTurnRequest = {
+  bindingStore: CodexAppServerBindingStore;
+  bindingIdentity: CodexAppServerBindingIdentity;
+  expectedBinding: CodexAppServerThreadBinding;
+  pluginConfig?: unknown;
+  authProfileId?: string;
+  agentDir?: string;
+  config?: CodexAppServerClientOptions["config"];
+  abortSignal?: AbortSignal;
+  clientLeaseFactory?: CodexAppServerClientLeaseFactory;
+};
+
+export type CodexNativeTurnKind = "compact" | "review";
+
+/** Starts one native Codex turn and retains its app-server owner through completion. */
+export async function requestCodexNativeTurnForBinding(
+  params: CodexNativeTurnRequest,
+  kind: CodexNativeTurnKind,
+): Promise<void> {
+  const isCompaction = kind === "compact";
+  const label = isCompaction ? "compaction" : "review";
+  const appServer = resolveCodexAppServerRuntimeOptions({ pluginConfig: params.pluginConfig });
+  const requestTimeoutMs = Math.min(
+    appServer.requestTimeoutMs,
+    CODEX_APP_SERVER_BINDING_GUARDED_REQUEST_TIMEOUT_MS,
+  );
+  await params.bindingStore.withLease(params.bindingIdentity, async () => {
+    const currentBinding = await params.bindingStore.read(params.bindingIdentity);
+    if (!currentBinding || !isSameNativeTurnBinding(currentBinding, params.expectedBinding)) {
+      throw new CodexNativeTurnBindingChangedError(
+        `Codex thread binding changed before native ${label}`,
+      );
+    }
+    const clientLease = await (params.clientLeaseFactory ?? leaseSharedCodexAppServerClient)({
+      startOptions: appServer.start,
+      authProfileId: params.authProfileId ?? currentBinding.authProfileId,
+      agentDir: params.agentDir,
+      config: params.config,
+      abandonSignal: params.abortSignal,
+      timeoutMs: appServer.requestTimeoutMs,
+    });
+    const client = clientLease.client;
+    let subscribedThreadId: string | undefined;
+    let abandonClient = false;
+    let lifecycleTransferred = false;
+    let awaitingNativeTurnStart = false;
+    const terminalTurnsBeforeWatch = new Set<string>();
+    let route: CodexThreadRouteReservation | undefined;
+    let completionWatch: CodexNativeTurnCompletionWatch | undefined;
+    let observedContextCompaction = false;
+    let bindingInvalidated = false;
+    let resolveNativeTurnStarted!: () => void;
+    const nativeTurnStarted = new Promise<void>((resolve) => {
+      resolveNativeTurnStarted = resolve;
+    });
+    try {
+      const router = getCodexAppServerTurnRouter(client);
+      route = router.reserveThread({
+        threadId: currentBinding.threadId,
+        onNotificationReceived: (notification, scope) => {
+          const contextCompactionStarted =
+            isCompaction &&
+            Boolean(scope.turnId) &&
+            notification.method === "item/started" &&
+            readCodexNotificationItem(notification.params)?.type === "contextCompaction";
+          if (contextCompactionStarted) {
+            observedContextCompaction = true;
+          }
+          if (!awaitingNativeTurnStart || !scope.turnId) {
+            return;
+          }
+          if (isCodexTerminalTurnNotification(notification)) {
+            terminalTurnsBeforeWatch.add(scope.turnId);
+          }
+          if (contextCompactionStarted) {
+            completionWatch ??= router.watchNativeTurnCompletion({
+              threadId: currentBinding.threadId,
+              turnId: scope.turnId,
+              timeoutMs: resolveCodexTurnTerminalIdleTimeoutMs(undefined),
+            });
+            resolveNativeTurnStarted();
+          }
+        },
+        onNotification: () => undefined,
+      });
+      throwIfCodexNativeTurnAborted(params.abortSignal, kind);
+      let resumed;
+      try {
+        subscribedThreadId = currentBinding.threadId;
+        resumed = await resumeCodexAppServerThread({
+          client,
+          abandonClient: clientLease.abandon,
+          request: {
+            threadId: currentBinding.threadId,
+            excludeTurns: true,
+            persistExtendedHistory: true,
+          },
+          timeoutMs: requestTimeoutMs,
+          signal: params.abortSignal,
+        });
+      } catch (error) {
+        abandonClient = isCodexAppServerUnsafeSubscriptionError(error);
+        throw error;
+      }
+      const invalidateNativeContextBinding = async () => {
+        if (bindingInvalidated) {
+          return;
+        }
+        const invalidated = await params.bindingStore.mutate(params.bindingIdentity, {
+          kind: "invalidate-native-context",
+          threadId: currentBinding.threadId,
+          ...(isCompaction ? { invalidateContextEngineProjection: true as const } : {}),
+        });
+        if (!invalidated) {
+          throw new CodexNativeTurnBindingChangedError(
+            `Codex thread binding changed before native ${label}`,
+          );
+        }
+        bindingInvalidated = true;
+      };
+      if (isCompaction && observedContextCompaction) {
+        await invalidateNativeContextBinding();
+      }
+      if (resumed.thread.status?.type === "active") {
+        throw new Error(
+          `Codex thread already has an active turn; retry ${label} after it finishes`,
+        );
+      }
+      throwIfCodexNativeTurnAborted(params.abortSignal, kind);
+      await invalidateNativeContextBinding();
+      awaitingNativeTurnStart = true;
+      let requestResult: JsonValue | undefined;
+      try {
+        requestResult = await client.request(
+          isCompaction ? "thread/compact/start" : "review/start",
+          isCompaction
+            ? { threadId: currentBinding.threadId }
+            : { threadId: currentBinding.threadId, target: { type: "uncommittedChanges" } },
+          { timeoutMs: requestTimeoutMs },
+        );
+      } catch (error) {
+        const requestRejected = error instanceof CodexAppServerRpcError;
+        if (requestRejected) {
+          // A structured rejection proves this request did not start a native
+          // turn. Preserve only compaction already observed on the same thread.
+          completionWatch?.cancel();
+          completionWatch = undefined;
+          if (!isCompaction || !observedContextCompaction) {
+            const restored = await params.bindingStore.mutate(params.bindingIdentity, {
+              kind: "set",
+              binding: currentBinding,
+            });
+            if (!restored) {
+              throw new Error(`Codex thread binding changed after native ${label} was rejected`, {
+                cause: error,
+              });
+            }
+          }
+          throw error;
+        }
+        if (completionWatch) {
+          embeddedAgentLog.debug(`codex app-server ${kind} request failed after startup`, {
+            threadId: currentBinding.threadId,
+            error,
+          });
+        } else {
+          abandonClient = true;
+          throw error;
+        }
+      }
+      if (!isCompaction) {
+        try {
+          const review = assertCodexReviewStartResponse(requestResult);
+          if (review.reviewThreadId !== currentBinding.threadId) {
+            throw new Error(
+              `Codex review/start returned ${review.reviewThreadId} for inline review on ${currentBinding.threadId}`,
+            );
+          }
+          completionWatch = terminalTurnsBeforeWatch.has(review.turnId)
+            ? { completion: Promise.resolve(true), cancel: () => undefined }
+            : router.watchNativeTurnCompletion({
+                threadId: currentBinding.threadId,
+                turnId: review.turnId,
+                timeoutMs: resolveCodexTurnTerminalIdleTimeoutMs(undefined),
+              });
+        } catch (error) {
+          abandonClient = true;
+          throw error;
+        }
+      } else if (!completionWatch) {
+        try {
+          await waitForCodexNativeTurnStart({
+            started: nativeTurnStarted,
+            routeSignal: route.signal,
+            timeoutMs: requestTimeoutMs,
+            threadId: currentBinding.threadId,
+            kind,
+          });
+        } catch (error) {
+          // Codex accepted Op::Compact, so missing startup confirmation is
+          // ambiguous. Keep facts invalidated and retire this connection.
+          abandonClient = true;
+          throw error;
+        }
+      }
+      awaitingNativeTurnStart = false;
+      route.release();
+      route = undefined;
+      const transferredWatch = completionWatch;
+      if (!transferredWatch) {
+        abandonClient = true;
+        throw new Error(
+          `codex app-server ${kind} turn started without a turn id for thread ${currentBinding.threadId}`,
+        );
+      }
+      completionWatch = undefined;
+      lifecycleTransferred = true;
+      monitorCodexNativeTurn({
+        completionWatch: transferredWatch,
+        clientLease,
+        subscribedThreadId,
+        threadId: currentBinding.threadId,
+        kind,
+      });
+    } finally {
+      if (!lifecycleTransferred) {
+        completionWatch?.cancel();
+        route?.release();
+        await settleCodexAppServerClientLease(clientLease, {
+          threadId: subscribedThreadId,
+          timeoutMs: CODEX_APP_SERVER_UNSUBSCRIBE_TIMEOUT_MS,
+          abandon: abandonClient,
+        });
+      }
+    }
+  });
+}
+
+function assertCodexReviewStartResponse(value: JsonValue | undefined): {
+  turnId: string;
+  reviewThreadId: string;
+} {
+  if (
+    !isJsonObject(value) ||
+    !isJsonObject(value.turn) ||
+    typeof value.turn.id !== "string" ||
+    !value.turn.id.trim() ||
+    typeof value.reviewThreadId !== "string" ||
+    !value.reviewThreadId.trim()
+  ) {
+    throw new Error("invalid Codex review/start response");
+  }
+  return { turnId: value.turn.id, reviewThreadId: value.reviewThreadId };
+}
+
+function monitorCodexNativeTurn(params: {
+  completionWatch: CodexNativeTurnCompletionWatch;
+  clientLease: CodexAppServerClientLease;
+  subscribedThreadId?: string;
+  threadId: string;
+  kind: CodexNativeTurnKind;
+}): void {
+  void (async () => {
+    const completed = await params.completionWatch.completion;
+    await settleCodexAppServerClientLease(params.clientLease, {
+      threadId: params.subscribedThreadId,
+      timeoutMs: CODEX_APP_SERVER_UNSUBSCRIBE_TIMEOUT_MS,
+      abandon: !completed,
+    });
+    if (!completed) {
+      embeddedAgentLog.warn(`codex app-server ${params.kind} turn lost terminal confirmation`, {
+        threadId: params.threadId,
+      });
+    }
+  })().catch(async (error: unknown) => {
+    await params.clientLease.abandon().catch(() => undefined);
+    embeddedAgentLog.warn(`codex app-server ${params.kind} turn cleanup failed`, {
+      threadId: params.threadId,
+      error,
+    });
+  });
+}
+
+function throwIfCodexNativeTurnAborted(
+  signal: AbortSignal | undefined,
+  kind: CodexNativeTurnKind,
+): void {
+  if (!signal?.aborted) {
+    return;
+  }
+  if (signal.reason instanceof Error) {
+    throw signal.reason;
+  }
+  throw new Error(`codex app-server ${kind} aborted before native turn startup`, {
+    cause: signal.reason,
+  });
+}
+
+async function waitForCodexNativeTurnStart(params: {
+  started: Promise<void>;
+  routeSignal: AbortSignal;
+  timeoutMs: number;
+  threadId: string;
+  kind: CodexNativeTurnKind;
+}): Promise<void> {
+  const signal = params.routeSignal;
+  let removeAbort: (() => void) | undefined;
+  const aborted = new Promise<never>((_resolve, reject) => {
+    const onAbort = () => reject(asNativeTurnAbortError(signal));
+    signal.addEventListener("abort", onAbort, { once: true });
+    removeAbort = () => signal.removeEventListener("abort", onAbort);
+    if (signal.aborted) {
+      onAbort();
+    }
+  });
+  try {
+    await withTimeout(
+      Promise.race([params.started, aborted]),
+      params.timeoutMs,
+      `codex app-server ${params.kind} turn did not start for thread ${params.threadId}`,
+    );
+  } finally {
+    removeAbort?.();
+  }
+}
+
+function asNativeTurnAbortError(signal: AbortSignal): Error {
+  return signal.reason instanceof Error
+    ? signal.reason
+    : new Error("codex app-server native turn startup aborted", { cause: signal.reason });
+}
+
 /**
  * Starts native Codex compaction for a manually requested bound session, or
  * reports why Codex-owned automatic compaction should handle the trigger.
  */
 export async function maybeCompactCodexAppServerSession(
   params: CompactEmbeddedAgentSessionParams,
-  options: CodexAppServerCompactOptions = {},
+  options: CodexAppServerCompactOptions,
 ): Promise<EmbeddedAgentCompactResult | undefined> {
-  warnIfIgnoringOpenClawCompactionOverrides(params);
   // Codex owns automatic context-pressure compaction for Codex runtime sessions.
   // This entry point starts native Codex compaction for the bound thread and
   // returns immediately; Codex applies the compaction inside its app-server.
   return compactCodexNativeThread(params, options);
 }
 
-function warnIfIgnoringOpenClawCompactionOverrides(
-  params: CompactEmbeddedAgentSessionParams,
-): void {
-  const ignoredConfig = readIgnoredCompactionOverridePaths(params);
-  if (ignoredConfig.length === 0) {
-    return;
-  }
-  const warningKey = ignoredConfig.join("\0");
-  if (warnedIgnoredCompactionOverrides.has(warningKey)) {
-    return;
-  }
-  warnedIgnoredCompactionOverrides.add(warningKey);
-  embeddedAgentLog.warn(
-    "ignoring OpenClaw compaction overrides for Codex app-server compaction; Codex uses native server-side compaction",
-    {
-      sessionId: params.sessionId,
-      sessionKey: params.sessionKey,
-      ignoredConfig,
-    },
-  );
-}
-
-function readIgnoredCompactionOverridePaths(params: CompactEmbeddedAgentSessionParams): string[] {
-  const ignored = new Set<string>();
-  for (const entry of readCompactionOverrideEntries(params)) {
-    const localProvider =
-      typeof entry.record.provider === "string" ? entry.record.provider.trim() : "";
-    const inheritedProvider =
-      !localProvider && typeof entry.inheritedRecord?.provider === "string"
-        ? entry.inheritedRecord.provider.trim()
-        : "";
-    const providerPath = localProvider
-      ? `${entry.path}.compaction.provider`
-      : inheritedProvider && entry.inheritedPath
-        ? `${entry.inheritedPath}.compaction.provider`
-        : undefined;
-    if (typeof entry.record.model === "string" && entry.record.model.trim()) {
-      ignored.add(`${entry.path}.compaction.model`);
-    }
-    if (providerPath) {
-      ignored.add(providerPath);
-    }
-  }
-  return [...ignored];
-}
-
-function readCompactionOverrideEntries(params: CompactEmbeddedAgentSessionParams): Array<{
-  path: string;
-  record: Record<string, unknown>;
-  inheritedRecord?: Record<string, unknown>;
-  inheritedPath?: string;
-}> {
-  const entries: Array<{
-    path: string;
-    record: Record<string, unknown>;
-    inheritedRecord?: Record<string, unknown>;
-    inheritedPath?: string;
-  }> = [];
-  const defaultCompaction = readRecord(readRecord(params.config?.agents)?.defaults)?.compaction;
-  const defaultRecord = readRecord(defaultCompaction);
-  if (defaultRecord) {
-    entries.push({ path: "agents.defaults", record: defaultRecord });
-  }
-  const agentId = readAgentIdFromSessionKey(params.sessionKey ?? params.sandboxSessionKey);
-  if (!agentId) {
-    return entries;
-  }
-  const agents = Array.isArray(params.config?.agents?.list) ? params.config.agents.list : [];
-  const activeAgent = agents.find((agent) => {
-    const id = typeof agent?.id === "string" ? agent.id.trim().toLowerCase() : "";
-    return id === agentId;
-  });
-  const agentCompaction = readRecord(activeAgent)?.compaction;
-  const agentRecord = readRecord(agentCompaction);
-  if (agentRecord) {
-    entries.push({
-      path: `agents.list.${agentId}`,
-      record: agentRecord,
-      inheritedRecord: defaultRecord,
-      inheritedPath: "agents.defaults",
-    });
-  }
-  return entries;
-}
-
-function readAgentIdFromSessionKey(sessionKey: string | undefined): string | undefined {
-  const parts = sessionKey?.trim().toLowerCase().split(":").filter(Boolean) ?? [];
-  if (parts.length < 3 || parts[0] !== "agent") {
-    return undefined;
-  }
-  return parts[1]?.trim() || undefined;
-}
-
-function readRecord(value: unknown): Record<string, unknown> | undefined {
-  return value && typeof value === "object" && !Array.isArray(value)
-    ? (value as Record<string, unknown>)
-    : undefined;
-}
-
 async function compactCodexNativeThread(
   params: CompactEmbeddedAgentSessionParams,
-  options: CodexAppServerCompactOptions = {},
+  options: CodexAppServerCompactOptions,
 ): Promise<EmbeddedAgentCompactResult | undefined> {
   if (params.trigger !== "manual" && !options.allowNonManualNativeRequest) {
     embeddedAgentLog.info("skipping codex app-server compaction for non-manual trigger", {
@@ -172,6 +423,7 @@ async function compactCodexNativeThread(
   }
   const nativeExecutionBlock = resolveCodexNativeExecutionBlock({
     config: params.config,
+    agentId: params.agentId,
     sessionKey: params.sandboxSessionKey ?? params.sessionKey,
     sessionId: params.sessionId,
     surface: "native compaction",
@@ -179,17 +431,20 @@ async function compactCodexNativeThread(
   if (nativeExecutionBlock) {
     return { ok: false, compacted: false, reason: nativeExecutionBlock };
   }
-  const appServer = resolveCodexAppServerRuntimeOptions({ pluginConfig: options.pluginConfig });
-  const initialBinding = await readCodexAppServerBinding(params.sessionFile, {
+  const bindingIdentity: CodexAppServerBindingIdentity = sessionBindingIdentity({
+    sessionId: params.sessionId,
+    sessionKey: params.sessionKey,
+    agentId: params.agentId,
     config: params.config,
   });
+  const initialBinding = await options.bindingStore.read(bindingIdentity);
   if (!initialBinding?.threadId) {
     return failedCodexThreadBindingCompactionResult(params, {
       reason: "no codex app-server thread binding",
       recovery: "missing_thread_binding",
     });
   }
-  let binding = initialBinding;
+  const binding = initialBinding;
   const requestedAuthProfileId = params.authProfileId?.trim() || undefined;
   if (
     requestedAuthProfileId &&
@@ -200,85 +455,42 @@ async function compactCodexNativeThread(
     // with another profile risks operating on a different Codex account.
     return { ok: false, compacted: false, reason: "auth profile mismatch for session binding" };
   }
-  const shouldReleaseDefaultLease = !options.clientFactory;
-  const clientFactory = options.clientFactory ?? defaultLeasedCodexAppServerClientFactory;
-  const client = await clientFactory(
-    appServer.start,
-    requestedAuthProfileId ?? binding.authProfileId,
-    params.agentDir,
-    params.config,
-  );
+  if (options.allowNonManualNativeRequest && params.abortSignal?.aborted) {
+    const currentBinding = await options.bindingStore.read(bindingIdentity);
+    return skippedCodexNativeCompactionResult(params, {
+      reason: "codex app-server compaction aborted before native compaction",
+      code: "aborted_before_native_compaction",
+      expectedThreadId: binding.threadId,
+      currentThreadId: currentBinding?.threadId,
+    });
+  }
   try {
-    if (options.allowNonManualNativeRequest) {
-      const guardedResult = await withCodexAppServerBindingLock(params.sessionFile, async () => {
-        const currentBinding = await readCodexAppServerBinding(params.sessionFile, {
-          config: params.config,
-        });
-        if (params.abortSignal?.aborted) {
-          return {
-            started: false as const,
-            result: skippedCodexNativeCompactionResult(params, {
-              reason: "codex app-server compaction aborted before native compaction",
-              code: "aborted_before_native_compaction",
-              expectedThreadId: binding.threadId,
-              currentThreadId: currentBinding?.threadId,
-            }),
-          };
-        }
-        if (!currentBinding || !isSameNativeCompactionBinding(currentBinding, binding)) {
-          embeddedAgentLog.warn(
-            "skipping codex app-server compaction because the thread binding changed",
-            {
-              sessionId: params.sessionId,
-              sessionKey: params.sessionKey,
-              expectedThreadId: binding.threadId,
-              currentThreadId: currentBinding?.threadId,
-            },
-          );
-          return {
-            started: false as const,
-            result: skippedCodexNativeCompactionResult(params, {
-              reason: "codex app-server binding changed before native compaction",
-              code: "binding_changed_before_native_compaction",
-              expectedThreadId: binding.threadId,
-              currentThreadId: currentBinding?.threadId,
-            }),
-          };
-        }
-        binding = currentBinding;
-        await clearContextEngineProjectionBeforeNativeCompaction({
-          sessionId: params.sessionId,
-          sessionFile: params.sessionFile,
-          binding,
-          config: params.config,
-        });
-        await client.request(
-          "thread/compact/start",
-          {
-            threadId: binding.threadId,
-          },
-          {
-            timeoutMs: Math.min(
-              appServer.requestTimeoutMs,
-              CODEX_APP_SERVER_BINDING_GUARDED_REQUEST_TIMEOUT_MS,
-            ),
-          },
-        );
-        return { started: true as const };
-      });
-      if (!guardedResult.started) {
-        return guardedResult.result;
-      }
-    } else {
-      await client.request("thread/compact/start", {
-        threadId: binding.threadId,
-      });
-    }
+    await requestCodexNativeTurnForBinding(
+      {
+        bindingIdentity,
+        bindingStore: options.bindingStore,
+        expectedBinding: binding,
+        pluginConfig: options.pluginConfig,
+        authProfileId: requestedAuthProfileId,
+        agentDir: params.agentDir,
+        config: params.config,
+        abortSignal: params.abortSignal,
+        clientLeaseFactory: options.clientLeaseFactory,
+      },
+      "compact",
+    );
     embeddedAgentLog.info("started codex app-server compaction", {
       sessionId: params.sessionId,
       threadId: binding.threadId,
     });
   } catch (error) {
+    if (
+      options.allowNonManualNativeRequest &&
+      error instanceof CodexNativeTurnBindingChangedError
+    ) {
+      const latestBinding = await options.bindingStore.read(bindingIdentity);
+      return skippedBindingChangeResult(params, binding.threadId, latestBinding?.threadId);
+    }
     if (isCodexThreadNotFoundError(error)) {
       return failedCodexThreadBindingCompactionResult(params, {
         threadId: binding.threadId,
@@ -297,10 +509,6 @@ async function compactCodexNativeThread(
       compacted: false,
       reason: formatCompactionError(error),
     };
-  } finally {
-    if (shouldReleaseDefaultLease) {
-      releaseLeasedSharedCodexAppServerClient(client);
-    }
   }
   const resultDetails: JsonObject = {
     backend: "codex-app-server",
@@ -326,6 +534,25 @@ async function compactCodexNativeThread(
   };
 }
 
+function skippedBindingChangeResult(
+  params: CompactEmbeddedAgentSessionParams,
+  expectedThreadId: string,
+  currentThreadId: string | undefined,
+): EmbeddedAgentCompactResult {
+  embeddedAgentLog.warn("skipping codex app-server compaction because the thread binding changed", {
+    sessionId: params.sessionId,
+    sessionKey: params.sessionKey,
+    expectedThreadId,
+    currentThreadId,
+  });
+  return skippedCodexNativeCompactionResult(params, {
+    reason: "codex app-server binding changed before native compaction",
+    code: "binding_changed_before_native_compaction",
+    expectedThreadId,
+    currentThreadId,
+  });
+}
+
 function skippedCodexNativeCompactionResult(
   params: CompactEmbeddedAgentSessionParams,
   skipped: {
@@ -382,39 +609,7 @@ function failedCodexThreadBindingCompactionResult(
   };
 }
 
-async function clearContextEngineProjectionBeforeNativeCompaction(params: {
-  sessionId: string;
-  sessionFile: string;
-  binding: CodexAppServerThreadBinding;
-  config: CompactEmbeddedAgentSessionParams["config"];
-}): Promise<void> {
-  const contextEngineBinding = params.binding.contextEngine;
-  if (!contextEngineBinding?.projection) {
-    return;
-  }
-  // Native Codex compaction mutates the thread history outside the projection
-  // guard. Clear only the projection marker so the next turn reprojects context.
-  await writeCodexAppServerBinding(
-    params.sessionFile,
-    {
-      ...params.binding,
-      contextEngine: {
-        ...contextEngineBinding,
-        projection: undefined,
-      },
-      createdAt: params.binding.createdAt,
-    },
-    { config: params.config },
-  );
-  embeddedAgentLog.info("cleared codex context-engine projection before native compaction", {
-    sessionId: params.sessionId,
-    threadId: params.binding.threadId,
-    previousEpoch: contextEngineBinding.projection.epoch,
-    previousFingerprint: contextEngineBinding.projection.fingerprint,
-  });
-}
-
-function isSameNativeCompactionBinding(
+function isSameNativeTurnBinding(
   current: CodexAppServerThreadBinding,
   expected: CodexAppServerThreadBinding,
 ): boolean {

extensions/codex/src/app-server/config.test.ts

@@ -1,5 +1,7 @@
 // Codex tests cover config plugin behavior.
 import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
 import { MAX_TIMER_TIMEOUT_MS } from "openclaw/plugin-sdk/number-runtime";
 import { describe, expect, it, vi } from "vitest";
 import {
@@ -306,7 +308,6 @@ describe("Codex app-server config", () => {
     const switchedLocalModel = resolveCodexModelBackedReviewerPolicyContext({
       model: "lmstudio/local-model",
       bindingModel: "gpt-5.5",
-      nativeAuthProfile: true,
     });
     expect(switchedLocalModel).toEqual({
       modelProvider: "lmstudio",
@@ -493,6 +494,39 @@ describe("Codex app-server config", () => {
     });
   });
 
+  it("reloads Codex config.toml policy when Codex can reload it", async () => {
+    const agentDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-config-"));
+    const codexHome = path.join(agentDir, "codex-home");
+    const configPath = path.join(codexHome, "config.toml");
+    await fs.mkdir(codexHome);
+    try {
+      await fs.writeFile(configPath, 'openai_base_url = "http://localhost:8080/v1"\n');
+      const context = { modelProvider: "openai", model: "gpt-5.5", agentDir };
+      expect(canUseCodexModelBackedApprovalsReviewerForModel(context)).toBe(false);
+
+      await fs.writeFile(configPath, 'openai_base_url = "https://api.openai.com/v1"\n');
+      expect(canUseCodexModelBackedApprovalsReviewerForModel(context)).toBe(true);
+    } finally {
+      await fs.rm(agentDir, { recursive: true, force: true });
+    }
+  });
+
+  it("observes a Codex config.toml created after the first policy check", async () => {
+    const agentDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-config-"));
+    const codexHome = path.join(agentDir, "codex-home");
+    const configPath = path.join(codexHome, "config.toml");
+    await fs.mkdir(codexHome);
+    try {
+      const context = { modelProvider: "openai", model: "gpt-5.5", agentDir };
+      expect(canUseCodexModelBackedApprovalsReviewerForModel(context)).toBe(true);
+
+      await fs.writeFile(configPath, 'openai_base_url = "http://localhost:8080/v1"\n');
+      expect(canUseCodexModelBackedApprovalsReviewerForModel(context)).toBe(false);
+    } finally {
+      await fs.rm(agentDir, { recursive: true, force: true });
+    }
+  });
+
   it("forces prompting when explicit no-prompt config cannot use model-backed review", () => {
     const runtime = resolveRuntimeForTest({
       pluginConfig: {
@@ -690,8 +724,8 @@ allowed_sandbox_modes = ["read-only", "workspace-write"]
       env: {},
       modelProvider: "openai",
       requirementsPath: "/custom/codex/requirements.toml",
-      readRequirementsFile: (path) => {
-        readPaths.push(path);
+      readRequirementsFile: (requirementsPath) => {
+        readPaths.push(requirementsPath);
         return 'allowed_sandbox_modes = ["read-only", "workspace-write"]\n';
       },
     });
@@ -711,8 +745,8 @@ allowed_sandbox_modes = ["read-only", "workspace-write"]
       env: { ProgramData: "D:\\ManagedData" },
       modelProvider: "openai",
       platform: "win32",
-      readRequirementsFile: (path) => {
-        readPaths.push(path);
+      readRequirementsFile: (requirementsPath) => {
+        readPaths.push(requirementsPath);
         return 'allowed_sandbox_modes = ["read-only", "workspace-write"]\n';
       },
     });

extensions/codex/src/app-server/config.ts

@@ -150,6 +150,11 @@ export type CodexAppServerRuntimeOptions = {
   serviceTier?: CodexServiceTier;
 };
 
+export type CodexAppServerRuntimeResolution = {
+  appServer: CodexAppServerRuntimeOptions;
+  modelBackedReviewerAvailable: boolean;
+};
+
 export type CodexModelBackedReviewerContext = {
   modelProvider?: string;
   model?: string;
@@ -405,25 +410,34 @@ export function resolveCodexPluginsPolicy(pluginConfig?: unknown): ResolvedCodex
   };
 }
 
+type CodexAppServerRuntimeParams = {
+  pluginConfig?: unknown;
+  execMode?: OpenClawExecMode;
+  execPolicy?: OpenClawExecPolicyForCodexAppServer;
+  modelProvider?: string;
+  model?: string;
+  config?: ProviderAuthAliasConfig;
+  env?: NodeJS.ProcessEnv;
+  agentDir?: string;
+  codexConfigToml?: string | null;
+  requirementsToml?: string | null;
+  requirementsPath?: string;
+  readRequirementsFile?: (path: string) => string | undefined;
+  platform?: NodeJS.Platform;
+  hostName?: string;
+  openClawSandboxActive?: boolean;
+};
+
 export function resolveCodexAppServerRuntimeOptions(
-  params: {
-    pluginConfig?: unknown;
-    execMode?: OpenClawExecMode;
-    execPolicy?: OpenClawExecPolicyForCodexAppServer;
-    modelProvider?: string;
-    model?: string;
-    config?: ProviderAuthAliasConfig;
-    env?: NodeJS.ProcessEnv;
-    agentDir?: string;
-    codexConfigToml?: string | null;
-    requirementsToml?: string | null;
-    requirementsPath?: string;
-    readRequirementsFile?: (path: string) => string | undefined;
-    platform?: NodeJS.Platform;
-    hostName?: string;
-    openClawSandboxActive?: boolean;
-  } = {},
+  params: CodexAppServerRuntimeParams = {},
 ): CodexAppServerRuntimeOptions {
+  return resolveCodexAppServerRuntime(params).appServer;
+}
+
+/** Resolves runtime options and the model-policy fact computed with them. */
+export function resolveCodexAppServerRuntime(
+  params: CodexAppServerRuntimeParams = {},
+): CodexAppServerRuntimeResolution {
   const env = params.env ?? process.env;
   const config = readCodexPluginConfig(params.pluginConfig).appServer ?? {};
   const transport = resolveTransport(config.transport);
@@ -547,43 +561,46 @@ export function resolveCodexAppServerRuntimeOptions(
         : "implicit";
 
   return {
-    start: {
-      transport,
-      command,
-      commandSource,
-      args: args.length > 0 ? args : ["app-server", "--listen", "stdio://"],
-      ...(url ? { url } : {}),
-      ...(authToken ? { authToken } : {}),
-      headers,
-      ...(transport === "stdio" && clearEnv.length > 0 ? { clearEnv } : {}),
+    modelBackedReviewerAvailable: canUseModelBackedReviewer,
+    appServer: {
+      start: {
+        transport,
+        command,
+        commandSource,
+        args: args.length > 0 ? args : ["app-server", "--listen", "stdio://"],
+        ...(url ? { url } : {}),
+        ...(authToken ? { authToken } : {}),
+        headers,
+        ...(transport === "stdio" && clearEnv.length > 0 ? { clearEnv } : {}),
+      },
+      codeModeOnly: config.codeModeOnly === true,
+      requestTimeoutMs: normalizePositiveNumber(config.requestTimeoutMs, 60_000),
+      turnCompletionIdleTimeoutMs: normalizePositiveNumber(
+        config.turnCompletionIdleTimeoutMs,
+        60_000,
+      ),
+      ...(config.postToolRawAssistantCompletionIdleTimeoutMs !== undefined
+        ? {
+            postToolRawAssistantCompletionIdleTimeoutMs: normalizePositiveNumber(
+              config.postToolRawAssistantCompletionIdleTimeoutMs,
+              60_000,
+            ),
+          }
+        : {}),
+      approvalPolicy: forcedPolicy?.approvalPolicy ?? approvalPolicy,
+      approvalPolicySource,
+      sandbox:
+        forcedPolicy?.sandbox ??
+        configuredSandbox ??
+        defaultPolicy?.sandbox ??
+        (policyMode === "guardian" ? "workspace-write" : "danger-full-access"),
+      approvalsReviewer:
+        forcedPolicy?.approvalsReviewer ??
+        explicitApprovalsReviewer ??
+        defaultPolicy?.approvalsReviewer ??
+        (policyMode === "guardian" ? "auto_review" : "user"),
+      ...(serviceTier ? { serviceTier } : {}),
     },
-    codeModeOnly: config.codeModeOnly === true,
-    requestTimeoutMs: normalizePositiveNumber(config.requestTimeoutMs, 60_000),
-    turnCompletionIdleTimeoutMs: normalizePositiveNumber(
-      config.turnCompletionIdleTimeoutMs,
-      60_000,
-    ),
-    ...(config.postToolRawAssistantCompletionIdleTimeoutMs !== undefined
-      ? {
-          postToolRawAssistantCompletionIdleTimeoutMs: normalizePositiveNumber(
-            config.postToolRawAssistantCompletionIdleTimeoutMs,
-            60_000,
-          ),
-        }
-      : {}),
-    approvalPolicy: forcedPolicy?.approvalPolicy ?? approvalPolicy,
-    approvalPolicySource,
-    sandbox:
-      forcedPolicy?.sandbox ??
-      configuredSandbox ??
-      defaultPolicy?.sandbox ??
-      (policyMode === "guardian" ? "workspace-write" : "danger-full-access"),
-    approvalsReviewer:
-      forcedPolicy?.approvalsReviewer ??
-      explicitApprovalsReviewer ??
-      defaultPolicy?.approvalsReviewer ??
-      (policyMode === "guardian" ? "auto_review" : "user"),
-    ...(serviceTier ? { serviceTier } : {}),
   };
 }
 
@@ -655,7 +672,6 @@ export function resolveCodexModelBackedReviewerPolicyContext(params: {
   model?: string;
   bindingModelProvider?: string;
   bindingModel?: string;
-  nativeAuthProfile?: boolean;
 }): CodexModelBackedReviewerContext {
   const provider = params.provider?.trim();
   if (provider && provider.toLowerCase() !== "codex") {
@@ -687,7 +703,7 @@ export function resolveCodexModelBackedReviewerPolicyContext(params: {
     };
   }
   return {
-    modelProvider: params.nativeAuthProfile === true ? "openai" : undefined,
+    modelProvider: undefined,
     model: params.model ?? params.bindingModel,
   };
 }
@@ -754,6 +770,7 @@ export function codexAppServerStartOptionsKey(
   options: CodexAppServerStartOptions,
   params: {
     authProfileId?: string;
+    authAccountCacheKey?: string;
     agentDir?: string;
     fallbackApiKeyCacheKey?: string;
   } = {},
@@ -773,6 +790,7 @@ export function codexAppServerStartOptionsKey(
       .map(([key, value]) => [key, hashSecretForKey(value, `env:${key}`)]),
     clearEnv: [...(options.clearEnv ?? [])].toSorted(),
     authProfileId: params.authProfileId ?? null,
+    authAccountCacheKey: params.authAccountCacheKey ?? null,
     agentDir: params.agentDir ?? null,
     fallbackApiKeyCacheKey: params.fallbackApiKeyCacheKey ?? null,
   });

extensions/codex/src/app-server/dynamic-tool-build.test.ts

@@ -9,15 +9,17 @@ import {
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import {
   addSandboxShellDynamicToolsIfAvailable,
-  buildDynamicTools,
   filterCodexDynamicToolsForAllowlist,
   hasWildcardCodexToolsAllow,
   includeForcedCodexDynamicToolAllow,
+  prepareDynamicToolCatalog,
   resetOpenClawCodingToolsFactoryForTests,
   resolveOpenClawCodingToolsSessionKeys,
+  resolveCodexMessageToolProvider,
   setOpenClawCodingToolsFactoryForTests,
   shouldEnableCodexAppServerNativeToolSurface,
   shouldForceMessageTool,
+  type OpenClawCodingToolsFactory,
 } from "./dynamic-tool-build.js";
 import {
   filterCodexDynamicTools,
@@ -99,13 +101,13 @@ function createRuntimeDynamicTool(name: string): RuntimeDynamicToolForTest {
 async function buildDynamicToolsForTest(
   params: EmbeddedRunAttemptParams,
   workspaceDir: string,
-  options: Partial<Parameters<typeof buildDynamicTools>[0]> = {},
+  options: Partial<Parameters<typeof prepareDynamicToolCatalog>[0]> = {},
 ) {
   const sandboxSessionKey = params.sessionKey;
   if (!sandboxSessionKey) {
     throw new Error("createParams must provide a sessionKey for Codex dynamic tool tests.");
   }
-  return buildDynamicTools({
+  const catalog = await prepareDynamicToolCatalog({
     params,
     resolvedWorkspace: workspaceDir,
     effectiveWorkspace: workspaceDir,
@@ -118,6 +120,7 @@ async function buildDynamicToolsForTest(
     onYieldDetected: () => undefined,
     ...options,
   });
+  return catalog.tools;
 }
 
 describe("Codex app-server dynamic tool build", () => {
@@ -132,6 +135,15 @@ describe("Codex app-server dynamic tool build", () => {
     await fs.rm(tempDir, { recursive: true, force: true });
   });
 
+  it("uses the message tool channel before a differing ingress provider", () => {
+    expect(
+      resolveCodexMessageToolProvider({
+        messageChannel: "discord",
+        messageProvider: "discord-voice",
+      }),
+    ).toBe("discord");
+  });
+
   it("filters Codex-native dynamic tools from app-server tool exposure", () => {
     const tools = [
       "read",
@@ -159,6 +171,53 @@ describe("Codex app-server dynamic tool build", () => {
     ]);
   });
 
+  it("prepares runtime and durable tool views from one OpenClaw catalog", async () => {
+    const messageTool = createRuntimeDynamicTool("message");
+    const webSearchTool = createRuntimeDynamicTool("web_search");
+    const heartbeatTool = createRuntimeDynamicTool("heartbeat_respond");
+    const factory = vi.fn<OpenClawCodingToolsFactory>((options) => [
+      messageTool,
+      webSearchTool,
+      ...(options?.enableHeartbeatTool ? [heartbeatTool] : []),
+    ]);
+    setOpenClawCodingToolsFactoryForTests(factory);
+    const sessionFile = path.join(tempDir, "session.jsonl");
+    const workspaceDir = path.join(tempDir, "workspace");
+    const params = createParams(sessionFile, workspaceDir);
+    params.disableTools = false;
+    const runtimePlan = createCodexRuntimePlanFixture();
+    params.runtimePlan = {
+      ...runtimePlan,
+      tools: {
+        normalize: (tools: Array<{ name: string }>) =>
+          tools.filter((tool) => tool.name === "message"),
+        logDiagnostics: () => undefined,
+      },
+    } as unknown as NonNullable<EmbeddedRunAttemptParams["runtimePlan"]>;
+
+    const catalog = await prepareDynamicToolCatalog({
+      params,
+      resolvedWorkspace: workspaceDir,
+      effectiveWorkspace: workspaceDir,
+      sandboxSessionKey: params.sessionKey ?? "agent:main:session-1",
+      sandbox: { enabled: false, backendId: "docker" } as never,
+      nativeToolSurfaceEnabled: true,
+      runAbortController: new AbortController(),
+      sessionAgentId: "main",
+      pluginConfig: {},
+      onYieldDetected: () => undefined,
+    });
+
+    expect(factory).toHaveBeenCalledTimes(1);
+    expect(factory.mock.calls[0]?.[0]?.enableHeartbeatTool).toBe(true);
+    expect(catalog.tools.map((tool) => tool.name)).toEqual(["message"]);
+    expect(catalog.registeredTools.map((tool) => tool.name)).toEqual([
+      "message",
+      "web_search",
+      "heartbeat_respond",
+    ]);
+  });
+
   it("applies additional Codex dynamic tool excludes without exposing Codex-native tools", () => {
     const tools = ["read", "exec", "message", "custom_tool"].map((name) => ({ name }));
 
@@ -549,6 +608,28 @@ describe("Codex app-server dynamic tool build", () => {
     );
   });
 
+  it("passes native and routable channel targets into Codex dynamic tools", async () => {
+    const sessionFile = path.join(tempDir, "session.jsonl");
+    const workspaceDir = path.join(tempDir, "workspace");
+    const params = createParams(sessionFile, workspaceDir);
+    params.disableTools = false;
+    params.currentChannelId = "D123";
+    params.currentMessagingTarget = "user:U123";
+    params.runtimePlan = createCodexRuntimePlanFixture();
+    const factoryOptions: unknown[] = [];
+    setOpenClawCodingToolsFactoryForTests((options) => {
+      factoryOptions.push(options);
+      return [];
+    });
+
+    await buildDynamicToolsForTest(params, workspaceDir, { sandbox: null as never });
+
+    expect(factoryOptions[0]).toMatchObject({
+      currentChannelId: "D123",
+      currentMessagingTarget: "user:U123",
+    });
+  });
+
   it("passes runtime config into Codex exec dynamic tool construction", async () => {
     const sessionFile = path.join(tempDir, "session.jsonl");
     const workspaceDir = path.join(tempDir, "workspace");

extensions/codex/src/app-server/dynamic-tool-build.ts

@@ -38,6 +38,9 @@ type OpenClawCodingToolsOptions = NonNullable<
 export type OpenClawCodingToolsFactory =
   (typeof import("openclaw/plugin-sdk/agent-harness"))["createOpenClawCodingTools"];
 type OpenClawDynamicTool = ReturnType<OpenClawCodingToolsFactory>[number];
+type OpenClawDynamicToolProjection = ReturnType<
+  typeof filterProviderNormalizableTools<OpenClawDynamicTool>
+>;
 type OpenClawSandboxContext = Awaited<ReturnType<typeof resolveSandboxContext>>;
 type CodexDynamicToolBuildEvent = Parameters<
   NonNullable<EmbeddedRunAttemptParams["onAgentEvent"]>
@@ -52,6 +55,7 @@ const CODEX_NATIVE_SANDBOX_TOOL_REQUIREMENTS = [
   "apply_patch",
 ] as const;
 const CODEX_MEMORY_FLUSH_DYNAMIC_TOOL_ALLOW = new Set(["read", "write"]);
+const CODEX_HEARTBEAT_DYNAMIC_TOOL_NAME = "heartbeat_respond";
 
 /** Runtime inputs needed to derive the exact Codex dynamic tool surface for a turn. */
 export type DynamicToolBuildParams = {
@@ -66,8 +70,6 @@ export type DynamicToolBuildParams = {
   sessionAgentId: string;
   pluginConfig: CodexPluginConfig;
   profilerEnabled?: boolean;
-  forceHeartbeatTool?: boolean;
-  ignoreRuntimePlan?: boolean;
   onYieldDetected: () => void;
   onCodexAppServerEvent?: (event: CodexDynamicToolBuildEvent) => void;
 };
@@ -96,6 +98,13 @@ export function resolveOpenClawCodingToolsSessionKeys(
   };
 }
 
+/** Returns the canonical channel used for Codex message routing and receipts. */
+export function resolveCodexMessageToolProvider(
+  params: Pick<EmbeddedRunAttemptParams, "messageChannel" | "messageProvider">,
+): string | undefined {
+  return params.messageChannel ?? params.messageProvider;
+}
+
 /** Resolves the channel id that hook events should target for this Codex app-server turn. */
 export function resolveCodexAppServerHookChannelId(
   params: EmbeddedRunAttemptParams,
@@ -121,6 +130,11 @@ type CodexDynamicToolBuildStageSummary = {
   stages: CodexDynamicToolBuildStageTiming[];
 };
 
+type CodexDynamicToolBuildStageTracker = {
+  mark: (name: string) => void;
+  snapshot: () => CodexDynamicToolBuildStageSummary;
+};
+
 const CODEX_DYNAMIC_TOOL_BUILD_WARN_TOTAL_MS = 1_000;
 const CODEX_DYNAMIC_TOOL_BUILD_WARN_STAGE_MS = 500;
 
@@ -182,17 +196,42 @@ export function formatCodexDynamicToolBuildStageSummary(
     : "none";
 }
 
-/** Builds, filters, and normalizes Codex-compatible runtime tools for a single turn. */
-export async function buildDynamicTools(input: DynamicToolBuildParams) {
+/** Builds the turn-visible and durable registration views from one OpenClaw tool catalog. */
+export async function prepareDynamicToolCatalog(input: DynamicToolBuildParams): Promise<{
+  tools: OpenClawDynamicTool[];
+  registeredTools: OpenClawDynamicTool[];
+}> {
   const { params } = input;
   if (params.disableTools || !supportsModelTools(params.model)) {
-    return [];
+    return { tools: [], registeredTools: [] };
   }
-  // Dynamic tool construction is on the reply hot path, so per-stage
-  // Date.now/span bookkeeping runs only when the Codex profiler flag is set.
   const toolBuildStages = createCodexDynamicToolBuildStageTracker({
     enabled: input.profilerEnabled,
   });
+  // The durable schema must include heartbeat_respond across normal and heartbeat
+  // turns. Build that superset once, then hide it only from normal turn exposure.
+  const allTools = await buildOpenClawDynamicToolSource(input, toolBuildStages);
+  const readableTools = filterProviderNormalizableTools(allTools);
+  toolBuildStages.mark("provider-normalization");
+  const tools = projectDynamicTools(input, readableTools, toolBuildStages, {
+    excludeHeartbeatTool: params.trigger !== "heartbeat",
+    phase: "runtime-tools",
+    stagePrefix: "runtime",
+  });
+  const registeredTools = projectDynamicTools(input, readableTools, toolBuildStages, {
+    ignoreRuntimePlan: true,
+    phase: "registered-tools",
+    reportDiagnostics: false,
+    stagePrefix: "registered",
+  });
+  return { tools, registeredTools };
+}
+
+async function buildOpenClawDynamicToolSource(
+  input: DynamicToolBuildParams,
+  toolBuildStages: CodexDynamicToolBuildStageTracker,
+): Promise<OpenClawDynamicTool[]> {
+  const { params } = input;
   const modelHasVision = params.model.input?.includes("image") ?? false;
   const agentDir = params.agentDir ?? resolveAgentDir(params.config ?? {}, input.sessionAgentId);
   const createOpenClawCodingTools =
@@ -209,7 +248,8 @@ export async function buildDynamicTools(input: DynamicToolBuildParams) {
       elevated: params.bashElevated,
     },
     sandbox: input.sandbox,
-    messageProvider: params.messageChannel ?? params.messageProvider,
+    messageProvider: resolveCodexMessageToolProvider(params),
+    toolPolicyMessageProvider: params.messageProvider ?? params.messageChannel,
     agentAccountId: params.agentAccountId,
     messageTo: params.messageTo,
     messageThreadId: params.messageThreadId,
@@ -258,6 +298,7 @@ export async function buildDynamicTools(input: DynamicToolBuildParams) {
     ),
     suppressManagedWebSearch: false,
     currentChannelId: params.currentChannelId,
+    currentMessagingTarget: params.currentMessagingTarget,
     hookChannelId: resolveCodexAppServerHookChannelId(params, input.sandboxSessionKey),
     currentThreadTs: params.currentThreadTs,
     currentMessageId: params.currentMessageId,
@@ -269,8 +310,8 @@ export async function buildDynamicTools(input: DynamicToolBuildParams) {
     sourceReplyDeliveryMode: params.sourceReplyDeliveryMode,
     disableMessageTool: params.disableMessageTool,
     forceMessageTool: shouldForceMessageTool(params),
-    enableHeartbeatTool: params.trigger === "heartbeat" || input.forceHeartbeatTool === true,
-    forceHeartbeatTool: params.trigger === "heartbeat" || input.forceHeartbeatTool === true,
+    enableHeartbeatTool: true,
+    forceHeartbeatTool: true,
     onYield: (message) => {
       input.onYieldDetected();
       input.onCodexAppServerEvent?.({
@@ -283,10 +324,30 @@ export async function buildDynamicTools(input: DynamicToolBuildParams) {
     },
   });
   toolBuildStages.mark("create-openclaw-coding-tools");
-  const preNormalizationDiagnostics: RuntimeToolSchemaDiagnostic[] = [];
-  const readableAllToolProjection = filterProviderNormalizableTools(allTools);
-  preNormalizationDiagnostics.push(...readableAllToolProjection.diagnostics);
-  const readableAllTools = [...readableAllToolProjection.tools];
+  return allTools;
+}
+
+function projectDynamicTools(
+  input: DynamicToolBuildParams,
+  source: OpenClawDynamicToolProjection,
+  toolBuildStages: CodexDynamicToolBuildStageTracker,
+  options: {
+    excludeHeartbeatTool?: boolean;
+    ignoreRuntimePlan?: boolean;
+    phase?: "runtime-tools" | "registered-tools";
+    reportDiagnostics?: boolean;
+    stagePrefix?: string;
+  } = {},
+): OpenClawDynamicTool[] {
+  const { params } = input;
+  const markStage = (name: string) =>
+    toolBuildStages.mark(options.stagePrefix ? `${options.stagePrefix}-${name}` : name);
+  const preNormalizationDiagnostics: RuntimeToolSchemaDiagnostic[] = [...source.diagnostics];
+  const readableAllTools = [...source.tools].filter(
+    (tool) =>
+      !options.excludeHeartbeatTool ||
+      normalizeCodexDynamicToolName(tool.name) !== CODEX_HEARTBEAT_DYNAMIC_TOOL_NAME,
+  );
   const codexFilteredTools = addNodeShellDynamicToolsIfNeeded(
     addSandboxShellDynamicToolsIfAvailable(
       isCodexMemoryFlushRun(params)
@@ -298,17 +359,18 @@ export async function buildDynamicTools(input: DynamicToolBuildParams) {
     readableAllTools,
     input,
   );
-  toolBuildStages.mark("codex-filtering");
+  markStage("codex-filtering");
+  const modelHasVision = params.model.input?.includes("image") ?? false;
   const visionFilteredTools = filterToolsForVisionInputs(codexFilteredTools, {
     modelHasVision,
     hasInboundImages: (params.images?.length ?? 0) > 0,
   });
-  toolBuildStages.mark("vision-filtering");
+  markStage("vision-filtering");
   const toolsAllow = includeForcedCodexDynamicToolAllow(params.toolsAllow, params);
   const filteredTools = filterCodexDynamicToolsForAllowlist(visionFilteredTools, toolsAllow);
-  toolBuildStages.mark("allowlist-filter");
+  markStage("allowlist-filter");
   const normalizedTools = normalizeAgentRuntimeTools({
-    runtimePlan: input.ignoreRuntimePlan ? undefined : params.runtimePlan,
+    runtimePlan: options.ignoreRuntimePlan ? undefined : params.runtimePlan,
     tools: filteredTools,
     provider: params.provider,
     config: params.config,
@@ -317,11 +379,14 @@ export async function buildDynamicTools(input: DynamicToolBuildParams) {
     modelId: params.modelId,
     modelApi: params.model.api,
     model: params.model,
+    // Registration is a projection of the already-prepared catalog. Never
+    // activate another provider runtime while constructing its durable schema.
+    allowProviderRuntimePluginLoad: options.ignoreRuntimePlan ? false : undefined,
     onPreNormalizationSchemaDiagnostics: (diagnostics) =>
       preNormalizationDiagnostics.push(...diagnostics),
   });
-  toolBuildStages.mark("runtime-normalization");
-  if (preNormalizationDiagnostics.length > 0) {
+  markStage("runtime-normalization");
+  if (options.reportDiagnostics !== false && preNormalizationDiagnostics.length > 0) {
     embeddedAgentLog.warn(
       `codex app-server quarantined ${preNormalizationDiagnostics.length} unsupported runtime tool schema${preNormalizationDiagnostics.length === 1 ? "" : "s"} before dynamic tool registration`,
       {
@@ -338,7 +403,7 @@ export async function buildDynamicTools(input: DynamicToolBuildParams) {
   }
   const summary = toolBuildStages.snapshot();
   if (shouldWarnCodexDynamicToolBuildStageSummary(summary)) {
-    const phase = input.forceHeartbeatTool ? "registered-tools" : "runtime-tools";
+    const phase = options.phase ?? "runtime-tools";
     embeddedAgentLog.warn(
       `codex app-server dynamic tool build timings runId=${params.runId} sessionId=${params.sessionId} phase=${phase} totalMs=${summary.totalMs} stages=${formatCodexDynamicToolBuildStageSummary(summary)}`,
       {
@@ -352,8 +417,7 @@ export async function buildDynamicTools(input: DynamicToolBuildParams) {
         visionFilteredToolCount: visionFilteredTools.length,
         filteredToolCount: filteredTools.length,
         normalizedToolCount: normalizedTools.length,
-        forceHeartbeatTool: input.forceHeartbeatTool === true,
-        ignoreRuntimePlan: input.ignoreRuntimePlan === true,
+        ignoreRuntimePlan: options.ignoreRuntimePlan === true,
         nativeToolSurfaceEnabled: input.nativeToolSurfaceEnabled === true,
       },
     );

extensions/codex/src/app-server/dynamic-tool-execution.test.ts

@@ -183,6 +183,7 @@ describe("dynamic tool execution helpers", () => {
     vi.useFakeTimers();
     let capturedSignal: AbortSignal | undefined;
     const onTimeout = vi.fn();
+    const onAgentToolResult = vi.fn();
     const response = handleDynamicToolCallWithTimeout({
       call: {
         threadId: "thread-1",
@@ -200,6 +201,7 @@ describe("dynamic tool execution helpers", () => {
       },
       signal: new AbortController().signal,
       timeoutMs: 1,
+      onAgentToolResult,
       onTimeout,
     });
 
@@ -216,6 +218,64 @@ describe("dynamic tool execution helpers", () => {
     });
     expect(capturedSignal?.aborted).toBe(true);
     expect(onTimeout).toHaveBeenCalledTimes(1);
+    expect(onAgentToolResult).toHaveBeenCalledWith({
+      toolName: "message",
+      result: {
+        content: [
+          {
+            type: "text",
+            text: "OpenClaw dynamic tool call timed out after 1ms while running tool message.",
+          },
+        ],
+        details: {
+          status: "failed",
+          error: "OpenClaw dynamic tool call timed out after 1ms while running tool message.",
+        },
+      },
+      isError: true,
+    });
+  });
+
+  it("reports pre-execution aborts to the private result observer", async () => {
+    const controller = new AbortController();
+    controller.abort(new Error("run cancelled"));
+    const onAgentToolResult = vi.fn();
+    const handleToolCall = vi.fn();
+
+    const result = await handleDynamicToolCallWithTimeout({
+      call: {
+        threadId: "thread-1",
+        turnId: "turn-1",
+        callId: "call-aborted",
+        namespace: null,
+        tool: "memory_search",
+        arguments: {},
+      },
+      toolBridge: { handleToolCall },
+      signal: controller.signal,
+      timeoutMs: 1_000,
+      onAgentToolResult,
+    });
+
+    expect(result).toEqual({
+      success: false,
+      contentItems: [
+        { type: "inputText", text: "OpenClaw dynamic tool call aborted before execution." },
+      ],
+    });
+    expect(handleToolCall).not.toHaveBeenCalled();
+    expect(onAgentToolResult).toHaveBeenCalledOnce();
+    expect(onAgentToolResult).toHaveBeenCalledWith({
+      toolName: "memory_search",
+      result: {
+        content: [{ type: "text", text: "OpenClaw dynamic tool call aborted before execution." }],
+        details: {
+          status: "failed",
+          error: "OpenClaw dynamic tool call aborted before execution.",
+        },
+      },
+      isError: true,
+    });
   });
 
   it("logs process poll timeout context separately from session idle", async () => {

extensions/codex/src/app-server/dynamic-tool-execution.ts

@@ -126,10 +126,41 @@ export async function handleDynamicToolCallWithTimeout(params: {
   toolBridge: Pick<CodexDynamicToolBridge, "handleToolCall">;
   signal: AbortSignal;
   timeoutMs: number;
+  onAgentToolResult?: EmbeddedRunAttemptParams["onAgentToolResult"];
   onTimeout?: () => void;
 }): Promise<CodexDynamicToolCallResponse> {
+  // Timeout or run abort can win while a tool ignores cancellation. Keep the
+  // private observer terminal result exactly once across those competing paths.
+  let didNotifyAgentToolResult = false;
+  const notifyAgentToolResult = (
+    event: Parameters<NonNullable<EmbeddedRunAttemptParams["onAgentToolResult"]>>[0],
+  ) => {
+    if (didNotifyAgentToolResult) {
+      return;
+    }
+    didNotifyAgentToolResult = true;
+    try {
+      params.onAgentToolResult?.(event);
+    } catch (error) {
+      embeddedAgentLog.warn(
+        `onAgentToolResult handler failed: tool=${params.call.tool} error=${String(error)}`,
+      );
+    }
+  };
+  const notifyFailedToolResult = (message: string) => {
+    notifyAgentToolResult({
+      toolName: params.call.tool,
+      result: {
+        content: [{ type: "text", text: message }],
+        details: { status: "failed", error: message },
+      },
+      isError: true,
+    });
+  };
   if (params.signal.aborted) {
-    return failedDynamicToolResponse("OpenClaw dynamic tool call aborted before execution.");
+    const message = "OpenClaw dynamic tool call aborted before execution.";
+    notifyFailedToolResult(message);
+    return failedDynamicToolResponse(message);
   }
 
   const controller = new AbortController();
@@ -139,6 +170,7 @@ export async function handleDynamicToolCallWithTimeout(params: {
   const abortFromRun = () => {
     const message = "OpenClaw dynamic tool call aborted.";
     controller.abort(params.signal.reason ?? new Error(message));
+    notifyFailedToolResult(message);
     resolveAbort?.(failedDynamicToolResponse(message, { sideEffectEvidence: true }));
   };
   const abortPromise = new Promise<CodexDynamicToolCallResponse>((resolve) => {
@@ -155,6 +187,7 @@ export async function handleDynamicToolCallWithTimeout(params: {
         ...timeoutDetails.meta,
         consoleMessage: timeoutDetails.consoleMessage,
       });
+      notifyFailedToolResult(timeoutDetails.responseMessage);
       resolve(
         failedDynamicToolResponse(timeoutDetails.responseMessage, { sideEffectEvidence: true }),
       );
@@ -167,13 +200,22 @@ export async function handleDynamicToolCallWithTimeout(params: {
     if (params.signal.aborted) {
       abortFromRun();
     }
-    return await Promise.race([
-      params.toolBridge.handleToolCall(params.call, { signal: controller.signal }),
+    const response = await Promise.race([
+      params.toolBridge.handleToolCall(params.call, {
+        signal: controller.signal,
+        onAgentToolResult: notifyAgentToolResult,
+      }),
       abortPromise,
       timeoutPromise,
     ]);
+    if (!response.success && !didNotifyAgentToolResult) {
+      notifyFailedToolResult(readDynamicToolResponseText(response));
+    }
+    return response;
   } catch (error) {
-    return failedDynamicToolResponse(error instanceof Error ? error.message : String(error), {
+    const message = error instanceof Error ? error.message : String(error);
+    notifyFailedToolResult(message);
+    return failedDynamicToolResponse(message, {
       sideEffectEvidence: true,
     });
   } finally {
@@ -188,6 +230,16 @@ export async function handleDynamicToolCallWithTimeout(params: {
   }
 }
 
+function readDynamicToolResponseText(response: CodexDynamicToolCallResponse): string {
+  const text = response.contentItems
+    .flatMap((item) =>
+      item.type === "inputText" && typeof item.text === "string" ? [item.text] : [],
+    )
+    .join("\n")
+    .trim();
+  return text || "OpenClaw dynamic tool call failed.";
+}
+
 function failedDynamicToolResponse(
   message: string,
   options?: { sideEffectEvidence?: boolean },

extensions/codex/src/app-server/dynamic-tools.test.ts

@@ -18,6 +18,7 @@ import {
 import {
   createEmptyPluginRegistry,
   createMockPluginRegistry,
+  createTestRegistry,
   setActivePluginRegistry,
 } from "openclaw/plugin-sdk/plugin-test-runtime";
 import { afterEach, describe, expect, it, vi } from "vitest";
@@ -222,6 +223,7 @@ describe("createCodexDynamicToolBridge", () => {
 
   it("can register a durable tool schema while denying execution for the current turn", async () => {
     const heartbeatExecute = vi.fn(async () => textToolResult("heartbeat recorded"));
+    const onAgentToolResult = vi.fn();
     const bridge = createCodexDynamicToolBridge({
       tools: [createTool({ name: "message" })],
       registeredTools: [
@@ -237,14 +239,17 @@ describe("createCodexDynamicToolBridge", () => {
       HEARTBEAT_RESPONSE_TOOL_NAME,
     ]);
 
-    const result = await bridge.handleToolCall({
-      threadId: "thread-1",
-      turnId: "turn-1",
-      callId: "call-1",
-      namespace: null,
-      tool: HEARTBEAT_RESPONSE_TOOL_NAME,
-      arguments: {},
-    });
+    const result = await bridge.handleToolCall(
+      {
+        threadId: "thread-1",
+        turnId: "turn-1",
+        callId: "call-1",
+        namespace: null,
+        tool: HEARTBEAT_RESPONSE_TOOL_NAME,
+        arguments: {},
+      },
+      { onAgentToolResult },
+    );
 
     expect(result).toEqual({
       success: false,
@@ -256,6 +261,22 @@ describe("createCodexDynamicToolBridge", () => {
       ],
     });
     expect(heartbeatExecute).not.toHaveBeenCalled();
+    expect(onAgentToolResult).toHaveBeenCalledWith({
+      toolName: HEARTBEAT_RESPONSE_TOOL_NAME,
+      result: {
+        content: [
+          {
+            type: "text",
+            text: `OpenClaw tool is not available for this turn: ${HEARTBEAT_RESPONSE_TOOL_NAME}`,
+          },
+        ],
+        details: {
+          status: "failed",
+          error: `OpenClaw tool is not available for this turn: ${HEARTBEAT_RESPONSE_TOOL_NAME}`,
+        },
+      },
+      isError: true,
+    });
   });
 
   it("keeps available and registered schemas paired with their tools", () => {
@@ -778,6 +799,163 @@ describe("createCodexDynamicToolBridge", () => {
     ]);
   });
 
+  it("records the current provider and transport thread for implicit message sends", async () => {
+    const hasRepliedRef = { value: false };
+    setActivePluginRegistry(
+      createTestRegistry([
+        {
+          pluginId: "slack",
+          plugin: {
+            id: "slack",
+            messaging: { normalizeTarget: (raw: string) => raw.trim().toLowerCase() },
+            threading: {
+              resolveAutoThreadId: ({
+                to,
+                toolContext,
+              }: {
+                to: string;
+                toolContext?: {
+                  currentChannelId?: string;
+                  currentMessagingTarget?: string;
+                  currentThreadTs?: string;
+                  replyToMode?: "off" | "first" | "all" | "batched";
+                  hasRepliedRef?: { value: boolean };
+                };
+              }) => {
+                if (
+                  to !== toolContext?.currentMessagingTarget &&
+                  to !== toolContext?.currentChannelId
+                ) {
+                  return undefined;
+                }
+                if (
+                  (toolContext?.replyToMode === "first" ||
+                    toolContext?.replyToMode === "batched") &&
+                  !toolContext.hasRepliedRef?.value
+                ) {
+                  return toolContext.currentThreadTs;
+                }
+                return undefined;
+              },
+            },
+          },
+          source: "test",
+        },
+      ]),
+    );
+    const bridge = createCodexDynamicToolBridge({
+      tools: [
+        createTool({
+          name: "message",
+          execute: vi.fn(async () => {
+            hasRepliedRef.value = true;
+            return textToolResult("Sent.");
+          }),
+        }),
+      ],
+      signal: new AbortController().signal,
+      hookContext: {
+        currentChannelProvider: "slack",
+        currentChannelId: "D1",
+        currentMessagingTarget: "user:u1",
+        currentThreadId: "171.222",
+        replyToMode: "first",
+        hasRepliedRef,
+      },
+    });
+
+    await handleMessageToolCall(bridge, {
+      action: "send",
+      to: "user:U1",
+      text: "hello from Codex",
+    });
+
+    expect(bridge.telemetry.messagingToolSentTargets).toEqual([
+      {
+        tool: "message",
+        provider: "slack",
+        to: "user:u1",
+        threadId: "171.222",
+        threadImplicit: true,
+        text: "hello from Codex",
+      },
+    ]);
+  });
+
+  it("records the provider-confirmed route for successful message sends", async () => {
+    const registry = createTestRegistry([
+      {
+        pluginId: "mattermost",
+        plugin: {
+          id: "mattermost",
+          messaging: { normalizeTarget: (raw: string) => raw.trim().toLowerCase() },
+          actions: {
+            extractToolSend: ({ args }: { args: Record<string, unknown> }) =>
+              args.action === "send" && typeof args.to === "string"
+                ? { to: args.to, threadImplicit: true }
+                : null,
+            extractToolSendResult: ({ result }: { result: unknown }) => {
+              const details = requireRecord(
+                requireRecord(result, "message result").details,
+                "message details",
+              );
+              const toolSend = requireRecord(details.toolSend, "tool send details");
+              return {
+                to: String(toolSend.to),
+                threadId: String(toolSend.threadId),
+              };
+            },
+          },
+        },
+        source: "test",
+      },
+    ]);
+    const middleware = vi.fn(async (event: { result: AgentToolResult<unknown> }) => {
+      const details = requireRecord(event.result.details, "middleware details");
+      const toolSend = requireRecord(details.toolSend, "middleware tool send");
+      toolSend.to = "channel:corrupted";
+      toolSend.threadId = "corrupted-root";
+      return undefined;
+    });
+    registry.agentToolResultMiddlewares.push({
+      pluginId: "route-details-stripper",
+      pluginName: "Route details stripper",
+      rawHandler: middleware,
+      handler: middleware,
+      runtimes: ["codex"],
+      source: "test",
+    });
+    setActivePluginRegistry(registry);
+    const bridge = createBridgeWithToolResult(
+      "message",
+      textToolResult("Sent.", {
+        toolSend: {
+          to: "channel:resolved-id",
+          threadId: "root-post-id",
+        },
+      }),
+    );
+
+    await handleMessageToolCall(bridge, {
+      action: "send",
+      provider: "mattermost",
+      to: "town-square",
+      text: "hello from Codex",
+    });
+
+    expect(bridge.telemetry.messagingToolSentTargets).toEqual([
+      {
+        tool: "message",
+        provider: "mattermost",
+        to: "channel:resolved-id",
+        threadId: "root-post-id",
+        threadImplicit: undefined,
+        threadSuppressed: undefined,
+        text: "hello from Codex",
+      },
+    ]);
+  });
+
   it("records message tool media attachment aliases as delivery evidence", async () => {
     const toolResult = {
       content: [{ type: "text", text: "Sent." }],
@@ -1027,6 +1205,152 @@ describe("createCodexDynamicToolBridge", () => {
     expectContextFields(callArg(handler, 0, 1, "middleware context"), { runtime: "codex" });
   });
 
+  it("keeps unrecognized non-success statuses fail-closed", async () => {
+    const onAgentToolResult = vi.fn();
+    const bridge = createCodexDynamicToolBridge({
+      tools: [
+        createTool({
+          name: "exec",
+          execute: vi.fn(async () =>
+            textToolResult("Approval is unavailable.", { status: "approval-unavailable" }),
+          ),
+        }),
+      ],
+      signal: new AbortController().signal,
+    });
+
+    const result = await bridge.handleToolCall(
+      {
+        threadId: "thread-1",
+        turnId: "turn-1",
+        callId: "call-1",
+        namespace: null,
+        tool: "exec",
+        arguments: { command: "pwd" },
+      },
+      { onAgentToolResult },
+    );
+
+    expect(result).toMatchObject({ success: false });
+    expect(onAgentToolResult).toHaveBeenCalledWith({
+      toolName: "exec",
+      result: textToolResult("Approval is unavailable.", { status: "approval-unavailable" }),
+      isError: true,
+    });
+  });
+
+  it("preserves explicitly successful cancellation outcomes", async () => {
+    const onAgentToolResult = vi.fn();
+    const cancelledResult = textToolResult("Approval rejected.", {
+      ok: true,
+      status: "cancelled",
+    });
+    const bridge = createCodexDynamicToolBridge({
+      tools: [
+        createTool({
+          name: "lobster",
+          execute: vi.fn(async () => cancelledResult),
+        }),
+      ],
+      signal: new AbortController().signal,
+    });
+
+    const result = await bridge.handleToolCall(
+      {
+        threadId: "thread-1",
+        turnId: "turn-1",
+        callId: "call-1",
+        namespace: null,
+        tool: "lobster",
+        arguments: {},
+      },
+      { onAgentToolResult },
+    );
+
+    expect(result).toMatchObject({ success: true });
+    expect(onAgentToolResult).toHaveBeenCalledWith({
+      toolName: "lobster",
+      result: cancelledResult,
+      isError: false,
+    });
+  });
+
+  it("reports sanitized dynamic tool results to the private result observer", async () => {
+    const onAgentToolResult = vi.fn();
+    const bridge = createCodexDynamicToolBridge({
+      tools: [
+        createTool({
+          name: "memory_lookup_custom",
+          execute: vi.fn(async () =>
+            textToolResult("OPENROUTER_API_KEY=sk-or-v1-abcdef0123456789", {
+              status: "failed",
+              error: "backend unavailable",
+            }),
+          ),
+        }),
+      ],
+      signal: new AbortController().signal,
+    });
+
+    await bridge.handleToolCall(
+      {
+        threadId: "thread-1",
+        turnId: "turn-1",
+        callId: "call-1",
+        namespace: null,
+        tool: "memory_lookup_custom",
+        arguments: {},
+      },
+      { onAgentToolResult },
+    );
+
+    expect(onAgentToolResult).toHaveBeenCalledOnce();
+    expect(onAgentToolResult).toHaveBeenCalledWith({
+      toolName: "memory_lookup_custom",
+      result: {
+        content: [{ type: "text", text: "OPENROUTER_API_KEY=sk-or-…6789" }],
+        details: { status: "failed", error: "backend unavailable" },
+      },
+      isError: true,
+    });
+  });
+
+  it("reports thrown dynamic tool failures to the private result observer", async () => {
+    const onAgentToolResult = vi.fn();
+    const bridge = createCodexDynamicToolBridge({
+      tools: [
+        createTool({
+          name: "memory_lookup_custom",
+          execute: vi.fn(async () => {
+            throw new Error("backend unavailable");
+          }),
+        }),
+      ],
+      signal: new AbortController().signal,
+    });
+
+    await bridge.handleToolCall(
+      {
+        threadId: "thread-1",
+        turnId: "turn-1",
+        callId: "call-1",
+        namespace: null,
+        tool: "memory_lookup_custom",
+        arguments: {},
+      },
+      { onAgentToolResult },
+    );
+
+    expect(onAgentToolResult).toHaveBeenCalledWith({
+      toolName: "memory_lookup_custom",
+      result: {
+        content: [{ type: "text", text: "backend unavailable" }],
+        details: { status: "failed", error: "backend unavailable" },
+      },
+      isError: true,
+    });
+  });
+
   it("preserves terminal async tool results without marking them as errors", async () => {
     const bridge = createBridgeWithToolResult("image_generate", {
       content: [{ type: "text", text: "Background task started." }],

extensions/codex/src/app-server/dynamic-tools.ts

@@ -6,17 +6,21 @@ import type { AgentToolResult } from "openclaw/plugin-sdk/agent-core";
 import {
   createAgentToolResultMiddlewareRunner,
   createCodexAppServerToolResultExtensionRunner,
+  extractMessagingToolSend,
+  extractMessagingToolSendResult,
   extractToolResultMediaArtifact,
   filterToolResultMediaUrls,
   HEARTBEAT_RESPONSE_TOOL_NAME,
   embeddedAgentLog,
   type EmbeddedRunAttemptParams,
   isToolWrappedWithBeforeToolCallHook,
+  isToolResultError,
   isMessagingTool,
   isMessagingToolSendAction,
   normalizeHeartbeatToolResponse,
   projectRuntimeToolInputSchema,
   runAgentHarnessAfterToolCallHook,
+  sanitizeToolResult,
   setBeforeToolCallDiagnosticsEnabled,
   type AnyAgentTool,
   type HeartbeatToolResponse,
@@ -49,10 +53,22 @@ type CodexDynamicToolHookContext = {
   sessionKey?: string;
   runId?: string;
   channelId?: string;
+  currentChannelProvider?: string;
+  currentChannelId?: string;
+  currentMessagingTarget?: string;
+  currentThreadId?: string;
+  replyToMode?: "off" | "first" | "all" | "batched";
+  hasRepliedRef?: { value: boolean };
 };
 
 type CodexToolResultHookContext = Omit<CodexDynamicToolHookContext, "config">;
 
+type AgentToolResultObserver = (event: {
+  toolName: string;
+  result: unknown;
+  isError: boolean;
+}) => void;
+
 type ProjectedCodexDynamicTool = {
   tool: AnyAgentTool;
   name: string;
@@ -65,13 +81,32 @@ type CodexDynamicToolSchemaQuarantine = {
   violations: readonly string[];
 };
 
+function applyCurrentMessageProvider(
+  toolName: string,
+  args: Record<string, unknown>,
+  currentProvider: string | undefined,
+): Record<string, unknown> {
+  const hasProvider =
+    typeof args.provider === "string" && args.provider.trim().length > 0
+      ? true
+      : typeof args.channel === "string" && args.channel.trim().length > 0;
+  const provider = currentProvider?.trim();
+  if (toolName !== "message" || hasProvider || !provider) {
+    return args;
+  }
+  return { ...args, provider };
+}
+
 /** Runtime bridge returned to Codex app-server attempt code. */
 export type CodexDynamicToolBridge = {
   availableSpecs: CodexDynamicToolSpec[];
   specs: CodexDynamicToolSpec[];
   handleToolCall: (
     params: CodexDynamicToolCallParams,
-    options?: { signal?: AbortSignal },
+    options?: {
+      signal?: AbortSignal;
+      onAgentToolResult?: AgentToolResultObserver;
+    },
   ) => Promise<CodexDynamicToolCallResponse>;
   telemetry: {
     didSendViaMessagingTool: boolean;
@@ -155,7 +190,6 @@ export function createCodexDynamicToolBridge(params: {
     ...ALWAYS_DIRECT_DYNAMIC_TOOL_NAMES,
     ...(params.directToolNames ?? []),
   ]);
-
   return {
     availableSpecs: availableTools.map((entry) =>
       createCodexDynamicToolSpec({
@@ -175,19 +209,28 @@ export function createCodexDynamicToolBridge(params: {
     handleToolCall: async (call, options) => {
       const toolEntry = toolMap.get(call.tool);
       if (!toolEntry) {
+        const message = registeredToolNames.has(call.tool)
+          ? `OpenClaw tool is not available for this turn: ${call.tool}`
+          : `Unknown OpenClaw tool: ${call.tool}`;
+        notifyAgentToolResult(
+          options?.onAgentToolResult,
+          call.tool,
+          failedToolResult(message),
+          true,
+        );
         if (registeredToolNames.has(call.tool)) {
           return {
             contentItems: [
               {
                 type: "inputText",
-                text: `OpenClaw tool is not available for this turn: ${call.tool}`,
+                text: message,
               },
             ],
             success: false,
           };
         }
         return {
-          contentItems: [{ type: "inputText", text: `Unknown OpenClaw tool: ${call.tool}` }],
+          contentItems: [{ type: "inputText", text: message }],
           success: false,
         };
       }
@@ -200,9 +243,30 @@ export function createCodexDynamicToolBridge(params: {
         // Prepare before marking side-effect evidence; argument preparation can
         // fail without the target tool actually starting.
         const preparedArgs = tool.prepareArguments ? tool.prepareArguments(args) : args;
+        const telemetryArgs = isRecord(preparedArgs) ? preparedArgs : args;
+        const messagingTelemetryArgs = applyCurrentMessageProvider(
+          toolName,
+          telemetryArgs,
+          params.hookContext?.currentChannelProvider,
+        );
+        const messagingTarget =
+          isMessagingTool(toolName) && isMessagingToolSendAction(toolName, telemetryArgs)
+            ? extractMessagingToolSend(toolName, messagingTelemetryArgs, {
+                config: params.hookContext?.config,
+                currentChannelId: params.hookContext?.currentChannelId,
+                currentMessagingTarget: params.hookContext?.currentMessagingTarget,
+                currentThreadId: params.hookContext?.currentThreadId,
+                replyToMode: params.hookContext?.replyToMode,
+                hasRepliedRef: params.hookContext?.hasRepliedRef,
+              })
+            : undefined;
         didStartExecution = true;
         const rawResult = await tool.execute(call.callId, preparedArgs, signal);
-        const rawIsError = isToolResultError(rawResult);
+        const rawIsError = isCodexToolResultError(rawResult);
+        const confirmedMessagingTarget =
+          !rawIsError && messagingTarget
+            ? extractMessagingToolSendResult(messagingTarget, rawResult)
+            : messagingTarget;
         const middlewareResult = await middlewareRunner.applyToolResultMiddleware({
           threadId: call.threadId,
           turnId: call.turnId,
@@ -220,14 +284,16 @@ export function createCodexDynamicToolBridge(params: {
           args,
           result: middlewareResult,
         });
-        const resultIsError = rawIsError || isToolResultError(result);
+        const resultIsError = rawIsError || isCodexToolResultError(result);
+        notifyAgentToolResult(options?.onAgentToolResult, toolName, result, resultIsError);
         collectToolTelemetry({
           toolName,
-          args,
+          args: telemetryArgs,
           result,
           mediaTrustResult: rawResult,
           telemetry,
           isError: resultIsError,
+          messagingTarget: confirmedMessagingTarget,
         });
         void runAgentHarnessAfterToolCallHook({
           toolName,
@@ -262,6 +328,13 @@ export function createCodexDynamicToolBridge(params: {
         );
         return withSideEffectEvidence(response, terminalType !== "blocked");
       } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        notifyAgentToolResult(
+          options?.onAgentToolResult,
+          toolName,
+          failedToolResult(errorMessage),
+          true,
+        );
         collectToolTelemetry({
           toolName,
           args,
@@ -278,7 +351,7 @@ export function createCodexDynamicToolBridge(params: {
           sessionKey: toolResultHookContext.sessionKey,
           channelId: toolResultHookContext.channelId,
           startArgs: args,
-          error: error instanceof Error ? error.message : String(error),
+          error: errorMessage,
           startedAt,
         });
         return withSideEffectEvidence(
@@ -287,7 +360,7 @@ export function createCodexDynamicToolBridge(params: {
               contentItems: [
                 {
                   type: "inputText",
-                  text: error instanceof Error ? error.message : String(error),
+                  text: errorMessage,
                 },
               ],
               success: false,
@@ -301,6 +374,32 @@ export function createCodexDynamicToolBridge(params: {
   };
 }
 
+function notifyAgentToolResult(
+  observer: AgentToolResultObserver | undefined,
+  toolName: string,
+  result: unknown,
+  isError: boolean,
+) {
+  try {
+    observer?.({
+      toolName,
+      result: sanitizeToolResult(result),
+      isError,
+    });
+  } catch (error) {
+    embeddedAgentLog.warn(
+      `onAgentToolResult handler failed: tool=${toolName} error=${String(error)}`,
+    );
+  }
+}
+
+function failedToolResult(message: string): AgentToolResult<unknown> {
+  return {
+    content: [{ type: "text", text: message }],
+    details: { status: "failed", error: message },
+  };
+}
+
 function wrapProjectedCodexDynamicTools(
   tools: readonly ProjectedCodexDynamicTool[],
   hookContext: CodexDynamicToolHookContext | undefined,
@@ -584,6 +683,7 @@ function collectToolTelemetry(params: {
   mediaTrustResult?: AgentToolResult<unknown>;
   telemetry: CodexDynamicToolBridge["telemetry"];
   isError: boolean;
+  messagingTarget?: MessagingToolSend;
 }): void {
   if (params.isError) {
     return;
@@ -636,11 +736,13 @@ function collectToolTelemetry(params: {
   const mediaUrls = collectMediaUrls(params.args);
   params.telemetry.messagingToolSentMediaUrls.push(...mediaUrls);
   params.telemetry.messagingToolSentTargets.push({
-    tool: params.toolName,
-    provider: readFirstString(params.args, ["provider", "channel"]) ?? params.toolName,
-    accountId: readFirstString(params.args, ["accountId", "account_id"]),
-    to: readFirstString(params.args, ["to", "target", "recipient"]),
-    threadId: readFirstString(params.args, ["threadId", "thread_id", "messageThreadId"]),
+    ...(params.messagingTarget ?? {
+      tool: params.toolName,
+      provider: readFirstString(params.args, ["provider", "channel"]) ?? params.toolName,
+      accountId: readFirstString(params.args, ["accountId", "account_id"]),
+      to: readFirstString(params.args, ["to", "target", "recipient"]),
+      threadId: readFirstString(params.args, ["threadId", "thread_id", "messageThreadId"]),
+    }),
     ...(text ? { text } : {}),
     ...(mediaUrls.length > 0 ? { mediaUrls } : {}),
   });
@@ -688,11 +790,17 @@ function readPositiveInteger(value: unknown): number | undefined {
   return Math.floor(value);
 }
 
-function isToolResultError(result: AgentToolResult<unknown>): boolean {
+function isCodexToolResultError(result: AgentToolResult<unknown>): boolean {
+  if (isToolResultError(result)) {
+    return true;
+  }
   const details = result.details;
   if (!isRecord(details)) {
     return false;
   }
+  if (details.ok === true || details.success === true) {
+    return false;
+  }
   if (details.timedOut === true) {
     return true;
   }

extensions/codex/src/app-server/event-projector.test.ts

@@ -24,7 +24,6 @@ import {
   type CodexAppServerEventProjectorOptions,
   type CodexAppServerToolTelemetry,
 } from "./event-projector.js";
-import { rememberCodexRateLimits, resetCodexRateLimitCacheForTests } from "./rate-limit-cache.js";
 import { createCodexTestModel } from "./test-support.js";
 
 const THREAD_ID = "thread-1";
@@ -108,7 +107,6 @@ afterEach(async () => {
   resetAgentEventsForTest();
   resetDiagnosticEventsForTest();
   resetGlobalHookRunner();
-  resetCodexRateLimitCacheForTests();
   vi.restoreAllMocks();
   vi.unstubAllEnvs();
   for (const tempDir of tempDirs) {
@@ -861,10 +859,11 @@ describe("CodexAppServerEventProjector", () => {
   });
 
   it("uses Codex rate-limit resets for usage-limit app-server errors", async () => {
-    const projector = await createProjector();
     const resetsAt = Math.ceil(Date.now() / 1000) + 120;
+    const projector = await createProjector(undefined, {
+      readRecentRateLimits: () => rateLimitsUpdated(resetsAt).params,
+    });
 
-    await projector.handleNotification(rateLimitsUpdated(resetsAt));
     await projector.handleNotification(
       forCurrentTurn("error", {
         error: {
@@ -885,10 +884,11 @@ describe("CodexAppServerEventProjector", () => {
   });
 
   it("uses Codex rate-limit resets for failed turns", async () => {
-    const projector = await createProjector();
     const resetsAt = Math.ceil(Date.now() / 1000) + 120;
+    const projector = await createProjector(undefined, {
+      readRecentRateLimits: () => rateLimitsUpdated(resetsAt).params,
+    });
 
-    await projector.handleNotification(rateLimitsUpdated(resetsAt));
     await projector.handleNotification(
       forCurrentTurn("turn/completed", {
         turn: {
@@ -912,9 +912,8 @@ describe("CodexAppServerEventProjector", () => {
   });
 
   it("uses a recent Codex rate-limit snapshot when failed turns omit reset details", async () => {
-    const projector = await createProjector();
     const resetsAt = Math.ceil(Date.now() / 1000) + 120;
-    rememberCodexRateLimits({
+    const rateLimits = {
       rateLimits: {
         limitId: "codex",
         limitName: "Codex",
@@ -925,6 +924,9 @@ describe("CodexAppServerEventProjector", () => {
         rateLimitReachedType: "rate_limit_reached",
       },
       rateLimitsByLimitId: null,
+    };
+    const projector = await createProjector(undefined, {
+      readRecentRateLimits: () => rateLimits,
     });
 
     await projector.handleNotification(
@@ -976,19 +978,19 @@ describe("CodexAppServerEventProjector", () => {
     expect(result.promptErrorSource).toBe("prompt");
   });
 
-  it("normalizes snake_case current token usage fields", async () => {
+  it("normalizes current app-server token usage", async () => {
     const projector = await createProjector();
 
     await projector.handleNotification(agentMessageDelta("done"));
     await projector.handleNotification(
       forCurrentTurn("thread/tokenUsage/updated", {
         tokenUsage: {
-          total: { total_tokens: 1_000_000 },
-          last_token_usage: {
-            total_tokens: 17,
-            input_tokens: 8,
-            cached_input_tokens: 3,
-            output_tokens: 9,
+          total: { totalTokens: 1_000_000 },
+          last: {
+            totalTokens: 17,
+            inputTokens: 8,
+            cachedInputTokens: 3,
+            outputTokens: 9,
           },
         },
       }),

extensions/codex/src/app-server/event-projector.ts

@@ -26,10 +26,7 @@ import type { AssistantMessage, Usage } from "openclaw/plugin-sdk/llm";
 import { saveMediaBuffer } from "openclaw/plugin-sdk/media-store";
 import { asDateTimestampMs } from "openclaw/plugin-sdk/number-runtime";
 import { resolveCodexLocalRuntimeAttribution } from "./local-runtime-attribution.js";
-import {
-  readCodexNotificationThreadId,
-  readCodexNotificationTurnId,
-} from "./notification-correlation.js";
+import { isCodexNotificationForTurn } from "./notification-correlation.js";
 import { readCodexTurn } from "./protocol-validators.js";
 import {
   isJsonObject,
@@ -40,7 +37,6 @@ import {
   type JsonObject,
   type JsonValue,
 } from "./protocol.js";
-import { readRecentCodexRateLimits, rememberCodexRateLimits } from "./rate-limit-cache.js";
 import { formatCodexUsageLimitErrorMessage } from "./rate-limits.js";
 import { readCodexMirroredSessionHistoryMessages } from "./session-history.js";
 import {
@@ -65,6 +61,7 @@ export type CodexAppServerToolTelemetry = {
 
 export type CodexAppServerEventProjectorOptions = {
   nativePostToolUseRelayEnabled?: boolean;
+  readRecentRateLimits?: () => JsonValue | undefined;
   trajectoryRecorder?: CodexTrajectoryRecorder | null;
 };
 
@@ -92,22 +89,6 @@ const ZERO_USAGE: Usage = {
   },
 };
 
-const CURRENT_TOKEN_USAGE_KEYS = [
-  "last",
-  "current",
-  "lastCall",
-  "lastCallUsage",
-  "lastTokenUsage",
-  "last_token_usage",
-] as const;
-
-const CODEX_PROMPT_TOTAL_INPUT_KEYS = [
-  "inputTokens",
-  "input_tokens",
-  "promptTokens",
-  "prompt_tokens",
-] as const;
-
 const MAX_TOOL_OUTPUT_DELTA_MESSAGES_PER_ITEM = 20;
 const TOOL_TRANSCRIPT_OUTPUT_MAX_CHARS = 12_000;
 const MISSING_TOOL_RESULT_ERROR =
@@ -198,8 +179,6 @@ export class CodexAppServerEventProjector {
   private tokenUsage: ReturnType<typeof normalizeUsage>;
   private guardianReviewCount = 0;
   private completedCompactionCount = 0;
-  private latestRateLimits: JsonValue | undefined;
-
   constructor(
     private readonly params: EmbeddedRunAttemptParams,
     private readonly threadId: string,
@@ -221,11 +200,6 @@ export class CodexAppServerEventProjector {
     if (!params) {
       return;
     }
-    if (notification.method === "account/rateLimits/updated") {
-      this.latestRateLimits = params;
-      rememberCodexRateLimits(params);
-      return;
-    }
     if (isHookNotificationMethod(notification.method)) {
       if (!this.isHookNotificationForCurrentThread(params)) {
         return;
@@ -278,7 +252,7 @@ export class CodexAppServerEventProjector {
         await this.handleRawResponseItemCompleted(params);
         break;
       case "error":
-        if (readBooleanAlias(params, ["willRetry", "will_retry"]) === true) {
+        if (params.willRetry === true) {
           break;
         }
         this.promptError = this.formatCodexErrorMessage(params) ?? "codex app-server error";
@@ -671,9 +645,7 @@ export class CodexAppServerEventProjector {
 
   private handleTokenUsage(params: JsonObject): void {
     const tokenUsage = isJsonObject(params.tokenUsage) ? params.tokenUsage : undefined;
-    const current =
-      (tokenUsage ? readFirstJsonObject(tokenUsage, CURRENT_TOKEN_USAGE_KEYS) : undefined) ??
-      readFirstJsonObject(params, CURRENT_TOKEN_USAGE_KEYS);
+    const current = tokenUsage && isJsonObject(tokenUsage.last) ? tokenUsage.last : undefined;
     if (!current) {
       return;
     }
@@ -744,7 +716,7 @@ export class CodexAppServerEventProjector {
         formatCodexUsageLimitErrorMessage({
           message: turn.error?.message,
           codexErrorInfo: turn.error?.codexErrorInfo as JsonValue | null | undefined,
-          rateLimits: this.latestRateLimits ?? readRecentCodexRateLimits(),
+          rateLimits: this.options.readRecentRateLimits?.(),
         }) ??
         turn.error?.message ??
         "codex app-server turn failed";
@@ -1611,7 +1583,7 @@ export class CodexAppServerEventProjector {
       formatCodexUsageLimitErrorMessage({
         message: error ? readString(error, "message") : undefined,
         codexErrorInfo: error?.codexErrorInfo,
-        rateLimits: this.latestRateLimits ?? readRecentCodexRateLimits(),
+        rateLimits: this.options.readRecentRateLimits?.(),
       }) ?? readCodexErrorNotificationMessage(params)
     );
   }
@@ -1786,9 +1758,7 @@ export class CodexAppServerEventProjector {
   }
 
   private isNotificationForTurn(params: JsonObject): boolean {
-    const threadId = readCodexNotificationThreadId(params);
-    const turnId = readNotificationTurnId(params);
-    return threadId === this.threadId && turnId === this.turnId;
+    return isCodexNotificationForTurn(params, this.threadId, this.turnId);
   }
 
   private isHookNotificationForCurrentThread(params: JsonObject): boolean {
@@ -1802,10 +1772,6 @@ function isHookNotificationMethod(method: string): method is "hook/started" | "h
   return method === "hook/started" || method === "hook/completed";
 }
 
-function readNotificationTurnId(record: JsonObject): string | undefined {
-  return readCodexNotificationTurnId(record);
-}
-
 function readString(record: JsonObject, key: string): string | undefined {
   const value = record[key];
   return typeof value === "string" ? value : undefined;
@@ -1895,21 +1861,6 @@ function readNonNegativeInteger(record: JsonObject, key: string): number | undef
   return value !== undefined && Number.isInteger(value) && value >= 0 ? value : undefined;
 }
 
-function readBoolean(record: JsonObject, key: string): boolean | undefined {
-  const value = record[key];
-  return typeof value === "boolean" ? value : undefined;
-}
-
-function readBooleanAlias(record: JsonObject, keys: readonly string[]): boolean | undefined {
-  for (const key of keys) {
-    const value = readBoolean(record, key);
-    if (value !== undefined) {
-      return value;
-    }
-  }
-  return undefined;
-}
-
 function readCodexErrorNotificationMessage(record: JsonObject): string | undefined {
   const error = record.error;
   if (isJsonObject(error)) {
@@ -1937,52 +1888,19 @@ function readHookOutputEntries(
   });
 }
 
-function readFirstJsonObject(record: JsonObject, keys: readonly string[]): JsonObject | undefined {
-  for (const key of keys) {
-    const value = record[key];
-    if (isJsonObject(value)) {
-      return value;
-    }
-  }
-  return undefined;
-}
-
-function readNumberAlias(record: JsonObject, keys: readonly string[]): number | undefined {
-  for (const key of keys) {
-    const value = readNumber(record, key);
-    if (value !== undefined) {
-      return value;
-    }
-  }
-  return undefined;
-}
-
 function normalizeCodexTokenUsage(record: JsonObject): ReturnType<typeof normalizeUsage> {
-  const promptTotalInput = readNumberAlias(record, CODEX_PROMPT_TOTAL_INPUT_KEYS);
-  const cacheRead = readNumberAlias(record, [
-    "cachedInputTokens",
-    "cached_input_tokens",
-    "cacheRead",
-    "cache_read",
-    "cache_read_input_tokens",
-    "cached_tokens",
-  ]);
+  const promptTotalInput = readNumber(record, "inputTokens");
+  const cacheRead = readNumber(record, "cachedInputTokens");
   const input =
     promptTotalInput !== undefined && cacheRead !== undefined
       ? Math.max(0, promptTotalInput - cacheRead)
-      : (promptTotalInput ?? readNumber(record, "input"));
+      : promptTotalInput;
 
   return normalizeUsage({
     input,
-    output: readNumberAlias(record, ["outputTokens", "output_tokens", "output"]),
+    output: readNumber(record, "outputTokens"),
     cacheRead,
-    cacheWrite: readNumberAlias(record, [
-      "cacheWrite",
-      "cache_write",
-      "cacheCreationInputTokens",
-      "cache_creation_input_tokens",
-    ]),
-    total: readNumberAlias(record, ["totalTokens", "total_tokens", "total"]),
+    total: readNumber(record, "totalTokens"),
   });
 }
 

extensions/codex/src/app-server/models.ts

@@ -8,6 +8,10 @@ import type { CodexAppServerClient } from "./client.js";
 import type { CodexAppServerStartOptions } from "./config.js";
 import { readCodexModelListResponse } from "./protocol-validators.js";
 import type { CodexModel, CodexReasoningEffortOption } from "./protocol.js";
+import {
+  createIsolatedCodexAppServerClient,
+  leaseSharedCodexAppServerClient,
+} from "./shared-client.js";
 
 /** Normalized model metadata returned by the Codex app-server model listing helper. */
 export type CodexAppServerModel = {
@@ -36,10 +40,11 @@ export type CodexAppServerListModelsOptions = {
   includeHidden?: boolean;
   timeoutMs?: number;
   startOptions?: CodexAppServerStartOptions;
-  authProfileId?: string;
+  authProfileId?: string | null;
   agentDir?: string;
   config?: Parameters<typeof resolveCodexAppServerAuthProfileIdForAgent>[0]["config"];
   sharedClient?: boolean;
+  signal?: AbortSignal;
 };
 
 /** Lists one Codex app-server model page using the configured auth/client options. */
@@ -54,27 +59,37 @@ export async function listCodexAppServerModels(
 /** Walks Codex app-server model pages until exhaustion or the max-page guard. */
 export async function listAllCodexAppServerModels(
   options: CodexAppServerListModelsOptions & { maxPages?: number } = {},
+): Promise<CodexAppServerModelListResult> {
+  return await withCodexAppServerModelClient(options, async ({ client, timeoutMs }) =>
+    listAllCodexAppServerModelsWithClient(client, { ...options, timeoutMs }),
+  );
+}
+
+/** Walks all model pages on an already-owned physical app-server client. */
+export async function listAllCodexAppServerModelsWithClient(
+  client: CodexAppServerClient,
+  options: CodexAppServerListModelsOptions & { maxPages?: number } = {},
 ): Promise<CodexAppServerModelListResult> {
   const maxPages = normalizeMaxPages(options.maxPages);
-  return await withCodexAppServerModelClient(options, async ({ client, timeoutMs }) => {
-    const models: CodexAppServerModel[] = [];
-    let cursor = options.cursor;
-    let nextCursor: string | undefined;
-    for (let page = 0; page < maxPages; page += 1) {
-      const result = await requestModelListPage(client, {
-        ...options,
-        timeoutMs,
-        cursor,
-      });
-      models.push(...result.models);
-      nextCursor = result.nextCursor;
-      if (!nextCursor) {
-        return { models };
-      }
-      cursor = nextCursor;
+  const timeoutMs = options.timeoutMs ?? 2500;
+  const models: CodexAppServerModel[] = [];
+  let cursor = options.cursor;
+  let nextCursor: string | undefined;
+  for (let page = 0; page < maxPages; page += 1) {
+    options.signal?.throwIfAborted();
+    const result = await requestModelListPage(client, {
+      ...options,
+      timeoutMs,
+      cursor,
+    });
+    models.push(...result.models);
+    nextCursor = result.nextCursor;
+    if (!nextCursor) {
+      return { models };
     }
-    return { models, nextCursor, truncated: true };
-  });
+    cursor = nextCursor;
+  }
+  return { models, nextCursor, truncated: true };
 }
 
 async function withCodexAppServerModelClient<T>(
@@ -83,33 +98,32 @@ async function withCodexAppServerModelClient<T>(
 ): Promise<T> {
   const timeoutMs = options.timeoutMs ?? 2500;
   const useSharedClient = options.sharedClient !== false;
-  const {
-    createIsolatedCodexAppServerClient,
-    getLeasedSharedCodexAppServerClient,
-    releaseLeasedSharedCodexAppServerClient,
-  } = await import("./shared-client.js");
-  const client = useSharedClient
-    ? await getLeasedSharedCodexAppServerClient({
+  const clientLease = useSharedClient
+    ? await leaseSharedCodexAppServerClient({
         startOptions: options.startOptions,
         timeoutMs,
         authProfileId: options.authProfileId,
         agentDir: options.agentDir,
         config: options.config,
+        abandonSignal: options.signal,
       })
-    : await createIsolatedCodexAppServerClient({
-        startOptions: options.startOptions,
-        timeoutMs,
-        authProfileId: options.authProfileId,
-        agentDir: options.agentDir,
-        config: options.config,
-      });
+    : undefined;
+  const client =
+    clientLease?.client ??
+    (await createIsolatedCodexAppServerClient({
+      startOptions: options.startOptions,
+      timeoutMs,
+      authProfileId: options.authProfileId,
+      agentDir: options.agentDir,
+      config: options.config,
+    }));
   try {
     return await run({ client, timeoutMs });
   } finally {
     if (useSharedClient) {
-      releaseLeasedSharedCodexAppServerClient(client);
+      clientLease?.release();
     } else {
-      client.close();
+      await client.closeAndWait({ exitTimeoutMs: 2_000, forceKillDelayMs: 250 });
     }
   }
 }
@@ -125,7 +139,7 @@ async function requestModelListPage(
       cursor: options.cursor ?? null,
       includeHidden: options.includeHidden ?? null,
     },
-    { timeoutMs: options.timeoutMs },
+    { timeoutMs: options.timeoutMs, signal: options.signal },
   );
   return readModelListResult(response);
 }

extensions/codex/src/app-server/native-execution-policy.ts

@@ -4,7 +4,12 @@
  */
 import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
 import { resolveSandboxRuntimeStatus } from "openclaw/plugin-sdk/sandbox";
-import { getSessionEntry, type SessionEntry } from "openclaw/plugin-sdk/session-store-runtime";
+import {
+  loadSessionStore,
+  resolveSessionStoreEntry,
+  resolveStorePath,
+  type SessionEntry,
+} from "openclaw/plugin-sdk/session-store-runtime";
 
 type ExecHost = "sandbox" | "gateway" | "node";
 type ExecTarget = "auto" | ExecHost;
@@ -44,20 +49,21 @@ export function resolveCodexNativeExecutionPolicy(params: {
 }): CodexNativeExecutionPolicy {
   const config = params.config ?? {};
   const sessionKey = params.sessionKey?.trim() || params.sessionId?.trim() || undefined;
+  const agentId = resolvePolicyAgentId({ config, sessionKey, agentId: params.agentId });
   const sessionEntry =
     params.sessionEntry ??
     (params.readRuntimeSessionEntry && sessionKey
-      ? readRuntimeSessionEntryBestEffort(sessionKey)
+      ? readRuntimeSessionEntryBestEffort(config, sessionKey, agentId)
       : undefined);
   const sandboxAvailable =
     params.sandboxAvailable ??
     (sessionKey
       ? resolveSandboxRuntimeStatus({
           cfg: config,
+          agentId,
           sessionKey,
         }).sandboxed
       : false);
-  const agentId = resolvePolicyAgentId({ config, sessionKey, agentId: params.agentId });
   const agentExec = resolvePolicyAgentExec({ config, agentId });
   const globalExec = config.tools?.exec;
   const requestedExecHost =
@@ -194,9 +200,17 @@ function resolveEffectiveExecHost(params: {
   return params.requestedExecHost;
 }
 
-function readRuntimeSessionEntryBestEffort(sessionKey: string): SessionEntry | undefined {
+function readRuntimeSessionEntryBestEffort(
+  config: OpenClawConfig,
+  sessionKey: string,
+  agentId: string,
+): SessionEntry | undefined {
   try {
-    return getSessionEntry({ sessionKey, hydrateSkillPromptRefs: false });
+    const storePath = resolveStorePath(config.session?.store, { agentId });
+    return resolveSessionStoreEntry({
+      store: loadSessionStore(storePath, { skipCache: true }),
+      sessionKey,
+    }).existing;
   } catch {
     return undefined;
   }

extensions/codex/src/app-server/native-hook-relay.ts

@@ -13,7 +13,6 @@ import {
   addTimerTimeoutGraceMs,
   finiteSecondsToTimerSafeMilliseconds,
 } from "openclaw/plugin-sdk/number-runtime";
-import type { CodexAppServerRuntimeOptions } from "./config.js";
 import type { JsonObject, JsonValue } from "./protocol.js";
 
 /** Codex hook events that can be registered through OpenClaw's native relay. */
@@ -24,8 +23,6 @@ export const CODEX_NATIVE_HOOK_RELAY_EVENTS: readonly NativeHookRelayEvent[] = [
   "before_agent_finalize",
 ] as const;
 
-const CODEX_NATIVE_HOOK_RELAY_EVENTS_WITH_APP_SERVER_APPROVALS =
-  CODEX_NATIVE_HOOK_RELAY_EVENTS.filter((event) => event !== "permission_request");
 const CODEX_NATIVE_HOOK_RELAY_MIN_TTL_MS = 30 * 60_000;
 /** Extra relay lifetime after the expected turn budget, preventing late hook drops. */
 export const CODEX_NATIVE_HOOK_RELAY_TTL_GRACE_MS = 5 * 60_000;
@@ -149,9 +146,8 @@ export function createCodexNativeHookRelay(params: {
     allowedEvents: params.events,
     ttlMs: resolveCodexNativeHookRelayTtlMs({
       explicitTtlMs: params.options?.ttlMs,
-      attemptTimeoutMs: params.attemptTimeoutMs,
-      startupTimeoutMs: params.startupTimeoutMs,
-      turnStartTimeoutMs: params.turnStartTimeoutMs,
+      operationBudgetMs:
+        params.attemptTimeoutMs + params.startupTimeoutMs + params.turnStartTimeoutMs,
     }),
     signal: params.signal,
     command: {
@@ -163,38 +159,27 @@ export function createCodexNativeHookRelay(params: {
   });
 }
 
-/** Selects the native hook events Codex should install for the current approval mode. */
+/** Selects the native hook events Codex should install for this thread. */
 export function resolveCodexNativeHookRelayEvents(params: {
   configuredEvents?: readonly NativeHookRelayEvent[];
-  appServer: Pick<CodexAppServerRuntimeOptions, "approvalPolicy">;
 }): readonly NativeHookRelayEvent[] {
   if (params.configuredEvents?.length) {
     return params.configuredEvents;
   }
-  // Codex emits PermissionRequest before the app-server approval reviewer has
-  // resolved the command. In native approval modes, let Codex's app-server
-  // approval bridge own the real escalation instead of surfacing a stale
-  // pre-guardian OpenClaw plugin approval prompt.
-  return params.appServer.approvalPolicy === "never"
-    ? CODEX_NATIVE_HOOK_RELAY_EVENTS
-    : CODEX_NATIVE_HOOK_RELAY_EVENTS_WITH_APP_SERVER_APPROVALS;
+  // Thread config is fixed before Codex reports the authoritative provider.
+  // Install the stable superset; the relay defers permission prompts from guarded turns.
+  return CODEX_NATIVE_HOOK_RELAY_EVENTS;
 }
 
 /** Derives the native hook relay TTL from the turn budget unless explicitly configured. */
 export function resolveCodexNativeHookRelayTtlMs(params: {
   explicitTtlMs: number | undefined;
-  attemptTimeoutMs: number;
-  startupTimeoutMs: number;
-  turnStartTimeoutMs: number;
+  operationBudgetMs: number;
 }): number {
   if (params.explicitTtlMs !== undefined) {
     return params.explicitTtlMs;
   }
-  const relayBudgetMs =
-    params.attemptTimeoutMs +
-    params.startupTimeoutMs +
-    params.turnStartTimeoutMs +
-    CODEX_NATIVE_HOOK_RELAY_TTL_GRACE_MS;
+  const relayBudgetMs = params.operationBudgetMs + CODEX_NATIVE_HOOK_RELAY_TTL_GRACE_MS;
   return Math.max(CODEX_NATIVE_HOOK_RELAY_MIN_TTL_MS, Math.floor(relayBudgetMs));
 }
 

extensions/codex/src/app-server/native-subagent-notification.test.ts

@@ -4,6 +4,7 @@ import {
   extractCodexNativeSubagentCompletions,
   extractCodexNativeSubagentCompletionsFromText,
 } from "./native-subagent-notification.js";
+import type { CodexServerNotification } from "./protocol.js";
 
 function trustedInterAgentNotification(params: {
   agentPath: string;
@@ -35,6 +36,29 @@ function trustedInterAgentNotification(params: {
   };
 }
 
+function trustedAgentMessageNotification(params: {
+  agentPath: string;
+  text?: string;
+  encryptedContent?: string;
+}): CodexServerNotification {
+  return {
+    method: "rawResponseItem/completed",
+    params: {
+      threadId: "parent-thread",
+      item: {
+        type: "agent_message",
+        author: params.agentPath,
+        recipient: "/root",
+        content: [
+          params.encryptedContent
+            ? { type: "encrypted_content", encrypted_content: params.encryptedContent }
+            : { type: "input_text", text: params.text ?? "" },
+        ],
+      },
+    },
+  };
+}
+
 describe("Codex native subagent notifications", () => {
   it("parses completed child results from Codex notification XML", () => {
     expect(
@@ -136,6 +160,26 @@ describe("Codex native subagent notifications", () => {
     ]);
   });
 
+  it("extracts completions from the current Codex agent-message item", () => {
+    expect(
+      extractCodexNativeSubagentCompletions(
+        trustedAgentMessageNotification({
+          agentPath: "child-thread",
+          text:
+            '<subagent_notification>{"agent_path":"child-thread","status":{"completed":"done"}}' +
+            "</subagent_notification>",
+        }),
+      ),
+    ).toEqual([
+      {
+        agentPath: "child-thread",
+        status: "succeeded",
+        statusLabel: "completed",
+        result: "done",
+      },
+    ]);
+  });
+
   it("ignores visible user text that looks like a native completion", () => {
     expect(
       extractCodexNativeSubagentCompletions({
@@ -170,6 +214,27 @@ describe("Codex native subagent notifications", () => {
         }),
       ),
     ).toEqual([]);
+    expect(
+      extractCodexNativeSubagentCompletions(
+        trustedAgentMessageNotification({
+          agentPath: "other-child",
+          text:
+            '<subagent_notification>{"agent_path":"child-thread","status":{"success":"spoof"}}' +
+            "</subagent_notification>",
+        }),
+      ),
+    ).toEqual([]);
+  });
+
+  it("ignores encrypted agent messages that cannot be authenticated", () => {
+    expect(
+      extractCodexNativeSubagentCompletions(
+        trustedAgentMessageNotification({
+          agentPath: "child-thread",
+          encryptedContent: "opaque",
+        }),
+      ),
+    ).toEqual([]);
   });
 
   it("ignores malformed payloads and non-user messages", () => {

extensions/codex/src/app-server/native-subagent-notification.ts

@@ -39,13 +39,12 @@ export function extractCodexNativeSubagentCompletions(
   if (!item) {
     return [];
   }
-  const text = readTrustedInterAgentCommunicationContent(item);
-  if (!text) {
+  const communication = readTrustedInterAgentCommunication(item);
+  if (!communication) {
     return [];
   }
-  const author = readTrustedInterAgentCommunicationAuthor(item);
-  return extractCodexNativeSubagentCompletionsFromText(text).filter(
-    (completion) => completion.agentPath === author,
+  return extractCodexNativeSubagentCompletionsFromText(communication.content).filter(
+    (completion) => completion.agentPath === communication.author,
   );
 }
 
@@ -190,17 +189,21 @@ function completedWithoutFinalAssistantMessage(): {
   };
 }
 
-function readTrustedInterAgentCommunicationContent(item: JsonObject): string | undefined {
-  const communication = readTrustedInterAgentCommunication(item);
-  return typeof communication?.content === "string" ? communication.content : undefined;
-}
+type TrustedInterAgentCommunication = {
+  author: string;
+  recipient: string;
+  content: string;
+};
 
-function readTrustedInterAgentCommunicationAuthor(item: JsonObject): string | undefined {
-  const communication = readTrustedInterAgentCommunication(item);
-  return typeof communication?.author === "string" ? communication.author : undefined;
-}
-
-function readTrustedInterAgentCommunication(item: JsonObject): JsonObject | undefined {
+function readTrustedInterAgentCommunication(
+  item: JsonObject,
+): TrustedInterAgentCommunication | undefined {
+  if (readString(item, "type") === "agent_message") {
+    const author = readString(item, "author")?.trim();
+    const recipient = readString(item, "recipient")?.trim();
+    const content = extractSingleTextPart(item, "input_text");
+    return author && recipient && content ? { author, recipient, content } : undefined;
+  }
   if (
     readString(item, "type") !== "message" ||
     readString(item, "role") !== "assistant" ||
@@ -208,7 +211,7 @@ function readTrustedInterAgentCommunication(item: JsonObject): JsonObject | unde
   ) {
     return undefined;
   }
-  const text = extractSingleTextPart(item);
+  const text = extractSingleTextPart(item, "output_text", "text");
   if (!text) {
     return undefined;
   }
@@ -221,18 +224,20 @@ function readTrustedInterAgentCommunication(item: JsonObject): JsonObject | unde
   if (!isJsonObject(parsed)) {
     return undefined;
   }
+  const author = typeof parsed.author === "string" ? parsed.author.trim() : "";
+  const recipient = typeof parsed.recipient === "string" ? parsed.recipient.trim() : "";
   if (
-    typeof parsed.author !== "string" ||
-    typeof parsed.recipient !== "string" ||
+    !author ||
+    !recipient ||
     typeof parsed.content !== "string" ||
     parsed.trigger_turn !== false
   ) {
     return undefined;
   }
-  return parsed;
+  return { author, recipient, content: parsed.content };
 }
 
-function extractSingleTextPart(item: JsonObject): string | undefined {
+function extractSingleTextPart(item: JsonObject, ...acceptedTypes: string[]): string | undefined {
   const content = item.content;
   if (!Array.isArray(content) || content.length !== 1) {
     return undefined;
@@ -242,7 +247,7 @@ function extractSingleTextPart(item: JsonObject): string | undefined {
     return undefined;
   }
   const type = readString(entry, "type");
-  if (type !== "output_text" && type !== "text") {
+  if (!type || !acceptedTypes.includes(type)) {
     return undefined;
   }
   return readString(entry, "text")?.trim();

extensions/codex/src/app-server/native-subagent-task-mirror.test.ts

@@ -26,7 +26,6 @@ describe("CodexNativeSubagentTaskMirror", () => {
       },
       runtime,
     );
-
     mirror.handleNotification({
       method: "thread/started",
       params: {
@@ -82,7 +81,6 @@ describe("CodexNativeSubagentTaskMirror", () => {
       },
       runtime,
     );
-
     mirror.handleNotification({
       method: "thread/started",
       params: {
@@ -105,6 +103,45 @@ describe("CodexNativeSubagentTaskMirror", () => {
     expect(runtime.finalizeTaskRunByRunId).not.toHaveBeenCalled();
   });
 
+  it("finalizes collab completion when no authoritative result path is available", () => {
+    const runtime = createRuntime();
+    const mirror = new CodexNativeSubagentTaskMirror(
+      {
+        parentThreadId: "parent-thread",
+        requesterSessionKey: "agent:main:main",
+        now: () => 44_000,
+      },
+      runtime,
+    );
+
+    mirror.handleNotification({
+      method: "item/completed",
+      params: {
+        threadId: "parent-thread",
+        item: {
+          type: "collabAgentToolCall",
+          tool: "spawn_agent",
+          prompt: "inspect one thing",
+          agentsStates: {
+            "child-thread": {
+              status: "completed",
+              message: "done",
+            },
+          },
+        },
+      },
+    });
+
+    expect(runtime.finalizeTaskRunByRunId).toHaveBeenCalledWith({
+      runId: "codex-thread:child-thread",
+      status: "succeeded",
+      endedAt: 44_000,
+      lastEventAt: 44_000,
+      progressSummary: "done",
+      terminalSummary: "done",
+    });
+  });
+
   it("deduplicates repeated thread-started notifications for the same child thread", () => {
     const runtime = createRuntime();
     const mirror = new CodexNativeSubagentTaskMirror(
@@ -147,7 +184,6 @@ describe("CodexNativeSubagentTaskMirror", () => {
       },
       runtime,
     );
-
     mirror.handleNotification({
       method: "thread/status/changed",
       params: {
@@ -163,15 +199,13 @@ describe("CodexNativeSubagentTaskMirror", () => {
       },
     });
 
-    expect(runtime.finalizeTaskRunByRunId).toHaveBeenNthCalledWith(1, {
+    expect(runtime.recordTaskRunProgressByRunId).toHaveBeenCalledWith({
       runId: codexNativeSubagentRunId("child-thread"),
-      status: "succeeded",
-      endedAt: 30_000,
       lastEventAt: 30_000,
       progressSummary: "Codex native subagent is idle.",
-      terminalSummary: "Codex native subagent finished.",
     });
-    expect(runtime.finalizeTaskRunByRunId).toHaveBeenNthCalledWith(2, {
+    expect(runtime.finalizeTaskRunByRunId).toHaveBeenCalledTimes(1);
+    expect(runtime.finalizeTaskRunByRunId).toHaveBeenCalledWith({
       runId: codexNativeSubagentRunId("failed-child"),
       status: "failed",
       endedAt: 30_000,
@@ -192,7 +226,7 @@ describe("CodexNativeSubagentTaskMirror", () => {
       },
       runtime,
     );
-
+    mirror.markAuthoritativeCompletionExpected("child-thread");
     mirror.handleNotification({
       method: "item/completed",
       params: {
@@ -249,14 +283,12 @@ describe("CodexNativeSubagentTaskMirror", () => {
       lastEventAt: 40_000,
       progressSummary: "Codex native subagent is initializing.",
     });
-    expect(runtime.finalizeTaskRunByRunId).toHaveBeenCalledWith({
+    expect(runtime.recordTaskRunProgressByRunId).toHaveBeenCalledWith({
       runId: "codex-thread:child-thread",
-      status: "succeeded",
-      endedAt: 40_000,
       lastEventAt: 40_000,
       progressSummary: "done",
-      terminalSummary: "done",
     });
+    expect(runtime.finalizeTaskRunByRunId).not.toHaveBeenCalled();
   });
 
   it("uses the notification thread id when collab agent items omit sender thread id", () => {
@@ -269,7 +301,6 @@ describe("CodexNativeSubagentTaskMirror", () => {
       },
       runtime,
     );
-
     mirror.handleNotification({
       method: "item/started",
       params: {
@@ -301,6 +332,7 @@ describe("CodexNativeSubagentTaskMirror", () => {
       },
       runtime,
     );
+    mirror.markAuthoritativeCompletionExpected("child-thread");
 
     mirror.handleNotification({
       method: "item/completed",
@@ -326,13 +358,13 @@ describe("CodexNativeSubagentTaskMirror", () => {
         task: "inspect one thing",
       }),
     );
-    expect(runtime.finalizeTaskRunByRunId).toHaveBeenCalledWith(
+    expect(runtime.recordTaskRunProgressByRunId).toHaveBeenCalledWith(
       expect.objectContaining({
         runId: "codex-thread:child-thread",
-        status: "succeeded",
-        terminalSummary: "done",
+        progressSummary: "done",
       }),
     );
+    expect(runtime.finalizeTaskRunByRunId).not.toHaveBeenCalled();
   });
 
   it("finalizes stale collab agent state from the blocked tool call status", () => {
@@ -459,7 +491,7 @@ describe("CodexNativeSubagentTaskMirror", () => {
     expect(runtime.finalizeTaskRunByRunId).not.toHaveBeenCalled();
   });
 
-  it("preserves a completed collab agent message when the thread later goes idle", () => {
+  it("records completed collab agent and idle thread states as progress only", () => {
     const runtime = createRuntime();
     const mirror = new CodexNativeSubagentTaskMirror(
       {
@@ -469,6 +501,7 @@ describe("CodexNativeSubagentTaskMirror", () => {
       },
       runtime,
     );
+    mirror.markAuthoritativeCompletionExpected("child-thread");
 
     mirror.handleNotification({
       method: "item/completed",
@@ -496,18 +529,60 @@ describe("CodexNativeSubagentTaskMirror", () => {
       },
     });
 
-    expect(runtime.finalizeTaskRunByRunId).toHaveBeenCalledTimes(1);
-    expect(runtime.finalizeTaskRunByRunId).toHaveBeenCalledWith({
+    expect(runtime.recordTaskRunProgressByRunId).toHaveBeenCalledTimes(1);
+    expect(runtime.recordTaskRunProgressByRunId).toHaveBeenCalledWith({
       runId: "codex-thread:child-thread",
-      status: "succeeded",
-      endedAt: 50_000,
       lastEventAt: 50_000,
       progressSummary: "No user task is specified.",
-      terminalSummary: "No user task is specified.",
     });
+    expect(runtime.finalizeTaskRunByRunId).not.toHaveBeenCalled();
   });
 
-  it("lets terminal collab agent state correct an earlier idle thread status", () => {
+  it("keeps terminal collab failures from rewriting authoritative completion", () => {
+    const runtime = createRuntime();
+    const mirror = new CodexNativeSubagentTaskMirror(
+      {
+        parentThreadId: "parent-thread",
+        requesterSessionKey: "agent:main:main",
+        now: () => 52_000,
+      },
+      runtime,
+    );
+
+    mirror.handleNotification({
+      method: "item/completed",
+      params: {
+        item: {
+          type: "collabAgentToolCall",
+          tool: "spawnAgent",
+          senderThreadId: "parent-thread",
+          receiverThreadIds: ["child-thread"],
+          prompt: "write the proof file",
+        },
+      },
+    });
+    mirror.markAuthoritativeCompletion("child-thread");
+    mirror.handleNotification({
+      method: "item/completed",
+      params: {
+        item: {
+          type: "collabAgentToolCall",
+          tool: "wait",
+          senderThreadId: "parent-thread",
+          agentsStates: {
+            "child-thread": {
+              status: "errored",
+              message: "later turn failed",
+            },
+          },
+        },
+      },
+    });
+
+    expect(runtime.finalizeTaskRunByRunId).not.toHaveBeenCalled();
+  });
+
+  it("lets terminal collab agent state finalize after an earlier idle thread status", () => {
     const runtime = createRuntime();
     const mirror = new CodexNativeSubagentTaskMirror(
       {
@@ -545,15 +620,13 @@ describe("CodexNativeSubagentTaskMirror", () => {
       },
     });
 
-    expect(runtime.finalizeTaskRunByRunId).toHaveBeenNthCalledWith(1, {
+    expect(runtime.recordTaskRunProgressByRunId).toHaveBeenCalledWith({
       runId: "codex-thread:child-thread",
-      status: "succeeded",
-      endedAt: 55_000,
       lastEventAt: 55_000,
       progressSummary: "Codex native subagent is idle.",
-      terminalSummary: "Codex native subagent finished.",
     });
-    expect(runtime.finalizeTaskRunByRunId).toHaveBeenNthCalledWith(2, {
+    expect(runtime.finalizeTaskRunByRunId).toHaveBeenCalledTimes(1);
+    expect(runtime.finalizeTaskRunByRunId).toHaveBeenCalledWith({
       runId: "codex-thread:child-thread",
       status: "failed",
       endedAt: 55_000,
@@ -574,6 +647,7 @@ describe("CodexNativeSubagentTaskMirror", () => {
       },
       runtime,
     );
+    mirror.markAuthoritativeCompletionExpected("child-thread");
 
     mirror.handleNotification({
       method: "item/completed",
@@ -614,13 +688,11 @@ describe("CodexNativeSubagentTaskMirror", () => {
       lastEventAt: 60_000,
       progressSummary: "Codex native subagent is initializing.",
     });
-    expect(runtime.finalizeTaskRunByRunId).toHaveBeenCalledWith({
+    expect(runtime.recordTaskRunProgressByRunId).toHaveBeenCalledWith({
       runId: "codex-thread:child-thread",
-      status: "succeeded",
-      endedAt: 60_000,
       lastEventAt: 60_000,
       progressSummary: "done",
-      terminalSummary: "done",
     });
+    expect(runtime.finalizeTaskRunByRunId).not.toHaveBeenCalled();
   });
 });

extensions/codex/src/app-server/native-subagent-task-mirror.ts

@@ -36,6 +36,8 @@ export class CodexNativeSubagentTaskMirror {
   private readonly mirroredThreadIds = new Set<string>();
   private readonly failedMirrorThreadIds = new Set<string>();
   private readonly terminalRunIds = new Set<string>();
+  private readonly authoritativeRunIds = new Set<string>();
+  private readonly expectedAuthoritativeRunIds = new Set<string>();
   private readonly now: () => number;
 
   constructor(
@@ -45,6 +47,20 @@ export class CodexNativeSubagentTaskMirror {
     this.now = params.now ?? Date.now;
   }
 
+  markAuthoritativeCompletion(childThreadId: string): void {
+    const runId = codexNativeSubagentRunId(childThreadId);
+    // Run identity is per child thread, not per resumed turn. Once the monitor
+    // finalizes and delivers this task, later mirror events must not rewrite it.
+    this.authoritativeRunIds.add(runId);
+    this.terminalRunIds.add(runId);
+  }
+
+  markAuthoritativeCompletionExpected(childThreadId: string): void {
+    // The monitor recovers the authoritative result through app-server history.
+    // Keep collab completion as progress so it cannot finalize stale text first.
+    this.expectedAuthoritativeRunIds.add(codexNativeSubagentRunId(childThreadId));
+  }
+
   handleNotification(notification: CodexServerNotification): void {
     const params = isJsonObject(notification.params) ? notification.params : undefined;
     if (!params) {
@@ -109,6 +125,7 @@ export class CodexNativeSubagentTaskMirror {
     }
     this.failedMirrorThreadIds.delete(threadId);
     this.terminalRunIds.delete(runId);
+    this.authoritativeRunIds.delete(runId);
     this.applyStatus(threadId, thread.status);
   }
 
@@ -129,6 +146,9 @@ export class CodexNativeSubagentTaskMirror {
       return;
     }
     const runId = codexNativeSubagentRunId(threadId);
+    if (this.authoritativeRunIds.has(runId)) {
+      return;
+    }
     if (this.terminalRunIds.has(runId) && statusType !== "systemError") {
       return;
     }
@@ -143,13 +163,10 @@ export class CodexNativeSubagentTaskMirror {
     }
     if (statusType === "idle") {
       this.terminalRunIds.add(runId);
-      this.runtime.finalizeTaskRunByRunId({
+      this.runtime.recordTaskRunProgressByRunId({
         runId,
-        status: "succeeded",
-        endedAt: eventAt,
         lastEventAt: eventAt,
         progressSummary: "Codex native subagent is idle.",
-        terminalSummary: "Codex native subagent finished.",
       });
       return;
     }
@@ -257,6 +274,7 @@ export class CodexNativeSubagentTaskMirror {
     }
     this.failedMirrorThreadIds.delete(normalizedThreadId);
     this.terminalRunIds.delete(runId);
+    this.authoritativeRunIds.delete(runId);
   }
 
   private applyCollabAgentStatus(
@@ -272,6 +290,9 @@ export class CodexNativeSubagentTaskMirror {
       return;
     }
     const runId = codexNativeSubagentRunId(threadId);
+    if (this.authoritativeRunIds.has(runId)) {
+      return;
+    }
     if (this.terminalRunIds.has(runId) && isNonTerminalAgentStateStatus(normalizedStatus)) {
       return;
     }
@@ -290,14 +311,25 @@ export class CodexNativeSubagentTaskMirror {
     }
     if (normalizedStatus === "completed") {
       this.terminalRunIds.add(runId);
-      this.runtime.finalizeTaskRunByRunId({
-        runId,
-        status: "succeeded",
-        endedAt: eventAt,
-        lastEventAt: eventAt,
-        progressSummary: trimOptional(message) ?? "Codex native subagent completed.",
-        terminalSummary: trimOptional(message) ?? "Codex native subagent finished.",
-      });
+      const summary = trimOptional(message) ?? "Codex native subagent completed.";
+      if (this.expectedAuthoritativeRunIds.has(runId)) {
+        this.runtime.recordTaskRunProgressByRunId({
+          runId,
+          lastEventAt: eventAt,
+          progressSummary: summary,
+        });
+      } else {
+        // Remote V1 has no trusted completion envelope or local transcript.
+        // Its collab-completed state is therefore the terminal fallback.
+        this.runtime.finalizeTaskRunByRunId({
+          runId,
+          status: "succeeded",
+          endedAt: eventAt,
+          lastEventAt: eventAt,
+          progressSummary: summary,
+          terminalSummary: summary,
+        });
+      }
       return;
     }
     if (normalizedStatus === "blocked") {

extensions/codex/src/app-server/notification-correlation.ts

@@ -2,28 +2,7 @@
  * Correlates Codex app-server notifications with the active thread/turn so
  * projectors can ignore global or stale events without losing diagnostics.
  */
-import {
-  isJsonObject,
-  type CodexServerNotification,
-  type JsonObject,
-  type JsonValue,
-} from "./protocol.js";
-
-/** Debug-friendly correlation summary for a Codex app-server notification. */
-export type CodexNotificationCorrelation = {
-  method: string;
-  paramsKeys?: string[];
-  activeThreadId: string;
-  activeTurnId?: string;
-  threadId?: string;
-  turnId?: string;
-  nestedTurnThreadId?: string;
-  nestedTurnId?: string;
-  turnStatus?: string;
-  turnItemCount?: number;
-  matchesActiveThread: boolean;
-  matchesActiveTurn?: boolean;
-};
+import { isJsonObject, type JsonObject, type JsonValue } from "./protocol.js";
 
 /** Returns true when a notification payload belongs to the exact active thread and turn. */
 export function isCodexNotificationForTurn(
@@ -40,9 +19,10 @@ export function isCodexNotificationForTurn(
   );
 }
 
-/** Reads a thread id from either top-level notification params or nested turn payloads. */
+/** Reads a thread id from canonical top-level or nested thread payloads. */
 export function readCodexNotificationThreadId(record: JsonObject): string | undefined {
-  return readNestedTurnThreadId(record) ?? readString(record, "threadId");
+  const thread = isJsonObject(record.thread) ? record.thread : undefined;
+  return readString(record, "threadId") ?? (thread ? readString(thread, "id") : undefined);
 }
 
 /** Reads a turn id from either top-level notification params or nested turn payloads. */
@@ -50,50 +30,11 @@ export function readCodexNotificationTurnId(record: JsonObject): string | undefi
   return readNestedTurnId(record) ?? readString(record, "turnId");
 }
 
-/** Builds structured correlation details for logs when notification routing is ambiguous. */
-export function describeCodexNotificationCorrelation(
-  notification: CodexServerNotification,
-  active: { threadId: string; turnId?: string },
-): CodexNotificationCorrelation {
-  const params = isJsonObject(notification.params) ? notification.params : undefined;
-  const turn = params && isJsonObject(params.turn) ? params.turn : undefined;
-  const threadId = params ? readString(params, "threadId") : undefined;
-  const turnId = params ? readString(params, "turnId") : undefined;
-  const nestedTurnThreadId = turn ? readString(turn, "threadId") : undefined;
-  const nestedTurnId = turn ? readString(turn, "id") : undefined;
-  const resolvedThreadId = params ? readCodexNotificationThreadId(params) : undefined;
-  const resolvedTurnId = params ? readCodexNotificationTurnId(params) : undefined;
-  const matchesActiveThread = resolvedThreadId === active.threadId;
-  const matchesActiveTurn = active.turnId
-    ? matchesActiveThread && resolvedTurnId === active.turnId
-    : undefined;
-  const items = turn?.items;
-  return {
-    method: notification.method,
-    ...(params ? { paramsKeys: Object.keys(params).toSorted() } : {}),
-    activeThreadId: active.threadId,
-    ...(active.turnId ? { activeTurnId: active.turnId } : {}),
-    ...(threadId ? { threadId } : {}),
-    ...(turnId ? { turnId } : {}),
-    ...(nestedTurnThreadId ? { nestedTurnThreadId } : {}),
-    ...(nestedTurnId ? { nestedTurnId } : {}),
-    ...(turn ? { turnStatus: readString(turn, "status") } : {}),
-    ...(Array.isArray(items) ? { turnItemCount: items.length } : {}),
-    matchesActiveThread,
-    ...(matchesActiveTurn === undefined ? {} : { matchesActiveTurn }),
-  };
-}
-
 function readNestedTurnId(record: JsonObject): string | undefined {
   const turn = record.turn;
   return isJsonObject(turn) ? readString(turn, "id") : undefined;
 }
 
-function readNestedTurnThreadId(record: JsonObject): string | undefined {
-  const turn = record.turn;
-  return isJsonObject(turn) ? readString(turn, "threadId") : undefined;
-}
-
 function readString(record: JsonObject, key: string): string | undefined {
   const value = record[key];
   return typeof value === "string" && value.trim() ? value.trim() : undefined;

extensions/codex/src/app-server/prompt-sections.ts

@@ -0,0 +1,4 @@
+/** Joins non-empty Codex prompt sections with stable paragraph spacing. */
+export function joinCodexPromptSections(...sections: Array<string | undefined>): string {
+  return sections.filter((section): section is string => Boolean(section?.trim())).join("\n\n");
+}

extensions/codex/src/app-server/protocol-validators.test.ts

@@ -60,14 +60,6 @@ describe("assertCodexThreadStartResponse", () => {
     expect(result.thread.sessionId).toBe("session-1");
   });
 
-  it("normalizes missing id from sessionId", () => {
-    const response = makeMinimalResponse({ id: undefined, sessionId: "session-1" });
-    delete (response.thread as Record<string, unknown>).id;
-    const result = assertCodexThreadStartResponse(response);
-    expect(result.thread.id).toBe("session-1");
-    expect(result.thread.sessionId).toBe("session-1");
-  });
-
   it("throws on invalid response", () => {
     expect(() => assertCodexThreadStartResponse({})).toThrow("Invalid Codex app-server");
   });

extensions/codex/src/app-server/protocol-validators.ts

@@ -8,7 +8,6 @@ import errorNotificationSchema from "./protocol-generated/json/v2/ErrorNotificat
 import modelListResponseSchema from "./protocol-generated/json/v2/ModelListResponse.json" with { type: "json" };
 import threadResumeResponseSchema from "./protocol-generated/json/v2/ThreadResumeResponse.json" with { type: "json" };
 import threadStartResponseSchema from "./protocol-generated/json/v2/ThreadStartResponse.json" with { type: "json" };
-import turnCompletedNotificationSchema from "./protocol-generated/json/v2/TurnCompletedNotification.json" with { type: "json" };
 import turnStartResponseSchema from "./protocol-generated/json/v2/TurnStartResponse.json" with { type: "json" };
 import type {
   CodexDynamicToolCallParams,
@@ -18,7 +17,6 @@ import type {
   CodexThreadResumeResponse,
   CodexThreadStartResponse,
   CodexTurn,
-  CodexTurnCompletedNotification,
   CodexTurnStartResponse,
 } from "./protocol.js";
 
@@ -221,9 +219,6 @@ const validateThreadResumeResponse = compileCodexSchema<CodexThreadResumeRespons
 );
 const validateThreadStartResponse =
   compileCodexSchema<CodexThreadStartResponse>(threadStartResponseSchema);
-const validateTurnCompletedNotification = compileCodexSchema<CodexTurnCompletedNotification>(
-  turnCompletedNotificationSchema,
-);
 const validateTurnStartResponse =
   compileCodexSchema<CodexTurnStartResponse>(turnStartResponseSchema);
 
@@ -298,19 +293,6 @@ export function readCodexTurn(value: unknown): CodexTurn | undefined {
   return response?.turn;
 }
 
-/** Reads a Codex turn/completed notification payload if it matches the protocol schema. */
-export function readCodexTurnCompletedNotification(
-  value: unknown,
-): CodexTurnCompletedNotification | undefined {
-  return readCodexShape(
-    validateTurnCompletedNotification,
-    normalizeWithDefaults(
-      turnCompletedNotificationSchema,
-      normalizeTurnCompletedNotification(value),
-    ),
-  );
-}
-
 function assertCodexShape<T>(validate: CodexValidator<T>, value: unknown, label: string): T {
   if (validate.check(value)) {
     return value;
@@ -375,9 +357,6 @@ function normalizeThreadResponse(value: unknown): unknown {
     if (typeof t.id === "string" && typeof t.sessionId !== "string") {
       return { ...value, thread: { ...thread, sessionId: t.id } };
     }
-    if (typeof t.sessionId === "string" && typeof t.id !== "string") {
-      return { ...value, thread: { ...thread, id: t.sessionId } };
-    }
   }
   return value;
 }
@@ -392,16 +371,6 @@ function normalizeTurnStartResponse(value: unknown): unknown {
   };
 }
 
-function normalizeTurnCompletedNotification(value: unknown): unknown {
-  if (!value || typeof value !== "object" || Array.isArray(value) || !("turn" in value)) {
-    return value;
-  }
-  return {
-    ...value,
-    turn: normalizeTurn((value as { turn?: unknown }).turn),
-  };
-}
-
 function formatValidationErrors(validate: CodexValidator<unknown>, value: unknown): string {
   const errors = validate.errors(value);
   if (!errors || errors.length === 0) {