refactor(codex): simplify native context ownership

.agents/skills/discord-user-post/SKILL.md

@@ -1,51 +0,0 @@
----
-name: discord-user-post
-description: Post an approved message as the logged-in Discord user through the Discord desktop app. Use for release announcements or other direct user-authored Discord posts; not for OpenClaw channel sends, bots, webhooks, relays, agent sessions, or archive search.
----
-
-# Discord User Post
-
-Use `$computer-use` to operate `/Applications/Discord.app` in the user's
-existing logged-in session. This workflow represents the user directly.
-
-## Prepare
-
-1. Draft the complete final message outside Discord.
-2. Confirm the intended server and channel with the user when either is
-   ambiguous.
-3. Open Discord and navigate to the exact destination without entering the
-   message.
-4. Verify the visible server name, channel header, and logged-in account.
-
-Do not infer the target from unrelated Discord content. Stop if Discord is not
-logged in, the account is wrong, or the exact destination cannot be verified.
-
-## Confirm and Post
-
-Posting is representational communication. Follow the `$computer-use`
-confirmation policy even when the user previously asked for an announcement:
-
-1. Show the user the exact final body and verified destination.
-2. Request action-time confirmation before typing into Discord.
-3. After confirmation, enter the approved body unchanged.
-4. Visually inspect the composed message and destination again.
-5. Send once.
-
-If the body or destination changes after confirmation, request confirmation
-again before sending.
-
-## Verify
-
-- Confirm the message appears once, from the user's account, in the intended
-  channel.
-- Report the server, channel, and visible send result.
-- Do not edit, delete, react, or send a follow-up without the corresponding
-  user instruction and confirmation.
-
-## Guardrails
-
-- Never use `openclaw message`, an OpenClaw agent, a Discord bot, webhook, relay,
-  or token for this workflow.
-- Never expose private Discord content or account details in public output.
-- Never send a draft, partial message, duplicate, or unreviewed attachment.
-- For Discord archive/history/search, use `$discrawl` instead.

.agents/skills/discord-user-post/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Discord User Post"
-  short_description: "Post approved messages through the logged-in Discord app"
-  default_prompt: "Post this approved message as me through the logged-in Discord desktop app."

.agents/skills/openclaw-qa-testing/SKILL.md

@@ -13,7 +13,7 @@ Use this skill for `qa-lab` / `qa-channel` work. Repo-local QA only.
 - `docs/help/testing.md`
 - `docs/channels/qa-channel.md`
 - `qa/README.md`
-- `qa/scenarios/index.yaml`
+- `qa/scenarios/index.md`
 - `extensions/qa-lab/src/suite.ts`
 - `extensions/qa-lab/src/character-eval.ts`
 
@@ -198,9 +198,7 @@ pnpm openclaw qa character-eval \
 - Judges default to `openai/gpt-5.4,thinking=xhigh,fast` and `anthropic/claude-opus-4-6,thinking=high`.
 - Report includes judge ranking, run stats, durations, and full transcripts; do not include raw judge replies. Duration is benchmark context, not a grading signal.
 - Candidate and judge concurrency default to 16. Use `--concurrency <n>` and `--judge-concurrency <n>` to override when local gateways or provider limits need a gentler lane.
-- Scenario source is YAML-only under `qa/scenarios/`: use `index.yaml` and
-  per-scenario `*.yaml` files with top-level `title`, `scenario`, and optional
-  `flow`. Never add fenced `qa-scenario` / `qa-flow` Markdown files.
+- Scenario source should stay markdown-driven under `qa/scenarios/`.
 - For isolated character/persona evals, write the persona into `SOUL.md` and blank `IDENTITY.md` in the scenario flow. Use `SOUL.md + IDENTITY.md` only when intentionally testing how the normal OpenClaw identity combines with the character.
 - Keep prompts natural and task-shaped. The candidate model should receive character setup through `SOUL.md`, then normal user turns such as chat, workspace help, and small file tasks; do not ask "how would you react?" or tell the model it is in an eval.
 - Prefer at least one real task, such as creating or editing a tiny workspace artifact, so the transcript captures character under normal tool use instead of pure roleplay.
@@ -236,8 +234,7 @@ pnpm openclaw qa manual \
 
 ## Repo facts
 
-- Seed scenarios live in `qa/scenarios/index.yaml` and
-  `qa/scenarios/<theme>/*.yaml`.
+- Seed scenarios live in `qa/`.
 - Main live runner: `extensions/qa-lab/src/suite.ts`
 - QA lab server: `extensions/qa-lab/src/lab-server.ts`
 - Child gateway harness: `extensions/qa-lab/src/gateway-child.ts`
@@ -265,9 +262,8 @@ pnpm openclaw qa manual \
 
 ## When adding scenarios
 
-- Add or update scenario YAML under `qa/scenarios/`; do not add `.md` scenario
-  files or fenced YAML blocks.
-- Keep kickoff expectations in `qa/scenarios/index.yaml` aligned
+- Add or update scenario markdown under `qa/scenarios/`
+- Keep kickoff expectations in `qa/scenarios/index.md` aligned
 - Add executable coverage in `extensions/qa-lab/src/suite.ts`
 - Prefer end-to-end assertions over mock-only checks
 - Save outputs under `.artifacts/qa-e2e/`

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

@@ -6,8 +6,7 @@ description: "Draft or post OpenClaw beta/stable Discord release announcements f
 # OpenClaw Release Announcement
 
 Use with `release-openclaw-maintainer` after a beta or stable release is live.
-Use with `$discord-user-post` when actually posting to Discord as the logged-in
-user.
+Use with `openclaw-discord` when actually posting to Discord.
 
 ## Evidence First
 
@@ -81,7 +80,6 @@ Fresh installs still point to `https://openclaw.ai`.
 
 ## Posting
 
-When asked to post, use `$discord-user-post` to operate the logged-in Discord
-desktop app as the user. Resolve and visibly verify the exact server/channel,
-inspect the final body, and request action-time confirmation before entering or
-sending it. Never use OpenClaw channel sends, bots, webhooks, relays, or tokens.
+When asked to post, use the configured Discord workflow from
+`openclaw-discord` or the approved OpenClaw relay. Never print tokens.
+For public channels, inspect the final body before sending.

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

@@ -321,7 +321,6 @@ Upgrade with the beta channel.
 Before tagging or publishing, run:
 
 ```bash
-pnpm release:fast-pretag-check
 pnpm check:architecture
 pnpm build
 pnpm ui:build
@@ -330,21 +329,6 @@ pnpm release:check
 pnpm test:install:smoke
 ```
 
-- Treat `pnpm release:fast-pretag-check` as a hard packaging gate. Every
-  publishable plugin must have a non-empty package-root `README.md`, build its
-  package-local runtime, and pass the npm and ClawHub release metadata checks
-  before a tag or publish workflow can start. Do not defer README, entrypoint,
-  or packed-artifact failures to postpublish verification.
-- Before tagging, require green CI for the exact release-candidate SHA, not an
-  earlier branch SHA. Heal every related red CI, release-check, packaging, or
-  root-Dockerfile lane on the release branch, forward-port the fix to `main`,
-  and rerun the affected exact-SHA gates. Never waive a red Docker lane because
-  npm preflight passed.
-- Root Dockerfile proof is mandatory before every beta and stable tag. Run the
-  release `install-smoke` group or equivalent root Dockerfile build for the
-  exact candidate SHA and require it to pass. The tag-triggered Docker Release
-  workflow is post-tag publishing, not the first valid proof that the root
-  Dockerfile can build.
 - Before tagging, diff publishable plugin package manifests against the last
   reachable stable/beta release tag. For every newly publishable package
   (`openclaw.release.publishToNpm: true` or `publishToClawHub: true`) whose
@@ -660,10 +644,9 @@ node --import tsx scripts/openclaw-npm-postpublish-verify.ts <published-version>
    off, live OpenAI off, and regression failure off. Let it run in parallel
    with preflight and validation work.
 10. Run the fast local beta preflight from the release branch before any npm
-    preflight or publish. Require exact-SHA CI and root Dockerfile install-smoke
-    to be green before tagging. Keep the remaining expensive Docker, Parallels,
-    and published-package install/update lanes for after the beta is live unless
-    the operator asks to run them before beta publication.
+    preflight or publish. Keep expensive Docker, Parallels, and published-package
+    install/update lanes for after the beta is live unless the operator asks to
+    run them before beta publication.
 11. For beta releases, skip mac app build/sign/notarize unless beta scope or a
     release blocker specifically requires it. For stable releases, include the
     mac app, signing, notarization, and appcast path.

.github/workflows/ci.yml

@@ -1288,7 +1288,6 @@ jobs:
         env:
           OPENCLAW_LOCAL_CHECK: "0"
           TASK: ${{ matrix.task }}
-          PR_BASE_SHA: ${{ github.event_name == 'pull_request' && github.event.pull_request.base.sha || '' }}
         shell: bash
         run: |
           set -euo pipefail
@@ -1298,10 +1297,6 @@ jobs:
               pnpm tool-display:check
               pnpm check:host-env-policy:swift
               pnpm dup:check:coverage
-              if [ -n "$PR_BASE_SHA" ]; then
-                git fetch --no-tags --depth=1 origin "+${PR_BASE_SHA}:refs/remotes/origin/pr-base"
-                node scripts/report-test-temp-creations.mjs --base refs/remotes/origin/pr-base --head HEAD --no-merge-base
-              fi
               pnpm deps:patches:check
               pnpm lint:webhook:no-low-level-body-read
               pnpm lint:auth:no-pairing-store-group

.github/workflows/ios-periphery-comment.yml

@@ -1,447 +0,0 @@
-name: iOS Periphery Dead Code Comment
-
-on:
-  workflow_run: # zizmor: ignore[dangerous-triggers] trusted PR commenter; job gates repository, source event, workflow name, live open PR, and exact current head before reading artifacts or writing comments
-    workflows: ["iOS Periphery Dead Code"]
-    types: [completed]
-
-env:
-  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
-
-permissions:
-  actions: read
-  contents: read
-  issues: write
-  pull-requests: read
-
-jobs:
-  comment:
-    name: Comment on PR
-    runs-on: ubuntu-24.04
-    if: >
-      github.repository == 'openclaw/openclaw' &&
-      github.event.workflow_run.event == 'pull_request' &&
-      github.event.workflow_run.name == 'iOS Periphery Dead Code'
-    steps:
-      - name: Upsert Periphery PR comment
-        uses: actions/github-script@v9
-        with:
-          script: |
-            const fs = require("node:fs");
-            const os = require("node:os");
-            const path = require("node:path");
-            const childProcess = require("node:child_process");
-
-            const marker = "<!-- openclaw-ios-periphery-dead-code -->";
-            const run = context.payload.workflow_run;
-            const pr = run.pull_requests?.[0];
-            if (!pr) {
-              core.info("No pull request attached to workflow_run.");
-              return;
-            }
-
-            const { owner, repo } = context.repo;
-            const repository = `${owner}/${repo}`;
-            if (run.repository?.full_name !== repository) {
-              core.info(`Skipping workflow_run from ${run.repository?.full_name ?? "unknown repository"}.`);
-              return;
-            }
-            if (run.event !== "pull_request") {
-              core.info(`Skipping workflow_run for ${run.event ?? "unknown"} event.`);
-              return;
-            }
-            if (run.name !== "iOS Periphery Dead Code") {
-              core.info(`Skipping unexpected workflow ${run.name ?? "unknown"}.`);
-              return;
-            }
-
-            const livePull = await github.rest.pulls.get({
-              owner,
-              repo,
-              pull_number: pr.number,
-            });
-            if (livePull.data.state !== "open") {
-              core.info(`Skipping closed PR #${pr.number}.`);
-              return;
-            }
-            if (livePull.data.base?.repo?.full_name !== repository) {
-              core.info(`Skipping PR #${pr.number} targeting ${livePull.data.base?.repo?.full_name ?? "unknown repository"}.`);
-              return;
-            }
-            if (livePull.data.head?.sha !== run.head_sha) {
-              core.info(`Skipping stale run ${run.id}; PR #${pr.number} is now at ${livePull.data.head?.sha}.`);
-              return;
-            }
-
-            const jobs = await github.paginate(github.rest.actions.listJobsForWorkflowRun, {
-              owner,
-              repo,
-              run_id: run.id,
-              filter: "latest",
-              per_page: 100,
-            });
-            const scopeJob = jobs.find((job) => job.name === "Detect iOS scan scope");
-            const scanJob = jobs.find((job) => job.name === "Scan iOS dead code");
-            const scanSkipped =
-              scopeJob?.conclusion === "success" && scanJob?.conclusion === "skipped";
-            if (scanSkipped) {
-              core.info(`Skipping intentionally omitted Periphery scan for PR #${pr.number}.`);
-            }
-
-            const artifacts = scanSkipped
-              ? []
-              : await github.paginate(github.rest.actions.listWorkflowRunArtifacts, {
-                  owner,
-                  repo,
-                  run_id: run.id,
-                  per_page: 100,
-                });
-
-            const readReport = async () => {
-              if (scanSkipped) {
-                return;
-              }
-              const artifactName = `ios-periphery-dead-code-${run.id}-${run.run_attempt}`;
-              const artifact = artifacts.find((item) => item.name === artifactName);
-              if (!artifact) {
-                core.warning(`No ${artifactName} artifact found.`);
-                return;
-              }
-              if (artifact.expired) {
-                core.warning(`${artifactName} artifact expired.`);
-                return;
-              }
-
-              const maxArchiveBytes = 1024 * 1024;
-              const archiveSize = Number(artifact.size_in_bytes);
-              if (!Number.isSafeInteger(archiveSize) || archiveSize < 0 || archiveSize > maxArchiveBytes) {
-                core.warning(`Skipping ${artifactName}; compressed artifact size ${artifact.size_in_bytes ?? "unknown"} exceeds the ${maxArchiveBytes} byte limit.`);
-                return;
-              }
-
-              const archive = await github.rest.actions.downloadArtifact({
-                owner,
-                repo,
-                artifact_id: artifact.id,
-                archive_format: "zip",
-              });
-
-              const dir = fs.mkdtempSync(path.join(os.tmpdir(), "ios-periphery-"));
-              const archivePath = path.join(dir, "artifact.zip");
-              const archiveBuffer = Buffer.from(archive.data);
-              fs.writeFileSync(archivePath, archiveBuffer);
-
-              const allowedArtifactFiles = new Set([
-                "periphery.json",
-                "periphery.status",
-                "periphery.stderr.log",
-                "periphery.stdout.json",
-                "should-fail.txt",
-              ]);
-              const maxEntries = allowedArtifactFiles.size;
-              const maxEntryBytes = 2 * 1024 * 1024;
-              const maxTotalBytes = 4 * 1024 * 1024;
-
-              const readUInt16 = (offset) => archiveBuffer.readUInt16LE(offset);
-              const readUInt32 = (offset) => archiveBuffer.readUInt32LE(offset);
-              const findEndOfCentralDirectoryOffset = () => {
-                const minimumOffset = Math.max(0, archiveBuffer.length - 0xffff - 22);
-                for (let offset = archiveBuffer.length - 22; offset >= minimumOffset; offset -= 1) {
-                  if (readUInt32(offset) === 0x06054b50) {
-                    return offset;
-                  }
-                }
-                return -1;
-              };
-
-              const endOfCentralDirectoryOffset = findEndOfCentralDirectoryOffset();
-              if (endOfCentralDirectoryOffset < 0) {
-                core.warning(`Skipping ${artifactName}; ZIP end-of-central-directory record was not found.`);
-                return;
-              }
-              const entryCount = readUInt16(endOfCentralDirectoryOffset + 10);
-              const centralDirectorySize = readUInt32(endOfCentralDirectoryOffset + 12);
-              const centralDirectoryOffset = readUInt32(endOfCentralDirectoryOffset + 16);
-              if (entryCount < 1 || entryCount > maxEntries) {
-                core.warning(`Skipping ${artifactName}; artifact has ${entryCount} entries.`);
-                return;
-              }
-              if (
-                centralDirectoryOffset + centralDirectorySize > archiveBuffer.length ||
-                readUInt32(centralDirectoryOffset) !== 0x02014b50
-              ) {
-                core.warning(`Skipping ${artifactName}; invalid ZIP central directory.`);
-                return;
-              }
-
-              const entries = new Map();
-              let totalUncompressedSize = 0;
-              let offset = centralDirectoryOffset;
-              for (let index = 0; index < entryCount; index += 1) {
-                if (offset + 46 > archiveBuffer.length || readUInt32(offset) !== 0x02014b50) {
-                  core.warning(`Skipping ${artifactName}; invalid central directory entry.`);
-                  return;
-                }
-
-                const compressionMethod = readUInt16(offset + 10);
-                const generalPurposeBitFlag = readUInt16(offset + 8);
-                const compressedSize = readUInt32(offset + 20);
-                const uncompressedSize = readUInt32(offset + 24);
-                const fileNameLength = readUInt16(offset + 28);
-                const extraLength = readUInt16(offset + 30);
-                const commentLength = readUInt16(offset + 32);
-                const externalAttributes = readUInt32(offset + 38);
-                const nameStart = offset + 46;
-                const nameEnd = nameStart + fileNameLength;
-                const nextOffset = nameEnd + extraLength + commentLength;
-                if (nextOffset > archiveBuffer.length) {
-                  core.warning(`Skipping ${artifactName}; central directory entry exceeds archive bounds.`);
-                  return;
-                }
-
-                const name = archiveBuffer.toString("utf8", nameStart, nameEnd);
-                const mode = externalAttributes >>> 16;
-                const fileType = mode & 0o170000;
-                const isRegularFile = fileType === 0 || fileType === 0o100000;
-                const invalidName =
-                  !allowedArtifactFiles.has(name) ||
-                  name.includes("/") ||
-                  name.includes("\\") ||
-                  name.includes("..") ||
-                  path.isAbsolute(name);
-                if (invalidName) {
-                  core.warning(`Skipping ${artifactName}; unexpected artifact entry ${name}.`);
-                  return;
-                }
-                if (!isRegularFile || name.endsWith("/")) {
-                  core.warning(`Skipping ${artifactName}; ${name} is not a regular file.`);
-                  return;
-                }
-                if (entries.has(name)) {
-                  core.warning(`Skipping ${artifactName}; duplicate artifact entry ${name}.`);
-                  return;
-                }
-                if (![0, 8].includes(compressionMethod)) {
-                  core.warning(`Skipping ${artifactName}; ${name} uses unsupported ZIP compression method ${compressionMethod}.`);
-                  return;
-                }
-                if ((generalPurposeBitFlag & 0x1) !== 0) {
-                  core.warning(`Skipping ${artifactName}; ${name} is encrypted.`);
-                  return;
-                }
-                if (compressedSize > maxEntryBytes || uncompressedSize > maxEntryBytes) {
-                  core.warning(`Skipping ${artifactName}; ${name} exceeds the per-file size limit.`);
-                  return;
-                }
-
-                totalUncompressedSize += uncompressedSize;
-                if (totalUncompressedSize > maxTotalBytes) {
-                  core.warning(`Skipping ${artifactName}; artifact exceeds the aggregate size limit.`);
-                  return;
-                }
-
-                entries.set(name, { uncompressedSize });
-                offset = nextOffset;
-              }
-
-              const files = new Map();
-              for (const [name, entry] of entries) {
-                const contents = childProcess.execFileSync("unzip", ["-p", archivePath, name], {
-                  encoding: "utf8",
-                  maxBuffer: Math.max(1, entry.uncompressedSize + 1024),
-                  timeout: 5000,
-                });
-                if (Buffer.byteLength(contents, "utf8") > maxEntryBytes) {
-                  core.warning(`Skipping ${artifactName}; ${name} exceeded the per-file size limit while reading.`);
-                  return;
-                }
-                files.set(name, contents);
-              }
-
-              const read = (name) => {
-                return files.get(name) ?? "";
-              };
-
-              const status = Number(read("periphery.status").trim() || "1");
-              let findings = null;
-              for (const name of ["periphery.json", "periphery.stdout.json"]) {
-                try {
-                  const parsed = JSON.parse(read(name));
-                  const validFindings =
-                    Array.isArray(parsed) &&
-                    parsed.every(
-                      (finding) =>
-                        finding !== null &&
-                        typeof finding === "object" &&
-                        !Array.isArray(finding),
-                    );
-                  if (validFindings) {
-                    findings = parsed;
-                    break;
-                  }
-                } catch {}
-              }
-              return { findings, status };
-            };
-            const report = await readReport();
-            const status = report?.status ?? 1;
-            const findings = report?.findings ?? null;
-
-            const sanitizeCell = (value) => {
-              const normalized = String(value ?? "")
-                .replace(/[\u0000-\u001f\u007f-\u009f]/gu, " ")
-                .replace(/[\u200b-\u200f\u202a-\u202e\u2060\u2066-\u2069\ufeff]/gu, "")
-                .replace(/\s+/gu, " ")
-                .trim();
-              const maxEncodedLength = 180;
-              let escaped = "";
-              for (const character of normalized) {
-                const encoded =
-                  character === "`"
-                    ? "'"
-                    : character === "|"
-                      ? "\\|"
-                      : character;
-                if (escaped.length + encoded.length > maxEncodedLength) {
-                  break;
-                }
-                escaped += encoded;
-              }
-              return `\`${escaped || "-"}\``;
-            };
-
-            const rows = (findings ?? []).map((finding) => {
-              const location = String(finding.location ?? "");
-              const [file, line] = location.split(":");
-              return {
-                file: file ? `apps/ios/${file}` : "",
-                line: line || "",
-                kind: String(finding.kind ?? ""),
-                name: String(finding.name ?? ""),
-              };
-            });
-
-            let mode = "failure";
-            let body = `${marker}\n`;
-            if (scanSkipped) {
-              mode = "skipped";
-              body += [
-                "### iOS Periphery",
-                "",
-                "Periphery scan skipped because the pull request is a draft or no longer touches iOS scan scope.",
-              ].join("\n");
-            } else if (findings === null) {
-              body += [
-                "### iOS Periphery",
-                "",
-                "Periphery did not complete or its report could not be safely read. Check the workflow run for details.",
-              ].join("\n");
-            } else if (rows.length === 0 && status === 0) {
-              mode = "success";
-              body += [
-                "### iOS Periphery",
-                "",
-                "No dead Swift code found.",
-              ].join("\n");
-            } else if (rows.length > 0) {
-              const shown = rows.slice(0, 50);
-              body += [
-                "### iOS Periphery",
-                "",
-                `Found ${rows.length} dead Swift code ${rows.length === 1 ? "symbol" : "symbols"}. Remove the code or add a narrow Periphery exemption with a comment explaining why it must stay.`,
-                "",
-                "| File | Line | Kind | Name |",
-                "| --- | ---: | --- | --- |",
-                ...shown.map((row) => `| ${sanitizeCell(row.file)} | ${sanitizeCell(row.line)} | ${sanitizeCell(row.kind)} | ${sanitizeCell(row.name)} |`),
-                rows.length > shown.length ? "" : null,
-                rows.length > shown.length ? `Showing first ${shown.length}; full JSON is in the workflow artifact.` : null,
-              ].filter(Boolean).join("\n");
-            } else {
-              body += [
-                "### iOS Periphery",
-                "",
-                "Periphery exited with a non-zero status before producing findings. Check the workflow artifact for stdout/stderr.",
-              ].join("\n");
-            }
-            body += "\n";
-            const maxCommentChars = 60_000;
-            if (body.length > maxCommentChars) {
-              body = [
-                marker,
-                "### iOS Periphery",
-                "",
-                `Found ${rows.length} dead Swift code ${rows.length === 1 ? "symbol" : "symbols"}. The rendered report exceeded the safe comment limit; use the workflow artifact for details.`,
-                "",
-              ].join("\n");
-            }
-
-            const comments = await github.paginate(github.rest.issues.listComments, {
-              owner,
-              repo,
-              issue_number: livePull.data.number,
-              per_page: 100,
-            });
-            const existing = comments.find(
-              (comment) =>
-                comment.user?.login === "github-actions[bot]" &&
-                comment.body?.includes(marker),
-            );
-
-            if (!existing && ["skipped", "success"].includes(mode)) {
-              core.info(`No existing Periphery comment and scan ${mode}; skipping comment.`);
-              return;
-            }
-
-            const currentPull = await github.rest.pulls.get({
-              owner,
-              repo,
-              pull_number: pr.number,
-            });
-            if (
-              currentPull.data.state !== "open" ||
-              currentPull.data.base?.repo?.full_name !== repository ||
-              currentPull.data.head?.sha !== run.head_sha
-            ) {
-              core.info(`Skipping stale run ${run.id}; PR #${pr.number} changed before comment update.`);
-              return;
-            }
-
-            const workflowRuns = await github.paginate(github.rest.actions.listWorkflowRuns, {
-              owner,
-              repo,
-              workflow_id: run.workflow_id,
-              event: "pull_request",
-              head_sha: run.head_sha,
-              per_page: 100,
-            });
-            const supersedingRun = workflowRuns.find(
-              (candidate) =>
-                (candidate.id === run.id ||
-                  candidate.pull_requests?.some(
-                    (candidatePull) => candidatePull.number === pr.number,
-                  )) &&
-                (candidate.run_number > run.run_number ||
-                  (candidate.run_number === run.run_number &&
-                    candidate.run_attempt > run.run_attempt)),
-            );
-            if (supersedingRun) {
-              core.info(`Skipping superseded run ${run.id} attempt ${run.run_attempt}; run ${supersedingRun.id} attempt ${supersedingRun.run_attempt} is newer.`);
-              return;
-            }
-
-            if (existing) {
-              await github.rest.issues.updateComment({
-                owner,
-                repo,
-                comment_id: existing.id,
-                body,
-              });
-              return;
-            }
-
-            await github.rest.issues.createComment({
-              owner,
-              repo,
-              issue_number: livePull.data.number,
-              body,
-            });

