feat: ACP thread-bound agents (#23580)

* docs: add ACP thread-bound agents plan doc

* docs: expand ACP implementation specification

* feat(acp): route ACP sessions through core dispatch and lifecycle cleanup

* feat(acp): add /acp commands and Discord spawn gate

* ACP: add acpx runtime plugin backend

* fix(subagents): defer transient lifecycle errors before announce

* Agents: harden ACP sessions_spawn and tighten spawn guidance

* Agents: require explicit ACP target for runtime spawns

* docs: expand ACP control-plane implementation plan

* ACP: harden metadata seeding and spawn guidance

* ACP: centralize runtime control-plane manager and fail-closed dispatch

* ACP: harden runtime manager and unify spawn helpers

* Commands: route ACP sessions through ACP runtime in agent command

* ACP: require persisted metadata for runtime spawns

* Sessions: preserve ACP metadata when updating entries

* Plugins: harden ACP backend registry across loaders

* ACPX: make availability probe compatible with adapters

* E2E: add manual Discord ACP plain-language smoke script

* ACPX: preserve streamed spacing across Discord delivery

* Docs: add ACP Discord streaming strategy

* ACP: harden Discord stream buffering for thread replies

* ACP: reuse shared block reply pipeline for projector

* ACP: unify streaming config and adopt coalesceIdleMs

* Docs: add temporary ACP production hardening plan

* Docs: trim temporary ACP hardening plan goals

* Docs: gate ACP thread controls by backend capabilities

* ACP: add capability-gated runtime controls and /acp operator commands

* Docs: remove temporary ACP hardening plan

* ACP: fix spawn target validation and close cache cleanup

* ACP: harden runtime dispatch and recovery paths

* ACP: split ACP command/runtime internals and centralize policy

* ACP: harden runtime lifecycle, validation, and observability

* ACP: surface runtime and backend session IDs in thread bindings

* docs: add temp plan for binding-service migration

* ACP: migrate thread binding flows to SessionBindingService

* ACP: address review feedback and preserve prompt wording

* ACPX plugin: pin runtime dependency and prefer bundled CLI

* Discord: complete binding-service migration cleanup and restore ACP plan

* Docs: add standalone ACP agents guide

* ACP: route harness intents to thread-bound ACP sessions

* ACP: fix spawn thread routing and queue-owner stall

* ACP: harden startup reconciliation and command bypass handling

* ACP: fix dispatch bypass type narrowing

* ACP: align runtime metadata to agentSessionId

* ACP: normalize session identifier handling and labels

* ACP: mark thread banner session ids provisional until first reply

* ACP: stabilize session identity mapping and startup reconciliation

* ACP: add resolved session-id notices and cwd in thread intros

* Discord: prefix thread meta notices consistently

* Discord: unify ACP/thread meta notices with gear prefix

* Discord: split thread persona naming from meta formatting

* Extensions: bump acpx plugin dependency to 0.1.9

* Agents: gate ACP prompt guidance behind acp.enabled

* Docs: remove temp experiment plan docs

* Docs: scope streaming plan to holy grail refactor

* Docs: refactor ACP agents guide for human-first flow

* Docs/Skill: add ACP feature-flag guidance and direct acpx telephone-game flow

* Docs/Skill: add OpenCode and Pi to ACP harness lists

* Docs/Skill: align ACP harness list with current acpx registry

* Dev/Test: move ACP plain-language smoke script and mark as keep

* Docs/Skill: reorder ACP harness lists with Pi first

* ACP: split control-plane manager into core/types/utils modules

* Docs: refresh ACP thread-bound agents plan

* ACP: extract dispatch lane and split manager domains

* ACP: centralize binding context and remove reverse deps

* Infra: unify system message formatting

* ACP: centralize error boundaries and session id rendering

* ACP: enforce init concurrency cap and strict meta clear

* Tests: fix ACP dispatch binding mock typing

* Tests: fix Discord thread-binding mock drift and ACP request id

* ACP: gate slash bypass and persist cleared overrides

* ACPX: await pre-abort cancel before runTurn return

* Extension: pin acpx runtime dependency to 0.1.11

* Docs: add pinned acpx install strategy for ACP extension

* Extensions/acpx: enforce strict local pinned startup

* Extensions/acpx: tighten acp-router install guidance

* ACPX: retry runtime test temp-dir cleanup

* Extensions/acpx: require proactive ACPX repair for thread spawns

* Extensions/acpx: require restart offer after acpx reinstall

* extensions/acpx: remove workspace protocol devDependency

* extensions/acpx: bump pinned acpx to 0.1.13

* extensions/acpx: sync lockfile after dependency bump

* ACPX: make runtime spawn Windows-safe

* fix: align doctor-config-flow repair tests with default-account migration (#23580) (thanks @osolmaz)

src/commands/agent.acp.test.ts

@@ -0,0 +1,294 @@
+import fs from "node:fs";
+import path from "node:path";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { withTempHome as withTempHomeBase } from "../../test/helpers/temp-home.js";
+import * as acpManagerModule from "../acp/control-plane/manager.js";
+import { AcpRuntimeError } from "../acp/runtime/errors.js";
+import * as embeddedModule from "../agents/pi-embedded.js";
+import type { OpenClawConfig } from "../config/config.js";
+import * as configModule from "../config/config.js";
+import type { RuntimeEnv } from "../runtime.js";
+import { agentCommand } from "./agent.js";
+
+const loadConfigSpy = vi.spyOn(configModule, "loadConfig");
+const runEmbeddedPiAgentSpy = vi.spyOn(embeddedModule, "runEmbeddedPiAgent");
+const getAcpSessionManagerSpy = vi.spyOn(acpManagerModule, "getAcpSessionManager");
+
+const runtime: RuntimeEnv = {
+  log: vi.fn(),
+  error: vi.fn(),
+  exit: vi.fn(() => {
+    throw new Error("exit");
+  }),
+};
+
+async function withTempHome<T>(fn: (home: string) => Promise<T>): Promise<T> {
+  return withTempHomeBase(fn, { prefix: "openclaw-agent-acp-" });
+}
+
+function mockConfig(home: string, storePath: string) {
+  loadConfigSpy.mockReturnValue({
+    acp: {
+      enabled: true,
+      backend: "acpx",
+      allowedAgents: ["codex"],
+      dispatch: { enabled: true },
+    },
+    agents: {
+      defaults: {
+        model: { primary: "openai/gpt-5.3-codex" },
+        models: { "openai/gpt-5.3-codex": {} },
+        workspace: path.join(home, "openclaw"),
+      },
+    },
+    session: { store: storePath, mainKey: "main" },
+  } satisfies OpenClawConfig);
+}
+
+function mockConfigWithAcpOverrides(
+  home: string,
+  storePath: string,
+  acpOverrides: Partial<NonNullable<OpenClawConfig["acp"]>>,
+) {
+  loadConfigSpy.mockReturnValue({
+    acp: {
+      enabled: true,
+      backend: "acpx",
+      allowedAgents: ["codex"],
+      dispatch: { enabled: true },
+      ...acpOverrides,
+    },
+    agents: {
+      defaults: {
+        model: { primary: "openai/gpt-5.3-codex" },
+        models: { "openai/gpt-5.3-codex": {} },
+        workspace: path.join(home, "openclaw"),
+      },
+    },
+    session: { store: storePath, mainKey: "main" },
+  } satisfies OpenClawConfig);
+}
+
+function writeAcpSessionStore(storePath: string) {
+  fs.mkdirSync(path.dirname(storePath), { recursive: true });
+  fs.writeFileSync(
+    storePath,
+    JSON.stringify(
+      {
+        "agent:codex:acp:test": {
+          sessionId: "acp-session-1",
+          updatedAt: Date.now(),
+          acp: {
+            backend: "acpx",
+            agent: "codex",
+            runtimeSessionName: "agent:codex:acp:test",
+            mode: "oneshot",
+            state: "idle",
+            lastActivityAt: Date.now(),
+          },
+        },
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+function resolveReadySession(
+  sessionKey: string,
+  agent = "codex",
+): ReturnType<ReturnType<typeof acpManagerModule.getAcpSessionManager>["resolveSession"]> {
+  return {
+    kind: "ready",
+    sessionKey,
+    meta: {
+      backend: "acpx",
+      agent,
+      runtimeSessionName: sessionKey,
+      mode: "oneshot",
+      state: "idle",
+      lastActivityAt: Date.now(),
+    },
+  };
+}
+
+function mockAcpManager(params: {
+  runTurn: (params: unknown) => Promise<void>;
+  resolveSession?: (params: {
+    cfg: OpenClawConfig;
+    sessionKey: string;
+  }) => ReturnType<ReturnType<typeof acpManagerModule.getAcpSessionManager>["resolveSession"]>;
+}) {
+  getAcpSessionManagerSpy.mockReturnValue({
+    runTurn: params.runTurn,
+    resolveSession:
+      params.resolveSession ??
+      ((input) => {
+        return resolveReadySession(input.sessionKey);
+      }),
+  } as unknown as ReturnType<typeof acpManagerModule.getAcpSessionManager>);
+}
+
+describe("agentCommand ACP runtime routing", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    runEmbeddedPiAgentSpy.mockResolvedValue({
+      payloads: [{ text: "embedded" }],
+      meta: {
+        durationMs: 5,
+      },
+    } as never);
+  });
+
+  it("routes ACP sessions through AcpSessionManager instead of embedded agent", async () => {
+    await withTempHome(async (home) => {
+      const storePath = path.join(home, "sessions.json");
+      writeAcpSessionStore(storePath);
+      mockConfig(home, storePath);
+
+      const runTurn = vi.fn(async (paramsUnknown: unknown) => {
+        const params = paramsUnknown as {
+          onEvent?: (event: { type: string; text?: string; stopReason?: string }) => Promise<void>;
+        };
+        await params.onEvent?.({ type: "text_delta", text: "ACP_" });
+        await params.onEvent?.({ type: "text_delta", text: "OK" });
+        await params.onEvent?.({ type: "done", stopReason: "stop" });
+      });
+
+      mockAcpManager({
+        runTurn: (params: unknown) => runTurn(params),
+      });
+
+      await agentCommand({ message: "ping", sessionKey: "agent:codex:acp:test" }, runtime);
+
+      expect(runTurn).toHaveBeenCalledWith(
+        expect.objectContaining({
+          sessionKey: "agent:codex:acp:test",
+          text: "ping",
+          mode: "prompt",
+        }),
+      );
+      expect(runEmbeddedPiAgentSpy).not.toHaveBeenCalled();
+      const hasAckLog = vi
+        .mocked(runtime.log)
+        .mock.calls.some(([first]) => typeof first === "string" && first.includes("ACP_OK"));
+      expect(hasAckLog).toBe(true);
+    });
+  });
+
+  it("fails closed for ACP-shaped session keys missing ACP metadata", async () => {
+    await withTempHome(async (home) => {
+      const storePath = path.join(home, "sessions.json");
+      fs.mkdirSync(path.dirname(storePath), { recursive: true });
+      fs.writeFileSync(
+        storePath,
+        JSON.stringify(
+          {
+            "agent:codex:acp:stale": {
+              sessionId: "stale-1",
+              updatedAt: Date.now(),
+            },
+          },
+          null,
+          2,
+        ),
+      );
+      mockConfig(home, storePath);
+
+      const runTurn = vi.fn(async (_params: unknown) => {});
+      mockAcpManager({
+        runTurn: (params: unknown) => runTurn(params),
+        resolveSession: ({ sessionKey }) => {
+          return {
+            kind: "stale",
+            sessionKey,
+            error: new AcpRuntimeError(
+              "ACP_SESSION_INIT_FAILED",
+              `ACP metadata is missing for session ${sessionKey}.`,
+            ),
+          };
+        },
+      });
+
+      await expect(
+        agentCommand({ message: "ping", sessionKey: "agent:codex:acp:stale" }, runtime),
+      ).rejects.toMatchObject({
+        code: "ACP_SESSION_INIT_FAILED",
+        message: expect.stringContaining("ACP metadata is missing"),
+      });
+      expect(runTurn).not.toHaveBeenCalled();
+      expect(runEmbeddedPiAgentSpy).not.toHaveBeenCalled();
+    });
+  });
+
+  it("blocks ACP turns when ACP is disabled by policy", async () => {
+    await withTempHome(async (home) => {
+      const storePath = path.join(home, "sessions.json");
+      writeAcpSessionStore(storePath);
+      mockConfigWithAcpOverrides(home, storePath, {
+        enabled: false,
+      });
+
+      const runTurn = vi.fn(async (_params: unknown) => {});
+      mockAcpManager({
+        runTurn: (params: unknown) => runTurn(params),
+      });
+
+      await expect(
+        agentCommand({ message: "ping", sessionKey: "agent:codex:acp:test" }, runtime),
+      ).rejects.toMatchObject({
+        code: "ACP_DISPATCH_DISABLED",
+      });
+      expect(runTurn).not.toHaveBeenCalled();
+      expect(runEmbeddedPiAgentSpy).not.toHaveBeenCalled();
+    });
+  });
+
+  it("blocks ACP turns when ACP dispatch is disabled by policy", async () => {
+    await withTempHome(async (home) => {
+      const storePath = path.join(home, "sessions.json");
+      writeAcpSessionStore(storePath);
+      mockConfigWithAcpOverrides(home, storePath, {
+        dispatch: { enabled: false },
+      });
+
+      const runTurn = vi.fn(async (_params: unknown) => {});
+      mockAcpManager({
+        runTurn: (params: unknown) => runTurn(params),
+      });
+
+      await expect(
+        agentCommand({ message: "ping", sessionKey: "agent:codex:acp:test" }, runtime),
+      ).rejects.toMatchObject({
+        code: "ACP_DISPATCH_DISABLED",
+      });
+      expect(runTurn).not.toHaveBeenCalled();
+      expect(runEmbeddedPiAgentSpy).not.toHaveBeenCalled();
+    });
+  });
+
+  it("blocks ACP turns when ACP agent is disallowed by policy", async () => {
+    await withTempHome(async (home) => {
+      const storePath = path.join(home, "sessions.json");
+      writeAcpSessionStore(storePath);
+      mockConfigWithAcpOverrides(home, storePath, {
+        allowedAgents: ["claude"],
+      });
+
+      const runTurn = vi.fn(async (_params: unknown) => {});
+      mockAcpManager({
+        runTurn: (params: unknown) => runTurn(params),
+        resolveSession: ({ sessionKey }) => resolveReadySession(sessionKey, "codex"),
+      });
+
+      await expect(
+        agentCommand({ message: "ping", sessionKey: "agent:codex:acp:test" }, runtime),
+      ).rejects.toMatchObject({
+        code: "ACP_SESSION_INIT_FAILED",
+        message: expect.stringContaining("not allowed by policy"),
+      });
+      expect(runTurn).not.toHaveBeenCalled();
+      expect(runEmbeddedPiAgentSpy).not.toHaveBeenCalled();
+    });
+  });
+});

src/commands/agent.test.ts

@@ -409,6 +409,73 @@ describe("agentCommand", () => {
     });
   });
 
+  it("persists cleared model and auth override fields when stored override falls back to default", async () => {
+    await withTempHome(async (home) => {
+      const store = path.join(home, "sessions.json");
+      writeSessionStoreSeed(store, {
+        "agent:main:subagent:clear-overrides": {
+          sessionId: "session-clear-overrides",
+          updatedAt: Date.now(),
+          providerOverride: "anthropic",
+          modelOverride: "claude-opus-4-5",
+          authProfileOverride: "profile-legacy",
+          authProfileOverrideSource: "user",
+          authProfileOverrideCompactionCount: 2,
+          fallbackNoticeSelectedModel: "anthropic/claude-opus-4-5",
+          fallbackNoticeActiveModel: "openai/gpt-4.1-mini",
+          fallbackNoticeReason: "fallback",
+        },
+      });
+
+      mockConfig(home, store, {
+        model: { primary: "openai/gpt-4.1-mini" },
+        models: {
+          "openai/gpt-4.1-mini": {},
+        },
+      });
+
+      vi.mocked(loadModelCatalog).mockResolvedValueOnce([
+        { id: "claude-opus-4-5", name: "Opus", provider: "anthropic" },
+        { id: "gpt-4.1-mini", name: "GPT-4.1 Mini", provider: "openai" },
+      ]);
+
+      await agentCommand(
+        {
+          message: "hi",
+          sessionKey: "agent:main:subagent:clear-overrides",
+        },
+        runtime,
+      );
+
+      const callArgs = vi.mocked(runEmbeddedPiAgent).mock.calls.at(-1)?.[0];
+      expect(callArgs?.provider).toBe("openai");
+      expect(callArgs?.model).toBe("gpt-4.1-mini");
+
+      const saved = JSON.parse(fs.readFileSync(store, "utf-8")) as Record<
+        string,
+        {
+          providerOverride?: string;
+          modelOverride?: string;
+          authProfileOverride?: string;
+          authProfileOverrideSource?: string;
+          authProfileOverrideCompactionCount?: number;
+          fallbackNoticeSelectedModel?: string;
+          fallbackNoticeActiveModel?: string;
+          fallbackNoticeReason?: string;
+        }
+      >;
+      const entry = saved["agent:main:subagent:clear-overrides"];
+      expect(entry?.providerOverride).toBeUndefined();
+      expect(entry?.modelOverride).toBeUndefined();
+      expect(entry?.authProfileOverride).toBeUndefined();
+      expect(entry?.authProfileOverrideSource).toBeUndefined();
+      expect(entry?.authProfileOverrideCompactionCount).toBeUndefined();
+      expect(entry?.fallbackNoticeSelectedModel).toBeUndefined();
+      expect(entry?.fallbackNoticeActiveModel).toBeUndefined();
+      expect(entry?.fallbackNoticeReason).toBeUndefined();
+    });
+  });
+
   it("keeps explicit sessionKey even when sessionId exists elsewhere", async () => {
     await withTempHome(async (home) => {
       const store = path.join(home, "sessions.json");

src/commands/agent.ts

@@ -1,3 +1,6 @@
+import { getAcpSessionManager } from "../acp/control-plane/manager.js";
+import { resolveAcpAgentPolicyError, resolveAcpDispatchPolicyError } from "../acp/policy.js";
+import { toAcpRuntimeError } from "../acp/runtime/errors.js";
 import {
   listAgentIds,
   resolveAgentDir,
@@ -41,6 +44,7 @@ import { formatCliCommand } from "../cli/command-format.js";
 import { type CliDeps, createDefaultDeps } from "../cli/deps.js";
 import { loadConfig } from "../config/config.js";
 import {
+  mergeSessionEntry,
   parseSessionThreadInfo,
   resolveAndPersistSessionFile,
   resolveAgentIdFromSessionKey,
@@ -75,11 +79,40 @@ type PersistSessionEntryParams = {
   entry: SessionEntry;
 };
 
+type OverrideFieldClearedByDelete =
+  | "providerOverride"
+  | "modelOverride"
+  | "authProfileOverride"
+  | "authProfileOverrideSource"
+  | "authProfileOverrideCompactionCount"
+  | "fallbackNoticeSelectedModel"
+  | "fallbackNoticeActiveModel"
+  | "fallbackNoticeReason";
+
+const OVERRIDE_FIELDS_CLEARED_BY_DELETE: OverrideFieldClearedByDelete[] = [
+  "providerOverride",
+  "modelOverride",
+  "authProfileOverride",
+  "authProfileOverrideSource",
+  "authProfileOverrideCompactionCount",
+  "fallbackNoticeSelectedModel",
+  "fallbackNoticeActiveModel",
+  "fallbackNoticeReason",
+];
+
 async function persistSessionEntry(params: PersistSessionEntryParams): Promise<void> {
-  params.sessionStore[params.sessionKey] = params.entry;
-  await updateSessionStore(params.storePath, (store) => {
-    store[params.sessionKey] = params.entry;
+  const persisted = await updateSessionStore(params.storePath, (store) => {
+    const merged = mergeSessionEntry(store[params.sessionKey], params.entry);
+    // Preserve explicit `delete` clears done by session override helpers.
+    for (const field of OVERRIDE_FIELDS_CLEARED_BY_DELETE) {
+      if (!Object.hasOwn(params.entry, field)) {
+        Reflect.deleteProperty(merged, field);
+      }
+    }
+    store[params.sessionKey] = merged;
+    return merged;
   });
+  params.sessionStore[params.sessionKey] = persisted;
 }
 
 function resolveFallbackRetryPrompt(params: { body: string; isFallbackRetry: boolean }): string {
@@ -292,6 +325,13 @@ export async function agentCommand(
   const workspaceDir = workspace.dir;
   let sessionEntry = resolvedSessionEntry;
   const runId = opts.runId?.trim() || sessionId;
+  const acpManager = getAcpSessionManager();
+  const acpResolution = sessionKey
+    ? acpManager.resolveSession({
+        cfg,
+        sessionKey,
+      })
+    : null;
 
   try {
     if (opts.deliver === true) {
@@ -307,6 +347,126 @@ export async function agentCommand(
       }
     }
 
+    if (acpResolution?.kind === "stale") {
+      throw acpResolution.error;
+    }
+
+    if (acpResolution?.kind === "ready" && sessionKey) {
+      const startedAt = Date.now();
+      registerAgentRunContext(runId, {
+        sessionKey,
+      });
+      emitAgentEvent({
+        runId,
+        stream: "lifecycle",
+        data: {
+          phase: "start",
+          startedAt,
+        },
+      });
+
+      let streamedText = "";
+      let stopReason: string | undefined;
+      try {
+        const dispatchPolicyError = resolveAcpDispatchPolicyError(cfg);
+        if (dispatchPolicyError) {
+          throw dispatchPolicyError;
+        }
+        const acpAgent = normalizeAgentId(
+          acpResolution.meta.agent || resolveAgentIdFromSessionKey(sessionKey),
+        );
+        const agentPolicyError = resolveAcpAgentPolicyError(cfg, acpAgent);
+        if (agentPolicyError) {
+          throw agentPolicyError;
+        }
+
+        await acpManager.runTurn({
+          cfg,
+          sessionKey,
+          text: body,
+          mode: "prompt",
+          requestId: runId,
+          signal: opts.abortSignal,
+          onEvent: (event) => {
+            if (event.type === "done") {
+              stopReason = event.stopReason;
+              return;
+            }
+            if (event.type !== "text_delta") {
+              return;
+            }
+            if (event.stream && event.stream !== "output") {
+              return;
+            }
+            if (!event.text) {
+              return;
+            }
+            streamedText += event.text;
+            emitAgentEvent({
+              runId,
+              stream: "assistant",
+              data: {
+                text: streamedText,
+                delta: event.text,
+              },
+            });
+          },
+        });
+      } catch (error) {
+        const acpError = toAcpRuntimeError({
+          error,
+          fallbackCode: "ACP_TURN_FAILED",
+          fallbackMessage: "ACP turn failed before completion.",
+        });
+        emitAgentEvent({
+          runId,
+          stream: "lifecycle",
+          data: {
+            phase: "error",
+            error: acpError.message,
+            endedAt: Date.now(),
+          },
+        });
+        throw acpError;
+      }
+
+      emitAgentEvent({
+        runId,
+        stream: "lifecycle",
+        data: {
+          phase: "end",
+          endedAt: Date.now(),
+        },
+      });
+
+      const finalText = streamedText.trim();
+      const payloads = finalText
+        ? [
+            {
+              text: finalText,
+            },
+          ]
+        : [];
+      const result = {
+        payloads,
+        meta: {
+          durationMs: Date.now() - startedAt,
+          aborted: opts.abortSignal?.aborted === true,
+          stopReason,
+        },
+      };
+
+      return await deliverAgentCommandResult({
+        cfg,
+        deps,
+        runtime,
+        opts,
+        sessionEntry,
+        result,
+        payloads,
+      });
+    }
+
     let resolvedThinkLevel =
       thinkOnce ??
       thinkOverride ??

src/commands/agent/session-store.test.ts

@@ -0,0 +1,66 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import type { SessionEntry } from "../../config/sessions.js";
+import { loadSessionStore } from "../../config/sessions.js";
+import { updateSessionStoreAfterAgentRun } from "./session-store.js";
+
+function acpMeta() {
+  return {
+    backend: "acpx",
+    agent: "codex",
+    runtimeSessionName: "runtime-1",
+    mode: "persistent" as const,
+    state: "idle" as const,
+    lastActivityAt: Date.now(),
+  };
+}
+
+describe("updateSessionStoreAfterAgentRun", () => {
+  it("preserves ACP metadata when caller has a stale session snapshot", async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-session-store-"));
+    const storePath = path.join(dir, "sessions.json");
+    const sessionKey = `agent:codex:acp:${randomUUID()}`;
+    const sessionId = randomUUID();
+
+    const existing: SessionEntry = {
+      sessionId,
+      updatedAt: Date.now(),
+      acp: acpMeta(),
+    };
+    await fs.writeFile(storePath, JSON.stringify({ [sessionKey]: existing }, null, 2), "utf8");
+
+    const staleInMemory: Record<string, SessionEntry> = {
+      [sessionKey]: {
+        sessionId,
+        updatedAt: Date.now(),
+      },
+    };
+
+    await updateSessionStoreAfterAgentRun({
+      cfg: {} as never,
+      sessionId,
+      sessionKey,
+      storePath,
+      sessionStore: staleInMemory,
+      defaultProvider: "openai",
+      defaultModel: "gpt-5.3-codex",
+      result: {
+        payloads: [],
+        meta: {
+          aborted: false,
+          agentMeta: {
+            provider: "openai",
+            model: "gpt-5.3-codex",
+          },
+        },
+      } as never,
+    });
+
+    const persisted = loadSessionStore(storePath, { skipCache: true })[sessionKey];
+    expect(persisted?.acp).toBeDefined();
+    expect(staleInMemory[sessionKey]?.acp).toBeDefined();
+  });
+});

src/commands/agent/session-store.ts

@@ -5,6 +5,7 @@ import { isCliProvider } from "../../agents/model-selection.js";
 import { deriveSessionTotalTokens, hasNonzeroUsage } from "../../agents/usage.js";
 import type { OpenClawConfig } from "../../config/config.js";
 import {
+  mergeSessionEntry,
   setSessionRuntimeModel,
   type SessionEntry,
   updateSessionStore,
@@ -94,8 +95,10 @@ export async function updateSessionStoreAfterAgentRun(params: {
   if (compactionsThisRun > 0) {
     next.compactionCount = (entry.compactionCount ?? 0) + compactionsThisRun;
   }
-  sessionStore[sessionKey] = next;
-  await updateSessionStore(storePath, (store) => {
-    store[sessionKey] = next;
+  const persisted = await updateSessionStore(storePath, (store) => {
+    const merged = mergeSessionEntry(store[sessionKey], next);
+    store[sessionKey] = merged;
+    return merged;
   });
+  sessionStore[sessionKey] = persisted;
 }

src/commands/doctor-config-flow.test.ts

@@ -26,14 +26,14 @@ type DiscordGuildRule = {
 };
 
 type DiscordAccountRule = {
-  allowFrom: string[];
-  dm: { allowFrom: string[]; groupChannels: string[] };
-  execApprovals: { approvers: string[] };
-  guilds: Record<string, DiscordGuildRule>;
+  allowFrom?: string[];
+  dm?: { allowFrom: string[]; groupChannels: string[] };
+  execApprovals?: { approvers: string[] };
+  guilds?: Record<string, DiscordGuildRule>;
 };
 
 type RepairedDiscordPolicy = {
-  allowFrom: string[];
+  allowFrom?: string[];
   dm: { allowFrom: string[]; groupChannels: string[] };
   execApprovals: { approvers: string[] };
   guilds: Record<string, DiscordGuildRule>;
@@ -186,18 +186,20 @@ describe("doctor config flow", () => {
       const cfg = result.cfg as unknown as {
         channels: {
           telegram: {
-            allowFrom: string[];
-            groupAllowFrom: string[];
+            allowFrom?: string[];
+            groupAllowFrom?: string[];
             groups: Record<
               string,
               { allowFrom: string[]; topics: Record<string, { allowFrom: string[] }> }
             >;
-            accounts: Record<string, { allowFrom: string[] }>;
+            accounts: Record<string, { allowFrom?: string[]; groupAllowFrom?: string[] }>;
           };
         };
       };
-      expect(cfg.channels.telegram.allowFrom).toEqual(["111"]);
-      expect(cfg.channels.telegram.groupAllowFrom).toEqual(["222"]);
+      expect(cfg.channels.telegram.allowFrom).toBeUndefined();
+      expect(cfg.channels.telegram.groupAllowFrom).toBeUndefined();
+      expect(cfg.channels.telegram.accounts.default.allowFrom).toEqual(["111"]);
+      expect(cfg.channels.telegram.accounts.default.groupAllowFrom).toEqual(["222"]);
       expect(cfg.channels.telegram.groups["-100123"].allowFrom).toEqual(["333"]);
       expect(cfg.channels.telegram.groups["-100123"].topics["99"].allowFrom).toEqual(["444"]);
       expect(cfg.channels.telegram.accounts.alerts.allowFrom).toEqual(["444"]);
@@ -262,7 +264,8 @@ describe("doctor config flow", () => {
         channels: { discord: RepairedDiscordPolicy };
       };
 
-      expect(cfg.channels.discord.allowFrom).toEqual(["123"]);
+      expect(cfg.channels.discord.allowFrom).toBeUndefined();
+      expect(cfg.channels.discord.accounts.default.allowFrom).toEqual(["123"]);
       expect(cfg.channels.discord.dm.allowFrom).toEqual(["456"]);
       expect(cfg.channels.discord.dm.groupChannels).toEqual(["789"]);
       expect(cfg.channels.discord.execApprovals.approvers).toEqual(["321"]);