.github/workflows/ios-periphery.yml

@@ -1,229 +0,0 @@
-name: iOS Periphery Dead Code
-
-on:
-  pull_request:
-    types: [opened, synchronize, reopened, ready_for_review, converted_to_draft]
-  workflow_dispatch:
-
-concurrency:
-  group: ios-periphery-${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
-  cancel-in-progress: true
-
-env:
-  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
-
-permissions:
-  contents: read
-  pull-requests: read
-
-jobs:
-  scope:
-    name: Detect iOS scan scope
-    runs-on: ubuntu-24.04
-    outputs:
-      should-scan: ${{ steps.scope.outputs.should-scan }}
-    steps:
-      - name: Detect changed paths
-        id: scope
-        uses: actions/github-script@v9
-        with:
-          script: |
-            if (context.eventName === "workflow_dispatch") {
-              core.setOutput("should-scan", "true");
-              return;
-            }
-            if (context.payload.pull_request?.draft) {
-              core.setOutput("should-scan", "false");
-              return;
-            }
-
-            const files = await github.paginate(github.rest.pulls.listFiles, {
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              pull_number: context.payload.pull_request.number,
-              per_page: 100,
-            });
-            const isScanPath = (filename) =>
-              typeof filename === "string" && (
-                filename.startsWith("apps/ios/") ||
-                filename === ".github/workflows/ios-periphery.yml" ||
-                filename === ".github/workflows/ios-periphery-comment.yml" ||
-                filename === "config/swiftformat" ||
-                filename === "config/swiftlint.yml"
-              );
-            const shouldScan = files.some(
-              ({ filename, previous_filename: previousFilename }) =>
-                isScanPath(filename) || isScanPath(previousFilename)
-            );
-            core.setOutput("should-scan", String(shouldScan));
-
-  scan:
-    name: Scan iOS dead code
-    needs: scope
-    if: ${{ needs.scope.outputs.should-scan == 'true' }}
-    runs-on: ${{ github.event_name == 'workflow_dispatch' && 'macos-26' || (github.repository == 'openclaw/openclaw' && 'blacksmith-12vcpu-macos-26' || 'macos-26') }}
-    timeout-minutes: 45
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v6
-        with:
-          fetch-depth: 1
-          fetch-tags: false
-          persist-credentials: false
-          submodules: false
-
-      - name: Verify Xcode
-        run: |
-          set -euo pipefail
-          for xcode_app in /Applications/Xcode_26.5.app /Applications/Xcode-26.5.0.app; do
-            if [ -d "$xcode_app/Contents/Developer" ]; then
-              sudo xcode-select -s "$xcode_app/Contents/Developer"
-              break
-            fi
-          done
-          xcodebuild -version
-          xcode_version="$(xcodebuild -version | awk 'NR == 1 { print $2 }')"
-          if [[ "$xcode_version" != 26.* ]]; then
-            echo "error: expected Xcode 26.x, got $xcode_version" >&2
-            exit 1
-          fi
-          swift --version
-
-      - name: Setup Node environment
-        uses: ./.github/actions/setup-node-env
-        with:
-          install-bun: "false"
-
-      - name: Install iOS Swift tooling
-        run: brew install xcodegen swiftformat swiftlint periphery
-
-      - name: Generate iOS project
-        run: |
-          set -euo pipefail
-          ./scripts/ios-configure-signing.sh
-          ./scripts/ios-write-version-xcconfig.sh
-          cd apps/ios
-          xcodegen generate
-
-      - name: Run Periphery
-        run: |
-          set -euo pipefail
-          output_dir="$RUNNER_TEMP/ios-periphery"
-          mkdir -p "$output_dir"
-          cd apps/ios
-          set +e
-          periphery scan \
-            --config .periphery.yml \
-            --strict \
-            --format json \
-            --write-results "$output_dir/periphery.json" \
-            >"$output_dir/periphery.stdout.json" \
-            2>"$output_dir/periphery.stderr.log"
-          periphery_status="$?"
-          set -e
-          printf '%s\n' "$periphery_status" >"$output_dir/periphery.status"
-          if [ ! -s "$output_dir/periphery.json" ]; then
-            cp "$output_dir/periphery.stdout.json" "$output_dir/periphery.json"
-          fi
-
-      - name: Build Periphery report
-        run: |
-          set -euo pipefail
-          node <<'NODE'
-          const fs = require("node:fs");
-          const path = require("node:path");
-
-          const outputDir = path.join(process.env.RUNNER_TEMP, "ios-periphery");
-          const read = (name) => {
-            const file = path.join(outputDir, name);
-            return fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
-          };
-
-          const status = Number(read("periphery.status").trim() || "1");
-          let findings = null;
-          for (const name of ["periphery.json", "periphery.stdout.json"]) {
-            try {
-              const parsed = JSON.parse(read(name));
-              if (Array.isArray(parsed)) {
-                findings = parsed;
-                break;
-              }
-            } catch {}
-          }
-
-          const escapeCommandData = (value) =>
-            String(value ?? "")
-              .replaceAll("%", "%25")
-              .replaceAll("\r", "%0D")
-              .replaceAll("\n", "%0A");
-          const escapeCommandProperty = (value) =>
-            escapeCommandData(value)
-              .replaceAll(":", "%3A")
-              .replaceAll(",", "%2C");
-
-          const rows = (findings ?? []).map((finding) => {
-            const location = String(finding.location ?? "");
-            const [file, line] = location.split(":");
-            const repoFile = file ? `apps/ios/${file}` : "";
-            return {
-              file: repoFile,
-              line: line || "",
-              kind: String(finding.kind ?? ""),
-              name: String(finding.name ?? ""),
-            };
-          });
-
-          for (const row of rows) {
-            if (!row.file) continue;
-            const line = row.line ? `,line=${escapeCommandProperty(row.line)}` : "";
-            const title = `${row.kind || "Unused code"} ${row.name}`.trim();
-            console.log(`::error file=${escapeCommandProperty(row.file)}${line},title=Dead Swift code::${escapeCommandData(title)}`);
-          }
-
-          let shouldFail = "1";
-          let summary = "";
-
-          if (findings === null) {
-            summary = [
-              "### iOS Periphery",
-              "",
-              "Periphery did not complete. Check the workflow artifact for stdout/stderr.",
-            ].join("\n");
-          } else if (rows.length === 0 && status === 0) {
-            shouldFail = "0";
-            summary = [
-              "### iOS Periphery",
-              "",
-              "No dead Swift code found.",
-            ].join("\n");
-          } else if (rows.length > 0) {
-            summary = [
-              "### iOS Periphery",
-              "",
-              `Found ${rows.length} dead Swift code ${rows.length === 1 ? "symbol" : "symbols"}. See the PR comment or workflow artifact for details.`,
-            ].join("\n");
-          } else {
-            summary = [
-              "### iOS Periphery",
-              "",
-              "Periphery exited with a non-zero status before producing findings. Check the workflow artifact for stdout/stderr.",
-            ].join("\n");
-          }
-
-          fs.writeFileSync(path.join(outputDir, "should-fail.txt"), `${shouldFail}\n`);
-          fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, `${summary.trim()}\n`);
-          NODE
-
-      - name: Upload Periphery report
-        if: always()
-        uses: actions/upload-artifact@v7
-        with:
-          name: ios-periphery-dead-code-${{ github.run_id }}-${{ github.run_attempt }}
-          path: ${{ runner.temp }}/ios-periphery
-          if-no-files-found: warn
-          retention-days: 14
-
-      - name: Fail on dead code
-        run: |
-          set -euo pipefail
-          test "$(cat "$RUNNER_TEMP/ios-periphery/should-fail.txt")" = "0"

.gitignore

@@ -127,8 +127,6 @@ mantis/
 !.agents/skills/clawdtributor/**
 !.agents/skills/control-ui-e2e/
 !.agents/skills/control-ui-e2e/**
-!.agents/skills/discord-user-post/
-!.agents/skills/discord-user-post/**
 !.agents/skills/gitcrawl/
 !.agents/skills/gitcrawl/**
 !.agents/skills/technical-documentation/

AGENTS.md

@@ -214,7 +214,6 @@ Skills own workflows; root owns hard policy and routing.
 
 - Vitest. Colocated `*.test.ts`; e2e `*.e2e.test.ts`; example models `sonnet-4.6`, `gpt-5.5`; test GPT with 5.5 preferred, 5.4 ok; no GPT-4.x agent-smoke defaults.
 - Prefer behavior tests over workflow/docs string greps. Put operator policy reminders in AGENTS/docs.
-- QA scenario sources are YAML only: `qa/scenarios/index.yaml` and `qa/scenarios/<theme>/*.yaml`. Do not add fenced `qa-scenario`/`qa-flow` Markdown files under `qa/scenarios/`.
 - Clean timers/env/globals/mocks/sockets/temp dirs/module state; `--isolate=false` safe.
 - Prefer injection and narrow `*.runtime.ts` mocks over broad barrels or `openclaw/plugin-sdk/*`.
 - Do not edit baseline/inventory/ignore/snapshot/expected-failure files to silence checks without explicit approval.

CHANGELOG.md

@@ -25,14 +25,11 @@ Docs: https://docs.openclaw.ai
 
 - 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.
 - 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, preserve fresh post-compaction usage while clearing stale usage snapshots, and require admin privileges for HTTP session/model override surfaces. (#91357, #92631, #92146, #91287, #92468, #92510, #91246, #50795, #50845, #82874, #92651, #92646) Thanks @ooiuuii, @openperf, @IWhatsskill, @ZengWen-DT, @zhangguiping-xydt, @Hollychou924, @leno23, and @TurboTheTurtle.
+- 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.
 - Release and test reliability: extend slow Gateway/full-suite watchdogs, split local full-suite shards when throttled, stabilize plugin auth marker fixtures, avoid brittle provider-ref error text, and keep QA Lab bootstrap selection assertions aligned with flow-only scenarios. (#92652)
-- macOS Peekaboo bridge: update the embedded Peekaboo package to 3.5.2 and route bundled-skill CLI commands through the OpenClaw app bridge so they inherit its Screen Recording and Accessibility grants.
-- Agent routing: route subagent RPC callbacks addressed to an agent-shaped `--to` target to the correct session key instead of falling back to the main session, so WeChat (and other channel) session-key callbacks reach the intended subagent session. (#90231) Thanks @zhangguiping-xydt.
-- QQBot delivery: keep markdown table chunks self-contained across message boundaries by preserving table state across block deliveries, flushing unfinished table-row fragments as plain text, and detecting short pipe-terminated rows by column count so split rows are not sent as malformed markdown. (#92428) Thanks @sliverp.
 
 ## 2026.6.6
 

Dockerfile

@@ -138,7 +138,7 @@ ARG OPENCLAW_BUNDLED_PLUGIN_DIR
 # BuildKit cache mounts are not part of cached layers; seed tarballs for the
 # installed prod graph in the same step that runs offline prune.
 RUN --mount=type=cache,id=openclaw-pnpm-store,target=/root/.local/share/pnpm/store,sharing=locked \
-    node scripts/list-prod-store-packages.mjs | xargs -r pnpm store add && \
+    pnpm list --prod --depth Infinity --json | node scripts/list-prod-store-packages.mjs | xargs -r pnpm store add && \
     CI=true pnpm prune --prod \
       --config.offline=true \
       --config.supportedArchitectures.os=linux \

apps/android/app/src/main/java/ai/openclaw/app/NodeRuntime.kt

@@ -443,7 +443,6 @@ class NodeRuntime(
         updateStatus()
         micCapture.onGatewayConnectionChanged(true)
         scope.launch {
-          subscribeOperatorSessionEvents()
           refreshHomeCanvasOverviewIfConnected()
           if (voiceReplySpeakerLazy.isInitialized()) {
             voiceReplySpeaker.refreshConfig()
@@ -486,14 +485,6 @@ class NodeRuntime(
       },
     )
 
-  private suspend fun subscribeOperatorSessionEvents() {
-    try {
-      operatorSession.request("sessions.subscribe", null)
-    } catch (err: Throwable) {
-      Log.d("OpenClawRuntime", "sessions.subscribe failed: ${err.message ?: err::class.java.simpleName}")
-    }
-  }
-
   private val nodeSession =
     GatewaySession(
       scope = scope,

apps/android/app/src/main/java/ai/openclaw/app/chat/ChatController.kt

@@ -311,6 +311,7 @@ class ChatController(
     }
   }
 
+  /** Applies gateway chat/agent stream events to local transcript and pending-run state. */
   fun handleGatewayEvent(
     event: String,
     payloadJson: String?,
@@ -320,6 +321,7 @@ class ChatController(
         scope.launch { pollHealthIfNeeded(force = false) }
       }
       "health" -> {
+        // If we receive a health snapshot, the gateway is reachable.
         _healthOk.value = true
       }
       "seqGap" -> {
@@ -330,17 +332,6 @@ class ChatController(
         if (payloadJson.isNullOrBlank()) return
         handleChatEvent(payloadJson)
       }
-      "sessions.changed" -> {
-        if (payloadJson.isNullOrBlank()) {
-          refreshSessionsForCurrentWindow()
-        } else {
-          handleSessionsChangedEvent(payloadJson)
-        }
-      }
-      "session.message" -> {
-        if (payloadJson.isNullOrBlank()) return
-        handleSessionMessageEvent(payloadJson)
-      }
       "agent" -> {
         if (payloadJson.isNullOrBlank()) return
         handleAgentEvent(payloadJson)
@@ -362,7 +353,6 @@ class ChatController(
         )
       if (!isCurrentHistoryLoad(sessionKey, _sessionKey.value, generation, historyLoadGeneration.get())) return
       val history = parseHistory(historyJson, sessionKey = sessionKey, previousMessages = _messages.value)
-      updateSessionFromHistory(history)
       prunePersistedOptimisticMessages(history.messages)
       _messages.value = mergeOptimisticMessages(incoming = history.messages, optimistic = optimisticMessagesByRunId.values)
       _sessionId.value = history.sessionId
@@ -398,10 +388,6 @@ class ChatController(
     }
   }
 
-  private fun refreshSessionsForCurrentWindow() {
-    scope.launch { fetchSessions(limit = _sessions.value.size.takeIf { it > 0 } ?: 100) }
-  }
-
   private suspend fun pollHealthIfNeeded(force: Boolean) {
     val now = System.currentTimeMillis()
     val last = lastHealthPollAtMs
@@ -471,7 +457,6 @@ class ChatController(
                 sessionKey = currentSessionKey,
                 previousMessages = _messages.value,
               )
-            updateSessionFromHistory(history)
             prunePersistedOptimisticMessages(history.messages)
             _messages.value = mergeOptimisticMessages(incoming = history.messages, optimistic = optimisticMessagesByRunId.values)
             _sessionId.value = history.sessionId
@@ -487,31 +472,6 @@ class ChatController(
     }
   }
 
-  private fun handleSessionsChangedEvent(payloadJson: String) {
-    val payload = json.parseToJsonElement(payloadJson).asObjectOrNull() ?: return
-    if (payload["reason"].asStringOrNull() == "delete") {
-      removeSessionEntry(payload["sessionKey"].asStringOrNull() ?: payload["key"].asStringOrNull())
-      return
-    }
-    val entry = parseEventSessionEntry(payload)
-    if (entry != null) {
-      upsertSessionEntry(entry)
-    } else {
-      refreshSessionsForCurrentWindow()
-    }
-  }
-
-  private fun handleSessionMessageEvent(payloadJson: String) {
-    val payload = json.parseToJsonElement(payloadJson).asObjectOrNull() ?: return
-    val entry = parseEventSessionEntry(payload)
-    if (entry != null) {
-      upsertSessionEntry(entry)
-    }
-  }
-
-  private fun parseEventSessionEntry(payload: JsonObject): ChatSessionEntry? =
-    payload["session"].asObjectOrNull()?.let(::parseSessionEntry) ?: parseSessionEntry(payload)
-
   private fun handleAgentEvent(payloadJson: String) {
     val payload = json.parseToJsonElement(payloadJson).asObjectOrNull() ?: return
     val sessionKey = payload["sessionKey"].asStringOrNull()?.trim()
@@ -640,7 +600,6 @@ class ChatController(
     val root = json.parseToJsonElement(historyJson).asObjectOrNull() ?: return ChatHistory(sessionKey, null, null, emptyList())
     val sid = root["sessionId"].asStringOrNull()
     val thinkingLevel = root["thinkingLevel"].asStringOrNull()
-    val sessionInfo = root["sessionInfo"].asObjectOrNull()?.let { parseSessionEntry(it, fallbackKey = sessionKey) }
     val array = root["messages"].asArrayOrNull() ?: JsonArray(emptyList())
 
     val messages =
@@ -663,69 +622,20 @@ class ChatController(
       sessionId = sid,
       thinkingLevel = thinkingLevel,
       messages = reconcileMessageIds(previous = previousMessages, incoming = messages),
-      sessionInfo = sessionInfo,
     )
   }
 
   private fun parseSessions(jsonString: String): List<ChatSessionEntry> {
     val root = json.parseToJsonElement(jsonString).asObjectOrNull() ?: return emptyList()
     val sessions = root["sessions"].asArrayOrNull() ?: return emptyList()
-    return sessions.mapNotNull { item -> parseSessionEntry(item.asObjectOrNull()) }
-  }
-
-  private fun parseSessionEntry(
-    obj: JsonObject?,
-    fallbackKey: String? = null,
-  ): ChatSessionEntry? {
-    if (obj == null) return null
-    val key =
-      obj["key"].asStringOrNull()?.trim().orEmpty()
-        .ifEmpty { obj["sessionKey"].asStringOrNull()?.trim().orEmpty() }
-        .ifEmpty { fallbackKey?.trim().orEmpty() }
-    if (key.isEmpty()) return null
-    return ChatSessionEntry(
-      key = key,
-      updatedAtMs = obj["updatedAt"].asLongOrNull(),
-      displayName = obj["displayName"].asStringOrNull()?.trim(),
-      totalTokens = obj["totalTokens"].asLongOrNull(),
-      totalTokensFresh = obj["totalTokensFresh"].asBooleanOrNull(),
-      contextTokens = obj["contextTokens"].asLongOrNull(),
-      hasContextUsageMetadata =
-        "totalTokens" in obj ||
-          "totalTokensFresh" in obj ||
-          "contextTokens" in obj,
-    )
-  }
-
-  private fun updateSessionFromHistory(history: ChatHistory) {
-    val info = history.sessionInfo ?: return
-    upsertSessionEntry(info, preserveExistingContextUsageWithoutTotal = true)
-  }
-
-  private fun upsertSessionEntry(
-    entry: ChatSessionEntry,
-    preserveExistingContextUsageWithoutTotal: Boolean = false,
-  ) {
-    val current = _sessions.value
-    val index = current.indexOfFirst { it.key == entry.key }
-    _sessions.value =
-      if (index >= 0) {
-        current.toMutableList().also {
-          it[index] =
-            mergeChatSessionEntry(
-              existing = it[index],
-              next = entry,
-              preserveExistingContextUsageWithoutTotal = preserveExistingContextUsageWithoutTotal,
-            )
-        }
-      } else {
-        listOf(entry) + current
-      }
-  }
-
-  private fun removeSessionEntry(sessionKey: String?) {
-    val key = sessionKey?.trim()?.takeIf { it.isNotEmpty() } ?: return
-    _sessions.value = _sessions.value.filterNot { it.key == key }
+    return sessions.mapNotNull { item ->
+      val obj = item.asObjectOrNull() ?: return@mapNotNull null
+      val key = obj["key"].asStringOrNull()?.trim().orEmpty()
+      if (key.isEmpty()) return@mapNotNull null
+      val updatedAt = obj["updatedAt"].asLongOrNull()
+      val displayName = obj["displayName"].asStringOrNull()?.trim()
+      ChatSessionEntry(key = key, updatedAtMs = updatedAt, displayName = displayName)
+    }
   }
 
   private fun parseRunId(resJson: String): String? =
@@ -947,44 +857,3 @@ private fun JsonElement?.asLongOrNull(): Long? =
     is JsonPrimitive -> content.toLongOrNull()
     else -> null
   }
-
-private fun JsonElement?.asBooleanOrNull(): Boolean? =
-  when (this) {
-    is JsonPrimitive -> content.toBooleanStrictOrNull()
-    else -> null
-  }
-
-internal fun mergeChatSessionEntry(
-  existing: ChatSessionEntry,
-  next: ChatSessionEntry,
-  preserveExistingContextUsageWithoutTotal: Boolean = false,
-): ChatSessionEntry {
-  val preserveExistingContextUsage = preserveExistingContextUsageWithoutTotal && next.totalTokens == null
-  return existing.copy(
-    updatedAtMs = next.updatedAtMs ?: existing.updatedAtMs,
-    displayName = next.displayName ?: existing.displayName,
-    totalTokens =
-      when {
-        preserveExistingContextUsage -> existing.totalTokens
-        next.hasContextUsageMetadata -> next.totalTokens
-        else -> null
-      },
-    totalTokensFresh =
-      when {
-        preserveExistingContextUsage -> existing.totalTokensFresh
-        next.hasContextUsageMetadata -> next.totalTokensFresh
-        else -> null
-      },
-    contextTokens =
-      when {
-        preserveExistingContextUsage -> next.contextTokens ?: existing.contextTokens
-        next.hasContextUsageMetadata -> next.contextTokens
-        else -> null
-      },
-    hasContextUsageMetadata =
-      when {
-        preserveExistingContextUsage -> existing.hasContextUsageMetadata || next.contextTokens != null
-        else -> next.hasContextUsageMetadata
-      },
-  )
-}

apps/android/app/src/main/java/ai/openclaw/app/chat/ChatModels.kt

@@ -40,10 +40,6 @@ data class ChatSessionEntry(
   val key: String,
   val updatedAtMs: Long?,
   val displayName: String? = null,
-  val totalTokens: Long? = null,
-  val totalTokensFresh: Boolean? = null,
-  val contextTokens: Long? = null,
-  val hasContextUsageMetadata: Boolean = totalTokens != null || totalTokensFresh != null || contextTokens != null,
 )
 
 /**
@@ -54,7 +50,6 @@ data class ChatHistory(
   val sessionId: String?,
   val thinkingLevel: String?,
   val messages: List<ChatMessage>,
-  val sessionInfo: ChatSessionEntry? = null,
 )
 
 /**

apps/android/app/src/main/java/ai/openclaw/app/ui/chat/ChatScreen.kt

@@ -74,7 +74,6 @@ import kotlinx.coroutines.withContext
 import java.text.DateFormat
 import java.util.Date
 import java.util.Locale
-import kotlin.math.roundToInt
 
 /** Full chat surface that wires MainViewModel state to messages, attachments, voice, and composer actions. */
 @Composable
@@ -96,7 +95,6 @@ fun ChatScreen(
   val sessions by viewModel.chatSessions.collectAsState()
   val chatDraft by viewModel.chatDraft.collectAsState()
   val pendingAssistantAutoSend by viewModel.pendingAssistantAutoSend.collectAsState()
-  val contextUsage = resolveChatContextUsage(sessionKey = sessionKey, mainSessionKey = mainSessionKey, sessions = sessions)
   val context = LocalContext.current
   val resolver = context.contentResolver
   val scope = rememberCoroutineScope()
@@ -198,7 +196,6 @@ fun ChatScreen(
       onValueChange = { input = it },
       attachments = attachments,
       thinkingLevel = thinkingLevel,
-      contextUsage = contextUsage,
       healthOk = healthOk,
       pendingRunCount = pendingRunCount,
       onThinkingLevelChange = viewModel::setChatThinkingLevel,
@@ -688,7 +685,6 @@ private fun ChatComposer(
   onValueChange: (String) -> Unit,
   attachments: List<PendingImageAttachment>,
   thinkingLevel: String,
-  contextUsage: ChatContextUsage,
   healthOk: Boolean,
   pendingRunCount: Int,
   onThinkingLevelChange: (String) -> Unit,
@@ -703,11 +699,7 @@ private fun ChatComposer(
       AttachmentStrip(attachments = attachments, onRemoveAttachment = onRemoveAttachment)
     }
 
-    ChatContextMeter(
-      thinkingLevel = thinkingLevel,
-      contextUsage = contextUsage,
-      onClick = { onThinkingLevelChange(nextThinkingValue(thinkingLevel)) },
-    )
+    ChatContextMeter(thinkingLevel = thinkingLevel, onClick = { onThinkingLevelChange(nextThinkingValue(thinkingLevel)) })
 
     Row(modifier = Modifier.fillMaxWidth(), verticalAlignment = Alignment.CenterVertically, horizontalArrangement = Arrangement.spacedBy(6.dp)) {
       ChatInputPill(value = value, onValueChange = onValueChange, onPickImages = onPickImages, onVoice = onVoice, modifier = Modifier.weight(1f))
@@ -743,10 +735,8 @@ private fun ChatComposer(
 @Composable
 private fun ChatContextMeter(
   thinkingLevel: String,
-  contextUsage: ChatContextUsage,
   onClick: () -> Unit,
 ) {
-  val contextFraction = contextMeterWidth(contextUsage) ?: 0f
   Row(
     modifier = Modifier.width(178.dp),
     verticalAlignment = Alignment.CenterVertically,
@@ -765,13 +755,7 @@ private fun ChatContextMeter(
         horizontalArrangement = Arrangement.spacedBy(6.dp),
       ) {
         Icon(imageVector = Icons.Default.Refresh, contentDescription = null, modifier = Modifier.size(12.dp), tint = ClawTheme.colors.textSubtle)
-        Text(
-          text = contextMeterLabel(contextUsage, thinkingLevel),
-          style = ClawTheme.type.caption.copy(fontSize = 12.5.sp, lineHeight = 16.sp),
-          color = ClawTheme.colors.textMuted,
-          maxLines = 1,
-          overflow = TextOverflow.Ellipsis,
-        )
+        Text(text = "Context ${contextPercent(thinkingLevel)}%", style = ClawTheme.type.caption.copy(fontSize = 12.5.sp, lineHeight = 16.sp), color = ClawTheme.colors.textMuted)
       }
     }
     Box(
@@ -784,7 +768,7 @@ private fun ChatContextMeter(
       Box(
         modifier =
           Modifier
-            .fillMaxWidth(contextFraction)
+            .fillMaxWidth(thinkingMeterWidth(thinkingLevel))
             .height(3.dp)
             .background(ClawTheme.colors.primary, RoundedCornerShape(999.dp)),
       )
@@ -918,32 +902,6 @@ private fun isActiveSessionChoice(
   return choiceKey == current
 }
 
-internal data class ChatContextUsage(
-  val totalTokens: Long?,
-  val totalTokensFresh: Boolean?,
-  val contextTokens: Long?,
-)
-
-internal fun resolveChatContextUsage(
-  sessionKey: String,
-  mainSessionKey: String,
-  sessions: List<ChatSessionEntry>,
-): ChatContextUsage {
-  val entry =
-    sessions.firstOrNull {
-      isActiveSessionChoice(
-        choiceKey = it.key,
-        sessionKey = sessionKey,
-        mainSessionKey = mainSessionKey,
-      )
-  }
-  return ChatContextUsage(
-    totalTokens = entry?.totalTokens,
-    totalTokensFresh = entry?.totalTokensFresh,
-    contextTokens = entry?.contextTokens,
-  )
-}
-
 @Composable
 private fun SendButton(
   enabled: Boolean,
@@ -1000,29 +958,17 @@ private fun nextThinkingValue(value: String): String =
     else -> "off"
   }
 
-internal fun contextMeterWidth(usage: ChatContextUsage): Float? {
-  if (usage.totalTokensFresh == false) return null
-  val total = usage.totalTokens?.takeIf { it >= 0L } ?: return null
-  val context = usage.contextTokens?.takeIf { it > 0L } ?: return null
-  return (total.toDouble() / context.toDouble()).coerceIn(0.0, 1.0).toFloat()
-}
-
-internal fun contextMeterLabel(
-  usage: ChatContextUsage,
-  thinkingLevel: String,
-): String {
-  val contextLabel = contextMeterWidth(usage)?.let { "Context ${(it * 100).roundToInt()}%" } ?: "Context --"
-  return "$contextLabel · ${contextMeterThinkingLabel(thinkingLevel)}"
-}
-
-internal fun contextMeterThinkingLabel(value: String): String =
+/** Maps thinking presets to the visual context meter fill fraction. */
+private fun thinkingMeterWidth(value: String): Float =
   when (value.lowercase(Locale.US)) {
-    "low" -> "low"
-    "medium" -> "medium"
-    "high" -> "high"
-    else -> "off"
+    "low" -> 0.34f
+    "medium" -> 0.58f
+    "high" -> 0.82f
+    else -> 0.18f
   }
 
+private fun contextPercent(value: String): Int = (thinkingMeterWidth(value) * 100).toInt()
+
 private fun formatChatTimestamp(timestampMs: Long): String = DateFormat.getTimeInstance(DateFormat.SHORT, Locale.getDefault()).format(Date(timestampMs))
 
 /** Quick markdown detector used to avoid routing plain chat text through the markdown renderer. */

apps/android/app/src/test/java/ai/openclaw/app/chat/ChatControllerSessionPolicyTest.kt

@@ -59,96 +59,4 @@ class ChatControllerSessionPolicyTest {
       ),
     )
   }
-
-  @Test
-  fun sessionMergeClearsUsageWhenNewSnapshotOmitsUsageMetadata() {
-    val existing =
-      ChatSessionEntry(
-        key = "agent:main:phone",
-        updatedAtMs = 1L,
-        displayName = "Phone",
-        totalTokens = 41_000L,
-        totalTokensFresh = true,
-        contextTokens = 100_000L,
-      )
-    val next =
-      ChatSessionEntry(
-        key = "agent:main:phone",
-        updatedAtMs = 2L,
-        displayName = "Phone renamed",
-        hasContextUsageMetadata = false,
-      )
-
-    val merged = mergeChatSessionEntry(existing, next)
-
-    assertEquals("agent:main:phone", merged.key)
-    assertEquals(2L, merged.updatedAtMs)
-    assertEquals("Phone renamed", merged.displayName)
-    assertEquals(null, merged.totalTokens)
-    assertEquals(null, merged.totalTokensFresh)
-    assertEquals(null, merged.contextTokens)
-    assertFalse(merged.hasContextUsageMetadata)
-  }
-
-  @Test
-  fun sessionMergePreservesUsageWhenHistorySnapshotOmitsTotalTokens() {
-    val existing =
-      ChatSessionEntry(
-        key = "agent:main:phone",
-        updatedAtMs = 1L,
-        displayName = "Phone",
-        totalTokens = 41_000L,
-        totalTokensFresh = true,
-        contextTokens = 100_000L,
-      )
-    val next =
-      ChatSessionEntry(
-        key = "agent:main:phone",
-        updatedAtMs = 2L,
-        displayName = "Phone renamed",
-        totalTokensFresh = false,
-        contextTokens = 120_000L,
-      )
-
-    val merged =
-      mergeChatSessionEntry(
-        existing = existing,
-        next = next,
-        preserveExistingContextUsageWithoutTotal = true,
-      )
-
-    assertEquals(2L, merged.updatedAtMs)
-    assertEquals("Phone renamed", merged.displayName)
-    assertEquals(41_000L, merged.totalTokens)
-    assertEquals(true, merged.totalTokensFresh)
-    assertEquals(120_000L, merged.contextTokens)
-    assertTrue(merged.hasContextUsageMetadata)
-  }
-
-  @Test
-  fun sessionMergeAppliesExplicitStaleUsageMetadata() {
-    val existing =
-      ChatSessionEntry(
-        key = "agent:main:phone",
-        updatedAtMs = 1L,
-        totalTokens = 41_000L,
-        totalTokensFresh = true,
-        contextTokens = 100_000L,
-      )
-    val next =
-      ChatSessionEntry(
-        key = "agent:main:phone",
-        updatedAtMs = 2L,
-        totalTokens = 82_000L,
-        totalTokensFresh = false,
-        contextTokens = 100_000L,
-      )
-
-    val merged = mergeChatSessionEntry(existing, next)
-
-    assertEquals(82_000L, merged.totalTokens)
-    assertEquals(false, merged.totalTokensFresh)
-    assertEquals(100_000L, merged.contextTokens)
-    assertTrue(merged.hasContextUsageMetadata)
-  }
 }

apps/android/app/src/test/java/ai/openclaw/app/ui/chat/ChatContextMeterTest.kt

@@ -1,84 +0,0 @@
-package ai.openclaw.app.ui.chat
-
-import ai.openclaw.app.chat.ChatSessionEntry
-import org.junit.Assert.assertEquals
-import org.junit.Assert.assertNull
-import org.junit.Test
-
-class ChatContextMeterTest {
-  @Test
-  fun contextMeterUsesActiveSessionTokenBudget() {
-    val sessions =
-      listOf(
-        ChatSessionEntry(key = "main", updatedAtMs = 1L, displayName = "Main", totalTokens = 8_000L, totalTokensFresh = true, contextTokens = 10_000L),
-        ChatSessionEntry(
-          key = "agent:main:mobile:test-device",
-          updatedAtMs = 2L,
-          displayName = "Phone",
-          totalTokens = 1_250L,
-          totalTokensFresh = true,
-          contextTokens = 5_000L,
-        ),
-      )
-
-    val usage =
-      resolveChatContextUsage(
-        sessionKey = "agent:main:mobile:test-device",
-        mainSessionKey = "main",
-        sessions = sessions,
-      )
-
-    assertEquals(ChatContextUsage(totalTokens = 1_250L, totalTokensFresh = true, contextTokens = 5_000L), usage)
-    assertEquals(0.25f, contextMeterWidth(usage))
-    assertEquals("Context 25% · high", contextMeterLabel(usage, "high"))
-  }
-
-  @Test
-  fun contextMeterResolvesCanonicalMainAlias() {
-    val sessions =
-      listOf(
-        ChatSessionEntry(
-          key = "agent:main:node-phone",
-          updatedAtMs = 1L,
-          displayName = "Main",
-          totalTokens = 41_000L,
-          totalTokensFresh = true,
-          contextTokens = 100_000L,
-        ),
-      )
-
-    val usage =
-      resolveChatContextUsage(
-        sessionKey = "main",
-        mainSessionKey = "agent:main:node-phone",
-        sessions = sessions,
-      )
-
-    assertEquals(ChatContextUsage(totalTokens = 41_000L, totalTokensFresh = true, contextTokens = 100_000L), usage)
-    assertEquals("Context 41% · off", contextMeterLabel(usage, "off"))
-  }
-
-  @Test
-  fun contextMeterDoesNotInventPercentWhenBudgetIsMissing() {
-    val usage = ChatContextUsage(totalTokens = 8_200L, totalTokensFresh = true, contextTokens = null)
-
-    assertNull(contextMeterWidth(usage))
-    assertEquals("Context -- · medium", contextMeterLabel(usage, "medium"))
-  }
-
-  @Test
-  fun contextMeterClampsOverfullSessions() {
-    val usage = ChatContextUsage(totalTokens = 150_000L, totalTokensFresh = true, contextTokens = 100_000L)
-
-    assertEquals(1.0f, contextMeterWidth(usage))
-    assertEquals("Context 100% · low", contextMeterLabel(usage, "low"))
-  }
-
-  @Test
-  fun contextMeterDoesNotDisplayStaleTokenUsage() {
-    val usage = ChatContextUsage(totalTokens = 82_000L, totalTokensFresh = false, contextTokens = 100_000L)
-
-    assertNull(contextMeterWidth(usage))
-    assertEquals("Context -- · high", contextMeterLabel(usage, "high"))
-  }
-}

apps/ios/.periphery.yml

@@ -1,18 +0,0 @@
-project: OpenClaw.xcodeproj
-schemes:
-  - OpenClaw
-retain_codable_properties: true
-retain_swift_ui_previews: true
-retain_objc_accessible: true
-retain_unused_protocol_func_params: true
-retain_assign_only_properties: true
-relative_results: true
-disable_update_check: true
-report_include:
-  - Sources/**
-  - ShareExtension/**
-  - ActivityWidget/**
-  - WatchExtension/Sources/**
-build_arguments:
-  - -destination
-  - generic/platform=iOS Simulator

apps/ios/Sources/Contacts/ContactsService.swift

@@ -202,4 +202,10 @@ final class ContactsService: ContactsServicing {
             phoneNumbers: contact.phoneNumbers.map(\.value.stringValue),
             emails: contact.emailAddresses.map { String($0.value) })
     }
+
+    #if DEBUG
+    static func _test_matches(contact: CNContact, phoneNumbers: [String], emails: [String]) -> Bool {
+        self.matchContacts(contacts: [contact], phoneNumbers: phoneNumbers, emails: emails) != nil
+    }
+    #endif
 }

apps/ios/Sources/Design/AgentProTab+DetailComponents.swift

@@ -1,4 +1,5 @@
 import OpenClawKit
+import OpenClawProtocol
 import SwiftUI
 
 extension AgentProTab {

apps/ios/Sources/Design/AgentProTab.swift

@@ -1,10 +1,12 @@
 import OpenClawKit
+import OpenClawProtocol
 import SwiftUI
 
 struct AgentProTab: View {
     @Environment(NodeAppModel.self) var appModel
     @Environment(\.colorScheme) var colorScheme
     @Environment(\.scenePhase) var scenePhase
+    let initialRoute: AgentRoute?
     let directRoute: AgentRoute?
     let headerLeadingAction: OpenClawSidebarHeaderAction?
     let headerTitle: String
@@ -125,11 +127,13 @@ struct AgentProTab: View {
     }
 
     init(
+        initialRoute: AgentRoute? = nil,
         directRoute: AgentRoute? = nil,
         headerLeadingAction: OpenClawSidebarHeaderAction? = nil,
         headerTitle: String = "Agents",
         openSettings: (() -> Void)? = nil)
     {
+        self.initialRoute = initialRoute
         self.directRoute = directRoute
         self.headerLeadingAction = headerLeadingAction
         self.headerTitle = headerTitle
@@ -180,6 +184,9 @@ struct AgentProTab: View {
                 self.destination(for: route)
             }
         }
+        .onAppear {
+            self.applyInitialRouteIfNeeded()
+        }
     }
 
     private func directDestination(for route: AgentRoute) -> some View {
@@ -188,4 +195,11 @@ struct AgentProTab: View {
                 self.directHeaderLeadingAction(for: route) == nil ? .visible : .hidden,
                 for: .navigationBar)
     }
+
+    private func applyInitialRouteIfNeeded() {
+        guard self.directRoute == nil else { return }
+        guard let initialRoute else { return }
+        guard self.navigationPath != [initialRoute] else { return }
+        self.navigationPath = [initialRoute]
+    }
 }

apps/ios/Sources/Design/CommandCenterSupport.swift

@@ -185,3 +185,33 @@ struct CommandEmptyStateRow: View {
         }
     }
 }
+
+struct CommandTaskRow: View {
+    let item: CommandCenterTab.WorkItem
+
+    var body: some View {
+        HStack(alignment: .center, spacing: 6) {
+            Text(self.item.title)
+                .font(.footnote.weight(.semibold))
+                .lineLimit(1)
+                .minimumScaleFactor(0.80)
+                .frame(maxWidth: .infinity, minHeight: 20, alignment: .leading)
+            Text(self.item.detail)
+                .font(.caption.weight(.medium))
+                .foregroundStyle(.secondary)
+                .lineLimit(1)
+                .minimumScaleFactor(0.78)
+                .frame(width: 64, alignment: .leading)
+            if let progress = self.item.progress {
+                ProProgressBar(progress: progress, color: self.item.color)
+                    .frame(width: 56)
+            }
+            Text(self.item.state)
+                .font(.footnote.weight(.medium))
+                .foregroundStyle(self.item.progress == nil ? self.item.color : .secondary)
+                .lineLimit(1)
+                .frame(width: self.item.progress == nil ? 58 : 34, alignment: .trailing)
+        }
+        .padding(.vertical, 8)
+    }
+}

apps/ios/Sources/Design/IPadSkillWorkshopScreen.swift

@@ -213,6 +213,32 @@ struct IPadSkillWorkshopScreen: View {
         }
     }
 
+    private var statusMenu: some View {
+        HStack(spacing: 8) {
+            Text("Status")
+                .font(.caption.weight(.semibold))
+                .foregroundStyle(.secondary)
+            Menu {
+                ForEach(Self.proposalStatusFilters, id: \.self) { filter in
+                    Button(Self.proposalStatusFilterLabel(filter)) {
+                        self.statusFilter = filter
+                    }
+                }
+            } label: {
+                HStack(spacing: 6) {
+                    Text(self.statusFilterLabel)
+                        .font(.subheadline.weight(.semibold))
+                    Image(systemName: "chevron.up.chevron.down")
+                        .font(.caption2.weight(.bold))
+                }
+                .frame(maxWidth: .infinity, alignment: .trailing)
+            }
+            .buttonStyle(.bordered)
+            .controlSize(.small)
+            .tint(self.neutralControlTint)
+        }
+    }
+
     private var agentScopeMenu: some View {
         HStack(spacing: 8) {
             Text("Agent")
@@ -1104,6 +1130,7 @@ struct IPadSkillProposalRecord: Decodable {
     let description: String
     let createdAt: String
     let updatedAt: String
+    let proposedVersion: String
     let target: IPadSkillProposalTarget
 }
 

apps/ios/Sources/Design/OpenClawBrand.swift

@@ -47,6 +47,13 @@ enum AppAppearancePreference: String, CaseIterable, Identifiable {
 }
 
 enum OpenClawBrand {
+    static let lightCanvasTop = Color(red: 246 / 255.0, green: 247 / 255.0, blue: 249 / 255.0)
+    static let lightCanvasMiddle = Color(red: 250 / 255.0, green: 251 / 255.0, blue: 252 / 255.0)
+    static let lightCanvasBottom = Color.white
+    static let darkCanvasTop = Color(red: 3 / 255.0, green: 7 / 255.0, blue: 7 / 255.0)
+    static let darkCanvasMiddle = Color(red: 13 / 255.0, green: 17 / 255.0, blue: 17 / 255.0)
+    static let darkCanvasBottom = Color(red: 17 / 255.0, green: 18 / 255.0, blue: 20 / 255.0)
+
     static let accent = Color(uiColor: UIColor { traits in
         traits.userInterfaceStyle == .dark
             ? UIColor(red: 198 / 255.0, green: 62 / 255.0, blue: 56 / 255.0, alpha: 1)
@@ -74,6 +81,11 @@ enum OpenClawBrand {
             ? UIColor(red: 34 / 255.0, green: 36 / 255.0, blue: 39 / 255.0, alpha: 1)
             : UIColor.white
     })
+    static let graphiteSoft = Color(uiColor: UIColor { traits in
+        traits.userInterfaceStyle == .dark
+            ? UIColor(red: 148 / 255.0, green: 163 / 255.0, blue: 184 / 255.0, alpha: 1)
+            : UIColor(red: 102 / 255.0, green: 112 / 255.0, blue: 133 / 255.0, alpha: 1)
+    })
 
     static var sheetBackground: LinearGradient {
         LinearGradient(
@@ -85,6 +97,40 @@ enum OpenClawBrand {
             startPoint: .topLeading,
             endPoint: .bottomTrailing)
     }
+
+    static var toolbarChrome: LinearGradient {
+        LinearGradient(
+            colors: [
+                graphiteElevated.opacity(0.92),
+                graphite.opacity(0.78),
+            ],
+            startPoint: .topLeading,
+            endPoint: .bottomTrailing)
+    }
+
+    static func glassFill(brighten: Bool) -> Color {
+        Color.black.opacity(brighten ? 0.10 : 0.22)
+    }
+
+    static func glassStroke(brighten: Bool, increasedContrast: Bool, active: Bool = false) -> Color {
+        if active {
+            return self.accent.opacity(increasedContrast ? 0.70 : 0.46)
+        }
+        return Color.white.opacity(increasedContrast ? 0.50 : (brighten ? 0.24 : 0.16))
+    }
+
+    static func formSectionHeader(_ title: String) -> some View {
+        Text(title)
+            .font(.caption.weight(.semibold))
+            .foregroundStyle(self.accent)
+            .textCase(.uppercase)
+    }
+
+    static func canvasColors(for colorScheme: ColorScheme) -> [Color] {
+        colorScheme == .dark
+            ? [self.darkCanvasTop, self.darkCanvasMiddle, self.darkCanvasBottom]
+            : [self.lightCanvasTop, self.lightCanvasMiddle, self.lightCanvasBottom]
+    }
 }
 
 extension View {

apps/ios/Sources/Design/OpenClawProComponents.swift

@@ -5,6 +5,7 @@ enum OpenClawProMetric {
     static let cardRadius: CGFloat = 10
     static let controlRadius: CGFloat = 8
     static let bottomScrollInset: CGFloat = 96
+    static let heroRadius: CGFloat = 12
 }
 
 struct OpenClawProBackground: View {
@@ -249,6 +250,13 @@ struct OpenClawSidebarRevealButton: View {
         self.headerAction = action
     }
 
+    init(action: @escaping () -> Void) {
+        self.headerAction = OpenClawSidebarHeaderAction(
+            systemName: "sidebar.left",
+            accessibilityLabel: "Show Sidebar",
+            action: action)
+    }
+
     var body: some View {
         let button = Button(action: self.headerAction.action) {
             Image(systemName: self.headerAction.systemName)
@@ -422,6 +430,46 @@ struct ProProgressBar: View {
     }
 }
 
+struct ProWorkRow: View {
+    let icon: String
+    let title: String
+    let detail: String
+    let state: String
+    let trailing: String
+    let color: Color
+    var progress: Double?
+
+    var body: some View {
+        HStack(alignment: .top, spacing: 12) {
+            ProIconBadge(systemName: self.icon, color: self.color)
+            VStack(alignment: .leading, spacing: 5) {
+                HStack(alignment: .firstTextBaseline) {
+                    Text(self.title)
+                        .font(.subheadline.weight(.semibold))
+                    Spacer(minLength: 8)
+                    Text(self.trailing)
+                        .font(.caption2)
+                        .foregroundStyle(.secondary)
+                }
+                Text(self.detail)
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+                    .lineLimit(1)
+                HStack(spacing: 8) {
+                    if let progress {
+                        ProProgressBar(progress: progress, color: self.color)
+                            .frame(maxWidth: 120)
+                    }
+                    Text(self.state)
+                        .font(.caption2.weight(.semibold))
+                        .foregroundStyle(self.color)
+                }
+            }
+        }
+        .padding(.vertical, 9)
+    }
+}
+
 struct ProCapsule: View {
     @Environment(\.colorScheme) private var colorScheme
     let title: String
@@ -505,6 +553,94 @@ struct OpenClawGatewayCompactPill: View {
     }
 }
 
+struct ProSegmentedControl: View {
+    @Environment(\.colorScheme) private var colorScheme
+    let labels: [String]
+    @Binding var selection: Int
+
+    var body: some View {
+        HStack(spacing: 4) {
+            ForEach(Array(self.labels.enumerated()), id: \.offset) { index, label in
+                Button {
+                    self.selection = index
+                } label: {
+                    Text(label)
+                        .font(.subheadline.weight(self.selection == index ? .semibold : .regular))
+                        .frame(maxWidth: .infinity)
+                        .padding(.vertical, 9)
+                        .background(self.segmentFill(isSelected: self.selection == index), in: Capsule())
+                }
+                .buttonStyle(.plain)
+            }
+        }
+        .padding(4)
+        .background {
+            Capsule()
+                .fill(self.trackFill)
+                .overlay {
+                    Capsule().strokeBorder(self.trackStroke, lineWidth: 1)
+                }
+        }
+    }
+
+    private func segmentFill(isSelected: Bool) -> Color {
+        guard isSelected else { return .clear }
+        return self.colorScheme == .dark ? Color.white.opacity(0.12) : Color.primary.opacity(0.08)
+    }
+
+    private var trackFill: Color {
+        self.colorScheme == .dark ? Color.white.opacity(0.045) : Color.white.opacity(0.72)
+    }
+
+    private var trackStroke: Color {
+        self.colorScheme == .dark ? Color.white.opacity(0.10) : Color.black.opacity(0.06)
+    }
+}
+
+struct ProHeroActionButton: View {
+    @Environment(\.colorScheme) private var colorScheme
+    let title: String
+    let detail: String
+    let systemImage: String
+    let action: () -> Void
+
+    var body: some View {
+        Button(action: self.action) {
+            HStack(spacing: 12) {
+                Image(systemName: self.systemImage)
+                    .font(.headline.weight(.semibold))
+                    .foregroundStyle(.white)
+                    .frame(width: 42, height: 42)
+                    .background(OpenClawBrand.accentHot, in: RoundedRectangle(cornerRadius: 13, style: .continuous))
+
+                VStack(alignment: .leading, spacing: 3) {
+                    Text(self.title)
+                        .font(.subheadline.weight(.semibold))
+                        .foregroundStyle(.primary)
+                    Text(self.detail)
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                        .lineLimit(1)
+                }
+
+                Spacer(minLength: 8)
+
+                Image(systemName: "arrow.right")
+                    .font(.subheadline.weight(.bold))
+                    .foregroundStyle(OpenClawBrand.accentHot)
+            }
+            .padding(12)
+            .proGlassSurface(
+                fill: self.colorScheme == .dark ? Color.white.opacity(0.045) : Color.white.opacity(0.68),
+                stroke: OpenClawBrand.accent.opacity(self.colorScheme == .dark ? 0.22 : 0.14),
+                radius: 18,
+                isProminent: true,
+                interactive: true)
+        }
+        .buttonStyle(.plain)
+    }
+}
+
 struct ProMetricTile: View {
     @Environment(\.colorScheme) private var colorScheme
     let title: String
@@ -659,3 +795,24 @@ struct ProStatusRow: View {
         .padding(.vertical, 10)
     }
 }
+
+struct ProTimelineRow: View {
+    let done: Bool
+    let title: String
+    let detail: String
+
+    var body: some View {
+        HStack(alignment: .top, spacing: 10) {
+            ProIconBadge(
+                systemName: self.done ? "checkmark.circle.fill" : "clock.fill",
+                color: self.done ? OpenClawBrand.ok : OpenClawBrand.warn)
+            VStack(alignment: .leading, spacing: 3) {
+                Text(self.title)
+                    .font(.subheadline.weight(.medium))
+                Text(self.detail)
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+            }
+        }
+    }
+}

apps/ios/Sources/Design/OpenClawProScreens.swift

@@ -0,0 +1,3 @@
+import SwiftUI
+
+// Pro UI surfaces are split by tab to keep SwiftLint file-length signal useful.

apps/ios/Sources/Design/SettingsChannelsDestination.swift

@@ -332,6 +332,65 @@ struct SettingsChannelsDestination: View {
     }
 }
 
+struct SettingsChannelsScreen: View {
+    let headerLeadingAction: OpenClawSidebarHeaderAction?
+    let gatewayAction: (() -> Void)?
+
+    init(headerLeadingAction: OpenClawSidebarHeaderAction? = nil, gatewayAction: (() -> Void)? = nil) {
+        self.headerLeadingAction = headerLeadingAction
+        self.gatewayAction = gatewayAction
+    }
+
+    var body: some View {
+        ZStack {
+            OpenClawProBackground()
+            ScrollView {
+                VStack(alignment: .leading, spacing: 14) {
+                    self.header
+                    SettingsChannelsDestination(showsSummaryCard: false)
+                }
+                .padding(.top, 18)
+                .padding(.bottom, OpenClawProMetric.bottomScrollInset)
+            }
+        }
+        .navigationTitle("Channels")
+        .navigationBarTitleDisplayMode(.inline)
+    }
+
+    private var header: some View {
+        HStack(alignment: .top, spacing: 12) {
+            if let headerLeadingAction {
+                OpenClawSidebarHeaderLeadingSlot(action: headerLeadingAction)
+            }
+
+            VStack(alignment: .leading, spacing: 5) {
+                Text("Channels / Integrations")
+                    .font(.title3.weight(.semibold))
+                Text("Message routing and external channel clients.")
+                    .font(.callout)
+                    .foregroundStyle(.secondary)
+                    .fixedSize(horizontal: false, vertical: true)
+            }
+            Spacer(minLength: 8)
+            self.gatewayPill
+        }
+        .padding(.horizontal, OpenClawProMetric.pagePadding)
+    }
+
+    @ViewBuilder
+    private var gatewayPill: some View {
+        if let gatewayAction {
+            Button(action: gatewayAction) {
+                OpenClawGatewayCompactPill()
+            }
+            .buttonStyle(.plain)
+            .accessibilityHint("Opens Settings / Gateway")
+        } else {
+            OpenClawGatewayCompactPill()
+        }
+    }
+}
+
 private struct SettingsChannelRow: View {
     let entry: SettingsChannelEntry
     let canAdmin: Bool

apps/ios/Sources/Design/SettingsProTabActions.swift

@@ -139,6 +139,15 @@ extension SettingsProTab {
         await self.gatewayController.connectLastKnown()
     }
 
+    func refreshGateway() async {
+        guard !self.isRefreshingGateway else { return }
+        self.isRefreshingGateway = true
+        defer { self.isRefreshingGateway = false }
+        self.gatewayController.refreshActiveGatewayRegistrationFromSettings()
+        self.gatewayController.restartDiscovery()
+        await self.appModel.refreshGatewayOverviewIfConnected()
+    }
+
     @MainActor
     func runDiagnostics() async {
         guard !self.isRefreshingGateway else { return }
@@ -191,7 +200,7 @@ extension SettingsProTab {
             self.setupStatusText = "Failed: invalid port"
             return
         }
-        guard await self.preflightGateway(host: host, port: port) else { return }
+        guard await self.preflightGateway(host: host, port: port, useTLS: self.manualGatewayTLS) else { return }
         self.setupStatusText = "Setup code applied. Connecting..."
         await self.connectManual()
     }
@@ -289,7 +298,7 @@ extension SettingsProTab {
             self.setupStatusText = "Failed: invalid port"
             return
         }
-        guard await self.preflightGateway(host: host, port: port) else { return }
+        guard await self.preflightGateway(host: host, port: port, useTLS: self.manualGatewayTLS) else { return }
         await self.connectManual()
     }
 
@@ -318,7 +327,7 @@ extension SettingsProTab {
             authOverride: authOverride)
     }
 
-    func preflightGateway(host: String, port: Int) async -> Bool {
+    func preflightGateway(host: String, port: Int, useTLS: Bool) async -> Bool {
         let trimmed = host.trimmingCharacters(in: .whitespacesAndNewlines)
         guard !trimmed.isEmpty else { return false }
         if Self.isTailnetHostOrIP(trimmed), !Self.hasTailnetIPv4() {

apps/ios/Sources/Gateway/GatewayConnectionController.swift

@@ -3,6 +3,7 @@ import Contacts
 import CoreLocation
 import CoreMotion
 import CryptoKit
+import Darwin
 import EventKit
 import Foundation
 import Network
@@ -168,6 +169,11 @@ final class GatewayConnectionController {
         }
     }
 
+    func allowAutoConnectAgain() {
+        self.didAutoConnect = false
+        self.maybeAutoConnect()
+    }
+
     func restartDiscovery() {
         self.discovery.stop()
         self.didAutoConnect = false
@@ -516,7 +522,8 @@ final class GatewayConnectionController {
             let stableID = self.manualStableID(host: manualHost, port: resolvedPort)
             let tlsParams = self.resolveManualTLSParams(
                 stableID: stableID,
-                tlsEnabled: resolvedUseTLS)
+                tlsEnabled: resolvedUseTLS,
+                allowTOFUReset: self.shouldRequireTLS(host: manualHost))
 
             guard let url = self.buildGatewayURL(
                 host: manualHost,
@@ -712,7 +719,8 @@ final class GatewayConnectionController {
     }
 
     private func resolveDiscoveredTLSParams(
-        gateway: GatewayDiscoveryModel.DiscoveredGateway) -> GatewayTLSParams?
+        gateway: GatewayDiscoveryModel.DiscoveredGateway,
+        allowTOFU: Bool) -> GatewayTLSParams?
     {
         let stableID = gateway.stableID
         let stored = GatewayTLSStore.loadFingerprint(stableID: stableID)
@@ -739,7 +747,8 @@ final class GatewayConnectionController {
 
     private func resolveManualTLSParams(
         stableID: String,
-        tlsEnabled: Bool) -> GatewayTLSParams?
+        tlsEnabled: Bool,
+        allowTOFUReset: Bool = false) -> GatewayTLSParams?
     {
         let stored = GatewayTLSStore.loadFingerprint(stableID: stableID)
         if tlsEnabled || stored != nil {
@@ -776,6 +785,126 @@ final class GatewayConnectionController {
             resolver.start()
         }
     }
+
+    private func resolveHostPortFromBonjourEndpoint(_ endpoint: NWEndpoint) async -> (host: String, port: Int)? {
+        switch endpoint {
+        case let .hostPort(host, port):
+            (host: host.debugDescription, port: Int(port.rawValue))
+        case let .service(name, type, domain, _):
+            await Self.resolveBonjourServiceToHostPort(name: name, type: type, domain: domain)
+        default:
+            nil
+        }
+    }
+
+    private static func resolveBonjourServiceToHostPort(
+        name: String,
+        type: String,
+        domain: String,
+        timeoutSeconds: TimeInterval = 3.0) async -> (host: String, port: Int)?
+    {
+        // NetService callbacks are delivered via a run loop. If we resolve from a thread without one,
+        // we can end up never receiving callbacks, which in turn leaks the continuation and leaves
+        // the UI stuck "connecting". Keep the whole lifecycle on the main run loop and always
+        // resume the continuation exactly once (timeout/cancel safe).
+        @MainActor
+        final class Resolver: NSObject, @preconcurrency NetServiceDelegate {
+            private var cont: CheckedContinuation<(host: String, port: Int)?, Never>?
+            private let service: NetService
+            private var timeoutTask: Task<Void, Never>?
+            private var finished = false
+
+            init(cont: CheckedContinuation<(host: String, port: Int)?, Never>, service: NetService) {
+                self.cont = cont
+                self.service = service
+                super.init()
+            }
+
+            func start(timeoutSeconds: TimeInterval) {
+                self.service.delegate = self
+                self.service.schedule(in: .main, forMode: .default)
+
+                // NetService has its own timeout, but we keep a manual one as a backstop in case
+                // callbacks never arrive (e.g. local network permission issues).
+                self.timeoutTask = Task { @MainActor [weak self] in
+                    guard let self else { return }
+                    let ns = UInt64(max(0.1, timeoutSeconds) * 1_000_000_000)
+                    try? await Task.sleep(nanoseconds: ns)
+                    self.finish(nil)
+                }
+
+                self.service.resolve(withTimeout: timeoutSeconds)
+            }
+
+            func netServiceDidResolveAddress(_ sender: NetService) {
+                self.finish(Self.extractHostPort(sender))
+            }
+
+            func netService(_ sender: NetService, didNotResolve errorDict: [String: NSNumber]) {
+                _ = errorDict // currently best-effort; callers surface a generic failure
+                self.finish(nil)
+            }
+
+            private func finish(_ result: (host: String, port: Int)?) {
+                guard !self.finished else { return }
+                self.finished = true
+
+                self.timeoutTask?.cancel()
+                self.timeoutTask = nil
+
+                self.service.stop()
+                self.service.remove(from: .main, forMode: .default)
+
+                let c = self.cont
+                self.cont = nil
+                c?.resume(returning: result)
+            }
+
+            private static func extractHostPort(_ svc: NetService) -> (host: String, port: Int)? {
+                let port = svc.port
+
+                if let host = svc.hostName?.trimmingCharacters(in: .whitespacesAndNewlines), !host.isEmpty {
+                    return (host: host, port: port)
+                }
+
+                guard let addrs = svc.addresses else { return nil }
+                for addrData in addrs {
+                    let host = addrData.withUnsafeBytes { ptr -> String? in
+                        guard let base = ptr.baseAddress, !ptr.isEmpty else { return nil }
+                        var buffer = [CChar](repeating: 0, count: Int(NI_MAXHOST))
+
+                        let rc = getnameinfo(
+                            base.assumingMemoryBound(to: sockaddr.self),
+                            socklen_t(ptr.count),
+                            &buffer,
+                            socklen_t(buffer.count),
+                            nil,
+                            0,
+                            NI_NUMERICHOST)
+                        guard rc == 0 else { return nil }
+                        let bytes = buffer.prefix { $0 != 0 }.map { UInt8(bitPattern: $0) }
+                        return String(bytes: bytes, encoding: .utf8)
+                    }
+
+                    if let host, !host.isEmpty {
+                        return (host: host, port: port)
+                    }
+                }
+
+                return nil
+            }
+        }
+
+        return await withCheckedContinuation { cont in
+            Task { @MainActor in
+                let service = NetService(domain: domain, type: type, name: name)
+                let resolver = Resolver(cont: cont, service: service)
+                // Keep the resolver alive for the lifetime of the NetService resolve.
+                objc_setAssociatedObject(service, "resolver", resolver, .OBJC_ASSOCIATION_RETAIN_NONATOMIC)
+                resolver.start(timeoutSeconds: timeoutSeconds)
+            }
+        }
+    }
 }
 
 extension GatewayConnectionController {
@@ -1033,10 +1162,30 @@ extension GatewayConnectionController {
         self.currentCommands()
     }
 
+    func _test_currentPermissions() async -> [String: Bool] {
+        await self.currentPermissions()
+    }
+
     static func _test_isLocationAvailable(servicesEnabled: Bool, status: CLAuthorizationStatus) -> Bool {
         self.isLocationAvailable(servicesEnabled: servicesEnabled, status: status)
     }
 
+    func _test_platformString() -> String {
+        DeviceInfoHelper.platformString()
+    }
+
+    func _test_deviceFamily() -> String {
+        DeviceInfoHelper.deviceFamily()
+    }
+
+    func _test_modelIdentifier() -> String {
+        DeviceInfoHelper.modelIdentifier()
+    }
+
+    func _test_appVersion() -> String {
+        DeviceInfoHelper.appVersion()
+    }
+
     func _test_setGateways(_ gateways: [GatewayDiscoveryModel.DiscoveredGateway]) {
         self.gateways = gateways
     }
@@ -1050,9 +1199,10 @@ extension GatewayConnectionController {
     }
 
     func _test_resolveDiscoveredTLSParams(
-        gateway: GatewayDiscoveryModel.DiscoveredGateway) -> GatewayTLSParams?
+        gateway: GatewayDiscoveryModel.DiscoveredGateway,
+        allowTOFU: Bool) -> GatewayTLSParams?
     {
-        self.resolveDiscoveredTLSParams(gateway: gateway)
+        self.resolveDiscoveredTLSParams(gateway: gateway, allowTOFU: allowTOFU)
     }
 
     func _test_resolveManualUseTLS(host: String, useTLS: Bool) -> Bool {

apps/ios/Sources/Gateway/GatewaySettingsStore.swift

@@ -9,6 +9,11 @@ enum GatewaySettingsStore {
     private static let instanceIdDefaultsKey = "node.instanceId"
     private static let preferredGatewayStableIDDefaultsKey = "gateway.preferredStableID"
     private static let lastDiscoveredGatewayStableIDDefaultsKey = "gateway.lastDiscoveredStableID"
+    private static let manualEnabledDefaultsKey = "gateway.manual.enabled"
+    private static let manualHostDefaultsKey = "gateway.manual.host"
+    private static let manualPortDefaultsKey = "gateway.manual.port"
+    private static let manualTlsDefaultsKey = "gateway.manual.tls"
+    private static let discoveryDebugLogsDefaultsKey = "gateway.discovery.debugLogs"
     private static let lastGatewayKindDefaultsKey = "gateway.last.kind"
     private static let lastGatewayHostDefaultsKey = "gateway.last.host"
     private static let lastGatewayPortDefaultsKey = "gateway.last.port"
@@ -179,6 +184,24 @@ enum GatewaySettingsStore {
     enum LastGatewayConnection: Equatable {
         case manual(host: String, port: Int, useTLS: Bool, stableID: String)
         case discovered(stableID: String, useTLS: Bool)
+
+        var stableID: String {
+            switch self {
+            case let .manual(_, _, _, stableID):
+                stableID
+            case let .discovered(stableID, _):
+                stableID
+            }
+        }
+
+        var useTLS: Bool {
+            switch self {
+            case let .manual(_, _, useTLS, _):
+                useTLS
+            case let .discovered(_, useTLS):
+                useTLS
+            }
+        }
     }
 
     private enum LastGatewayKind: String, Codable {
@@ -206,6 +229,17 @@ enum GatewaySettingsStore {
         return nil
     }
 
+    static func saveTalkProviderApiKey(_ apiKey: String?, provider: String) {
+        guard let providerId = self.normalizedTalkProviderID(provider) else { return }
+        let account = self.talkProviderApiKeyAccount(providerId: providerId)
+        let trimmed = apiKey?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if trimmed.isEmpty {
+            _ = KeychainStore.delete(service: self.talkService, account: account)
+            return
+        }
+        _ = KeychainStore.saveString(trimmed, service: self.talkService, account: account)
+    }
+
     static func saveLastGatewayConnectionManual(host: String, port: Int, useTLS: Bool, stableID: String) {
         let payload = LastGatewayConnectionData(
             kind: .manual, stableID: stableID, useTLS: useTLS, host: host, port: port)
@@ -546,4 +580,11 @@ enum GatewayDiagnostics {
             }
         }
     }
+
+    static func reset() {
+        guard let url = fileURL else { return }
+        self.queue.async {
+            try? FileManager.default.removeItem(at: url)
+        }
+    }
 }

apps/ios/Sources/LiveActivity/LiveActivityManager.swift

@@ -17,6 +17,15 @@ final class LiveActivityManager {
         self.hydrateCurrentAndPruneDuplicates()
     }
 
+    var isActive: Bool {
+        guard let activity = self.currentActivity else { return false }
+        guard activity.activityState == .active else {
+            self.currentActivity = nil
+            return false
+        }
+        return true
+    }
+
     func showConnecting(statusText: String = "Connecting...", agentName: String, sessionKey: String) {
         self.hydrateCurrentAndPruneDuplicates()
 
@@ -87,6 +96,10 @@ final class LiveActivityManager {
         self.endActivity(reason: "connected")
     }
 
+    func handleDisconnect() {
+        self.endActivity(reason: "disconnected")
+    }
+
     func endActivity(reason: String) {
         guard let activity = self.currentActivity else { return }
         self.currentActivity = nil
@@ -170,6 +183,15 @@ final class LiveActivityManager {
             startedAt: self.activityStartDate)
     }
 
+    private func idleState() -> OpenClawActivityAttributes.ContentState {
+        OpenClawActivityAttributes.ContentState(
+            statusText: "Idle",
+            isIdle: true,
+            isDisconnected: false,
+            isConnecting: false,
+            startedAt: self.activityStartDate)
+    }
+
     private func disconnectedState() -> OpenClawActivityAttributes.ContentState {
         OpenClawActivityAttributes.ContentState(
             statusText: "Disconnected",

apps/ios/Sources/LiveActivity/OpenClawActivityAttributes.swift

@@ -14,3 +14,39 @@ struct OpenClawActivityAttributes: ActivityAttributes {
         var startedAt: Date
     }
 }
+
+#if DEBUG
+extension OpenClawActivityAttributes {
+    static let preview = OpenClawActivityAttributes(agentName: "main", sessionKey: "main")
+}
+
+extension OpenClawActivityAttributes.ContentState {
+    static let connecting = OpenClawActivityAttributes.ContentState(
+        statusText: "Connecting...",
+        isIdle: false,
+        isDisconnected: false,
+        isConnecting: true,
+        startedAt: .now)
+
+    static let idle = OpenClawActivityAttributes.ContentState(
+        statusText: "Idle",
+        isIdle: true,
+        isDisconnected: false,
+        isConnecting: false,
+        startedAt: .now)
+
+    static let disconnected = OpenClawActivityAttributes.ContentState(
+        statusText: "Disconnected",
+        isIdle: false,
+        isDisconnected: true,
+        isConnecting: false,
+        startedAt: .now)
+
+    static let attention = OpenClawActivityAttributes.ContentState(
+        statusText: "Approval needed",
+        isIdle: false,
+        isDisconnected: false,
+        isConnecting: false,
+        startedAt: .now)
+}
+#endif

apps/ios/Sources/Location/LocationService.swift

@@ -12,6 +12,8 @@ final class LocationService: NSObject, CLLocationManagerDelegate, LocationServic
     private let manager = CLLocationManager()
     private var authContinuation: CheckedContinuation<CLAuthorizationStatus, Never>?
     private var locationContinuation: CheckedContinuation<CLLocation, Swift.Error>?
+    private var updatesContinuation: AsyncStream<CLLocation>.Continuation?
+    private var isStreaming = false
     private var significantLocationCallback: (@Sendable (CLLocation) -> Void)?
     private var isMonitoringSignificantChanges = false
 
@@ -82,6 +84,42 @@ final class LocationService: NSObject, CLLocationManagerDelegate, LocationServic
         try await AsyncTimeout.withTimeoutMs(timeoutMs: timeoutMs, onTimeout: { Error.timeout }, operation: operation)
     }
 
+    func startLocationUpdates(
+        desiredAccuracy: OpenClawLocationAccuracy,
+        significantChangesOnly: Bool) -> AsyncStream<CLLocation>
+    {
+        self.stopLocationUpdates()
+
+        self.manager.desiredAccuracy = LocationCurrentRequest.accuracyValue(desiredAccuracy)
+        self.manager.pausesLocationUpdatesAutomatically = true
+        self.manager.allowsBackgroundLocationUpdates = true
+
+        self.isStreaming = true
+        if significantChangesOnly {
+            self.manager.startMonitoringSignificantLocationChanges()
+        } else {
+            self.manager.startUpdatingLocation()
+        }
+
+        return AsyncStream(bufferingPolicy: .bufferingNewest(1)) { continuation in
+            self.updatesContinuation = continuation
+            continuation.onTermination = { @Sendable _ in
+                Task { @MainActor in
+                    self.stopLocationUpdates()
+                }
+            }
+        }
+    }
+
+    func stopLocationUpdates() {
+        guard self.isStreaming else { return }
+        self.isStreaming = false
+        self.manager.stopUpdatingLocation()
+        self.manager.stopMonitoringSignificantLocationChanges()
+        self.updatesContinuation?.finish()
+        self.updatesContinuation = nil
+    }
+
     func startMonitoringSignificantLocationChanges(onUpdate: @escaping @Sendable (CLLocation) -> Void) {
         self.significantLocationCallback = onUpdate
         guard !self.isMonitoringSignificantChanges else { return }
@@ -89,6 +127,13 @@ final class LocationService: NSObject, CLLocationManagerDelegate, LocationServic
         self.manager.startMonitoringSignificantLocationChanges()
     }
 
+    func stopMonitoringSignificantLocationChanges() {
+        guard self.isMonitoringSignificantChanges else { return }
+        self.isMonitoringSignificantChanges = false
+        self.significantLocationCallback = nil
+        self.manager.stopMonitoringSignificantLocationChanges()
+    }
+
     nonisolated func locationManagerDidChangeAuthorization(_ manager: CLLocationManager) {
         let status = manager.authorizationStatus
         Task { @MainActor in
@@ -116,6 +161,9 @@ final class LocationService: NSObject, CLLocationManagerDelegate, LocationServic
             if let callback = self.significantLocationCallback, let latest = locs.last {
                 callback(latest)
             }
+            if let latest = locs.last, let updates = self.updatesContinuation {
+                updates.yield(latest)
+            }
         }
     }
 

apps/ios/Sources/Model/NodeAppModel.swift

@@ -133,6 +133,7 @@ final class NodeAppModel {
         self.lastGatewayProblem?.statusText ?? self.gatewayStatusText
     }
 
+    var seamColorHex: String?
     private var mainSessionBaseKey: String = "main"
     private var focusedChatSessionKey: String?
     var selectedAgentId: String?
@@ -201,6 +202,9 @@ final class NodeAppModel {
     private var apnsDeviceTokenHex: String?
     private var apnsLastRegisteredTokenHex: String?
     @ObservationIgnored private let pushRegistrationManager = PushRegistrationManager()
+    var gatewaySession: GatewayNodeSession {
+        self.nodeGateway
+    }
 
     var operatorSession: GatewayNodeSession {
         self.operatorGateway
@@ -720,6 +724,11 @@ final class NodeAppModel {
         }
     }
 
+    var seamColor: Color {
+        Self.color(fromHex: self.seamColorHex) ?? Self.defaultSeamColor
+    }
+
+    private static let defaultSeamColor = Color(red: 79 / 255.0, green: 122 / 255.0, blue: 154 / 255.0)
     private static let apnsDeviceTokenUserDefaultsKey = "push.apns.deviceTokenHex"
     private static let deepLinkKeyUserDefaultsKey = "deeplink.agent.key"
     private static let canvasUnattendedDeepLinkKey: String = NodeAppModel.generateDeepLinkKey()
@@ -729,9 +738,12 @@ final class NodeAppModel {
             let res = try await self.operatorGateway.request(method: "config.get", paramsJSON: "{}", timeoutSeconds: 8)
             guard let json = try JSONSerialization.jsonObject(with: res) as? [String: Any] else { return }
             guard let config = json["config"] as? [String: Any] else { return }
+            let ui = config["ui"] as? [String: Any]
+            let raw = (ui?["seamColor"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
             let session = config["session"] as? [String: Any]
             let mainKey = SessionKey.normalizeMainKey(session?["mainKey"] as? String)
             await MainActor.run {
+                self.seamColorHex = raw.isEmpty ? nil : raw
                 self.mainSessionBaseKey = mainKey
                 self.talkMode.updateMainSessionKey(self.mainSessionKey)
                 self.homeCanvasRevision &+= 1
@@ -1936,7 +1948,7 @@ extension NodeAppModel {
         }
 
         self.activeGatewayConnectConfig = nextConfig
-        self.prepareForGatewayConnect(stableID: effectiveStableID)
+        self.prepareForGatewayConnect(url: url, stableID: effectiveStableID)
         if operatorLoopRequired {
             self.startOperatorGatewayLoop(
                 url: url,
@@ -2033,6 +2045,7 @@ extension NodeAppModel {
         self.gatewayConnected = false
         self.setOperatorConnected(false)
         self.talkMode.updateGatewayConnected(false)
+        self.seamColorHex = nil
         self.mainSessionBaseKey = "main"
         self.talkMode.updateMainSessionKey(self.mainSessionKey)
         ShareGatewayRelaySettings.clearConfig()
@@ -2041,7 +2054,7 @@ extension NodeAppModel {
 }
 
 extension NodeAppModel {
-    private func prepareForGatewayConnect(stableID: String) {
+    private func prepareForGatewayConnect(url: URL, stableID: String) {
         self.isAppleReviewDemoModeEnabled = false
         self.gatewayAutoReconnectEnabled = true
         self.gatewayPairingPaused = false
@@ -2645,6 +2658,7 @@ extension NodeAppModel {
                 self.gatewayConnected = false
                 self.setOperatorConnected(false)
                 self.talkMode.updateGatewayConnected(false)
+                self.seamColorHex = nil
                 self.mainSessionBaseKey = "main"
                 self.talkMode.updateMainSessionKey(self.mainSessionKey)
                 self.showLocalCanvasOnDisconnect()
@@ -2817,6 +2831,7 @@ extension NodeAppModel {
         self.talkMode.updateGatewayConnected(false)
         self.talkMode.setEnabled(false)
         self.talkMode.statusText = "Demo mode only"
+        self.seamColorHex = nil
         self.mainSessionBaseKey = "main"
         self.selectedAgentId = nil
         self.gatewayDefaultAgentId = "main"
@@ -2931,6 +2946,14 @@ extension NodeAppModel {
         self.refreshLastShareEventFromRelay()
     }
 
+    func reloadTalkConfig() {
+        Task { [weak self] in
+            guard let self else { return }
+            await self.talkMode.reloadConfig()
+            await self.talkMode.prefetchRealtimeSessionIfReady(reason: "config_reload")
+        }
+    }
+
     /// Back-compat hook retained for older gateway-connect flows.
     func onNodeGatewayConnected() async {
         await self.registerAPNsTokenIfNeeded()
@@ -3891,6 +3914,32 @@ extension NodeAppModel {
         }
     }
 
+    func handleExecApprovalNotificationDecision(
+        approvalId: String,
+        decision: String) async
+    {
+        let normalizedApprovalID = approvalId.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !normalizedApprovalID.isEmpty else { return }
+
+        if self.pendingExecApprovalPrompt?.id == normalizedApprovalID {
+            self.pendingExecApprovalPromptResolving = true
+            self.pendingExecApprovalPromptErrorText = nil
+        }
+
+        let outcome = await self.resolveExecApprovalNotificationDecision(
+            approvalId: normalizedApprovalID,
+            decision: decision)
+        switch outcome {
+        case .resolved, .stale, .unavailable:
+            break
+        case let .failed(message):
+            if self.pendingExecApprovalPrompt?.id == normalizedApprovalID {
+                self.pendingExecApprovalPromptResolving = false
+                self.pendingExecApprovalPromptErrorText = message
+            }
+        }
+    }
+
     private func resolveExecApprovalNotificationDecision(
         approvalId: String,
         decision: String,
@@ -4427,6 +4476,17 @@ extension NodeAppModel {
         self.talkMode.updateMainSessionKey(self.mainSessionKey)
     }
 
+    private static func color(fromHex raw: String?) -> Color? {
+        let trimmed = (raw ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return nil }
+        let hex = trimmed.hasPrefix("#") ? String(trimmed.dropFirst()) : trimmed
+        guard hex.count == 6, let value = Int(hex, radix: 16) else { return nil }
+        let r = Double((value >> 16) & 0xFF) / 255.0
+        let g = Double((value >> 8) & 0xFF) / 255.0
+        let b = Double(value & 0xFF) / 255.0
+        return Color(red: r, green: g, blue: b)
+    }
+
     func approvePendingAgentDeepLinkPrompt() async {
         guard let prompt = self.pendingAgentDeepLinkPrompt else { return }
         self.pendingAgentDeepLinkPrompt = nil
@@ -4576,10 +4636,30 @@ extension NodeAppModel {
         try self.encodePayload(obj)
     }
 
+    func _test_isCameraEnabled() -> Bool {
+        self.isCameraEnabled()
+    }
+
+    func _test_triggerCameraFlash() {
+        self.triggerCameraFlash()
+    }
+
+    func _test_showCameraHUD(text: String, kind: CameraHUDKind, autoHideSeconds: Double? = nil) {
+        self.showCameraHUD(text: text, kind: kind, autoHideSeconds: autoHideSeconds)
+    }
+
     func _test_handleCanvasA2UIAction(body: [String: Any]) async {
         await self.handleCanvasA2UIAction(body: body)
     }
 
+    func _test_showLocalCanvasOnDisconnect() {
+        self.showLocalCanvasOnDisconnect()
+    }
+
+    func _test_applyTalkModeSync(enabled: Bool, phase: String? = nil) {
+        self.applyTalkModeSync(enabled: enabled, phase: phase)
+    }
+
     func _test_queuedWatchReplyCount() -> Int {
         self.watchReplyCoordinator.queuedCount
     }

apps/ios/Sources/Onboarding/GatewayOnboardingView.swift

@@ -0,0 +1,365 @@
+import Foundation
+import OpenClawKit
+import SwiftUI
+
+struct GatewayOnboardingView: View {
+    var body: some View {
+        NavigationStack {
+            List {
+                Section {
+                    Text("Connect to your gateway to get started.")
+                        .foregroundStyle(.secondary)
+                }
+
+                Section {
+                    NavigationLink("Auto detect") {
+                        AutoDetectStep()
+                    }
+                    NavigationLink("Manual entry") {
+                        ManualEntryStep()
+                    }
+                }
+            }
+            .navigationTitle("Connect Gateway")
+        }
+        .gatewayTrustPromptAlert()
+    }
+}
+
+private struct AutoDetectStep: View {
+    @Environment(NodeAppModel.self) private var appModel: NodeAppModel
+    @Environment(GatewayConnectionController.self) private var gatewayController: GatewayConnectionController
+    @AppStorage("gateway.preferredStableID") private var preferredGatewayStableID: String = ""
+    @AppStorage("gateway.lastDiscoveredStableID") private var lastDiscoveredGatewayStableID: String = ""
+
+    @State private var connectingGatewayID: String?
+    @State private var connectStatusText: String?
+
+    var body: some View {
+        Form {
+            Section {
+                Text("We’ll scan for gateways on your network and connect automatically when we find one.")
+                    .foregroundStyle(.secondary)
+            }
+
+            gatewayConnectionStatusSection(
+                appModel: self.appModel,
+                gatewayController: self.gatewayController,
+                secondaryLine: self.connectStatusText)
+
+            Section {
+                Button("Retry") {
+                    resetGatewayConnectionState(
+                        appModel: self.appModel,
+                        connectStatusText: &self.connectStatusText,
+                        connectingGatewayID: &self.connectingGatewayID)
+                    self.triggerAutoConnect()
+                }
+                .disabled(self.connectingGatewayID != nil)
+            }
+        }
+        .navigationTitle("Auto detect")
+        .onAppear { self.triggerAutoConnect() }
+        .onChange(of: self.gatewayController.gateways) { _, _ in
+            self.triggerAutoConnect()
+        }
+    }
+
+    private func triggerAutoConnect() {
+        guard self.appModel.gatewayServerName == nil else { return }
+        guard self.connectingGatewayID == nil else { return }
+        guard let candidate = self.autoCandidate() else { return }
+
+        self.connectingGatewayID = candidate.id
+        Task {
+            defer { self.connectingGatewayID = nil }
+            await self.gatewayController.connect(candidate)
+        }
+    }
+
+    private func autoCandidate() -> GatewayDiscoveryModel.DiscoveredGateway? {
+        let preferred = self.preferredGatewayStableID.trimmingCharacters(in: .whitespacesAndNewlines)
+        let lastDiscovered = self.lastDiscoveredGatewayStableID.trimmingCharacters(in: .whitespacesAndNewlines)
+
+        if !preferred.isEmpty,
+           let match = self.gatewayController.gateways.first(where: { $0.stableID == preferred })
+        {
+            return match
+        }
+        if !lastDiscovered.isEmpty,
+           let match = self.gatewayController.gateways.first(where: { $0.stableID == lastDiscovered })
+        {
+            return match
+        }
+        if self.gatewayController.gateways.count == 1 {
+            return self.gatewayController.gateways.first
+        }
+        return nil
+    }
+}
+
+private struct ManualEntryStep: View {
+    @Environment(NodeAppModel.self) private var appModel: NodeAppModel
+    @Environment(GatewayConnectionController.self) private var gatewayController: GatewayConnectionController
+
+    @State private var setupCode: String = ""
+    @State private var setupStatusText: String?
+    @State private var manualHost: String = ""
+    @State private var manualPortText: String = ""
+    @State private var manualUseTLS: Bool = true
+    @State private var manualToken: String = ""
+    @State private var manualPassword: String = ""
+    @State private var pendingManualAuthOverride: GatewayConnectionController.ManualAuthOverride?
+
+    @State private var connectingGatewayID: String?
+    @State private var connectStatusText: String?
+
+    var body: some View {
+        Form {
+            Section("Setup code") {
+                Text("Use /pair in your bot to get a setup code.")
+                    .font(.footnote)
+                    .foregroundStyle(.secondary)
+
+                TextField("Paste setup code", text: self.$setupCode)
+                    .textInputAutocapitalization(.never)
+                    .autocorrectionDisabled()
+
+                Button("Apply setup code") {
+                    self.applySetupCode()
+                }
+                .disabled(self.setupCode.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty)
+
+                if let setupStatusText, !setupStatusText.isEmpty {
+                    Text(setupStatusText)
+                        .font(.footnote)
+                        .foregroundStyle(.secondary)
+                }
+            }
+
+            Section {
+                TextField("Host", text: self.$manualHost)
+                    .textInputAutocapitalization(.never)
+                    .autocorrectionDisabled()
+
+                TextField("Port", text: self.$manualPortText)
+                    .keyboardType(.numberPad)
+
+                Toggle("Use TLS", isOn: self.$manualUseTLS)
+
+                TextField("Gateway token", text: self.$manualToken)
+                    .textInputAutocapitalization(.never)
+                    .autocorrectionDisabled()
+
+                SecureField("Gateway password", text: self.$manualPassword)
+                    .textInputAutocapitalization(.never)
+                    .autocorrectionDisabled()
+            }
+
+            gatewayConnectionStatusSection(
+                appModel: self.appModel,
+                gatewayController: self.gatewayController,
+                secondaryLine: self.connectStatusText)
+
+            Section {
+                Button {
+                    Task { await self.connectManual() }
+                } label: {
+                    if self.connectingGatewayID == "manual" {
+                        HStack(spacing: 8) {
+                            ProgressView()
+                                .progressViewStyle(.circular)
+                            Text("Connecting…")
+                        }
+                    } else {
+                        Text("Connect")
+                    }
+                }
+                .disabled(self.connectingGatewayID != nil)
+
+                Button("Retry") {
+                    resetGatewayConnectionState(
+                        appModel: self.appModel,
+                        connectStatusText: &self.connectStatusText,
+                        connectingGatewayID: &self.connectingGatewayID)
+                    self.resetManualForm()
+                }
+                .disabled(self.connectingGatewayID != nil)
+            }
+        }
+        .navigationTitle("Manual entry")
+    }
+
+    private func connectManual() async {
+        let host = self.manualHost.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !host.isEmpty else {
+            self.connectStatusText = "Failed: host required"
+            return
+        }
+
+        if let port = self.manualPortValue(), !(1...65535).contains(port) {
+            self.connectStatusText = "Failed: invalid port"
+            return
+        }
+
+        let defaults = UserDefaults.standard
+        defaults.set(true, forKey: "gateway.manual.enabled")
+        defaults.set(host, forKey: "gateway.manual.host")
+        defaults.set(self.manualPortValue() ?? 0, forKey: "gateway.manual.port")
+        defaults.set(self.manualUseTLS, forKey: "gateway.manual.tls")
+
+        let instanceId = GatewaySettingsStore.currentInstanceID()
+        if !instanceId.isEmpty {
+            let trimmedToken = self.manualToken.trimmingCharacters(in: .whitespacesAndNewlines)
+            let trimmedPassword = self.manualPassword.trimmingCharacters(in: .whitespacesAndNewlines)
+            if !trimmedToken.isEmpty {
+                GatewaySettingsStore.saveGatewayToken(trimmedToken, instanceId: instanceId)
+            }
+            GatewaySettingsStore.saveGatewayPassword(trimmedPassword, instanceId: instanceId)
+        }
+
+        self.connectingGatewayID = "manual"
+        defer { self.connectingGatewayID = nil }
+        let authOverride = GatewayConnectionController.ManualAuthOverride.currentManualInput(
+            token: self.manualToken,
+            pendingOverride: self.pendingManualAuthOverride,
+            password: self.manualPassword)
+        self.pendingManualAuthOverride = nil
+        await self.gatewayController.connectManual(
+            host: host,
+            port: self.manualPortValue() ?? 0,
+            useTLS: self.manualUseTLS,
+            authOverride: authOverride)
+    }
+
+    private func manualPortValue() -> Int? {
+        let trimmed = self.manualPortText.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return nil }
+        return Int(trimmed.filter(\.isNumber))
+    }
+
+    private func resetManualForm() {
+        self.setupCode = ""
+        self.setupStatusText = nil
+        self.manualHost = ""
+        self.manualPortText = ""
+        self.manualUseTLS = true
+        self.manualToken = ""
+        self.manualPassword = ""
+    }
+
+    private func applySetupCode() {
+        let raw = self.setupCode.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !raw.isEmpty else {
+            self.setupStatusText = "Paste a setup code to continue."
+            return
+        }
+
+        if AppleReviewDemoMode.isSetupCode(raw) {
+            self.setupCode = ""
+            self.setupStatusText = "Apple Review demo mode enabled."
+            self.appModel.enterAppleReviewDemoMode()
+            return
+        }
+
+        guard let link = GatewayConnectDeepLink.fromSetupInput(raw) else {
+            self.setupStatusText = "Setup code not recognized or uses an insecure ws:// gateway URL."
+            return
+        }
+
+        self.manualHost = link.host
+        self.manualPortText = String(link.port)
+        self.manualUseTLS = link.tls
+
+        let setupAuth = GatewayConnectionController.ManualAuthOverride.setupAuth(from: link)
+        if setupAuth.shouldApplyTokenField {
+            self.manualToken = setupAuth.token
+        }
+        if setupAuth.shouldApplyPasswordField {
+            self.manualPassword = setupAuth.password
+        }
+
+        let trimmedInstanceId = GatewaySettingsStore.currentInstanceID()
+        if !trimmedInstanceId.isEmpty {
+            if setupAuth.hasBootstrapToken {
+                GatewayOnboardingReset.prepareForBootstrapPairing(
+                    appModel: self.appModel,
+                    instanceId: trimmedInstanceId)
+            }
+            GatewaySettingsStore.saveGatewayBootstrapToken(setupAuth.bootstrapToken, instanceId: trimmedInstanceId)
+        }
+        self.pendingManualAuthOverride = setupAuth.manualAuthOverride
+
+        self.setupStatusText = "Setup code applied."
+    }
+}
+
+@MainActor
+private func gatewayConnectionStatusLines(
+    appModel: NodeAppModel,
+    gatewayController: GatewayConnectionController) -> [String]
+{
+    ConnectionStatusBox.defaultLines(appModel: appModel, gatewayController: gatewayController)
+}
+
+@MainActor
+private func resetGatewayConnectionState(
+    appModel: NodeAppModel,
+    connectStatusText: inout String?,
+    connectingGatewayID: inout String?)
+{
+    appModel.disconnectGateway()
+    connectStatusText = nil
+    connectingGatewayID = nil
+}
+
+@MainActor
+private func gatewayConnectionStatusSection(
+    appModel: NodeAppModel,
+    gatewayController: GatewayConnectionController,
+    secondaryLine: String?) -> some View
+{
+    Section("Connection status") {
+        ConnectionStatusBox(
+            statusLines: gatewayConnectionStatusLines(
+                appModel: appModel,
+                gatewayController: gatewayController),
+            secondaryLine: secondaryLine)
+    }
+}
+
+private struct ConnectionStatusBox: View {
+    let statusLines: [String]
+    let secondaryLine: String?
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 6) {
+            ForEach(self.statusLines, id: \.self) { line in
+                Text(line)
+                    .font(.system(size: 12, weight: .regular, design: .monospaced))
+                    .foregroundStyle(.secondary)
+            }
+            if let secondaryLine, !secondaryLine.isEmpty {
+                Text(secondaryLine)
+                    .font(.footnote)
+                    .foregroundStyle(.secondary)
+            }
+        }
+        .frame(maxWidth: .infinity, alignment: .leading)
+        .padding(10)
+        .background(.thinMaterial, in: RoundedRectangle(cornerRadius: 10, style: .continuous))
+    }
+
+    static func defaultLines(
+        appModel: NodeAppModel,
+        gatewayController: GatewayConnectionController) -> [String]
+    {
+        var lines: [String] = [
+            "gateway: \(appModel.gatewayDisplayStatusText)",
+            "discovery: \(gatewayController.discoveryStatusText)",
+        ]
+        lines.append("server: \(appModel.gatewayServerName ?? "—")")
+        lines.append("address: \(appModel.gatewayRemoteAddress ?? "—")")
+        return lines
+    }
+}

apps/ios/Sources/Onboarding/OnboardingStateStore.swift

@@ -53,6 +53,10 @@ enum OnboardingStateStore {
         defaults.set(true, forKey: self.firstRunIntroSeenDefaultsKey)
     }
 
+    static func markIncomplete(defaults: UserDefaults = .standard) {
+        defaults.set(false, forKey: self.completedDefaultsKey)
+    }
+
     static func reset(defaults: UserDefaults = .standard) {
         defaults.set(false, forKey: self.completedDefaultsKey)
         defaults.set(false, forKey: self.firstRunIntroSeenDefaultsKey)

apps/ios/Sources/Onboarding/OnboardingWizardView.swift

@@ -17,6 +17,10 @@ private enum OnboardingStep: Int, CaseIterable {
         Self(rawValue: self.rawValue - 1)
     }
 
+    var next: Self? {
+        Self(rawValue: self.rawValue + 1)
+    }
+
     /// Progress label for the manual setup flow (mode → connect → auth → success).
     var manualProgressTitle: String {
         let manualSteps: [OnboardingStep] = [.mode, .connect, .auth, .success]

apps/ios/Sources/Push/PushBuildConfig.swift

@@ -39,6 +39,10 @@ struct PushBuildConfig {
         self.relayBaseURL = Self.readURL(bundle: bundle, key: "OpenClawPushRelayBaseURL")
     }
 
+    var usesRelay: Bool {
+        self.transport == .relay
+    }
+
     private static func readURL(bundle: Bundle, key: String) -> URL? {
         guard let raw = bundle.object(forInfoDictionaryKey: key) as? String else { return nil }
         let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)

apps/ios/Sources/Push/PushRelayKeychainStore.swift

@@ -71,6 +71,11 @@ enum PushRelayRegistrationStore {
         return KeychainStore.saveString(raw, service: self.service, account: self.registrationStateAccount)
     }
 
+    @discardableResult
+    static func clearRegistrationState() -> Bool {
+        KeychainStore.delete(service: self.service, account: self.registrationStateAccount)
+    }
+
     static func loadAppAttestKeyID() -> String? {
         let value = KeychainStore.loadString(service: self.service, account: self.appAttestKeyIDAccount)?
             .trimmingCharacters(in: .whitespacesAndNewlines)

apps/ios/Sources/RootTabsNavigation.swift

@@ -7,6 +7,7 @@ extension RootTabs {
         980
     }
 
+    static let sidebarSplitMinimumWidth: CGFloat = 292
     static let sidebarSplitIdealWidth: CGFloat = 316
     static let sidebarSplitMaximumWidth: CGFloat = 340
     static let sidebarDrawerMaximumWidth: CGFloat = 340

apps/ios/Sources/RootView.swift

@@ -0,0 +1,15 @@
+import SwiftUI
+
+struct RootView: View {
+    @AppStorage(AppAppearancePreference.storageKey) private var appearancePreferenceRaw: String =
+        AppAppearancePreference.system.rawValue
+
+    var body: some View {
+        RootTabs()
+            .preferredColorScheme(self.appearancePreference.colorScheme)
+    }
+
+    private var appearancePreference: AppAppearancePreference {
+        AppAppearancePreference(rawValue: self.appearancePreferenceRaw) ?? .system
+    }
+}

apps/ios/Sources/Screen/ScreenController.swift

@@ -181,6 +181,16 @@ final class ScreenController {
         return try await WebViewJavaScriptSupport.evaluateToString(webView: webView, javaScript: javaScript)
     }
 
+    func snapshotPNGBase64(maxWidth: CGFloat? = nil) async throws -> String {
+        let image = try await self.snapshotImage(maxWidth: maxWidth)
+        guard let data = image.pngData() else {
+            throw NSError(domain: "Screen", code: 1, userInfo: [
+                NSLocalizedDescriptionKey: "snapshot encode failed",
+            ])
+        }
+        return data.base64EncodedString()
+    }
+
     func snapshotBase64(
         maxWidth: CGFloat? = nil,
         format: OpenClawCanvasSnapshotFormat,

apps/ios/Sources/Services/NodeServiceProtocols.swift

@@ -31,7 +31,12 @@ protocol LocationServicing: Sendable {
         desiredAccuracy: OpenClawLocationAccuracy,
         maxAgeMs: Int?,
         timeoutMs: Int?) async throws -> CLLocation
+    func startLocationUpdates(
+        desiredAccuracy: OpenClawLocationAccuracy,
+        significantChangesOnly: Bool) -> AsyncStream<CLLocation>
+    func stopLocationUpdates()
     func startMonitoringSignificantLocationChanges(onUpdate: @escaping @Sendable (CLLocation) -> Void)
+    func stopMonitoringSignificantLocationChanges()
 }
 
 @MainActor

apps/ios/Sources/SessionKey.swift

@@ -22,4 +22,11 @@ enum SessionKey {
         let agentId = String(parts[1]).trimmingCharacters(in: .whitespacesAndNewlines)
         return agentId.isEmpty ? nil : agentId
     }
+
+    static func isCanonicalMainSessionKey(_ value: String?) -> Bool {
+        let trimmed = (value ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmed.isEmpty { return false }
+        if trimmed == "global" { return true }
+        return trimmed.hasPrefix("agent:")
+    }
 }

apps/ios/Sources/Settings/SettingsNetworkingHelpers.swift

@@ -0,0 +1,40 @@
+import Foundation
+
+struct SettingsHostPort: Equatable {
+    var host: String
+    var port: Int
+}
+
+enum SettingsNetworkingHelpers {
+    static func parseHostPort(from address: String) -> SettingsHostPort? {
+        let trimmed = address.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return nil }
+
+        if trimmed.hasPrefix("["),
+           let close = trimmed.firstIndex(of: "]"),
+           close < trimmed.endIndex
+        {
+            let host = String(trimmed[trimmed.index(after: trimmed.startIndex)..<close])
+            let portStart = trimmed.index(after: close)
+            guard portStart < trimmed.endIndex, trimmed[portStart] == ":" else { return nil }
+            let portString = String(trimmed[trimmed.index(after: portStart)...])
+            guard let port = Int(portString) else { return nil }
+            return SettingsHostPort(host: host, port: port)
+        }
+
+        guard let colon = trimmed.lastIndex(of: ":") else { return nil }
+        let host = String(trimmed[..<colon])
+        let portString = String(trimmed[trimmed.index(after: colon)...])
+        guard !host.isEmpty, let port = Int(portString) else { return nil }
+        return SettingsHostPort(host: host, port: port)
+    }
+
+    static func httpURLString(host: String?, port: Int?, fallback: String) -> String {
+        if let host, let port {
+            let needsBrackets = host.contains(":") && !host.hasPrefix("[") && !host.hasSuffix("]")
+            let hostPart = needsBrackets ? "[\(host)]" : host
+            return "http://\(hostPart):\(port)"
+        }
+        return "http://\(fallback)"
+    }
+}

apps/ios/Sources/Voice/TalkModeGatewayConfig.swift

@@ -3,6 +3,7 @@ import OpenClawKit
 
 enum TalkModeExecutionMode {
     case native
+    case realtimeClient
     case realtimeRelay
 }
 

apps/ios/Sources/Voice/TalkModeManager+Permissions.swift

@@ -64,6 +64,22 @@ extension TalkModeManager {
         }
     }
 
+    static func permissionMessage(
+        kind: String,
+        status: AVAudioSession.RecordPermission) -> String
+    {
+        switch status {
+        case .denied:
+            return "\(kind) permission denied"
+        case .undetermined:
+            return "\(kind) permission not granted"
+        case .granted:
+            return "\(kind) permission denied"
+        @unknown default:
+            return "\(kind) permission denied"
+        }
+    }
+
     static func permissionMessage(
         kind: String,
         status: SFSpeechRecognizerAuthorizationStatus) -> String

apps/ios/Sources/Voice/TalkModeManager.swift

@@ -70,6 +70,11 @@ final class TalkModeManager: NSObject {
         self.gatewayConnected
     }
 
+    var hasActiveAudioCapture: Bool {
+        self.isEnabled || self.isListening || self.isPushToTalkActive || self.realtimeRelaySession != nil
+            || self.realtimeRelayStartInFlight
+    }
+
     private enum CaptureMode {
         case idle
         case continuous
@@ -470,6 +475,13 @@ final class TalkModeManager: NSObject {
         return wasActive
     }
 
+    func setForegroundAudioCaptureAllowed(_ allowed: Bool) {
+        self.foregroundAudioCaptureAllowed = allowed
+        if !allowed {
+            self.cancelPendingStart()
+        }
+    }
+
     func resumeAfterBackground(wasSuspended: Bool, wasKeptActive: Bool = false) async {
         if wasKeptActive { return }
         guard wasSuspended else { return }
@@ -477,6 +489,14 @@ final class TalkModeManager: NSObject {
         await self.start()
     }
 
+    func userTappedOrb() {
+        if let realtimeSession {
+            realtimeSession.cancelResponse()
+        }
+        self.realtimeRelaySession?.cancelOutput()
+        self.stopSpeaking()
+    }
+
     func beginPushToTalk() async throws -> OpenClawTalkPTTStartPayload {
         guard self.gatewayConnected else {
             self.statusText = "Offline"
@@ -3084,6 +3104,23 @@ extension TalkModeManager {
         self.gatewayTalkCurrentFallbackIssue
     }
 
+    func _test_seedTranscript(_ transcript: String) {
+        self.lastTranscript = transcript
+        self.lastHeard = Date()
+    }
+
+    func _test_handleTranscript(_ transcript: String, isFinal: Bool) async {
+        await self.handleTranscript(transcript: transcript, isFinal: isFinal)
+    }
+
+    func _test_backdateLastHeard(seconds: TimeInterval) {
+        self.lastHeard = Date().addingTimeInterval(-seconds)
+    }
+
+    func _test_runSilenceCheck() async {
+        await self.checkSilence()
+    }
+
     func _test_incrementalReset() {
         self.incrementalSpeechBuffer = IncrementalSpeechBuffer()
     }

apps/ios/Sources/Voice/TalkPermissionPromptView.swift

@@ -3,6 +3,7 @@ import SwiftUI
 struct TalkPermissionPromptView: View {
     enum Style {
         case card
+        case settings
         case sheet
     }
 

apps/ios/Sources/Voice/TalkRealtimeWebRTCSession.swift

@@ -61,6 +61,7 @@ final class TalkRealtimeWebRTCSession: NSObject {
         let runId: String?
         let status: String?
         let startedAt: Double?
+        let endedAt: Double?
         let error: String?
         let stopReason: String?
         let timeoutPhase: String?
@@ -195,6 +196,11 @@ final class TalkRealtimeWebRTCSession: NSObject {
         Self.logger.info("timeline +\(self.elapsedMs(), privacy: .public)ms \(message, privacy: .public)")
     }
 
+    func cancelResponse() {
+        self.sendRealtimeEvent(["type": "response.cancel"])
+        self.cancelActiveToolCalls()
+    }
+
     private func cancelActiveToolCalls() {
         let runIds = Array(Set(activeToolRunIds.values))
         for task in self.activeToolTasks.values {

apps/ios/Sources/Voice/TalkSpeechLocale.swift

@@ -70,6 +70,14 @@ enum TalkSpeechLocale {
         return (recognizer, recognizer?.locale.identifier)
     }
 
+    static func normalizedExplicitLocaleID(_ raw: String?) -> String? {
+        TalkConfigParsing.normalizedExplicitSpeechLocaleID(raw, automaticID: self.automaticID)
+    }
+
+    private static func normalizedLocaleID(_ raw: String?) -> String? {
+        TalkConfigParsing.normalizedSpeechLocaleID(raw)
+    }
+
     private static func canonicalID(_ raw: String) -> String {
         raw.replacingOccurrences(of: "_", with: "-")
     }

apps/ios/SwiftSources.input.xcfilelist

@@ -16,6 +16,7 @@ Sources/Design/ChatProTab.swift
 Sources/Design/CommandCenterTab.swift
 Sources/Design/TalkProTab.swift
 Sources/Design/OpenClawProComponents.swift
+Sources/Design/OpenClawProScreens.swift
 Sources/Design/SettingsProTab.swift
 Sources/Design/SettingsProTabSupport.swift
 Sources/Design/SettingsProTabSections.swift
@@ -66,6 +67,7 @@ Sources/Model/NodeAppModel.swift
 Sources/Model/WatchReplyCoordinator.swift
 Sources/Motion/MotionService.swift
 Sources/Onboarding/GatewayOnboardingReset.swift
+Sources/Onboarding/GatewayOnboardingView.swift
 Sources/Onboarding/OnboardingStateStore.swift
 Sources/Onboarding/OnboardingWizardSteps.swift
 Sources/Onboarding/OnboardingWizardView.swift
@@ -81,6 +83,7 @@ Sources/Push/PushRelayKeychainStore.swift
 Sources/Reminders/RemindersService.swift
 Sources/RootTabs.swift
 Sources/RootTabsNavigation.swift
+Sources/RootView.swift
 Sources/Screen/ScreenController.swift
 Sources/Screen/ScreenRecordService.swift
 Sources/Screen/ScreenWebView.swift
@@ -91,6 +94,7 @@ Sources/Services/WatchMessagingPayloadCodec.swift
 Sources/Services/WatchMessagingService.swift
 Sources/SessionKey.swift
 Sources/Settings/PrivacyAccessSectionView.swift
+Sources/Settings/SettingsNetworkingHelpers.swift
 Sources/Settings/VoiceWakeWordsSettingsView.swift
 Sources/Status/GatewayStatusBuilder.swift
 Sources/Status/VoiceWakeToast.swift

apps/ios/Tests/GatewayConnectionSecurityTests.swift

@@ -39,19 +39,19 @@ import Testing
     @Test @MainActor func discoveredTLSParams_prefersStoredPinOverAdvertisedTXT() async {
         let stableID = "test|\(UUID().uuidString)"
         defer { clearTLSFingerprint(stableID: stableID) }
-        self.clearTLSFingerprint(stableID: stableID)
+        clearTLSFingerprint(stableID: stableID)
 
         GatewayTLSStore.saveFingerprint("11", stableID: stableID)
 
-        let gateway = self.makeDiscoveredGateway(
+        let gateway = makeDiscoveredGateway(
             stableID: stableID,
             lanHost: "evil.example.com",
             tailnetDns: "evil.example.com",
             gatewayPort: 12345,
             fingerprint: "22")
-        let controller = self.makeController()
+        let controller = makeController()
 
-        let params = controller._test_resolveDiscoveredTLSParams(gateway: gateway)
+        let params = controller._test_resolveDiscoveredTLSParams(gateway: gateway, allowTOFU: true)
         #expect(params?.expectedFingerprint == "11")
         #expect(params?.allowTOFU == false)
     }
@@ -59,17 +59,17 @@ import Testing
     @Test @MainActor func discoveredTLSParams_doesNotTrustAdvertisedFingerprint() async {
         let stableID = "test|\(UUID().uuidString)"
         defer { clearTLSFingerprint(stableID: stableID) }
-        self.clearTLSFingerprint(stableID: stableID)
+        clearTLSFingerprint(stableID: stableID)
 
-        let gateway = self.makeDiscoveredGateway(
+        let gateway = makeDiscoveredGateway(
             stableID: stableID,
             lanHost: nil,
             tailnetDns: nil,
             gatewayPort: nil,
             fingerprint: "22")
-        let controller = self.makeController()
+        let controller = makeController()
 
-        let params = controller._test_resolveDiscoveredTLSParams(gateway: gateway)
+        let params = controller._test_resolveDiscoveredTLSParams(gateway: gateway, allowTOFU: true)
         #expect(params?.expectedFingerprint == nil)
         #expect(params?.allowTOFU == false)
     }
@@ -77,7 +77,7 @@ import Testing
     @Test @MainActor func autoconnectRequiresStoredPinForDiscoveredGateways() async {
         let stableID = "test|\(UUID().uuidString)"
         defer { clearTLSFingerprint(stableID: stableID) }
-        self.clearTLSFingerprint(stableID: stableID)
+        clearTLSFingerprint(stableID: stableID)
 
         let defaults = UserDefaults.standard
         defaults.set(true, forKey: "gateway.autoconnect")
@@ -90,13 +90,13 @@ import Testing
         defaults.removeObject(forKey: "gateway.preferredStableID")
         defaults.set(stableID, forKey: "gateway.lastDiscoveredStableID")
 
-        let gateway = self.makeDiscoveredGateway(
+        let gateway = makeDiscoveredGateway(
             stableID: stableID,
             lanHost: "test.local",
             tailnetDns: nil,
             gatewayPort: 18789,
             fingerprint: nil)
-        let controller = self.makeController()
+        let controller = makeController()
         controller._test_setGateways([gateway])
         controller._test_triggerAutoConnect()
 
@@ -104,7 +104,7 @@ import Testing
     }
 
     @Test @MainActor func manualConnectionsForceTLSForNonLoopbackHosts() async {
-        let controller = self.makeController()
+        let controller = makeController()
 
         #expect(controller._test_resolveManualUseTLS(host: "gateway.example.com", useTLS: false) == true)
         #expect(controller._test_resolveManualUseTLS(host: "127.attacker.example", useTLS: false) == true)
@@ -120,7 +120,7 @@ import Testing
     }
 
     @Test @MainActor func manualConnectionsAllowPrivateLanPlaintext() async {
-        let controller = self.makeController()
+        let controller = makeController()
 
         #expect(controller._test_resolveManualUseTLS(host: "openclaw.local", useTLS: false) == false)
         #expect(controller._test_resolveManualUseTLS(host: "192.168.1.20", useTLS: false) == false)
@@ -131,7 +131,7 @@ import Testing
     }
 
     @Test @MainActor func manualDefaultPortUses443OnlyForTailnetTLSHosts() async {
-        let controller = self.makeController()
+        let controller = makeController()
 
         #expect(controller._test_resolveManualPort(host: "gateway.example.com", port: 0, useTLS: true) == 18789)
         #expect(controller._test_resolveManualPort(host: "device.sample.ts.net", port: 0, useTLS: true) == 443)

apps/ios/Tests/GatewaySettingsStoreTests.swift

@@ -9,9 +9,11 @@ private struct KeychainEntry: Hashable {
 
 private let gatewayService = "ai.openclaw.gateway"
 private let nodeService = "ai.openclaw.node"
+private let talkService = "ai.openclaw.talk"
 private let instanceIdEntry = KeychainEntry(service: nodeService, account: "instanceId")
 private let preferredGatewayEntry = KeychainEntry(service: gatewayService, account: "preferredStableID")
 private let lastGatewayEntry = KeychainEntry(service: gatewayService, account: "lastDiscoveredStableID")
+private let talkAcmeProviderEntry = KeychainEntry(service: talkService, account: "provider.apiKey.acme")
 private let bootstrapDefaultsKeys = [
     "node.instanceId",
     "gateway.preferredStableID",
@@ -185,4 +187,17 @@ private func withLastGatewaySnapshot(_ body: () -> Void) {
             #expect(defaults.object(forKey: "gateway.last.host") == nil)
         }
     }
+
+    @Test func talkProviderApiKey_genericRoundTrip() {
+        let keychainSnapshot = snapshotKeychain([talkAcmeProviderEntry])
+        defer { restoreKeychain(keychainSnapshot) }
+
+        _ = KeychainStore.delete(service: talkService, account: talkAcmeProviderEntry.account)
+
+        GatewaySettingsStore.saveTalkProviderApiKey("acme-key", provider: "acme")
+        #expect(GatewaySettingsStore.loadTalkProviderApiKey(provider: "acme") == "acme-key")
+
+        GatewaySettingsStore.saveTalkProviderApiKey(nil, provider: "acme")
+        #expect(GatewaySettingsStore.loadTalkProviderApiKey(provider: "acme") == nil)
+    }
 }

apps/ios/Tests/OnboardingStateStoreTests.swift

@@ -56,6 +56,12 @@ import Testing
             appModel: appModel,
             defaults: defaults,
             hasSavedGatewayConnection: false))
+
+        OnboardingStateStore.markIncomplete(defaults: defaults)
+        #expect(OnboardingStateStore.shouldPresentOnLaunch(
+            appModel: appModel,
+            defaults: defaults,
+            hasSavedGatewayConnection: false))
     }
 
     @Test func firstRunIntroDefaultsToVisibleThenPersists() {

apps/ios/Tests/RootTabsSourceGuardTests.swift

@@ -153,9 +153,13 @@ import Testing
         let destinationsSource = try String(contentsOf: Self.agentProTabDestinationsSourceURL(), encoding: .utf8)
         let nodesSource = try String(contentsOf: Self.agentProNodesDestinationSourceURL(), encoding: .utf8)
         let dreamingSource = try String(contentsOf: Self.agentProDreamingDestinationSourceURL(), encoding: .utf8)
+        let directDestination = try Self.extract(
+            source,
+            from: "private func directDestination(for route: AgentRoute) -> some View",
+            to: "private func applyInitialRouteIfNeeded()")
 
-        #expect(!source.contains("ToolbarItem"))
-        #expect(source.contains("self.directHeaderLeadingAction(for: route) == nil ? .visible : .hidden"))
+        #expect(!directDestination.contains("ToolbarItem"))
+        #expect(directDestination.contains("self.directHeaderLeadingAction(for: route) == nil ? .visible : .hidden"))
         #expect(destinationsSource.contains("self.directHeaderLeadingAction(for: .instances)"))
         #expect(destinationsSource.contains("self.directHeaderLeadingAction(for: .dreaming)"))
         #expect(destinationsSource.contains("self.directHeader(\n                        for: .usage"))
@@ -494,6 +498,7 @@ import Testing
         let chatSource = try String(contentsOf: Self.chatProTabSourceURL(), encoding: .utf8)
         let docsSource = try String(contentsOf: Self.docsSourceURL(), encoding: .utf8)
         let settingsSource = try String(contentsOf: Self.settingsProTabSectionsSourceURL(), encoding: .utf8)
+        let channelsSource = try String(contentsOf: Self.channelsSourceURL(), encoding: .utf8)
 
         #expect(rootSource.matches(of: /openSettings: \{ self\.selectSidebarDestination\(\.gateway\) \}/).count >= 2)
         #expect(rootSource.matches(of: /gatewayAction: \{ self\.selectSidebarDestination\(\.gateway\) \}/).count == 1)
@@ -517,7 +522,9 @@ import Testing
         #expect(rootSource.contains("SettingsProTab(initialRoute: self.selectedSidebarDestination.settingsRoute)"))
         #expect(settingsSource.contains("title: \"Channels / Integrations\""))
         #expect(settingsSource.contains("route: .channels"))
+        #expect(channelsSource.contains("let gatewayAction: (() -> Void)?"))
         #expect(docsSource.contains(".accessibilityHint(\"Opens Settings / Gateway\")"))
+        #expect(channelsSource.contains(".accessibilityHint(\"Opens Settings / Gateway\")"))
     }
 
     @Test func gatewaySettingsKeepsPairingTrustDiagnosticsAndTailscaleActions() throws {

apps/ios/Tests/SettingsNetworkingHelpersTests.swift

@@ -29,4 +29,50 @@ import Testing
                 talkConfigLoaded: true,
                 notificationStatusText: "Allowed") == 0)
     }
+
+    @Test func parseHostPortParsesIPv4() {
+        #expect(SettingsNetworkingHelpers.parseHostPort(from: "127.0.0.1:8080") == .init(host: "127.0.0.1", port: 8080))
+    }
+
+    @Test func parseHostPortParsesHostnameAndTrims() {
+        #expect(SettingsNetworkingHelpers.parseHostPort(from: "  example.com:80 \n") == .init(
+            host: "example.com",
+            port: 80))
+    }
+
+    @Test func parseHostPortParsesBracketedIPv6() {
+        #expect(
+            SettingsNetworkingHelpers.parseHostPort(from: "[2001:db8::1]:443") ==
+                .init(host: "2001:db8::1", port: 443))
+    }
+
+    @Test func parseHostPortRejectsMissingPort() {
+        #expect(SettingsNetworkingHelpers.parseHostPort(from: "example.com") == nil)
+        #expect(SettingsNetworkingHelpers.parseHostPort(from: "[2001:db8::1]") == nil)
+    }
+
+    @Test func parseHostPortRejectsInvalidPort() {
+        #expect(SettingsNetworkingHelpers.parseHostPort(from: "example.com:lol") == nil)
+        #expect(SettingsNetworkingHelpers.parseHostPort(from: "[2001:db8::1]:lol") == nil)
+    }
+
+    @Test func httpURLStringFormatsIPv4AndPort() {
+        #expect(SettingsNetworkingHelpers
+            .httpURLString(host: "127.0.0.1", port: 8080, fallback: "fallback") == "http://127.0.0.1:8080")
+    }
+
+    @Test func httpURLStringBracketsIPv6() {
+        #expect(SettingsNetworkingHelpers
+            .httpURLString(host: "2001:db8::1", port: 8080, fallback: "fallback") == "http://[2001:db8::1]:8080")
+    }
+
+    @Test func httpURLStringLeavesAlreadyBracketedIPv6() {
+        #expect(SettingsNetworkingHelpers
+            .httpURLString(host: "[2001:db8::1]", port: 8080, fallback: "fallback") == "http://[2001:db8::1]:8080")
+    }
+
+    @Test func httpURLStringFallsBackWhenMissingHostOrPort() {
+        #expect(SettingsNetworkingHelpers.httpURLString(host: nil, port: 80, fallback: "x") == "http://x")
+        #expect(SettingsNetworkingHelpers.httpURLString(host: "example.com", port: nil, fallback: "y") == "http://y")
+    }
 }

apps/ios/Tests/SwiftUIRenderSmokeTests.swift

@@ -103,6 +103,7 @@ import UIKit
             AnyView(CommandCenterTab(openChat: {}, openSettings: {})),
             AnyView(IPadActivityScreen(openChat: {}, openSettings: {})),
             AnyView(OpenClawDocsScreen()),
+            AnyView(SettingsChannelsScreen()),
             AnyView(IPadWorkboardScreen(openChat: {}, openSettings: {})),
             AnyView(IPadSkillWorkshopScreen(openSettings: {})),
             AnyView(AgentProTab(directRoute: .agents)),

apps/macos/Package.resolved

@@ -1,5 +1,5 @@
 {
-  "originHash" : "4f7b315ce0e0a16d150d8d74dce445628c03d8926485ad2f5595e091b4d33440",
+  "originHash" : "ae9f37f50cff0d32d189e60948f61e2fa1704e997a6ef4ad5e37f6a11c165ea4",
   "pins" : [
     {
       "identity" : "axorcist",
@@ -42,8 +42,8 @@
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/steipete/Peekaboo.git",
       "state" : {
-        "revision" : "1fa8eead7eeac3ff618a3111fc333ae78db043d2",
-        "version" : "3.5.2"
+        "revision" : "ee0e3185431788dad533ffca77cd75315aa3d26f",
+        "version" : "3.4.1"
       }
     },
     {

apps/macos/Package.swift

@@ -19,7 +19,7 @@ let package = Package(
         .package(url: "https://github.com/swiftlang/swift-subprocess.git", from: "0.4.0"),
         .package(url: "https://github.com/apple/swift-log.git", from: "1.10.1"),
         .package(url: "https://github.com/sparkle-project/Sparkle", from: "2.9.0"),
-        .package(url: "https://github.com/steipete/Peekaboo.git", exact: "3.5.2"),
+        .package(url: "https://github.com/steipete/Peekaboo.git", exact: "3.4.1"),
         .package(path: "../shared/OpenClawKit"),
         .package(path: "../swabble"),
     ],

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

@@ -46,17 +46,6 @@ public enum NodePresenceAliveReason: String, Codable, Sendable {
     case connect = "connect"
 }
 
-public enum SessionFileKind: String, Codable, Sendable {
-    case modified = "modified"
-    case read = "read"
-}
-
-public enum SessionFileRelevance: String, Codable, Sendable {
-    case modified = "modified"
-    case read = "read"
-    case mixed = "mixed"
-}
-
 public struct ConnectParams: Codable, Sendable {
     public let minprotocol: Int
     public let maxprotocol: Int
@@ -1767,7 +1756,6 @@ public struct SessionsResolveParams: Codable, Sendable {
     public let spawnedby: String?
     public let includeglobal: Bool?
     public let includeunknown: Bool?
-    public let allowmissing: Bool?
 
     public init(
         key: String?,
@@ -1776,8 +1764,7 @@ public struct SessionsResolveParams: Codable, Sendable {
         agentid: String? = nil,
         spawnedby: String?,
         includeglobal: Bool?,
-        includeunknown: Bool?,
-        allowmissing: Bool? = nil)
+        includeunknown: Bool?)
     {
         self.key = key
         self.sessionid = sessionid
@@ -1786,7 +1773,6 @@ public struct SessionsResolveParams: Codable, Sendable {
         self.spawnedby = spawnedby
         self.includeglobal = includeglobal
         self.includeunknown = includeunknown
-        self.allowmissing = allowmissing
     }
 
     private enum CodingKeys: String, CodingKey {
@@ -1797,7 +1783,6 @@ public struct SessionsResolveParams: Codable, Sendable {
         case spawnedby = "spawnedBy"
         case includeglobal = "includeGlobal"
         case includeunknown = "includeUnknown"
-        case allowmissing = "allowMissing"
     }
 }
 

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

@@ -1,2 +1,2 @@
-303312830e2d7275bfe5abcdbdb3b47fd8648067a7b51ca043503a78bb18d275  plugin-sdk-api-baseline.json
-71e94e1de9f1b03aa44da55ec63d16146ab279740c44854d5998bc0f04d6ae0d  plugin-sdk-api-baseline.jsonl
+b121079a0912b3051a9fc319a675ef920da9db23364ca0c0ccd3c9f0a05a3a49  plugin-sdk-api-baseline.json
+61a0108da670e0f44ba4b861c002eb6eaa5cf63e392d4e7e7de42044cbe7d115  plugin-sdk-api-baseline.jsonl

docs/automation/cron-jobs.md

@@ -157,9 +157,6 @@ If stdout is non-empty, that text is the delivered result. If stdout is empty an
 <ParamField path="--model" type="string">
   Model override; uses the selected allowed model for the job.
 </ParamField>
-<ParamField path="--clear-model" type="boolean">
-  On `cron edit`, removes the per-job model override so the job follows normal cron model-selection precedence (a stored cron-session override if set, otherwise the agent/default model). Cannot be combined with `--model`.
-</ParamField>
 <ParamField path="--thinking" type="string">
   Thinking level override.
 </ParamField>
@@ -474,7 +471,6 @@ Model override note:
 - If the model is allowed, that exact provider/model reaches the isolated agent run.
 - If it is not allowed or cannot be resolved, cron fails the run with an explicit validation error.
 - API `cron.update` payload patches can set `model: null` to clear a stored job model override.
-- `openclaw cron edit <job-id> --clear-model` clears that override from the CLI (same effect as the `model: null` patch) and cannot be combined with `--model`.
 - Configured fallback chains still apply because cron `--model` is a job primary, not a session `/model` override.
 - Payload `fallbacks` replaces configured fallbacks for that job; `fallbacks: []` disables fallback and makes the run strict.
 - A plain `--model` with no explicit or configured fallback list does not fall through to the agent primary as a silent extra retry target.

docs/automation/tasks.md

@@ -360,7 +360,7 @@ A sweeper runs every **60 seconds** and handles four things:
 
   </Accordion>
   <Accordion title="Tasks and sessions">
-    A task may reference a `childSessionKey` (where work runs) and a `requesterSessionKey` (who started it). Its `agentId` identifies the agent executing the work, while the requester and owner fields preserve launch and control context. Sessions are conversation context; tasks are activity tracking on top of that.
+    A task may reference a `childSessionKey` (where work runs) and a `requesterSessionKey` (who started it). Sessions are conversation context; tasks are activity tracking on top of that.
   </Accordion>
   <Accordion title="Tasks and agent runs">
     A task's `runId` links to the agent run doing the work. Agent lifecycle events (start, end, error) automatically update the task status - you do not need to manage the lifecycle manually.

docs/channels/telegram.md

@@ -403,11 +403,11 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
   <Accordion title="Rich message formatting">
     Outbound text uses Telegram rich messages.
 
-    - Markdown text is rendered through OpenClaw's Markdown IR and sent as Telegram rich HTML.
-    - Explicit rich HTML payloads preserve supported Bot API 10.1 tags such as headings, tables, details, rich media, and formulas.
+    - Markdown text is sent as rich Markdown without converting it to HTML.
+    - Explicit HTML payloads are sent as rich HTML.
     - Media captions still use Telegram HTML captions because rich messages do not replace captions.
 
-    This keeps model text away from Telegram Rich Markdown sigils, so currency like `$400-600K` is not parsed as math. Long rich text is split automatically across Telegram's rich text and rich block limits. Tables over Telegram's column limit are sent as code blocks.
+    Long rich text is split automatically across Telegram's rich text and rich block limits. Tables over Telegram's column limit are sent as code blocks.
 
     Link previews are enabled by default. `channels.telegram.linkPreview: false` skips automatic entity detection for rich text.
 

docs/channels/whatsapp.md

@@ -164,7 +164,7 @@ handoff path over manual terminal capture.
 
 - Gateway owns the WhatsApp socket and reconnect loop.
 - The reconnect watchdog uses WhatsApp Web transport activity, not only inbound app-message volume, so a quiet linked-device session is not restarted solely because nobody has sent a message recently. A longer application-silence cap still forces a reconnect if transport frames keep arriving but no application messages are handled for the watchdog window; after a transient reconnect for a recently active session, that application-silence check uses the normal message timeout for the first recovery window.
-- Baileys socket timings are explicit under `web.whatsapp.*`: `keepAliveIntervalMs` controls WhatsApp Web application pings, `connectTimeoutMs` controls the opening handshake timeout, and `defaultQueryTimeoutMs` controls Baileys query waits plus OpenClaw's local outbound send/presence operation bound.
+- Baileys socket timings are explicit under `web.whatsapp.*`: `keepAliveIntervalMs` controls WhatsApp Web application pings, `connectTimeoutMs` controls the opening handshake timeout, and `defaultQueryTimeoutMs` controls Baileys query timeouts.
 - Outbound sends require an active WhatsApp listener for the target account.
 - Group sends attach native mention metadata for `@+<digits>` and `@<digits>` tokens in text and media captions when the token matches current WhatsApp participant metadata, including LID-backed groups.
 - Status and broadcast chats are ignored (`@status`, `@broadcast`).

docs/cli/cron.md

@@ -168,7 +168,7 @@ Use `--due` when you want the manual command to run only if the job is currently
 
 ## Models
 
-`cron add|edit --model <ref>` selects an allowed model for the job. `cron edit <job-id> --clear-model` removes the per-job model override so the job follows normal cron model-selection precedence (a stored cron-session override if present, otherwise the agent/default model); it cannot be combined with `--model`.
+`cron add|edit --model <ref>` selects an allowed model for the job.
 
 <Warning>
 If the model is not allowed or cannot be resolved, cron fails the run with an explicit validation error instead of falling back to the job's agent or default model selection.

docs/cli/status.md

@@ -26,7 +26,7 @@ Notes:
 - When the current session snapshot is sparse, `/status` can backfill token and cache counters from the most recent transcript usage log. Existing nonzero live values still win over transcript fallback values.
 - `/status` includes compact Gateway process uptime and host system uptime.
 - Transcript fallback can also recover the active runtime model label when the live session entry is missing it. If that transcript model differs from the selected model, status resolves the context window against the recovered runtime model instead of the selected one.
-- When a session is pinned to a model that differs from the configured primary, status prints both values, the reason (`session override`), and the clear hint (`/model default`). The configured primary applies to new or unpinned sessions; existing pinned sessions keep their session selection until cleared.
+- When a session is pinned to a model that differs from the configured primary, status prints both values, the reason (`session override`), and the clear hint (`/model <configured-default>` or `/reset`). The configured primary applies to new or unpinned sessions; existing pinned sessions keep their session selection until cleared.
 - For prompt-size accounting, transcript fallback prefers the larger prompt-oriented total when session metadata is missing or smaller, so custom-provider sessions do not collapse to `0` token displays.
 - Output includes per-agent session stores when multiple agents are configured.
 - Overview includes Gateway + node host service install/runtime status when available.

docs/concepts/model-providers.md

@@ -99,7 +99,7 @@ Official provider plugins publish their own model catalog rows. These providers
 - Use `params.serviceTier` when you want an explicit tier instead of the shared `/fast` toggle
 - Hidden OpenClaw attribution headers (`originator`, `version`, `User-Agent`) apply only on native OpenAI traffic to `api.openai.com`, not generic OpenAI-compatible proxies
 - Native OpenAI routes also keep Responses `store`, prompt-cache hints, and OpenAI reasoning-compat payload shaping; proxy routes do not
-- `openai/gpt-5.3-codex-spark` is available through ChatGPT/Codex OAuth subscription auth when your signed-in account exposes it; OpenClaw still suppresses direct OpenAI API-key and Azure API-key routes for this model because those transports reject it
+- `openai/gpt-5.3-codex-spark` is intentionally suppressed in OpenClaw because live OpenAI API requests reject it and the current Codex catalog does not expose it
 
 ```json5
 {

docs/concepts/models.md

@@ -61,7 +61,7 @@ The same `provider/model` can mean different things depending on where it came f
 - Configured defaults (`agents.defaults.model.primary` and agent-specific primaries) are the normal starting point and use `agents.defaults.model.fallbacks`.
 - Auto fallback selections are temporary recovery state. They are stored with `modelOverrideSource: "auto"` so later turns can keep using the fallback chain without probing a known-bad primary every time; OpenClaw periodically probes the original primary again, clears the auto selection when it recovers, and announces fallback/recovery transitions once per state change.
 - User session selections are exact. `/model`, the model picker, `session_status(model=...)`, and `sessions.patch` store `modelOverrideSource: "user"`; if that selected provider/model is unreachable, OpenClaw fails visibly instead of falling through to another configured model.
-- Changing `agents.defaults.model.primary` does not rewrite existing session selections. If status says `This session is pinned to X; config primary Y will apply to new/unpinned sessions.`, clear the current session selection with `/model default` so it inherits the configured primary again.
+- Changing `agents.defaults.model.primary` does not rewrite existing session selections. If status says `This session is pinned to X; config primary Y will apply to new/unpinned sessions.`, switch the current session with `/model Y` or clear stale session state with `/reset`.
 - Cron `--model` / payload `model` is a per-job primary. It still uses configured fallbacks unless the job supplies explicit payload `fallbacks` (use `fallbacks: []` for a strict cron run).
 - CLI default-model and allowlist pickers respect `models.mode: "replace"` by listing explicit `models.providers.*.models` instead of loading the full built-in catalog.
 - The Control UI model picker asks the Gateway for its configured model view: `agents.defaults.models` when present, including provider-wide `provider/*` entries, otherwise explicit `models.providers.*.models` plus providers with usable auth. The full built-in catalog is reserved for explicit browse views such as `models.list` with `view: "all"` or `openclaw models list --all`.
@@ -188,7 +188,6 @@ You can switch models for the current session without restarting:
 /model list
 /model 3
 /model openai/gpt-5.4
-/model default
 /model status
 ```
 
@@ -206,7 +205,6 @@ You can switch models for the current session without restarting:
     - If the agent is idle, the next run uses the new model right away.
     - If a run is already active, OpenClaw marks a live switch as pending and only restarts into the new model at a clean retry point.
     - If tool activity or reply output has already started, the pending switch can stay queued until a later retry opportunity or the next user turn.
-    - `/model default` clears the session selection and returns the session to the configured default model.
     - A user-selected `/model` ref is strict for that session: if the selected provider/model is unreachable, the reply fails visibly instead of silently answering from `agents.defaults.model.fallbacks`. This is different from configured defaults and cron job primaries, which can still use fallback chains.
     - `/model status` is the detailed view (auth candidates and, when configured, provider endpoint `baseUrl` + `api` mode).
 

docs/concepts/personal-agent-benchmark-pack.md

@@ -11,7 +11,7 @@ The Personal Agent Benchmark Pack is a small repo-backed QA scenario pack for
 local personal assistant workflows. It is not a generic model benchmark and it
 does not require a new runner. The pack reuses the private QA stack described in
 [QA overview](/concepts/qa-e2e-automation), the synthetic
-[QA channel](/channels/qa-channel), and the existing `qa/scenarios` YAML
+[QA channel](/channels/qa-channel), and the existing `qa/scenarios` markdown
 catalog.
 
 The first pack is intentionally narrow:
@@ -61,9 +61,9 @@ to inspect and file in issues.
 
 ## Extending The Pack
 
-Add new `.yaml` cases under `qa/scenarios/personal/`, then add the scenario id
-to `QA_PERSONAL_AGENT_SCENARIO_IDS`. Keep each case small, local, deterministic
-in `mock-openai`, and focused on one personal assistant behavior.
+Add new cases under `qa/scenarios/personal/`, then add the scenario id to
+`QA_PERSONAL_AGENT_SCENARIO_IDS`. Keep each case small, local, deterministic in
+`mock-openai`, and focused on one personal assistant behavior.
 
 Good follow-up candidates:
 

docs/concepts/qa-e2e-automation.md

@@ -31,9 +31,9 @@ script aliases; both forms are supported.
 
 | Command                                             | Purpose                                                                                                                                                                                                                                                                 |
 | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `qa run`                                            | Bundled QA self-check without `--qa-profile`; taxonomy-backed maturity profile runner with `--qa-profile smoke-ci` or `--qa-profile release`.                                                                                                                           |
+| `qa run`                                            | Bundled QA self-check; writes a Markdown report.                                                                                                                                                                                                                        |
 | `qa suite`                                          | Run repo-backed scenarios against the QA gateway lane. Aliases: `pnpm openclaw qa suite --runner multipass` for a disposable Linux VM.                                                                                                                                  |
-| `qa coverage`                                       | Print the YAML scenario-coverage inventory (`--json` for machine output).                                                                                                                                                                                               |
+| `qa coverage`                                       | Print the markdown scenario-coverage inventory (`--json` for machine output).                                                                                                                                                                                           |
 | `qa parity-report`                                  | Compare two `qa-suite-summary.json` files and write the agentic parity report, or use `--runtime-axis --token-efficiency` to write Codex-vs-OpenClaw runtime parity and token-efficiency reports from one runtime-pair summary.                                         |
 | `qa character-eval`                                 | Run the character QA scenario across multiple live models with a judged report. See [Reporting](#reporting).                                                                                                                                                            |
 | `qa manual`                                         | Run a one-off prompt against the selected provider/model lane.                                                                                                                                                                                                          |
@@ -51,30 +51,6 @@ script aliases; both forms are supported.
 | `qa whatsapp`                                       | Live transport lane against real WhatsApp Web accounts.                                                                                                                                                                                                                 |
 | `qa mantis`                                         | Before and after verification runner for live transport bugs, with Discord status-reactions evidence, Crabbox desktop/browser smoke, and Slack-in-VNC smoke. See [Mantis](/concepts/mantis) and [Mantis Slack Desktop Runbook](/concepts/mantis-slack-desktop-runbook). |
 
-Profile-backed `qa run` reads membership from `taxonomy.yaml`, then dispatches
-the resolved scenarios through `qa suite`. `--surface` and
-`--category` filter the selected profile instead of defining separate lanes.
-The resulting `qa-evidence.json` includes a profile scorecard summary with
-selected-category counts and missing coverage IDs; the individual evidence
-entries remain the source of truth for the tests, coverage roles, artifacts,
-and results:
-
-```bash
-pnpm openclaw qa run \
-  --qa-profile smoke-ci \
-  --category agent-runtime-and-provider-execution.agent-turn-execution \
-  --provider-mode mock-openai \
-  --output-dir .artifacts/qa-e2e/smoke-ci-profile-dispatch
-```
-
-Use `smoke-ci` for deterministic no-live-service proof and `release` for the
-Stable/LTS proof lane. When a command also needs an OpenClaw root profile, put
-the root profile before the QA command:
-
-```bash
-pnpm openclaw --profile work qa run --qa-profile smoke-ci
-```
-
 ## Operator flow
 
 The current QA operator flow is a two-pane QA site:
@@ -793,26 +769,25 @@ Operational env vars and the Convex broker endpoint contract live in [Testing
 
 Seed assets live in `qa/`:
 
-- `qa/scenarios/index.yaml`
-- `qa/scenarios/<theme>/*.yaml`
+- `qa/scenarios/index.md`
+- `qa/scenarios/<theme>/*.md`
 
 These are intentionally in git so the QA plan is visible to both humans and the
 agent.
 
-`qa-lab` should stay a generic YAML scenario runner. Each scenario YAML file is
+`qa-lab` should stay a generic markdown runner. Each scenario markdown file is
 the source of truth for one test run and should define:
 
-- top-level `title`
-- `scenario` metadata
-- optional category, capability, lane, and risk metadata in `scenario`
-- docs and code refs in `scenario`
-- optional plugin requirements in `scenario`
-- optional gateway config patch in `scenario`
-- executable top-level `flow` for flow scenarios, or `scenario.execution.kind` /
-  `scenario.execution.path` for Vitest and Playwright scenarios
+- scenario metadata
+- optional category, capability, lane, and risk metadata
+- docs and code refs
+- optional plugin requirements
+- optional gateway config patch
+- an executable `qa-flow` block for flow scenarios, or `execution.kind`/`execution.path`
+  for Vitest and Playwright scenarios
 
-The reusable runtime surface that backs `flow` is allowed to stay generic
-and cross-cutting. For example, YAML scenarios can combine transport-side
+The reusable runtime surface that backs `qa-flow` blocks is allowed to stay generic
+and cross-cutting. For example, markdown scenarios can combine transport-side
 helpers with browser-side helpers that drive the embedded Control UI through the
 Gateway `browser.request` seam without adding a special-case runner.
 
@@ -850,17 +825,17 @@ provider names.
 
 ## Transport adapters
 
-`qa-lab` owns a generic transport seam for YAML QA scenarios. `qa-channel` is the first adapter on that seam, but the design target is wider: future real or synthetic channels should plug into the same suite runner instead of adding a transport-specific QA runner.
+`qa-lab` owns a generic transport seam for markdown QA scenarios. `qa-channel` is the first adapter on that seam, but the design target is wider: future real or synthetic channels should plug into the same suite runner instead of adding a transport-specific QA runner.
 
 At the architecture level, the split is:
 
 - `qa-lab` owns generic scenario execution, worker concurrency, artifact writing, and reporting.
 - The transport adapter owns gateway config, readiness, inbound and outbound observation, transport actions, and normalized transport state.
-- YAML scenario files under `qa/scenarios/` define the test run; `qa-lab` provides the reusable runtime surface that executes them.
+- Markdown scenario files under `qa/scenarios/` define the test run; `qa-lab` provides the reusable runtime surface that executes them.
 
 ### Adding a channel
 
-Adding a channel to the YAML QA system requires exactly two things:
+Adding a channel to the markdown QA system requires exactly two things:
 
 1. A transport adapter for the channel.
 2. A scenario pack that exercises the channel contract.
@@ -894,7 +869,7 @@ The minimum adoption bar for a new channel:
 2. Implement the transport runner on the shared `qa-lab` host seam.
 3. Keep transport-specific mechanics inside the runner plugin or channel harness.
 4. Mount the runner as `openclaw qa <runner>` instead of registering a competing root command. Runner plugins should declare `qaRunners` in `openclaw.plugin.json` and export a matching `qaRunnerCliRegistrations` array from `runtime-api.ts`. Keep `runtime-api.ts` light; lazy CLI and runner execution should stay behind separate entrypoints.
-5. Author or adapt YAML scenarios under the themed `qa/scenarios/` directories.
+5. Author or adapt markdown scenarios under the themed `qa/scenarios/` directories.
 6. Use the generic scenario helpers for new scenarios.
 7. Keep existing compatibility aliases working unless the repo is doing an intentional migration.
 
@@ -937,13 +912,7 @@ The report should answer:
 For the inventory of available scenarios - useful when sizing follow-up work or wiring a new transport - run `pnpm openclaw qa coverage` (add `--json` for machine-readable output).
 When choosing focused proof for a touched behavior or file path, run `pnpm openclaw qa coverage --match <query>`.
 The match report searches scenario metadata, docs refs, code refs, coverage IDs, plugins, and provider requirements, then prints matching `qa suite --scenario ...` targets.
-Every `qa suite` run writes top-level `qa-evidence.json`,
-`qa-suite-summary.json`, and `qa-suite-report.md` artifacts for the selected
-scenario set. Scenarios that declare `execution.kind: vitest` or
-`execution.kind: playwright` run the matching test path and also write
-per-scenario logs. When `qa suite` is reached through
-`qa run --qa-profile`, the same `qa-evidence.json` also includes the profile
-scorecard summary for the selected taxonomy categories.
+Every `qa suite` scenario execution writes a `qa-evidence.json` artifact. Flow scenarios also write `qa-suite-summary.json` for existing suite/report tooling; scenarios that declare `execution.kind: vitest` or `execution.kind: playwright` run the matching test path and write `qa-vitest-report.md` or `qa-playwright-report.md` plus per-scenario logs.
 Treat it as a discovery aid, not a gate replacement; the selected scenario still needs the right provider mode, live transport, Multipass, Testbox, or release lane for the behavior under test.
 
 For character and style checks, run the same scenario across multiple live model

docs/gateway/protocol.md

@@ -542,9 +542,7 @@ runtime state.
 `TaskSummary` includes `id`, `status`, and optional metadata such as `kind`,
 `runtime`, `title`, `agentId`, `sessionKey`, `childSessionKey`, `ownerKey`,
 `runId`, `taskId`, `flowId`, `parentTaskId`, `sourceId`, timestamps, progress,
-terminal summary, and sanitized error text. `agentId` identifies the agent
-executing the task; `sessionKey` and `ownerKey` preserve requester and control
-context.
+terminal summary, and sanitized error text.
 
 ### Operator helper methods
 

docs/help/testing.md

@@ -42,45 +42,6 @@ When you touch tests or want extra confidence:
 - Coverage gate: `pnpm test:coverage`
 - E2E suite: `pnpm test:e2e`
 
-## Test Temp Directories
-
-Prefer the shared helpers in `test/helpers/temp-dir.ts` for test-owned
-temporary directories. They make ownership explicit and keep cleanup in the same
-test lifecycle:
-
-```ts
-import { afterEach } from "vitest";
-import { createTempDirTracker } from "../helpers/temp-dir.js";
-
-const tempDirs = createTempDirTracker();
-
-afterEach(tempDirs.cleanup);
-
-it("uses a temp workspace", () => {
-  const workspace = tempDirs.make("openclaw-example-");
-  // use workspace
-});
-```
-
-Use `makeTempDir(tempDirs, prefix)` and `cleanupTempDirs(tempDirs)` when a test
-already owns an array or set of paths. Avoid new bare `fs.mkdtemp*` calls in
-tests unless a case is explicitly verifying raw temp-dir behavior. Add an
-auditable allow comment with a concrete reason when a test intentionally needs a
-bare temp directory:
-
-```ts
-// openclaw-temp-dir: allow verifies raw fs cleanup behavior
-const workspace = fs.mkdtempSync(prefix);
-```
-
-For migration visibility, `node scripts/report-test-temp-creations.mjs` reports
-new bare temp-dir creation in added diff lines without blocking existing cleanup
-styles. Its file scope intentionally follows the same test-path classification
-used by `scripts/changed-lanes.mjs` instead of maintaining a separate test-helper
-filename heuristic, while skipping the shared helper implementation itself.
-`check:changed` runs this report for changed test paths as a warning-only CI
-signal; findings are GitHub warning annotations, not failures.
-
 When debugging real providers/models (requires real creds):
 
 - Live suite (models + gateway tool/image probes): `pnpm test:live`
@@ -184,11 +145,6 @@ inside every shard.
 
 - `pnpm openclaw qa suite`
   - Runs repo-backed QA scenarios directly on the host.
-  - Writes top-level `qa-evidence.json`, `qa-suite-summary.json`, and
-    `qa-suite-report.md` artifacts for the selected scenario set, including
-    mixed flow, Vitest, and Playwright scenario selections.
-  - When dispatched by `pnpm openclaw qa run --qa-profile <profile>`, embeds the
-    selected taxonomy profile scorecard in the same `qa-evidence.json`.
   - Runs multiple selected scenarios in parallel by default with isolated
     gateway workers. `qa-channel` defaults to concurrency 4 (bounded by the
     selected scenario count). Use `--concurrency <count>` to tune the worker

docs/plugins/adding-capabilities.md

@@ -71,7 +71,7 @@ If the work is vendor-only and no shared contract exists yet, stop and define th
 
 Use **provider hooks** when the behavior belongs to the model provider contract rather than the generic agent loop. Examples include provider-specific request params after transport selection, auth-profile preference, prompt overlays, and follow-up fallback routing after model/profile failover.
 
-Use **agent harness hooks** when the behavior belongs to the runtime that is executing a turn. Harnesses can classify explicit protocol outcomes such as empty output, reasoning without visible output, or a structured plan without a final answer so the outer model fallback policy can make the retry decision.
+Use **agent harness hooks** when the behavior belongs to the runtime that is executing a turn. Harnesses can classify successful-but-unusable attempt results such as empty, reasoning-only, or planning-only responses so the outer model fallback policy can make the retry decision.
 
 Keep both seams narrow:
 

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/codex-native-plugins.md

@@ -200,12 +200,11 @@ enabled.
 
 OpenClaw sets app-level `destructive_enabled` from the effective global or
 per-plugin `allow_destructive_actions` policy and lets Codex enforce
-destructive tool metadata from its native app tool annotations. `true` and
-`"auto"` both set `destructive_enabled: true`; `false` sets it false. The
-`_default` app config is disabled with `open_world_enabled: false`. Enabled
-plugin apps are emitted with `open_world_enabled: true`; OpenClaw does not
-expose a separate plugin open-world policy knob and does not maintain
-per-plugin destructive tool-name deny lists.
+destructive tool metadata from its native app tool annotations. The `_default`
+app config is disabled with `open_world_enabled: false`. Enabled plugin apps
+are emitted with `open_world_enabled: true`; OpenClaw does not expose a separate
+plugin open-world policy knob and does not maintain per-plugin destructive
+tool-name deny lists.
 
 Tool approval mode is automatic by default for plugin apps so non-destructive
 read tools can run without a same-thread approval UI. Destructive tools remain
@@ -222,9 +221,6 @@ plugins, while unsafe schemas and ambiguous ownership still fail closed:
 - When policy is `false`, OpenClaw returns a deterministic decline.
 - When policy is `true`, OpenClaw auto-accepts only safe schemas it can map to
   an approval response, such as a boolean approve field.
-- When policy is `"auto"`, OpenClaw exposes destructive plugin actions to
-  Codex but turns ownership-proven MCP approval elicitations into OpenClaw
-  plugin approvals before returning the Codex approval response.
 - Missing plugin identity, ambiguous ownership, a missing turn id, a wrong turn
   id, or an unsafe elicitation schema declines instead of prompting.
 
@@ -272,8 +268,8 @@ Codex thread bindings keep the app config they started with until OpenClaw
 establishes a new harness session or replaces a stale binding.
 
 **Destructive action is declined:** check the global and per-plugin
-`allow_destructive_actions` values. Even when policy is true or `"auto"`,
-unsafe elicitation schemas and ambiguous plugin identity still fail closed.
+`allow_destructive_actions` values. Even when policy is true, unsafe elicitation
+schemas and ambiguous plugin identity still fail closed.
 
 ## Related
 

docs/plugins/sdk-agent-harness.md

@@ -180,10 +180,8 @@ Native harnesses that own their own protocol projection can use
 `openclaw/plugin-sdk/agent-harness-runtime` when a completed turn produced no
 visible assistant text. The helper returns `empty`, `reasoning-only`, or
 `planning-only` so OpenClaw's fallback policy can decide whether to retry on a
-different model. `planning-only` requires the harness's explicit `planText`
-field; OpenClaw does not infer it from assistant prose. The helper intentionally
-leaves prompt errors, in-flight turns, and intentional silent replies such as
-`NO_REPLY` unclassified.
+different model. It intentionally leaves prompt errors, in-flight turns, and
+intentional silent replies such as `NO_REPLY` unclassified.
 
 ### Native Codex harness mode
 

docs/providers/openai.md

@@ -1040,11 +1040,10 @@ the Server-side compaction accordion below.
     ```
 
     With `strict-agentic`, OpenClaw:
+    - No longer treats a plan-only turn as successful progress when a tool action is available
+    - Retries the turn with an act-now steer
     - Auto-enables `update_plan` for substantial work
-    - Retries structurally empty or reasoning-only turns with a visible-answer continuation
-    - Uses explicit harness plan events when the selected harness provides them
-
-    OpenClaw does not classify assistant prose to decide whether a turn is a plan, progress update, or final answer.
+    - Surfaces an explicit blocked state if the model keeps planning without acting
 
     <Note>
     Scoped to OpenAI and Codex GPT-5-family runs only. Other providers and older model families keep default behavior.

docs/providers/openrouter.md

@@ -86,7 +86,6 @@ Bundled fallback examples:
 | Model ref                         | Notes                        |
 | --------------------------------- | ---------------------------- |
 | `openrouter/auto`                 | OpenRouter automatic routing |
-| `openrouter/openrouter/fusion`    | OpenRouter Fusion router     |
 | `openrouter/moonshotai/kimi-k2.6` | Kimi K2.6 via MoonshotAI     |
 | `openrouter/moonshotai/kimi-k2.5` | Kimi K2.5 via MoonshotAI     |
 
@@ -214,79 +213,6 @@ media understanding preflight.
 OpenClaw sends OpenRouter STT requests as JSON with base64 audio under
 `input_audio` (OpenRouter STT contract), not as multipart OpenAI form uploads.
 
-## Fusion router
-
-Use OpenRouter Fusion when you want one OpenClaw model ref to ask several
-OpenRouter models in parallel, have OpenRouter judge their answers, and return a
-single final response through the normal OpenRouter provider endpoint. Because
-the upstream model slug is `openrouter/fusion`, the OpenClaw model ref includes
-both the OpenClaw provider prefix and the upstream OpenRouter namespace:
-
-```bash
-openclaw models set openrouter/openrouter/fusion
-```
-
-Configure Fusion's panel and judge through the model's `params.extraBody`. Those
-fields are forwarded into the OpenRouter chat-completions request body. Fusion
-works with either OpenRouter OAuth onboarding or API-key onboarding; if you use
-OAuth, omit the `env.OPENROUTER_API_KEY` line from the example below.
-
-```json5
-{
-  env: { OPENROUTER_API_KEY: "sk-or-..." },
-  agents: {
-    defaults: {
-      model: { primary: "openrouter/openrouter/fusion" },
-      models: {
-        "openrouter/openrouter/fusion": {
-          params: {
-            extraBody: {
-              plugins: [
-                {
-                  id: "fusion",
-                  analysis_models: [
-                    "google/gemini-3.5-flash",
-                    "moonshotai/kimi-k2.6",
-                    "deepseek/deepseek-v4-pro",
-                  ],
-                  model: "google/gemini-3.5-flash",
-                },
-              ],
-            },
-          },
-        },
-      },
-    },
-  },
-}
-```
-
-The `analysis_models` list is the parallel panel, and `model` inside the Fusion
-plugin config is the judge model. Do not set top-level `tool_choice` to
-`"required"` in normal OpenClaw agent/chat turns to try to force Fusion;
-OpenClaw turns may include OpenClaw tool definitions, and a top-level required
-tool choice can require one of those tools instead of the Fusion router. When
-this Fusion plugin config is present, OpenClaw also adds a sanitized
-system-prompt note with the configured analysis models and judge model so the
-agent can answer questions about its current Fusion panel. Other `extraBody`
-fields are not copied into the prompt.
-
-Fusion is slower by design. OpenRouter may send the same OpenClaw prompt to
-multiple analysis models and then run a final judge/synthesis step, so latency is
-usually higher than a direct single-model request. Use Fusion for deliberate,
-high-quality answers or escalation paths, not as the default for
-latency-sensitive chat. For faster responses, keep the panel small and choose
-faster analysis and judge models.
-
-Test the configured ref with a one-shot local model call:
-
-```bash
-openclaw infer model run --local \
-  --model openrouter/openrouter/fusion \
-  --prompt "Reply with exactly: FUSION_OK" \
-  --json
-```
-
 ## Authentication and headers
 
 OpenRouter uses a Bearer token with your API key under the hood. OpenRouter

docs/refactor/database-first.md

@@ -1406,13 +1406,22 @@ create` validates the written archive by default; `--no-verify` is the
   explicit `dbPath`.
 - `check:database-first-legacy-stores` fails new runtime source that pairs
   legacy store names with write-style filesystem APIs. It also fails runtime
-  source that reintroduces the retired transcript bridge markers
-  `transcriptLocator` or `sqlite-transcript://...`. Migration, doctor, import,
-  and explicit non-session export code remain allowed. Broader legacy contract
-  names such as `sessionFile`, `storePath`, and old `SessionManager` file-era
-  facades still have current owners and need separate migration guard work
-  before they can become a required preflight check. The guard now also covers
-  runtime `cache/*.json` stores, generic
+  source that reintroduces transcript bridge contracts such as
+  `transcriptLocator`, `sqlite-transcript://...`, `sessionFile`, or
+  `storePath`, and scans tests for those bridge-contract names too. It also
+  bans `SessionManager.open(...)` and the old static SessionManager facades so
+  runtime and tests cannot silently re-create a file-backed session opener or
+  file-era session discovery. It also bans the old session JSONL downloader
+  hook/class from export UI. It also bans sidecar-shaped plugin-state/task
+  SQLite helper names; tests should assert `databasePath` and the shared
+  `state/openclaw.sqlite` location instead of pretending those features own
+  separate SQLite files. It also bans the old generic memory index SQL table
+  names (`meta`, `files`, `chunks`, `chunks_vec`,
+  `chunks_fts`, `embedding_cache`) in runtime source so the agent database keeps
+  its explicit `memory_index_*` schema. It also bans embedding TEXT schemas and
+  embedding JSON-array writes so vectors stay compact SQLite BLOBs. Migration,
+  doctor, import, and explicit non-session export code remain allowed. The
+  guard now also covers runtime `cache/*.json` stores, generic
   `thread-bindings.json` sidecars, cron state/run-log JSON, config health JSON,
   restart and lock sidecars, Voice Wake settings, plugin binding approvals,
   installed plugin index JSON, File Transfer audit JSONL, Memory Wiki activity

docs/tools/slash-commands.md

@@ -185,8 +185,7 @@ plugins.
       dashboard session, except when `session.dmScope: "main"` is configured
       and the current parent is the agent's main session — in that case `/new`
       resets the main session in place. Typed `/reset` still runs the Gateway's
-      in-place reset. Use `/model default` when you want to clear a pinned
-      session model selection.
+      in-place reset.
     </Note>
 
   </Accordion>
@@ -359,7 +358,6 @@ use the Control UI Tools panel or config surfaces.
 /model 3           # select by number from picker
 /model openai/gpt-5.4
 /model opus@anthropic:default
-/model default     # clear the session model selection
 /model status      # detailed view with endpoint and API mode
 ```
 

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", () => {
@@ -13,31 +51,6 @@ describe("codex doctor contract", () => {
     expect(legacyConfigRules[0]?.match({ codexDynamicToolsLoading: "direct" })).toBe(false);
   });
 
-  it("reports old approval-routed destructive plugin policy values", () => {
-    expect(
-      legacyConfigRules[1]?.match({
-        allow_destructive_actions: "on-request",
-        plugins: {},
-      }),
-    ).toBe(true);
-    expect(
-      legacyConfigRules[1]?.match({
-        allow_destructive_actions: true,
-        plugins: {
-          "google-calendar": { allow_destructive_actions: "on-request" },
-        },
-      }),
-    ).toBe(true);
-    expect(
-      legacyConfigRules[1]?.match({
-        allow_destructive_actions: "auto",
-        plugins: {
-          "google-calendar": { allow_destructive_actions: true },
-        },
-      }),
-    ).toBe(false);
-  });
-
   it("removes the retired dynamic tools profile without dropping other Codex config", () => {
     const original = {
       plugins: {
@@ -68,59 +81,855 @@ describe("codex doctor contract", () => {
     expect(original.plugins.entries.codex.config).toHaveProperty("codexDynamicToolsProfile");
   });
 
-  it("renames old approval-routed destructive plugin policy values", () => {
-    const original = {
-      plugins: {
-        entries: {
-          codex: {
-            enabled: true,
-            config: {
-              codexDynamicToolsProfile: "openclaw-compat",
-              codexPlugins: {
-                enabled: true,
-                allow_destructive_actions: "on-request",
-                plugins: {
-                  "google-calendar": {
-                    enabled: true,
-                    allow_destructive_actions: "on-request",
-                  },
-                  slack: {
-                    enabled: true,
-                    allow_destructive_actions: false,
-                  },
-                },
-              },
-            },
-          },
-        },
-      },
+  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",
     };
-
-    const result = normalizeCompatibilityConfig({ cfg: original });
-
-    expect(result.changes).toEqual([
-      "Removed retired plugins.entries.codex.config.codexDynamicToolsProfile; Codex app-server always keeps Codex-native workspace tools native.",
-      'Renamed plugins.entries.codex.config.codexPlugins allow_destructive_actions="on-request" values to "auto".',
-    ]);
-    expect(result.config.plugins?.entries?.codex?.config).toEqual({
-      codexPlugins: {
-        enabled: true,
-        allow_destructive_actions: "auto",
-        plugins: {
-          "google-calendar": {
-            enabled: true,
-            allow_destructive_actions: "auto",
-          },
-          slack: {
-            enabled: true,
-            allow_destructive_actions: false,
-          },
+    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(
-      original.plugins.entries.codex.config.codexPlugins.plugins["google-calendar"]
-        .allow_destructive_actions,
-    ).toBe("on-request");
+      (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";
 
@@ -21,20 +18,6 @@ function hasRetiredDynamicToolsProfile(value: unknown): boolean {
   return Object.hasOwn(asRecord(value) ?? {}, "codexDynamicToolsProfile");
 }
 
-function hasLegacyPluginDestructivePolicy(value: unknown): boolean {
-  const codexPlugins = asRecord(value);
-  if (!codexPlugins) {
-    return false;
-  }
-  if (codexPlugins.allow_destructive_actions === "on-request") {
-    return true;
-  }
-  const plugins = asRecord(codexPlugins.plugins);
-  return Object.values(plugins ?? {}).some(
-    (plugin) => asRecord(plugin)?.allow_destructive_actions === "on-request",
-  );
-}
-
 /** Legacy Codex config keys that doctor should report or repair. */
 export const legacyConfigRules: LegacyConfigRule[] = [
   {
@@ -43,70 +26,35 @@ export const legacyConfigRules: LegacyConfigRule[] = [
       'plugins.entries.codex.config.codexDynamicToolsProfile is retired; Codex app-server always keeps Codex-native workspace tools native. Run "openclaw doctor --fix".',
     match: hasRetiredDynamicToolsProfile,
   },
-  {
-    path: ["plugins", "entries", "codex", "config", "codexPlugins"],
-    message:
-      'plugins.entries.codex.config.codexPlugins.allow_destructive_actions="on-request" was renamed to "auto". Run "openclaw doctor --fix".',
-    match: hasLegacyPluginDestructivePolicy,
-  },
 ];
 
-/**
- * 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[];
 } {
   const rawEntry = asRecord(cfg.plugins?.entries?.codex);
   const rawPluginConfig = asRecord(rawEntry?.config);
-  const rawCodexPlugins = asRecord(rawPluginConfig?.codexPlugins);
-  const shouldRemoveDynamicToolsProfile =
-    rawPluginConfig !== null && hasRetiredDynamicToolsProfile(rawPluginConfig);
-  const shouldRewriteDestructivePolicy = hasLegacyPluginDestructivePolicy(rawCodexPlugins);
-  if (!rawPluginConfig || (!shouldRemoveDynamicToolsProfile && !shouldRewriteDestructivePolicy)) {
+  if (!rawPluginConfig || !hasRetiredDynamicToolsProfile(rawPluginConfig)) {
     return { config: cfg, changes: [] };
   }
 
   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: [] };
   }
 
-  const changes: string[] = [];
-  if (shouldRemoveDynamicToolsProfile) {
-    delete nextPluginConfig.codexDynamicToolsProfile;
-    changes.push(
-      "Removed retired plugins.entries.codex.config.codexDynamicToolsProfile; Codex app-server always keeps Codex-native workspace tools native.",
-    );
-  }
-
-  if (shouldRewriteDestructivePolicy) {
-    const nextCodexPlugins = asRecord(nextPluginConfig.codexPlugins);
-    if (nextCodexPlugins?.allow_destructive_actions === "on-request") {
-      nextCodexPlugins.allow_destructive_actions = "auto";
-    }
-    const nextPluginPolicies = asRecord(nextCodexPlugins?.plugins);
-    for (const plugin of Object.values(nextPluginPolicies ?? {})) {
-      const nextPlugin = asRecord(plugin);
-      if (nextPlugin?.allow_destructive_actions === "on-request") {
-        nextPlugin.allow_destructive_actions = "auto";
-      }
-    }
-    changes.push(
-      'Renamed plugins.entries.codex.config.codexPlugins allow_destructive_actions="on-request" values to "auto".',
-    );
-  }
-
+  delete nextPluginConfig.codexDynamicToolsProfile;
   return {
     config: nextConfig,
-    changes,
+    changes: [
+      "Removed retired plugins.entries.codex.config.codexDynamicToolsProfile; Codex app-server always keeps Codex-native workspace tools native.",
+    ],
   };
 }
 
@@ -121,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,25 @@
 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(),
@@ -85,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") {
@@ -104,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
@@ -164,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 {};
   });
 
@@ -173,14 +207,17 @@ 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", () => {
@@ -192,11 +229,9 @@ describe("codex media understanding provider", () => {
 
   it("runs image understanding through a bounded Codex app-server turn", async () => {
     const { client, requests } = createFakeClient();
-    const clientFactory = vi.fn(
-      async (_startOptions, _authProfileId, _agentDir, _config) => client,
-    );
+    const clientFactory = vi.fn(async () => client);
     const provider = buildCodexMediaUnderstandingProvider({
-      clientFactory,
+      clientLeaseFactory: adaptCodexTestClientFactory(clientFactory),
     });
     const cfg = {
       auth: {
@@ -219,35 +254,33 @@ describe("codex media understanding provider", () => {
     });
 
     expect(result).toEqual({ text: "A red square.", model: "gpt-5.4" });
-    expect(requests.map((entry) => entry.method)).toEqual([
-      "model/list",
-      "thread/start",
-      "turn/start",
-    ]);
     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",
@@ -255,9 +288,6 @@ 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",
     });
   });
@@ -265,8 +295,12 @@ describe("codex media understanding provider", () => {
   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({ clientFactory });
-    const cfg = {};
+    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"),
@@ -279,9 +313,16 @@ describe("codex media understanding provider", () => {
       agentDir: " ",
     });
 
-    expect(clientFactory).toHaveBeenCalledWith(expect.any(Object), undefined, undefined, cfg);
-    expect(requests[1]?.params).toEqual(expect.objectContaining({ cwd: process.cwd() }));
-    expect(requests[2]?.params).toEqual(expect.objectContaining({ cwd: process.cwd() }));
+    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 () => {
@@ -323,7 +364,7 @@ describe("codex media understanding provider", () => {
     try {
       const { client } = createFakeClient();
       const provider = buildCodexMediaUnderstandingProvider({
-        clientFactory: async () => client,
+        clientLeaseFactory: adaptCodexTestClientFactory(async () => client),
       });
 
       const result = await provider.describeImage?.({
@@ -346,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?.({
@@ -391,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(
@@ -412,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(
@@ -429,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?.({
@@ -475,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
       | {
@@ -506,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");
@@ -531,7 +727,7 @@ describe("codex media understanding provider", () => {
       responseText: '{"summary":"only text"}',
     });
     const provider = buildCodexMediaUnderstandingProvider({
-      clientFactory: async () => client,
+      clientLeaseFactory: adaptCodexTestClientFactory(async () => client),
     });
 
     await expect(
@@ -551,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(
@@ -580,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,549 +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,
-    authStore: req.authStore,
-    cfg: req.cfg,
-    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;
-  authStore?: ImagesDescriptionRequest["authStore"];
-  cfg: ImagesDescriptionRequest["cfg"];
-  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 agentDir = params.agentDir?.trim() || undefined;
-  const cwd = agentDir ?? process.cwd();
-  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, agentDir, params.cfg)
-    : await import("./src/app-server/shared-client.js").then(
-        ({ createIsolatedCodexAppServerClient }) =>
-          createIsolatedCodexAppServerClient({
-            startOptions: appServer.start,
-            timeoutMs,
-            authProfileId: params.profile,
-            agentDir,
-            authProfileStore: params.authStore,
-            config: params.cfg,
-          }),
-      );
-  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,
-          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,
-            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,
-    authStore: req.authStore,
-    cfg: req.cfg,
-    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/openclaw.plugin.json

@@ -100,7 +100,7 @@
             "default": false
           },
           "allow_destructive_actions": {
-            "oneOf": [{ "type": "boolean" }, { "const": "auto" }],
+            "type": "boolean",
             "default": true
           },
           "plugins": {
@@ -120,7 +120,7 @@
                   "type": "string"
                 },
                 "allow_destructive_actions": {
-                  "oneOf": [{ "type": "boolean" }, { "const": "auto" }]
+                  "type": "boolean"
                 }
               }
             }
@@ -290,7 +290,7 @@
     },
     "codexPlugins.allow_destructive_actions": {
       "label": "Allow Destructive Plugin Actions",
-      "help": "Default policy for plugin app write or destructive action elicitations. Use true to accept safe schemas without prompting, false to decline, or auto to ask through plugin approvals.",
+      "help": "Default policy for plugin app write or destructive action elicitations. Defaults to true.",
       "advanced": true
     },
     "codexPlugins.plugins": {

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-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 &&