Add files using upload-large-folder tool

src/auto-reply/reply/abort-cutoff.runtime.test.ts

@@ -0,0 +1,53 @@
+// Covers abort-cutoff clearing against missing persisted rows.
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { loadSessionEntry } from "../../config/sessions/session-accessor.js";
+import type { SessionEntry } from "../../config/sessions/types.js";
+import { clearAbortCutoffInSessionRuntime } from "./abort-cutoff.runtime.js";
+
+async function withTempStore<T>(run: (storePath: string) => Promise<T>): Promise<T> {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-abort-cutoff-"));
+  try {
+    return await run(path.join(dir, "sessions.json"));
+  } finally {
+    await fs.rm(dir, { recursive: true, force: true });
+  }
+}
+
+describe("clearAbortCutoffInSessionRuntime", () => {
+  it("recreates a complete persisted row when clearing abort cutoff state", async () => {
+    await withTempStore(async (storePath) => {
+      const sessionKey = "agent:main:explicit:cutoff-missing-row";
+      const entry: SessionEntry = {
+        sessionId: "cutoff-session",
+        updatedAt: 1,
+        modelProvider: "anthropic",
+        model: "claude-opus-4-6",
+        abortCutoffMessageSid: "msg-42",
+        abortCutoffTimestamp: 123,
+      };
+      const sessionStore: Record<string, SessionEntry> = { [sessionKey]: entry };
+
+      const cleared = await clearAbortCutoffInSessionRuntime({
+        sessionEntry: entry,
+        sessionStore,
+        sessionKey,
+        storePath,
+      });
+
+      const persisted = loadSessionEntry({ storePath, sessionKey });
+      expect(cleared).toBe(true);
+      expect(sessionStore[sessionKey]?.sessionId).toBe("cutoff-session");
+      expect(sessionStore[sessionKey]?.modelProvider).toBe("anthropic");
+      expect(sessionStore[sessionKey]?.abortCutoffMessageSid).toBeUndefined();
+      expect(sessionStore[sessionKey]?.abortCutoffTimestamp).toBeUndefined();
+      expect(persisted?.sessionId).toBe("cutoff-session");
+      expect(persisted?.modelProvider).toBe("anthropic");
+      expect(persisted?.model).toBe("claude-opus-4-6");
+      expect(persisted?.abortCutoffMessageSid).toBeUndefined();
+      expect(persisted?.abortCutoffTimestamp).toBeUndefined();
+    });
+  });
+});

src/auto-reply/reply/abort-cutoff.runtime.ts

@@ -0,0 +1,36 @@
+/** Runtime persistence helper for clearing abort-cutoff state from sessions. */
+import { patchSessionEntryCore } from "../../config/sessions/session-accessor.js";
+import type { SessionEntry } from "../../config/sessions/types.js";
+import { applyAbortCutoffToSessionEntry, hasAbortCutoff } from "./abort-cutoff.js";
+
+/** Clears abort cutoff state in memory and persisted session storage. */
+export async function clearAbortCutoffInSessionRuntime(params: {
+  sessionEntry?: SessionEntry;
+  sessionStore?: Record<string, SessionEntry>;
+  sessionKey?: string;
+  storePath?: string;
+}): Promise<boolean> {
+  const { sessionEntry, sessionStore, sessionKey, storePath } = params;
+  if (!sessionEntry || !sessionStore || !sessionKey || !hasAbortCutoff(sessionEntry)) {
+    return false;
+  }
+
+  applyAbortCutoffToSessionEntry(sessionEntry, undefined);
+  const updatedAt = Date.now();
+  sessionEntry.updatedAt = updatedAt;
+  sessionStore[sessionKey] = sessionEntry;
+
+  if (storePath) {
+    await patchSessionEntryCore(
+      { storePath, sessionKey },
+      () => ({
+        abortCutoffMessageSid: undefined,
+        abortCutoffTimestamp: undefined,
+        updatedAt,
+      }),
+      { fallbackEntry: sessionEntry },
+    );
+  }
+
+  return true;
+}

src/auto-reply/reply/abort-cutoff.ts

@@ -0,0 +1,107 @@
+// Resolves abort cutoff markers used to stop stale reply streams.
+import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
+import type { SessionEntry } from "../../config/sessions/types.js";
+import type { MsgContext } from "../templating.js";
+
+export type AbortCutoff = {
+  messageSid?: string;
+  timestamp?: number;
+};
+
+type SessionAbortCutoffEntry = Pick<SessionEntry, "abortCutoffMessageSid" | "abortCutoffTimestamp">;
+
+export function resolveAbortCutoffFromContext(ctx: MsgContext): AbortCutoff | undefined {
+  const messageSid =
+    normalizeOptionalString(ctx.MessageSidFull) ?? normalizeOptionalString(ctx.MessageSid);
+  const timestamp =
+    typeof ctx.Timestamp === "number" && Number.isFinite(ctx.Timestamp) ? ctx.Timestamp : undefined;
+  if (!messageSid && timestamp === undefined) {
+    return undefined;
+  }
+  return { messageSid, timestamp };
+}
+
+export function readAbortCutoffFromSessionEntry(
+  entry: SessionAbortCutoffEntry | undefined,
+): AbortCutoff | undefined {
+  if (!entry) {
+    return undefined;
+  }
+  const messageSid = normalizeOptionalString(entry.abortCutoffMessageSid);
+  const timestamp =
+    typeof entry.abortCutoffTimestamp === "number" && Number.isFinite(entry.abortCutoffTimestamp)
+      ? entry.abortCutoffTimestamp
+      : undefined;
+  if (!messageSid && timestamp === undefined) {
+    return undefined;
+  }
+  return { messageSid, timestamp };
+}
+
+export function hasAbortCutoff(entry: SessionAbortCutoffEntry | undefined): boolean {
+  return readAbortCutoffFromSessionEntry(entry) !== undefined;
+}
+
+export function applyAbortCutoffToSessionEntry(
+  entry: SessionAbortCutoffEntry,
+  cutoff: AbortCutoff | undefined,
+): void {
+  entry.abortCutoffMessageSid = cutoff?.messageSid;
+  entry.abortCutoffTimestamp = cutoff?.timestamp;
+}
+
+function toNumericMessageSid(value: string | undefined): bigint | undefined {
+  const trimmed = normalizeOptionalString(value);
+  if (!trimmed || !/^\d+$/.test(trimmed)) {
+    return undefined;
+  }
+  try {
+    return BigInt(trimmed);
+  } catch {
+    return undefined;
+  }
+}
+
+export function shouldSkipMessageByAbortCutoff(params: {
+  cutoffMessageSid?: string;
+  cutoffTimestamp?: number;
+  messageSid?: string;
+  timestamp?: number;
+}): boolean {
+  const cutoffSid = normalizeOptionalString(params.cutoffMessageSid);
+  const currentSid = normalizeOptionalString(params.messageSid);
+  if (cutoffSid && currentSid) {
+    const cutoffNumeric = toNumericMessageSid(cutoffSid);
+    const currentNumeric = toNumericMessageSid(currentSid);
+    if (cutoffNumeric !== undefined && currentNumeric !== undefined) {
+      return currentNumeric <= cutoffNumeric;
+    }
+    if (currentSid === cutoffSid) {
+      return true;
+    }
+  }
+  if (
+    typeof params.cutoffTimestamp === "number" &&
+    Number.isFinite(params.cutoffTimestamp) &&
+    typeof params.timestamp === "number" &&
+    Number.isFinite(params.timestamp)
+  ) {
+    return params.timestamp <= params.cutoffTimestamp;
+  }
+  return false;
+}
+
+export function shouldPersistAbortCutoff(params: {
+  commandSessionKey?: string;
+  targetSessionKey?: string;
+}): boolean {
+  const commandSessionKey = normalizeOptionalString(params.commandSessionKey);
+  const targetSessionKey = normalizeOptionalString(params.targetSessionKey);
+  if (!commandSessionKey || !targetSessionKey) {
+    return true;
+  }
+  // Native targeted /stop can run from a slash/session-control key while the
+  // actual target session uses different message id/timestamp spaces.
+  // Persist cutoff only when command source and target are the same session.
+  return commandSessionKey === targetSessionKey;
+}

src/auto-reply/reply/abort-operation.ts

@@ -0,0 +1,389 @@
+// Handles abort requests and active reply run cancellation.
+import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
+import { getAcpSessionManager } from "../../acp/control-plane/manager.js";
+import { retireSessionMcpRuntime } from "../../agents/agent-bundle-mcp-manager-api.js";
+import { resolveSessionAgentId } from "../../agents/agent-scope.js";
+import { resolveActiveEmbeddedRunSessionId } from "../../agents/embedded-agent-runner/active-run-projections.js";
+import { abortEmbeddedAgentRun } from "../../agents/embedded-agent-runner/runs.js";
+import { killAllControlledSubagentRuns } from "../../agents/subagents/registry/subagent-control.js";
+import { listSubagentRunsForController } from "../../agents/subagents/registry/subagent-registry-read.js";
+import {
+  resolveInternalSessionKey,
+  resolveMainSessionAlias,
+} from "../../agents/tools/sessions-helpers.js";
+import { resolveSessionStorePathCore } from "../../config/sessions.js";
+import {
+  loadSessionEntry,
+  markSessionAbortTarget,
+  resolveSessionAbortTarget,
+  type SessionAbortTargetContext,
+  type SessionAbortTargetIdentity,
+  type SessionAbortTargetResult,
+} from "../../config/sessions/session-accessor.js";
+import type { OpenClawConfig } from "../../config/types.openclaw.js";
+import { logVerbose } from "../../globals.js";
+import { formatErrorMessage } from "../../infra/errors.js";
+import { isAcpSessionKey, isSubagentSessionKey } from "../../routing/session-key.js";
+import { resolveCommandAuthorization } from "../command-auth.js";
+import type { FinalizedRuntimeMsgContext } from "../templating.js";
+import {
+  type AbortCutoff,
+  resolveAbortCutoffFromContext,
+  shouldPersistAbortCutoff,
+} from "./abort-cutoff.js";
+import { setAbortMemory } from "./abort-primitives.js";
+import type { FastAbortRequestParams, FastAbortResult, PreparedFastAbortRequest } from "./abort.js";
+import { resolveEffectiveResetTargetSessionKey } from "./acp-reset-target.js";
+import { resolveConversationBindingContextFromMessage } from "./conversation-binding-input.js";
+import { clearSessionQueues } from "./queue.js";
+import { replyRunRegistry } from "./reply-run-registry.js";
+
+export function abortSessionRunTargetWithOutcome(params: { key?: string; sessionId?: string }): {
+  active: boolean;
+  aborted: boolean;
+  retirement?: Promise<void>;
+} {
+  const sessionIds = new Set<string>();
+  const key = normalizeOptionalString(params.key);
+  let active = key ? replyRunRegistry.isActive(key) : false;
+  if (key) {
+    const activeSessionId = resolveActiveEmbeddedRunSessionId(key);
+    if (activeSessionId) {
+      active = true;
+      sessionIds.add(activeSessionId);
+    }
+  }
+  const explicitSessionId = normalizeOptionalString(params.sessionId);
+  if (explicitSessionId) {
+    sessionIds.add(explicitSessionId);
+  }
+
+  let aborted = key ? replyRunRegistry.abort(key) : false;
+  for (const sessionId of sessionIds) {
+    aborted = abortEmbeddedAgentRun(sessionId) || aborted;
+  }
+  // Stop owns these captured IDs; a later turn may rebind the session key.
+  const retirement =
+    !active || aborted
+      ? Promise.all(
+          [...sessionIds].map((sessionId) =>
+            retireSessionMcpRuntime({
+              sessionId,
+              reason: "session-stop",
+            }),
+          ),
+        ).then(() => undefined)
+      : undefined;
+  return { active, aborted, retirement };
+}
+
+function resolveStoredSessionId(params: {
+  cfg: OpenClawConfig;
+  sessionKey: string;
+}): string | undefined {
+  const agentId = resolveSessionAgentId({
+    sessionKey: params.sessionKey,
+    config: params.cfg,
+  });
+  const storePath = resolveSessionStorePathCore(params.cfg.session?.store, { agentId });
+  try {
+    return loadSessionEntry({
+      agentId,
+      clone: false,
+      sessionKey: params.sessionKey,
+      storePath,
+    })?.sessionId;
+  } catch {
+    return undefined;
+  }
+}
+
+function resolveBoundAcpAbortTargetSessionKey(params: {
+  ctx: FinalizedRuntimeMsgContext;
+  cfg: OpenClawConfig;
+  activeSessionKey: string;
+}): string | undefined {
+  const bindingContext = resolveConversationBindingContextFromMessage({
+    cfg: params.cfg,
+    ctx: params.ctx,
+  });
+  if (!bindingContext) {
+    return undefined;
+  }
+  return resolveEffectiveResetTargetSessionKey({
+    cfg: params.cfg,
+    channel: bindingContext.channel,
+    accountId: bindingContext.accountId,
+    conversationId: bindingContext.conversationId,
+    parentConversationId: bindingContext.parentConversationId,
+    activeSessionKey: params.activeSessionKey,
+    skipConfiguredFallbackWhenActiveSessionNonAcp: false,
+    fallbackToActiveAcpWhenUnbound: false,
+  });
+}
+
+function normalizeRequesterSessionKey(
+  cfg: OpenClawConfig,
+  key: string | undefined,
+): string | undefined {
+  const cleaned = normalizeOptionalString(key);
+  if (!cleaned) {
+    return undefined;
+  }
+  const { mainKey, alias } = resolveMainSessionAlias(cfg);
+  return resolveInternalSessionKey({ key: cleaned, alias, mainKey });
+}
+
+export async function stopSubagentsForRequester(params: {
+  cfg: OpenClawConfig;
+  requesterSessionKey?: string;
+  requesterAgentId?: string;
+  beforeKill?: Parameters<typeof killAllControlledSubagentRuns>[0]["beforeKill"];
+}): Promise<{ stopped: number; failed: number }> {
+  const requesterKey = normalizeRequesterSessionKey(params.cfg, params.requesterSessionKey);
+  if (!requesterKey) {
+    await params.beforeKill?.();
+    return { stopped: 0, failed: 0 };
+  }
+  const controllerAgentId = resolveSessionAgentId({
+    config: params.cfg,
+    sessionKey: requesterKey,
+    fallbackAgentId: params.requesterAgentId,
+  });
+  const result = await killAllControlledSubagentRuns({
+    cfg: params.cfg,
+    controller: {
+      controllerSessionKey: requesterKey,
+      controllerAgentId,
+      callerSessionKey: requesterKey,
+      callerIsSubagent: isSubagentSessionKey(requesterKey),
+      controlScope: "children",
+    },
+    runs: listSubagentRunsForController(requesterKey),
+    suppressTaskDelivery: true,
+    beforeKill: params.beforeKill,
+  });
+  if (result.status === "error") {
+    logVerbose(`abort: failed to stop subagents for ${requesterKey}: ${result.error}`);
+  }
+  if (result.killed > 0) {
+    logVerbose(`abort: stopped ${result.killed} subagent run(s) for ${requesterKey}`);
+  }
+  return { stopped: result.killed, failed: result.status === "error" ? result.failed : 0 };
+}
+
+export async function executeFastAbortRequest(
+  params: FastAbortRequestParams,
+  request: PreparedFastAbortRequest,
+): Promise<FastAbortResult> {
+  const { ctx, cfg } = params;
+  const { commandSessionKey, targetKey, resolveTargetAgentId } = request;
+
+  const commandAuthorized = ctx.CommandAuthorized;
+  const auth = resolveCommandAuthorization({
+    ctx,
+    cfg,
+    commandAuthorized,
+  });
+  if (!auth.isAuthorizedSender) {
+    return { handled: false, aborted: false };
+  }
+
+  const agentId = resolveTargetAgentId();
+  const abortKey = targetKey ?? auth.from ?? auth.to;
+  const requesterSessionKey = targetKey ?? ctx.SessionKey ?? abortKey;
+
+  if (targetKey) {
+    const storePath = resolveSessionStorePathCore(cfg.session?.store, { agentId });
+    const abortCutoffForTarget = (target: SessionAbortTargetContext): AbortCutoff | undefined =>
+      shouldPersistAbortCutoff({
+        commandSessionKey,
+        targetSessionKey: target.sessionKey,
+      })
+        ? resolveAbortCutoffFromContext(ctx)
+        : undefined;
+    let resolvedAbortTarget: SessionAbortTargetIdentity | null = null;
+    try {
+      resolvedAbortTarget = resolveSessionAbortTarget({
+        agentId,
+        sessionKey: targetKey,
+        storePath,
+      });
+    } catch (error) {
+      logVerbose(
+        `abort: failed to resolve abort metadata for ${targetKey}: ${formatErrorMessage(error)}`,
+      );
+    }
+    const resolvedTargetKey = resolvedAbortTarget?.sessionKey ?? targetKey;
+    const conversationBoundAcpTargetKey = commandSessionKey
+      ? resolveBoundAcpAbortTargetSessionKey({
+          ctx,
+          cfg,
+          activeSessionKey: commandSessionKey,
+        })
+      : undefined;
+    const boundAcpTargetKey = !isAcpSessionKey(resolvedTargetKey)
+      ? conversationBoundAcpTargetKey
+      : undefined;
+    const abortTargetKeys = [resolvedTargetKey];
+    if (boundAcpTargetKey && boundAcpTargetKey !== resolvedTargetKey) {
+      abortTargetKeys.push(boundAcpTargetKey);
+    }
+    let aborted = false;
+    let activeAbortRejected = false;
+    const acpCancellations: Promise<void>[] = [];
+    try {
+      const { stopped, failed } = await stopSubagentsForRequester({
+        cfg,
+        requesterSessionKey,
+        requesterAgentId: agentId,
+        beforeKill: () => {
+          if (params.isCommandTargetCurrent?.() === false) {
+            throw new Error("The selected session changed before it could be stopped.");
+          }
+          try {
+            const sourceAbortKey =
+              commandSessionKey &&
+              !abortTargetKeys.includes(commandSessionKey) &&
+              conversationBoundAcpTargetKey &&
+              abortTargetKeys.includes(conversationBoundAcpTargetKey)
+                ? commandSessionKey
+                : undefined;
+            const sessionIdsByKey = new Map<string, string | undefined>(
+              abortTargetKeys.map((abortTargetKey) => [
+                abortTargetKey,
+                replyRunRegistry.resolveSessionId(abortTargetKey) ??
+                  (abortTargetKey === resolvedTargetKey
+                    ? resolvedAbortTarget?.sessionId
+                    : resolveStoredSessionId({ cfg, sessionKey: abortTargetKey })),
+              ]),
+            );
+            for (const abortTargetKey of abortTargetKeys) {
+              const outcome = abortSessionRunTargetWithOutcome({
+                key: abortTargetKey,
+                sessionId: sessionIdsByKey.get(abortTargetKey),
+              });
+              if (outcome.retirement) {
+                acpCancellations.push(outcome.retirement);
+              }
+              activeAbortRejected ||= outcome.active && !outcome.aborted;
+              aborted = outcome.aborted || aborted;
+            }
+            const sourceSessionId = sourceAbortKey
+              ? (replyRunRegistry.resolveSessionId(sourceAbortKey) ??
+                resolveStoredSessionId({ cfg, sessionKey: sourceAbortKey }))
+              : undefined;
+            if (sourceAbortKey) {
+              const outcome = abortSessionRunTargetWithOutcome({
+                key: sourceAbortKey,
+                sessionId: sourceSessionId,
+              });
+              if (outcome.retirement) {
+                acpCancellations.push(outcome.retirement);
+              }
+              activeAbortRejected ||= outcome.active && !outcome.aborted;
+              aborted = outcome.aborted || aborted;
+            }
+            const cleared = clearSessionQueues(
+              abortTargetKeys
+                .flatMap((abortTargetKey) => [abortTargetKey, sessionIdsByKey.get(abortTargetKey)])
+                .concat(sourceAbortKey, sourceSessionId),
+            );
+            if (cleared.followupCleared > 0 || cleared.laneCleared > 0) {
+              logVerbose(
+                `abort: cleared followups=${cleared.followupCleared} lane=${cleared.laneCleared} keys=${cleared.keys.join(",")}`,
+              );
+            }
+          } finally {
+            // The tree already holds queued reservations. Initiate ACP without awaiting
+            // either backend so native cleanup cannot delay signal-less ACP steer turns.
+            const acpManager = getAcpSessionManager();
+            for (const acpTargetKey of abortTargetKeys) {
+              const resolution = acpManager.resolveSession({
+                cfg,
+                sessionKey: acpTargetKey,
+                agentId: acpTargetKey === resolvedTargetKey ? agentId : undefined,
+              });
+              if (resolution.kind === "none") {
+                continue;
+              }
+              acpCancellations.push(
+                acpManager
+                  .cancelSession({
+                    cfg,
+                    sessionKey: resolution.sessionKey,
+                    agentId: resolution.agentId,
+                    reason: "fast-abort",
+                  })
+                  .catch((error: unknown) => {
+                    logVerbose(
+                      `abort: ACP cancel failed for ${acpTargetKey}: ${formatErrorMessage(error)}`,
+                    );
+                  }),
+              );
+            }
+          }
+          return true;
+        },
+      });
+      const rejectionReason = activeAbortRejected && !aborted ? "finalizing" : undefined;
+      if (!rejectionReason) {
+        let persistedAbortTarget: SessionAbortTargetResult | null = null;
+        try {
+          persistedAbortTarget = await markSessionAbortTarget({
+            isCurrent: params.isCommandTargetCurrent,
+            scope: {
+              agentId,
+              sessionKey: targetKey,
+              storePath,
+            },
+            resolveAbortCutoff: abortCutoffForTarget,
+          });
+        } catch (error) {
+          logVerbose(
+            `abort: failed to persist abort metadata for ${targetKey}: ${formatErrorMessage(error)}`,
+          );
+        }
+        if (persistedAbortTarget?.persisted === false) {
+          logVerbose(
+            `abort: failed to persist abort metadata for ${targetKey}: ${persistedAbortTarget.persistenceError ?? "unknown error"}`,
+          );
+        }
+        const abortMemoryKey =
+          persistedAbortTarget?.sessionKey ?? resolvedAbortTarget?.sessionKey ?? abortKey;
+        const hasAbortTargetEntry = Boolean(
+          persistedAbortTarget?.entry ?? resolvedAbortTarget?.entry,
+        );
+        if (
+          persistedAbortTarget?.persisted !== true &&
+          abortMemoryKey &&
+          !hasAbortTargetEntry &&
+          params.isCommandTargetCurrent?.() !== false
+        ) {
+          setAbortMemory(abortMemoryKey, true);
+        }
+      }
+      return {
+        handled: true,
+        aborted,
+        ...(rejectionReason ? { rejectionReason } : {}),
+        stoppedSubagents: stopped,
+        failedSubagents: failed,
+      };
+    } finally {
+      // Join even when native signaling or metadata exits exceptionally.
+      await Promise.all(acpCancellations);
+    }
+  }
+
+  if (abortKey) {
+    setAbortMemory(abortKey, true);
+  }
+  const { stopped, failed } = await stopSubagentsForRequester({ cfg, requesterSessionKey });
+  return {
+    handled: true,
+    aborted: false,
+    stoppedSubagents: stopped,
+    failedSubagents: failed,
+  };
+}

src/auto-reply/reply/abort-primitives.ts

@@ -0,0 +1,128 @@
+// Normalizes abort command primitives before runtime cancellation.
+import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
+import { resolveGlobalMap } from "../../shared/global-singleton.js";
+import { normalizeCommandBody } from "../commands-registry-normalize.js";
+import type { CommandNormalizeOptions } from "../commands-registry.types.js";
+
+const ABORT_TRIGGERS = new Set([
+  "stop",
+  "esc",
+  "abort",
+  "exit",
+  "interrupt",
+  "detente",
+  "deten",
+  "detén",
+  "arrete",
+  "arrête",
+  "停止",
+  "停下来",
+  "暂停",
+  "やめて",
+  "止めて",
+  "रुको",
+  "توقف",
+  "стоп",
+  "остановись",
+  "останови",
+  "остановить",
+  "прекрати",
+  "halt",
+  "anhalten",
+  "aufhören",
+  "hoer auf",
+  "stopp",
+  "pare",
+  "stop openclaw",
+  "openclaw stop",
+  "stop action",
+  "stop current action",
+  "stop run",
+  "stop current run",
+  "stop agent",
+  "stop the agent",
+  "stop don't do anything",
+  "stop dont do anything",
+  "stop do not do anything",
+  "stop doing anything",
+  "do not do that",
+  "please stop",
+  "stop please",
+]);
+const ABORT_MEMORY = resolveGlobalMap<string, boolean>(
+  Symbol.for("openclaw.abortMemory"),
+  "close-and-restart",
+);
+const ABORT_MEMORY_MAX = 2000;
+const TRAILING_ABORT_PUNCTUATION_RE = /[.!?！？…,，。;；:：'"’”)\]}]+$/u;
+
+function normalizeAbortTriggerText(text: string): string {
+  return normalizeLowercaseStringOrEmpty(text)
+    .replace(/[’`]/g, "'")
+    .replace(/\s+/g, " ")
+    .replace(TRAILING_ABORT_PUNCTUATION_RE, "")
+    .trim();
+}
+
+export function isAbortTrigger(text?: string): boolean {
+  if (!text) {
+    return false;
+  }
+  const normalized = normalizeAbortTriggerText(text);
+  return ABORT_TRIGGERS.has(normalized);
+}
+
+export function isAbortRequestText(text?: string, options?: CommandNormalizeOptions): boolean {
+  if (!text) {
+    return false;
+  }
+  const normalized = normalizeCommandBody(text, options).trim();
+  if (!normalized) {
+    return false;
+  }
+  const normalizedLower = normalizeLowercaseStringOrEmpty(normalized);
+  return (
+    normalizedLower === "/stop" ||
+    normalizeAbortTriggerText(normalizedLower) === "/stop" ||
+    isAbortTrigger(normalizedLower)
+  );
+}
+
+export function getAbortMemory(key: string): boolean | undefined {
+  const normalized = key.trim();
+  if (!normalized) {
+    return undefined;
+  }
+  return ABORT_MEMORY.get(normalized);
+}
+
+function pruneAbortMemory(): void {
+  if (ABORT_MEMORY.size <= ABORT_MEMORY_MAX) {
+    return;
+  }
+  const excess = ABORT_MEMORY.size - ABORT_MEMORY_MAX;
+  let removed = 0;
+  for (const entryKey of ABORT_MEMORY.keys()) {
+    ABORT_MEMORY.delete(entryKey);
+    removed += 1;
+    if (removed >= excess) {
+      break;
+    }
+  }
+}
+
+export function setAbortMemory(key: string, value: boolean): void {
+  const normalized = key.trim();
+  if (!normalized) {
+    return;
+  }
+  if (!value) {
+    ABORT_MEMORY.delete(normalized);
+    return;
+  }
+  if (ABORT_MEMORY.has(normalized)) {
+    ABORT_MEMORY.delete(normalized);
+  }
+  ABORT_MEMORY.set(normalized, true);
+  pruneAbortMemory();
+}

src/auto-reply/reply/abort.acp-boundary.test.ts

@@ -0,0 +1,352 @@
+/** Channel Stop initiates native and ACP cancellation independently of either drain. */
+import type { AcpRuntime } from "@openclaw/acp-core/runtime/types";
+import { expect, it, vi } from "vitest";
+import { createDeferred } from "../../../test/helpers/promise.js";
+import { getAcpSessionManager, testing as acpTesting } from "../../acp/control-plane/manager.js";
+import { disposeAcpSessionManagerInstance } from "../../acp/control-plane/manager.lifecycle.js";
+import {
+  registerAcpRuntimeBackend,
+  unregisterAcpRuntimeBackend,
+} from "../../acp/runtime/registry.js";
+import { readAcpSessionMeta } from "../../acp/runtime/session-meta.js";
+import {
+  createOperationalRunInstanceRef,
+  prepareAgentRunAdmission,
+} from "../../agents/admitted-run-context.js";
+import {
+  clearActiveEmbeddedRun,
+  setActiveEmbeddedRun,
+} from "../../agents/embedded-agent-runner/runs.js";
+import { createEmbeddedRunHandle } from "../../agents/embedded-agent-runner/runs.test-support.js";
+import { registerSubagentRun } from "../../agents/subagents/registry/subagent-registry.js";
+import { writeSubagentSessionEntry } from "../../agents/subagents/registry/subagent-registry.persistence.test-support.js";
+import { getSubagentRunByChildSessionKey } from "../../agents/subagents/registry/subagent-registry.test-helpers.js";
+import { enqueueSwarmRun, releaseSwarmRun } from "../../agents/subagents/swarm/swarm-scheduler.js";
+import { getRuntimeConfig } from "../../config/config.js";
+import { resolveSessionStorePathCore } from "../../config/sessions/paths.js";
+import { loadExactSessionEntryReadOnly } from "../../config/sessions/session-accessor.js";
+import { useChatAbortRegistryFixture } from "../../gateway/server-methods/chat.abort-registry.test-support.js";
+import { getSessionBindingService } from "../../infra/outbound/session-binding-service.js";
+import {
+  captureActivePluginRegistrySnapshot,
+  restoreActivePluginRegistrySnapshot,
+  setActivePluginRegistry,
+} from "../../plugins/runtime.js";
+import {
+  beginSessionWorkAdmission,
+  isSessionWorkAdmissionActive,
+  type SessionWorkAdmissionLease,
+} from "../../sessions/session-lifecycle-admission.js";
+import {
+  createChannelTestPluginBase,
+  createTestRegistry,
+} from "../../test-utils/channel-plugins.js";
+import { tryFastAbortFromMessage } from "./abort.js";
+import { createReplyOperation } from "./reply-run-registry.js";
+import { buildTestCtx } from "./test-ctx.js";
+
+const fixture = useChatAbortRegistryFixture();
+
+it.each(
+  ["idle", "active", "native failure"].flatMap((scenario) =>
+    ["resolve", "reject"].map((completion) => ({ scenario, completion })),
+  ),
+)(
+  "native and bound ACP cancellation initiate before either drain ($scenario, $completion)",
+  async ({ scenario, completion }) => {
+    const active = scenario !== "idle";
+    const nativeFailure = scenario === "native failure";
+    const nativeError = new Error("native cancellation failed");
+    const sourceKey = "agent:main:stop-test:direct:room";
+    const acpKey = "agent:main:acp:bound-stop";
+    const runningKey = "agent:main:subagent:running";
+    const queuedKey = "agent:main:subagent:queued";
+    for (const [runId, sessionKey] of [
+      ["source", sourceKey],
+      ["acp", acpKey],
+      ["running", runningKey],
+      ["queued", queuedKey],
+    ] as const) {
+      await writeSubagentSessionEntry({
+        stateDir: fixture.stateDir,
+        agentId: "main",
+        sessionKey,
+        defaultSessionId: `${runId}-session`,
+      });
+    }
+    const cfg = getRuntimeConfig();
+    const storePath = resolveSessionStorePathCore(cfg.session?.store, { agentId: "main" });
+    const registry = captureActivePluginRegistrySnapshot();
+    setActivePluginRegistry(
+      createTestRegistry([
+        {
+          pluginId: "stop-test",
+          source: "test",
+          plugin: {
+            ...createChannelTestPluginBase({ id: "stop-test" }),
+            conversationBindings: { supportsCurrentConversationBinding: true },
+          },
+        },
+      ]),
+    );
+    const binding = await getSessionBindingService().bind({
+      targetSessionKey: acpKey,
+      targetKind: "session",
+      conversation: { channel: "stop-test", accountId: "default", conversationId: "room" },
+      placement: "current",
+    });
+    const entered = createDeferred();
+    const proceed = createDeferred();
+    const cancelFinished = createDeferred();
+    const turnStarted = createDeferred<AbortSignal>();
+    const finishTurn = createDeferred();
+    const nativeInterrupted = createDeferred();
+    const cancel = vi.fn<AcpRuntime["cancel"]>(async () => {
+      entered.resolve();
+      await proceed.promise;
+      cancelFinished.resolve();
+      if (completion === "reject") {
+        throw new Error("backend cancellation failed");
+      }
+    });
+    registerAcpRuntimeBackend({
+      id: "stop-test",
+      runtime: {
+        ensureSession: async ({ sessionKey }) => ({
+          sessionKey,
+          backend: "stop-test",
+          runtimeSessionName: "mock-runtime",
+        }),
+        async *runTurn({ signal }) {
+          if (!signal) {
+            throw new Error("ACP manager did not provide its active turn signal");
+          }
+          turnStarted.resolve(signal);
+          await finishTurn.promise;
+          yield { type: "done", status: "cancelled" };
+        },
+        cancel,
+        close: async () => {},
+      },
+    });
+    acpTesting.resetAcpSessionManagerForTests();
+    const manager = getAcpSessionManager();
+    const native = createReplyOperation({
+      sessionKey: sourceKey,
+      sessionId: "source-session",
+      resetTriggered: false,
+    });
+    native.attachBackend({
+      kind: "embedded",
+      isStreaming: () => true,
+      cancel: () => {
+        releaseSwarmRun("capacity");
+        if (nativeFailure) {
+          throw nativeError;
+        }
+      },
+    });
+    const runningAbort = vi.fn();
+    const handle = createEmbeddedRunHandle({ runId: "running", abort: runningAbort });
+    setActiveEmbeddedRun("running-session", handle, runningKey);
+    const selectedDispatch = vi.fn(async () => {});
+    const survivorDispatch = vi.fn(async () => {});
+    let pending: ReturnType<typeof tryFastAbortFromMessage> | undefined;
+    let childAdmission: SessionWorkAdmissionLease | undefined;
+    const preparedAdmission = prepareAgentRunAdmission({
+      cfg,
+      operationalRunInstance: createOperationalRunInstanceRef("acp-steer"),
+      facts: {
+        runId: "acp-steer",
+        agentId: "main",
+        ingress: { kind: "acp", boundary: "acp.command.steer", state: "absent" },
+      },
+    });
+    let turn: Promise<void> | undefined;
+    let acpSignal: AbortSignal | undefined;
+    let stopSettled = false;
+    try {
+      await manager.initializeSession({
+        cfg,
+        sessionKey: acpKey,
+        agent: "main",
+        mode: "persistent",
+        backendId: "stop-test",
+      });
+      if (active) {
+        const admittedRunContext = await preparedAdmission.admit("acp");
+        // Match /acp steer: the manager owns the only cancellation signal.
+        turn = manager
+          .runTurn({
+            cfg,
+            admittedRunContext,
+            sessionKey: acpKey,
+            requestId: "acp-steer",
+            mode: "steer",
+            provenance: "agent",
+            text: "keep working",
+          })
+          .finally(() => preparedAdmission.close());
+        acpSignal = await Promise.race([
+          turnStarted.promise,
+          turn.then(() => {
+            throw new Error("ACP steer completed before the active-turn gate");
+          }),
+        ]);
+        expect(acpSignal.aborted).toBe(false);
+        expect(manager.getObservabilitySnapshot().turns.active).toBe(1);
+        childAdmission = await beginSessionWorkAdmission({
+          scope: storePath,
+          identities: [runningKey, "running-session"],
+          assertAllowed: () => {},
+          onInterrupt: () => nativeInterrupted.resolve(),
+        });
+      }
+      for (const [runId, childSessionKey] of [
+        ["running", runningKey],
+        ["queued", queuedKey],
+      ] as const) {
+        registerSubagentRun({
+          runId,
+          childSessionKey,
+          requesterSessionKey: sourceKey,
+          requesterAgentId: "main",
+          requesterDisplayKey: sourceKey,
+          task: runId,
+          cleanup: "keep",
+          collect: true,
+          queued: runId === "queued",
+          expectsCompletionMessage: false,
+        });
+      }
+      for (const [runId, start] of [
+        ["queued", selectedDispatch],
+        ["survivor", survivorDispatch],
+      ] as const) {
+        enqueueSwarmRun({
+          groupId: "bound-acp",
+          runId,
+          maxConcurrent: 1,
+          activeRunIds: ["capacity"],
+          start,
+          onStartFailure: () => true,
+        });
+      }
+      pending = tryFastAbortFromMessage({
+        cfg,
+        ctx: buildTestCtx({
+          SessionKey: sourceKey,
+          CommandBody: "/stop",
+          RawBody: "/stop",
+          CommandAuthorized: true,
+          Provider: "stop-test",
+          Surface: "stop-test",
+          From: "stop-test:room",
+          To: "stop-test:room",
+          MessageSid: "77",
+          Timestamp: 1234567890000,
+        }),
+      }).finally(() => {
+        stopSettled = true;
+      });
+      const outcome = pending.then(
+        (result) => ({ result }),
+        (error: unknown) => ({ error }),
+      );
+      if (nativeFailure) {
+        await Promise.race([
+          entered.promise,
+          outcome.then(() => {
+            throw new Error("Native failure escaped before ACP cancellation started");
+          }),
+        ]);
+        expect(native.abortSignal.aborted).toBe(true);
+        expect(acpSignal?.aborted).toBe(true);
+        expect(stopSettled).toBe(false);
+        proceed.resolve();
+        expect(await outcome).toEqual({ error: nativeError });
+        expect(cancel).toHaveBeenCalledOnce();
+        return;
+      }
+      if (active) {
+        await nativeInterrupted.promise;
+        expect(native.abortSignal.aborted).toBe(true);
+        expect(isSessionWorkAdmissionActive(storePath, [runningKey, "running-session"])).toBe(true);
+        await vi.waitFor(() => expect(acpSignal?.aborted).toBe(true));
+        expect(cancel).toHaveBeenCalledOnce();
+        expect(stopSettled).toBe(false);
+        expect(selectedDispatch).not.toHaveBeenCalled();
+        if (completion === "reject") {
+          proceed.resolve();
+          await cancelFinished.promise;
+          // Let rejection observers run while the native admission is still retained.
+          await new Promise<void>((resolve) => {
+            setImmediate(resolve);
+          });
+          expect(stopSettled).toBe(false);
+        }
+        childAdmission?.release();
+      }
+      await Promise.race([
+        entered.promise,
+        pending.then(() => {
+          throw new Error("Stop missed the bound ACP backend");
+        }),
+      ]);
+      expect(native.abortSignal.aborted).toBe(true);
+      // Synchronize on native terminal state, never on the still-held ACP completion.
+      await vi.waitFor(() => expect(runningAbort).toHaveBeenCalledOnce());
+      await vi.waitFor(() => expect(survivorDispatch).toHaveBeenCalledOnce());
+      expect(selectedDispatch).not.toHaveBeenCalled();
+      for (const key of [runningKey, queuedKey]) {
+        expect(getSubagentRunByChildSessionKey(key)?.endedReason).toBe("subagent-killed");
+      }
+      await vi.waitFor(() =>
+        expect(loadExactSessionEntryReadOnly({ sessionKey: sourceKey })?.entry).toMatchObject({
+          abortedLastRun: true,
+          abortCutoffMessageSid: "77",
+          abortCutoffTimestamp: 1234567890000,
+        }),
+      );
+      if (!active || completion !== "reject") {
+        expect(stopSettled).toBe(false);
+      }
+      proceed.resolve();
+      expect(await pending).toEqual({
+        handled: true,
+        aborted: true,
+        stoppedSubagents: 2,
+        failedSubagents: 0,
+      });
+      expect(cancel).toHaveBeenCalledExactlyOnceWith({
+        handle: expect.objectContaining({ sessionKey: acpKey }),
+        reason: "fast-abort",
+      });
+      finishTurn.resolve();
+      await turn;
+      expect(readAcpSessionMeta({ cfg, sessionKey: acpKey })?.state).toBe(
+        !active && completion === "reject" ? "error" : "idle",
+      );
+    } finally {
+      childAdmission?.release();
+      proceed.resolve();
+      finishTurn.resolve();
+      await pending?.catch(() => undefined);
+      await turn?.catch(() => undefined);
+      preparedAdmission.close();
+      native.complete();
+      clearActiveEmbeddedRun("running-session", handle, runningKey);
+      releaseSwarmRun("capacity");
+      releaseSwarmRun("queued");
+      releaseSwarmRun("survivor");
+      await disposeAcpSessionManagerInstance(manager, "test-cleanup");
+      acpTesting.resetAcpSessionManagerForTests();
+      unregisterAcpRuntimeBackend("stop-test");
+      await getSessionBindingService().unbind({
+        bindingId: binding.bindingId,
+        reason: "test-cleanup",
+      });
+      restoreActivePluginRegistrySnapshot(registry);
+    }
+  },
+);

src/auto-reply/reply/abort.lazy.test.ts

@@ -0,0 +1,19 @@
+import { expect, it, vi } from "vitest";
+import { buildTestCtx } from "./test-ctx.js";
+
+vi.mock("../../agents/subagents/registry/subagent-control.js", () => {
+  throw new Error("ordinary messages must not initialize cancellation owners");
+});
+
+it.each(["direct", "group"])(
+  "keeps %s ordinary messages outside cancellation runtime",
+  async (chatType) => {
+    const { tryFastAbortFromMessage } = await import("./abort.js");
+    await expect(
+      tryFastAbortFromMessage({
+        ctx: buildTestCtx({ CommandBody: "continue the conversation", ChatType: chatType }),
+        cfg: {},
+      }),
+    ).resolves.toEqual({ handled: false, aborted: false });
+  },
+);

src/auto-reply/reply/abort.runtime-types.ts

@@ -0,0 +1,26 @@
+// Shared abort runtime types for cancellation and cutoff persistence.
+import type { OpenClawConfig } from "../../config/types.openclaw.js";
+import type { FinalizedRuntimeMsgContext } from "../templating.js";
+
+/** Result from the fast abort path before normal reply dispatch starts. */
+type FastAbortResult = {
+  handled: boolean;
+  aborted: boolean;
+  rejectionReason?: "finalizing";
+  stoppedSubagents?: number;
+  failedSubagents?: number;
+};
+
+/** Runtime hook that may convert a message into an immediate abort action. */
+export type TryFastAbortFromMessage = (params: {
+  ctx: FinalizedRuntimeMsgContext;
+  cfg: OpenClawConfig;
+  isCommandTargetCurrent?: () => boolean;
+}) => Promise<FastAbortResult>;
+
+/** Formats the user-visible abort acknowledgement text. */
+export type FormatAbortReplyText = (
+  stoppedSubagents?: number,
+  rejectionReason?: FastAbortResult["rejectionReason"],
+  failedSubagents?: number,
+) => string;

src/auto-reply/reply/abort.runtime.ts

@@ -0,0 +1,2 @@
+/** Runtime facade for fast abort handling used by reply dispatch. */
+export { formatAbortReplyText, tryFastAbortFromMessage } from "./abort.js";

src/auto-reply/reply/abort.target-owner.test.ts

@@ -0,0 +1,383 @@
+import path from "node:path";
+import { afterAll, afterEach, beforeAll, describe, expect, it, onTestFinished } from "vitest";
+import { createDeferred } from "../../../test/helpers/promise.js";
+import {
+  loadSessionEntry,
+  replaceSessionEntry,
+  replaceSessionEntrySync,
+} from "../../config/sessions/session-accessor.js";
+import {
+  getConversationSession,
+  normalizeSessionDeliveryState,
+  patchSessionEntry,
+} from "../../plugin-sdk/session-store-runtime.js";
+import { createSuiteTempRootTracker } from "../../test-helpers/temp-dir.js";
+import { tryFastAbortFromMessage } from "./abort.js";
+import { handleStopCommand } from "./commands-session-abort.js";
+import type { HandleCommandsParams } from "./commands-types.js";
+import { parseInlineSessionDirectives } from "./directive-handling.parse.js";
+import { clearSessionQueues, enqueueFollowupRun, getFollowupQueueDepth } from "./queue.js";
+import { createQueueTestRun } from "./queue.test-helpers.js";
+import { createReplyOperation } from "./reply-run-registry.js";
+import { testing } from "./reply-run-registry.test-support.js";
+import { buildTestCtx } from "./test-ctx.js";
+
+const dirs = createSuiteTempRootTracker({ prefix: "openclaw-stop-owner-" });
+const sessionKey = "agent:main:slack:group:g12345678";
+
+beforeAll(() => dirs.setup());
+afterAll(() => dirs.cleanup());
+afterEach(() => {
+  clearSessionQueues([sessionKey]);
+  testing.resetReplyRunRegistry();
+});
+
+async function setupStop() {
+  const root = await dirs.make("case");
+  const storePath = path.join(root, "sessions.json");
+  const cfg = { session: { store: storePath }, commands: { allowFrom: { "*": ["*"] } } };
+  const entry = { sessionId: "session-a", updatedAt: Date.now() };
+  await replaceSessionEntry({ storePath, sessionKey }, entry);
+  const ctx = buildTestCtx({
+    Body: "/stop",
+    CommandBody: "/stop",
+    RawBody: "/stop",
+    Provider: "slack",
+    Surface: "slack",
+    From: "slack:U12345678",
+    To: "slack:G12345678",
+    SenderId: "U12345678",
+    CommandSource: "native",
+    CommandAuthorized: true,
+    SessionKey: "slack:slash:U12345678",
+    CommandTargetSessionKey: sessionKey,
+  });
+  const isCommandTargetCurrent = () =>
+    loadSessionEntry({ storePath, sessionKey })?.sessionId === entry.sessionId;
+  const params: HandleCommandsParams = {
+    cfg,
+    ctx,
+    command: {
+      commandBodyNormalized: "/stop",
+      rawBodyNormalized: "/stop",
+      isAuthorizedSender: true,
+      senderIsOwner: true,
+      senderId: "U12345678",
+      channel: "slack",
+      surface: "slack",
+      ownerList: [],
+    },
+    agentId: "main",
+    directives: parseInlineSessionDirectives(""),
+    elevated: { enabled: false, allowed: false, failures: [] },
+    sessionKey: ctx.SessionKey ?? "",
+    sessionStore: { [sessionKey]: entry },
+    storePath,
+    workspaceDir: root,
+    defaultGroupActivation: () => "always",
+    resolvedVerboseLevel: "off",
+    resolvedReasoningLevel: "off",
+    resolvedBlockStreamingBreak: "text_end",
+    resolveDefaultThinkingLevel: async () => undefined,
+    provider: "openai",
+    model: "gpt-test",
+    contextTokens: 1000,
+    isGroup: true,
+    opts: { isCommandTargetCurrent },
+  };
+  return { cfg, ctx, entry, params, storePath, isCommandTargetCurrent };
+}
+
+describe.each(["fast", "command"] as const)("%s Stop current owner", (pathKind) => {
+  it("retires an idle MCP runtime on explicit Stop", async () => {
+    const state = await setupStop();
+    const { getOrCreateSessionMcpRuntime } =
+      await import("../../agents/agent-bundle-mcp-manager.test-support.js");
+    const { getSessionMcpRuntimeManagerForTesting } =
+      await import("../../agents/agent-bundle-mcp-manager-api.js");
+    const manager = getSessionMcpRuntimeManagerForTesting();
+    try {
+      await getOrCreateSessionMcpRuntime({
+        sessionId: state.entry.sessionId,
+        sessionKey,
+        workspaceDir: state.params.workspaceDir,
+        cfg: { mcp: { servers: {} } },
+        manifestRegistry: { plugins: [] },
+      });
+      if (pathKind === "fast") {
+        await tryFastAbortFromMessage({
+          ctx: state.ctx,
+          cfg: state.cfg,
+          isCommandTargetCurrent: state.isCommandTargetCurrent,
+        });
+      } else {
+        await handleStopCommand(state.params, true);
+      }
+      expect(manager.peekSession({ sessionId: state.entry.sessionId })).toBeUndefined();
+    } finally {
+      await manager.disposeAll();
+    }
+  });
+
+  it("stops the selected agent's global session in an explicit roster", async () => {
+    const state = await setupStop();
+    const agentId = "selected";
+    const globalKey = "global";
+    const storePath = path.join(
+      state.params.workspaceDir,
+      "agents",
+      agentId,
+      "sessions",
+      "sessions.json",
+    );
+    const cfg = {
+      ...state.cfg,
+      agents: { ownership: "explicit" as const, entries: { other: {}, [agentId]: {} } },
+      session: {
+        scope: "global" as const,
+        store: path.join(
+          state.params.workspaceDir,
+          "agents",
+          "{agentId}",
+          "sessions",
+          "sessions.json",
+        ),
+      },
+    };
+    const scope = { agentId, storePath, sessionKey: globalKey };
+    await replaceSessionEntry(scope, state.entry);
+    const ctx = { ...state.ctx, AgentId: agentId, CommandTargetSessionKey: globalKey };
+    const isCommandTargetCurrent = () =>
+      loadSessionEntry(scope)?.sessionId === state.entry.sessionId;
+    const operation = createReplyOperation({
+      sessionKey: globalKey,
+      sessionId: state.entry.sessionId,
+      resetTriggered: false,
+    });
+    operation.attachBackend({ kind: "embedded", cancel: () => {}, isStreaming: () => true });
+    try {
+      const result = await (pathKind === "fast"
+        ? tryFastAbortFromMessage({ cfg, ctx, isCommandTargetCurrent })
+        : handleStopCommand(
+            {
+              ...state.params,
+              cfg,
+              ctx,
+              agentId,
+              sessionKey: globalKey,
+              sessionStore: { [globalKey]: state.entry },
+              storePath,
+              opts: { isCommandTargetCurrent },
+            },
+            true,
+          ));
+      expect(operation.abortSignal.aborted).toBe(true);
+      expect(result).toMatchObject(
+        pathKind === "fast"
+          ? { handled: true, aborted: true }
+          : { shouldContinue: false, reply: { text: "⚙️ Agent was aborted." } },
+      );
+      expect(loadSessionEntry(scope)).toMatchObject({
+        sessionId: state.entry.sessionId,
+        abortedLastRun: true,
+      });
+    } finally {
+      operation.complete();
+      clearSessionQueues([globalKey]);
+    }
+  });
+
+  it("does not reclaim a conversation reassigned after abort preparation", async () => {
+    const state = await setupStop();
+    const nextKey = `${sessionKey}:thread:123.456`;
+    const address = {
+      agentId: "main",
+      storePath: state.storePath,
+      channel: "slack",
+      accountId: "default",
+      kind: "group" as const,
+      peerId: "g12345678",
+      threadId: "123.456",
+    };
+    const delivery = normalizeSessionDeliveryState({
+      context: {
+        channel: "slack",
+        accountId: "default",
+        to: "group:g12345678",
+        threadId: "123.456",
+      },
+    });
+    await replaceSessionEntry(
+      { storePath: state.storePath, sessionKey },
+      { ...state.entry, updatedAt: 100, chatType: "group", delivery },
+    );
+    const operation = createReplyOperation({
+      sessionKey,
+      sessionId: state.entry.sessionId,
+      resetTriggered: false,
+    });
+    operation.attachBackend({ kind: "embedded", cancel: () => {}, isStreaming: () => true });
+    let reassigned = false;
+    state.isCommandTargetCurrent = () => {
+      const current = getConversationSession(address);
+      if (
+        !reassigned &&
+        operation.abortSignal.aborted &&
+        (pathKind === "fast" || state.params.sessionStore?.[sessionKey]?.abortedLastRun === true)
+      ) {
+        reassigned = true;
+        // A separate synchronous writer commits while abort's prepared patch yields.
+        queueMicrotask(() => {
+          replaceSessionEntrySync(
+            { storePath: state.storePath, sessionKey: nextKey },
+            { sessionId: "session-b", updatedAt: 200, chatType: "group", delivery },
+          );
+        });
+      }
+      return current?.sessionKey === sessionKey;
+    };
+    state.params.opts = { isCommandTargetCurrent: state.isCommandTargetCurrent };
+    const failure = await (
+      pathKind === "fast" ? tryFastAbortFromMessage(state) : handleStopCommand(state.params, true)
+    ).then(
+      () => undefined,
+      (error: unknown) => error,
+    );
+    expect(operation.abortSignal.aborted).toBe(true);
+    expect(reassigned).toBe(true);
+    expect(getConversationSession(address)).toEqual({
+      sessionKey: nextKey,
+      sessionId: "session-b",
+    });
+    expect(loadSessionEntry({ storePath: state.storePath, sessionKey })?.abortedLastRun).not.toBe(
+      true,
+    );
+    if (failure) {
+      expect(failure).toMatchObject({
+        message: "The selected session changed before it could be stopped.",
+      });
+    }
+    operation.complete();
+  });
+
+  it("skips stale abort bookkeeping after waiting for a replacement writer", async () => {
+    const state = await setupStop();
+    const entered = createDeferred();
+    const release = createDeferred();
+    const writer = patchSessionEntry({
+      storePath: state.storePath,
+      sessionKey,
+      update: async () => {
+        entered.resolve();
+        await release.promise;
+        return { sessionId: "session-b", updatedAt: Date.now() };
+      },
+    });
+    await entered.promise;
+    const operation = createReplyOperation({
+      sessionKey,
+      sessionId: "session-a",
+      resetTriggered: false,
+    });
+    operation.attachBackend({ kind: "embedded", cancel: () => {}, isStreaming: () => true });
+    const aborted = createDeferred();
+    const onAbort = () => aborted.resolve();
+    operation.abortSignal.addEventListener("abort", onAbort, { once: true });
+    const stopping =
+      pathKind === "fast" ? tryFastAbortFromMessage(state) : handleStopCommand(state.params, true);
+    onTestFinished(async () => {
+      operation.abortSignal.removeEventListener("abort", onAbort);
+      release.resolve();
+      await Promise.allSettled([writer, stopping]);
+      operation.complete();
+    });
+    void stopping.then(
+      () => {
+        if (!operation.abortSignal.aborted) {
+          aborted.reject(new Error("Stop completed without aborting the active operation"));
+        }
+      },
+      (error: unknown) => aborted.reject(error),
+    );
+    await aborted.promise;
+    expect(operation.abortSignal.aborted).toBe(true);
+    release.resolve();
+    await writer;
+    await stopping;
+    expect(loadSessionEntry({ storePath: state.storePath, sessionKey })).toMatchObject({
+      sessionId: "session-b",
+    });
+    expect(loadSessionEntry({ storePath: state.storePath, sessionKey })?.abortedLastRun).toBe(
+      false,
+    );
+  });
+
+  it("completes cancellation when its own abort releases the live publisher", async () => {
+    const state = await setupStop();
+    const operation = createReplyOperation({
+      sessionKey,
+      sessionId: "session-a",
+      resetTriggered: false,
+    });
+    operation.attachBackend({ kind: "embedded", cancel: () => {}, isStreaming: () => true });
+    state.isCommandTargetCurrent = () => !operation.abortSignal.aborted;
+    state.params.opts = { isCommandTargetCurrent: state.isCommandTargetCurrent };
+    const result = await (pathKind === "fast"
+      ? tryFastAbortFromMessage(state)
+      : handleStopCommand(state.params, true));
+    expect(operation.abortSignal.aborted).toBe(true);
+    expect(result).toMatchObject(
+      pathKind === "fast" ? { handled: true, aborted: true } : { shouldContinue: false },
+    );
+    expect(
+      loadSessionEntry({ storePath: state.storePath, sessionKey })?.abortedLastRun,
+    ).toBeUndefined();
+    operation.complete();
+  });
+
+  it("preserves a replacement run and its queued input after dispatch handoff", async () => {
+    const state = await setupStop();
+    const admitted = createReplyOperation({
+      sessionKey,
+      sessionId: "session-a",
+      resetTriggered: false,
+    });
+    const dispatch = createDeferred();
+    expect(state.isCommandTargetCurrent()).toBe(true);
+    const pending = dispatch.promise.then(async () =>
+      pathKind === "fast" ? tryFastAbortFromMessage(state) : handleStopCommand(state.params, true),
+    );
+    admitted.complete();
+    await replaceSessionEntry(
+      { storePath: state.storePath, sessionKey },
+      {
+        sessionId: "session-b",
+        updatedAt: Date.now(),
+      },
+    );
+    const replacement = createReplyOperation({
+      sessionKey,
+      sessionId: "session-b",
+      resetTriggered: false,
+    });
+    replacement.attachBackend({ kind: "embedded", cancel: () => {}, isStreaming: () => true });
+    enqueueFollowupRun(
+      sessionKey,
+      createQueueTestRun({ prompt: "next conversation" }),
+      { mode: "collect", debounceMs: 0, cap: 20, dropPolicy: "summarize" },
+      "none",
+    );
+    dispatch.resolve();
+    const result = await pending.then(
+      () => undefined,
+      (error: unknown) => error,
+    );
+    expect(replacement.abortSignal.aborted).toBe(false);
+    expect(result).toBeInstanceOf(Error);
+    expect(getFollowupQueueDepth(sessionKey)).toBe(1);
+    expect(
+      loadSessionEntry({ storePath: state.storePath, sessionKey })?.abortedLastRun,
+    ).toBeUndefined();
+    replacement.complete();
+  });
+});

src/auto-reply/reply/abort.test.ts

@@ -0,0 +1,1559 @@
+// Tests abort request handling, cutoff persistence, and active run cleanup.
+import path from "node:path";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { createDeferred } from "../../../test/helpers/promise.js";
+import { registerSubagentRun } from "../../agents/subagents/registry/subagent-registry.js";
+import { settleSubagentRegistryPersistenceWork } from "../../agents/subagents/registry/subagent-registry.persistence.test-support.js";
+import {
+  addSubagentRunForTests,
+  getSubagentRunByChildSessionKey,
+  resetSubagentRegistryForTests,
+  testing as subagentRegistryTesting,
+} from "../../agents/subagents/registry/subagent-registry.test-helpers.js";
+import type { OpenClawConfig } from "../../config/config.js";
+import {
+  loadSessionEntry,
+  markSessionAbortTarget,
+  replaceSessionEntry,
+  resolveSessionAbortTarget,
+  type SessionAbortTargetResult,
+} from "../../config/sessions/session-accessor.js";
+import { getSessionBindingService } from "../../infra/outbound/session-binding-service.js";
+import { createSuiteTempRootTracker } from "../../test-helpers/temp-dir.js";
+import { resolveAbortCutoffFromContext, shouldSkipMessageByAbortCutoff } from "./abort-cutoff.js";
+import { stopSubagentsForRequester } from "./abort-operation.js";
+import {
+  getAbortMemory,
+  isAbortRequestText,
+  isAbortTrigger,
+  setAbortMemory,
+} from "./abort-primitives.js";
+import { formatAbortReplyText, tryFastAbortFromMessage } from "./abort.js";
+import { enqueueFollowupRun, getFollowupQueueDepth, type FollowupRun } from "./queue.js";
+import { clearFollowupQueue } from "./queue/state.js";
+import { createReplyOperation, replyRunRegistry } from "./reply-run-registry.js";
+import { testing as replyRunRegistryTesting } from "./reply-run-registry.test-support.js";
+import { buildTestCtx } from "./test-ctx.js";
+
+type SubagentRunFixture = Parameters<typeof addSubagentRunForTests>[0];
+
+function addSubagentFixture(run: SubagentRunFixture) {
+  addSubagentRunForTests({ requesterAgentId: "main", ...run });
+}
+
+type AbortEmbeddedAgentRunOptions = Parameters<
+  typeof import("../../agents/embedded-agent-runner/runs.js").abortEmbeddedAgentRun
+>[1];
+
+vi.mock("../../agents/embedded-agent.js", () => ({
+  abortEmbeddedAgentRun: vi.fn().mockReturnValue(true),
+  resolveEmbeddedSessionLane: (key: string) => `session:${key.trim() || "main"}`,
+}));
+
+const commandQueueMocks = vi.hoisted(() => ({
+  clearCommandLane: vi.fn(() => 1),
+}));
+
+vi.mock("../../process/command-queue.js", () => commandQueueMocks);
+
+const acpManagerMocks = vi.hoisted(() => ({
+  resolveSession: vi.fn<
+    () =>
+      | { kind: "none" }
+      | {
+          kind: "ready";
+          sessionKey: string;
+          meta: unknown;
+        }
+  >(() => ({ kind: "none" })),
+  cancelSession: vi.fn(async () => {}),
+}));
+
+const runtimeAbortMocks = vi.hoisted(() => ({
+  abortEmbeddedAgentRun: vi.fn<
+    (sessionId: string | undefined, opts?: AbortEmbeddedAgentRunOptions) => boolean
+  >(() => true),
+  resolveActiveEmbeddedRunSessionId: vi.fn(() => undefined as string | undefined),
+  isEmbeddedAgentRunActive: vi.fn(() => false),
+}));
+
+vi.mock("../../agents/embedded-agent-runner/runs.js", () => ({
+  abortEmbeddedAgentRun: runtimeAbortMocks.abortEmbeddedAgentRun,
+  isEmbeddedAgentRunActive: runtimeAbortMocks.isEmbeddedAgentRunActive,
+}));
+vi.mock("../../agents/embedded-agent-runner/active-run-projections.js", () => ({
+  resolveActiveEmbeddedRunSessionId: runtimeAbortMocks.resolveActiveEmbeddedRunSessionId,
+}));
+vi.mock("../../config/sessions/session-accessor.js", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../../config/sessions/session-accessor.js")>();
+  return {
+    ...actual,
+    markSessionAbortTarget: vi.fn(actual.markSessionAbortTarget),
+    resolveSessionAbortTarget: vi.fn(actual.resolveSessionAbortTarget),
+  };
+});
+
+vi.mock("../../acp/control-plane/manager.js", () => ({
+  getAcpSessionManager: () => ({
+    resolveSession: acpManagerMocks.resolveSession,
+    cancelSession: acpManagerMocks.cancelSession,
+  }),
+}));
+
+const suiteTempDirs = createSuiteTempRootTracker({ prefix: "openclaw-abort-" });
+
+describe("abort detection", () => {
+  const trackedAbortMemoryKeys = new Set<string>();
+
+  function setTrackedAbortMemory(key: string, value: boolean): void {
+    trackedAbortMemoryKeys.add(key);
+    setAbortMemory(key, value);
+  }
+
+  beforeAll(async () => {
+    await suiteTempDirs.setup();
+  });
+
+  afterAll(async () => {
+    await suiteTempDirs.cleanup();
+  });
+
+  async function writeSessionStore(
+    storePath: string,
+    sessionIdsByKey: Record<string, string>,
+    nowMs = Date.now(),
+  ) {
+    await Promise.all(
+      Object.entries(sessionIdsByKey).map(([sessionKey, sessionId]) =>
+        replaceSessionEntry({ storePath, sessionKey }, { sessionId, updatedAt: nowMs }),
+      ),
+    );
+  }
+
+  function readAbortSessionEntry(storePath: string, sessionKey: string) {
+    return loadSessionEntry({ storePath, sessionKey });
+  }
+
+  async function createAbortConfig(params?: {
+    commandsTextEnabled?: boolean;
+    sessionIdsByKey?: Record<string, string>;
+    nowMs?: number;
+  }) {
+    const root = await suiteTempDirs.make("case");
+    const storePath = path.join(root, "sessions.json");
+    const cfg = {
+      session: { store: storePath },
+      ...(typeof params?.commandsTextEnabled === "boolean"
+        ? { commands: { text: params.commandsTextEnabled } }
+        : {}),
+    } as OpenClawConfig;
+    if (params?.sessionIdsByKey) {
+      for (const sessionKey of Object.keys(params.sessionIdsByKey)) {
+        trackedAbortMemoryKeys.add(sessionKey);
+      }
+      await writeSessionStore(storePath, params.sessionIdsByKey, params.nowMs);
+    }
+    return { root, storePath, cfg };
+  }
+
+  async function runStopCommand(params: {
+    cfg: OpenClawConfig;
+    sessionKey?: string;
+    parentSessionKey?: string;
+    from: string;
+    to: string;
+    senderId?: string;
+    commandSource?: "native" | "text";
+    targetSessionKey?: string;
+    messageSid?: string;
+    timestamp?: number;
+  }) {
+    for (const key of [
+      params.sessionKey,
+      params.parentSessionKey,
+      params.targetSessionKey,
+      params.from,
+      params.to,
+    ]) {
+      if (key) {
+        trackedAbortMemoryKeys.add(key);
+      }
+    }
+    return tryFastAbortFromMessage({
+      ctx: buildTestCtx({
+        CommandBody: "/stop",
+        RawBody: "/stop",
+        CommandAuthorized: true,
+        Provider: "telegram",
+        Surface: "telegram",
+        From: params.from,
+        To: params.to,
+        ...(params.sessionKey ? { SessionKey: params.sessionKey } : {}),
+        ...(params.parentSessionKey ? { ParentSessionKey: params.parentSessionKey } : {}),
+        ...(params.senderId ? { SenderId: params.senderId } : {}),
+        ...(params.commandSource ? { CommandSource: params.commandSource } : {}),
+        ...(params.targetSessionKey ? { CommandTargetSessionKey: params.targetSessionKey } : {}),
+        ...(params.messageSid ? { MessageSid: params.messageSid } : {}),
+        ...(typeof params.timestamp === "number" ? { Timestamp: params.timestamp } : {}),
+      }),
+      cfg: params.cfg,
+    });
+  }
+
+  function enqueueQueuedFollowupRun(params: {
+    root: string;
+    cfg: OpenClawConfig;
+    sessionId: string;
+    sessionKey: string;
+  }) {
+    trackedAbortMemoryKeys.add(params.sessionKey);
+    const followupRun: FollowupRun = {
+      prompt: "queued",
+      enqueuedAt: Date.now(),
+      run: {
+        agentId: "main",
+        agentDir: path.join(params.root, "agent"),
+        sessionId: params.sessionId,
+        sessionKey: params.sessionKey,
+        messageProvider: "telegram",
+        agentAccountId: "acct",
+        sessionFile: path.join(params.root, "session.jsonl"),
+        workspaceDir: path.join(params.root, "workspace"),
+        config: params.cfg,
+        provider: "anthropic",
+        model: "claude-opus-4-6",
+        timeoutMs: 1000,
+        blockReplyBreak: "text_end",
+      },
+    };
+    enqueueFollowupRun(
+      params.sessionKey,
+      followupRun,
+      { mode: "collect", debounceMs: 0, cap: 20, dropPolicy: "summarize" },
+      "none",
+    );
+  }
+
+  function expectSessionLaneCleared(sessionKey: string) {
+    expect(commandQueueMocks.clearCommandLane).toHaveBeenCalledWith(`session:${sessionKey}`);
+  }
+
+  function bindAcpSessionForTest(targetSessionKey: string) {
+    vi.spyOn(getSessionBindingService(), "resolveByConversation").mockImplementation(
+      (conversation) => ({
+        bindingId: "test-acp-binding",
+        targetKind: "session",
+        targetSessionKey,
+        conversation,
+        status: "active",
+        boundAt: 0,
+      }),
+    );
+  }
+
+  beforeEach(() => {
+    subagentRegistryTesting.setDepsForTest({
+      persistSubagentRunsToDisk: () => {},
+      persistSubagentRunsToDiskOrThrow: () => {},
+      restoreSubagentRunsFromDisk: () => 0,
+      cleanupBrowserSessionsForLifecycleEnd: async () => {},
+      ensureContextEnginesInitialized: () => {},
+      loadAgentRuntimePluginRegistryHandle: () => undefined,
+    });
+    commandQueueMocks.clearCommandLane.mockClear().mockReturnValue(1);
+  });
+
+  afterEach(async () => {
+    for (const key of trackedAbortMemoryKeys) {
+      setAbortMemory(key, false);
+      clearFollowupQueue(key);
+    }
+    trackedAbortMemoryKeys.clear();
+    vi.restoreAllMocks();
+    vi.mocked(markSessionAbortTarget).mockReset();
+    vi.mocked(resolveSessionAbortTarget).mockReset();
+    replyRunRegistryTesting.resetReplyRunRegistry();
+    commandQueueMocks.clearCommandLane.mockClear().mockReturnValue(1);
+    acpManagerMocks.resolveSession.mockReset().mockReturnValue({ kind: "none" });
+    acpManagerMocks.cancelSession.mockReset().mockResolvedValue(undefined);
+    runtimeAbortMocks.abortEmbeddedAgentRun.mockReset().mockReturnValue(true);
+    runtimeAbortMocks.resolveActiveEmbeddedRunSessionId.mockReset().mockReturnValue(undefined);
+    await settleSubagentRegistryPersistenceWork();
+    resetSubagentRegistryForTests({ persist: false });
+    subagentRegistryTesting.setDepsForTest();
+  });
+
+  it("isAbortTrigger matches standalone abort trigger phrases", () => {
+    const positives = [
+      "stop",
+      "esc",
+      "abort",
+      "exit",
+      "interrupt",
+      "stop openclaw",
+      "openclaw stop",
+      "stop action",
+      "stop current action",
+      "stop run",
+      "stop current run",
+      "stop agent",
+      "stop the agent",
+      "stop don't do anything",
+      "stop dont do anything",
+      "stop do not do anything",
+      "stop doing anything",
+      "do not do that",
+      "please stop",
+      "stop please",
+      "STOP OPENCLAW",
+      "stop openclaw!!!",
+      "stop don’t do anything",
+      "detente",
+      "detén",
+      "arrête",
+      "停止",
+      "停下来",
+      "暂停",
+      "停下来！",
+      "やめて",
+      "止めて",
+      "रुको",
+      "توقف",
+      "стоп",
+      "остановись",
+      "останови",
+      "остановить",
+      "прекрати",
+      "halt",
+      "anhalten",
+      "aufhören",
+      "hoer auf",
+      "stopp",
+      "pare",
+    ];
+    for (const candidate of positives) {
+      expect(isAbortTrigger(candidate)).toBe(true);
+    }
+
+    expect(isAbortTrigger("hello")).toBe(false);
+    expect(isAbortTrigger("wait")).toBe(false);
+    expect(isAbortTrigger("please wait")).toBe(false);
+    expect(isAbortTrigger("please do not do that")).toBe(false);
+    // /stop is NOT matched by isAbortTrigger - it's handled separately.
+    expect(isAbortTrigger("/stop")).toBe(false);
+  });
+
+  it("isAbortRequestText aligns abort command semantics", () => {
+    expect(isAbortRequestText("/stop")).toBe(true);
+    expect(isAbortRequestText("/STOP")).toBe(true);
+    expect(isAbortRequestText("/stop!!!")).toBe(true);
+    expect(isAbortRequestText("/Stop!!!")).toBe(true);
+    expect(isAbortRequestText("stop")).toBe(true);
+    expect(isAbortRequestText("Stop")).toBe(true);
+    expect(isAbortRequestText("STOP")).toBe(true);
+    expect(isAbortRequestText("stop action")).toBe(true);
+    expect(isAbortRequestText("stop openclaw!!!")).toBe(true);
+    expect(isAbortRequestText("停下来")).toBe(true);
+    expect(isAbortRequestText("暂停")).toBe(true);
+    expect(isAbortRequestText("やめて")).toBe(true);
+    expect(isAbortRequestText("остановись")).toBe(true);
+    expect(isAbortRequestText("halt")).toBe(true);
+    expect(isAbortRequestText("stopp")).toBe(true);
+    expect(isAbortRequestText("pare")).toBe(true);
+    expect(isAbortRequestText(" توقف ")).toBe(true);
+    expect(isAbortRequestText("/stop@openclaw_bot", { botUsername: "openclaw_bot" })).toBe(true);
+    expect(isAbortRequestText("/Stop@openclaw_bot", { botUsername: "openclaw_bot" })).toBe(true);
+    expect(
+      isAbortRequestText("/stop@unresolved_bot", {
+        targetedCommandMode: "pre-identity",
+      }),
+    ).toBe(true);
+    expect(
+      isAbortRequestText("/stop@unresolved_bot!", {
+        targetedCommandMode: "pre-identity",
+      }),
+    ).toBe(true);
+    expect(
+      isAbortRequestText("/queue@unresolved_bot", {
+        targetedCommandMode: "pre-identity",
+      }),
+    ).toBe(false);
+    expect(
+      isAbortRequestText("/stop@some_other_bot", {
+        botUsername: "openclaw_bot",
+        targetedCommandMode: "pre-identity",
+      }),
+    ).toBe(false);
+
+    expect(isAbortRequestText("/status")).toBe(false);
+    expect(isAbortRequestText("wait")).toBe(false);
+    expect(isAbortRequestText("please wait")).toBe(false);
+    expect(isAbortRequestText("do not do that")).toBe(true);
+    expect(isAbortRequestText("please do not do that")).toBe(false);
+    expect(isAbortRequestText("/abort")).toBe(false);
+  });
+
+  it("removes abort memory entry when flag is reset", () => {
+    setTrackedAbortMemory("session-1", true);
+    expect(getAbortMemory("session-1")).toBe(true);
+
+    setTrackedAbortMemory("session-1", false);
+    expect(getAbortMemory("session-1")).toBeUndefined();
+  });
+
+  it("caps abort memory tracking to a bounded max size", () => {
+    for (let i = 0; i < 2105; i += 1) {
+      setTrackedAbortMemory(`bounded-memory-session-${i}`, true);
+    }
+    expect(getAbortMemory("bounded-memory-session-0")).toBeUndefined();
+    expect(getAbortMemory("bounded-memory-session-2104")).toBe(true);
+  });
+
+  it("extracts abort cutoff metadata from context", () => {
+    expect(
+      resolveAbortCutoffFromContext(
+        buildTestCtx({
+          MessageSid: "42",
+          Timestamp: 123,
+        }),
+      ),
+    ).toEqual({
+      messageSid: "42",
+      timestamp: 123,
+    });
+  });
+
+  it("treats numeric message IDs at or before cutoff as stale", () => {
+    expect(
+      shouldSkipMessageByAbortCutoff({
+        cutoffMessageSid: "200",
+        messageSid: "199",
+      }),
+    ).toBe(true);
+    expect(
+      shouldSkipMessageByAbortCutoff({
+        cutoffMessageSid: "200",
+        messageSid: "200",
+      }),
+    ).toBe(true);
+    expect(
+      shouldSkipMessageByAbortCutoff({
+        cutoffMessageSid: "200",
+        messageSid: "201",
+      }),
+    ).toBe(false);
+  });
+
+  it("falls back to timestamp cutoff when message IDs are unavailable", () => {
+    expect(
+      shouldSkipMessageByAbortCutoff({
+        cutoffTimestamp: 2000,
+        timestamp: 1999,
+      }),
+    ).toBe(true);
+    expect(
+      shouldSkipMessageByAbortCutoff({
+        cutoffTimestamp: 2000,
+        timestamp: 2000,
+      }),
+    ).toBe(true);
+    expect(
+      shouldSkipMessageByAbortCutoff({
+        cutoffTimestamp: 2000,
+        timestamp: 2001,
+      }),
+    ).toBe(false);
+  });
+
+  it("fast-aborts even when text commands are disabled", async () => {
+    const { cfg } = await createAbortConfig({ commandsTextEnabled: false });
+
+    const result = await runStopCommand({
+      cfg,
+      sessionKey: "telegram:123",
+      from: "telegram:123",
+      to: "telegram:123",
+    });
+
+    expect(result.handled).toBe(true);
+  });
+
+  it("resolves owner authorization after loading cancellation runtime", async () => {
+    const sessionKey = "telegram:123";
+    const sessionId = "session-123";
+    const { root, cfg } = await createAbortConfig({
+      sessionIdsByKey: { [sessionKey]: sessionId },
+    });
+    cfg.commands = { ownerAllowFrom: ["telegram:123"] };
+    enqueueQueuedFollowupRun({ root, cfg, sessionId, sessionKey });
+    const pending = runStopCommand({
+      cfg,
+      sessionKey,
+      from: "telegram:123",
+      to: "telegram:123",
+      senderId: "123",
+    });
+    cfg.commands.ownerAllowFrom = ["telegram:other-owner"];
+
+    await expect(pending).resolves.toEqual({ handled: false, aborted: false });
+    expect(getFollowupQueueDepth(sessionKey)).toBe(1);
+  });
+
+  it("fast-aborts authorized text slash stop commands before they queue", async () => {
+    const sessionKey = "telegram:123";
+    const sessionId = "session-123";
+    const activeSessionId = "session-active";
+    const { root, cfg } = await createAbortConfig({
+      sessionIdsByKey: { [sessionKey]: sessionId },
+    });
+    cfg.commands = {
+      ...cfg.commands,
+      ownerAllowFrom: ["telegram:123"],
+    };
+    runtimeAbortMocks.resolveActiveEmbeddedRunSessionId.mockReturnValue(activeSessionId);
+    enqueueQueuedFollowupRun({ root, cfg, sessionId, sessionKey });
+    expect(getFollowupQueueDepth(sessionKey)).toBe(1);
+
+    const result = await runStopCommand({
+      cfg,
+      sessionKey,
+      from: "telegram:123",
+      to: "telegram:123",
+      senderId: "123",
+      commandSource: "text",
+    });
+
+    expect(result.handled).toBe(true);
+    expect(runtimeAbortMocks.resolveActiveEmbeddedRunSessionId).toHaveBeenCalledWith(sessionKey);
+    expect(runtimeAbortMocks.abortEmbeddedAgentRun).toHaveBeenCalledWith(activeSessionId);
+    expect(getFollowupQueueDepth(sessionKey)).toBe(0);
+    expectSessionLaneCleared(sessionKey);
+  });
+
+  it("fast-abort clears queued followups and session lane", async () => {
+    const sessionKey = "telegram:123";
+    const sessionId = "session-123";
+    const { root, cfg } = await createAbortConfig({
+      sessionIdsByKey: { [sessionKey]: sessionId },
+    });
+    enqueueQueuedFollowupRun({ root, cfg, sessionId, sessionKey });
+    expect(getFollowupQueueDepth(sessionKey)).toBe(1);
+
+    const result = await runStopCommand({
+      cfg,
+      sessionKey,
+      from: "telegram:123",
+      to: "telegram:123",
+    });
+
+    expect(result.handled).toBe(true);
+    expect(getFollowupQueueDepth(sessionKey)).toBe(0);
+    expectSessionLaneCleared(sessionKey);
+  });
+
+  it("fast-abort resolves canonical stored session identity before metadata persistence", async () => {
+    const storeKey = "agent:main:telegram:group:-1001234567890:topic:99";
+    const lookupKey = "Agent:Main:Telegram:Group:-1001234567890:Topic:99";
+    const sessionId = "agent-topic-99";
+    const { root, cfg } = await createAbortConfig({
+      sessionIdsByKey: { [storeKey]: sessionId },
+    });
+    enqueueQueuedFollowupRun({ root, cfg, sessionId, sessionKey: storeKey });
+
+    const result = await runStopCommand({
+      cfg,
+      sessionKey: lookupKey,
+      from: "telegram:123",
+      to: "telegram:123",
+    });
+
+    expect(result.handled).toBe(true);
+    expect(runtimeAbortMocks.abortEmbeddedAgentRun).toHaveBeenCalledWith(sessionId);
+    expect(getFollowupQueueDepth(storeKey)).toBe(0);
+    expectSessionLaneCleared(storeKey);
+  });
+
+  it("fast-abort still stops active runs when abort metadata persistence fails", async () => {
+    const sessionKey = "telegram:persistence-failure";
+    const sessionId = "session-persistence-failure";
+    const activeSessionId = "active-persistence-failure";
+    const { root, cfg } = await createAbortConfig({
+      sessionIdsByKey: { [sessionKey]: sessionId },
+    });
+    runtimeAbortMocks.resolveActiveEmbeddedRunSessionId.mockReturnValue(activeSessionId);
+    vi.mocked(markSessionAbortTarget).mockRejectedValueOnce(
+      new Error("simulated persistence failure"),
+    );
+    enqueueQueuedFollowupRun({ root, cfg, sessionId, sessionKey });
+
+    const result = await runStopCommand({
+      cfg,
+      sessionKey,
+      from: "telegram:123",
+      to: "telegram:123",
+    });
+
+    expect(result.handled).toBe(true);
+    expect(runtimeAbortMocks.abortEmbeddedAgentRun).toHaveBeenCalledWith(activeSessionId);
+    expect(getFollowupQueueDepth(sessionKey)).toBe(0);
+    expectSessionLaneCleared(sessionKey);
+    expect(getAbortMemory(sessionKey)).toBeUndefined();
+  });
+
+  it("fast-abort uses resolved target identity when abort metadata save fails", async () => {
+    const requestedKey = "Agent:Main:Telegram:Group:-1001234567890:Topic:99";
+    const canonicalKey = "agent:main:telegram:group:-1001234567890:topic:99";
+    const sessionId = "resolved-persistence-failure";
+    const { root, cfg } = await createAbortConfig();
+    vi.mocked(markSessionAbortTarget).mockResolvedValueOnce({
+      entry: {
+        sessionId,
+        updatedAt: 10,
+      },
+      persisted: false,
+      persistenceError: "simulated persistence failure",
+      sessionId,
+      sessionKey: canonicalKey,
+    });
+    vi.mocked(resolveSessionAbortTarget).mockReturnValueOnce({
+      entry: {
+        sessionId,
+        updatedAt: 10,
+      },
+      sessionId,
+      sessionKey: canonicalKey,
+    });
+    enqueueQueuedFollowupRun({ root, cfg, sessionId, sessionKey: canonicalKey });
+
+    const result = await runStopCommand({
+      cfg,
+      sessionKey: requestedKey,
+      from: "telegram:123",
+      to: "telegram:123",
+    });
+
+    expect(result.handled).toBe(true);
+    expect(runtimeAbortMocks.abortEmbeddedAgentRun).toHaveBeenCalledWith(sessionId);
+    expect(getFollowupQueueDepth(canonicalKey)).toBe(0);
+    expectSessionLaneCleared(canonicalKey);
+    expect(getAbortMemory(canonicalKey)).toBeUndefined();
+  });
+
+  it("fast-abort uses abort memory when no persisted target entry exists", async () => {
+    const sessionKey = "telegram:missing-persistence-target";
+    const { cfg } = await createAbortConfig();
+    vi.mocked(markSessionAbortTarget).mockResolvedValueOnce(null);
+    vi.mocked(resolveSessionAbortTarget).mockReturnValueOnce(null);
+
+    const result = await runStopCommand({
+      cfg,
+      sessionKey,
+      from: "telegram:123",
+      to: "telegram:123",
+    });
+
+    expect(result.handled).toBe(true);
+    expect(getAbortMemory(sessionKey)).toBe(true);
+  });
+
+  it("fast-abort does not wait for abort metadata persistence before stopping runs", async () => {
+    const sessionKey = "telegram:slow-persistence";
+    const childKey = "agent:main:subagent:slow-persistence-child";
+    const sessionId = "session-slow-persistence";
+    const childSessionId = "session-slow-persistence-child";
+    const { root, cfg } = await createAbortConfig({
+      sessionIdsByKey: {
+        [childKey]: childSessionId,
+        [sessionKey]: sessionId,
+      },
+    });
+    let finishPersistence: (() => void) | undefined;
+    const persistenceStarted = new Promise<void>((resolveStarted) => {
+      vi.mocked(markSessionAbortTarget).mockImplementationOnce(
+        () =>
+          new Promise<SessionAbortTargetResult | null>((resolvePersistence) => {
+            resolveStarted();
+            finishPersistence = () => {
+              resolvePersistence({
+                entry: {
+                  sessionId,
+                  updatedAt: 10,
+                },
+                persisted: true,
+                sessionId,
+                sessionKey,
+              });
+            };
+          }),
+      );
+      vi.mocked(resolveSessionAbortTarget).mockReturnValueOnce({
+        entry: {
+          sessionId,
+          updatedAt: 10,
+        },
+        sessionId,
+        sessionKey,
+      });
+    });
+    enqueueQueuedFollowupRun({ root, cfg, sessionId, sessionKey });
+    addSubagentFixture({
+      runId: "slow-child-run",
+      childSessionKey: childKey,
+      requesterSessionKey: sessionKey,
+      requesterDisplayKey: sessionKey,
+      task: "slow child",
+      cleanup: "keep",
+      createdAt: Date.now(),
+    });
+
+    const resultPromise = runStopCommand({
+      cfg,
+      sessionKey,
+      from: "telegram:123",
+      to: "telegram:123",
+    });
+    await persistenceStarted;
+
+    expect(runtimeAbortMocks.abortEmbeddedAgentRun).toHaveBeenCalledWith(sessionId);
+    expect(runtimeAbortMocks.abortEmbeddedAgentRun).toHaveBeenCalledWith(childSessionId);
+    expect(getSubagentRunByChildSessionKey(childKey)).toMatchObject({
+      endedReason: "subagent-killed",
+      killReconciliation: { suppressTaskDelivery: true },
+    });
+    expect(getFollowupQueueDepth(sessionKey)).toBe(0);
+    expectSessionLaneCleared(sessionKey);
+
+    finishPersistence?.();
+    await expect(resultPromise).resolves.toMatchObject({
+      aborted: true,
+      handled: true,
+    });
+  });
+
+  it("plain-language stop on ACP-bound session triggers ACP cancel", async () => {
+    const sessionKey = "agent:codex:acp:test-1";
+    const sessionId = "session-123";
+    const { cfg } = await createAbortConfig({
+      sessionIdsByKey: { [sessionKey]: sessionId },
+    });
+    acpManagerMocks.resolveSession.mockReturnValue({
+      kind: "ready",
+      sessionKey,
+      meta: {} as never,
+    });
+
+    const result = await runStopCommand({
+      cfg,
+      sessionKey,
+      from: "telegram:123",
+      to: "telegram:123",
+      targetSessionKey: sessionKey,
+    });
+
+    expect(result.handled).toBe(true);
+    expect(acpManagerMocks.cancelSession).toHaveBeenCalledWith({
+      cfg,
+      sessionKey,
+      reason: "fast-abort",
+    });
+  });
+
+  it("ACP cancel failures do not skip queue and lane cleanup", async () => {
+    const sessionKey = "agent:codex:acp:test-2";
+    const sessionId = "session-456";
+    const { root, cfg } = await createAbortConfig({
+      sessionIdsByKey: { [sessionKey]: sessionId },
+    });
+    enqueueQueuedFollowupRun({ root, cfg, sessionId, sessionKey });
+    acpManagerMocks.resolveSession.mockReturnValue({
+      kind: "ready",
+      sessionKey,
+      meta: {} as never,
+    });
+    acpManagerMocks.cancelSession.mockRejectedValueOnce(new Error("cancel failed"));
+
+    const result = await runStopCommand({
+      cfg,
+      sessionKey,
+      from: "telegram:123",
+      to: "telegram:123",
+      targetSessionKey: sessionKey,
+    });
+
+    expect(result.handled).toBe(true);
+    expect(getFollowupQueueDepth(sessionKey)).toBe(0);
+    expectSessionLaneCleared(sessionKey);
+  });
+
+  it("signals the native parent before deferred ACP cancellation and never retargets its replacement", async () => {
+    const sessionKey = "agent:main:discord:channel:deferred-acp";
+    const acpKey = "agent:main:acp:deferred-acp";
+    const { root, cfg } = await createAbortConfig({
+      sessionIdsByKey: { [sessionKey]: "native-session", [acpKey]: "acp-session" },
+    });
+    const native = createReplyOperation({
+      sessionKey,
+      sessionId: "native-session",
+      resetTriggered: false,
+    });
+    native.attachBackend({ kind: "embedded", cancel: () => {}, isStreaming: () => true });
+    enqueueQueuedFollowupRun({ root, cfg, sessionId: "native-session", sessionKey });
+    bindAcpSessionForTest(acpKey);
+    acpManagerMocks.resolveSession.mockReturnValue({ kind: "ready", sessionKey: acpKey, meta: {} });
+    const entered = createDeferred();
+    const proceed = createDeferred();
+    acpManagerMocks.cancelSession.mockImplementationOnce(async () => {
+      entered.resolve();
+      await proceed.promise;
+    });
+    const pending = runStopCommand({
+      cfg,
+      sessionKey,
+      from: "discord:deferred-acp",
+      to: "discord:deferred-acp",
+    });
+    let replacement: ReturnType<typeof createReplyOperation> | undefined;
+    try {
+      await entered.promise;
+      const signaledBeforeAcpWait = native.abortSignal.aborted;
+      if (!signaledBeforeAcpWait) {
+        // This is still-live parent work, not a post-closure registration claim.
+        registerSubagentRun({
+          runId: "during-acp-wait",
+          childSessionKey: "agent:main:subagent:during-acp-wait",
+          requesterSessionKey: sessionKey,
+          requesterAgentId: "main",
+          requesterDisplayKey: sessionKey,
+          task: "registered before native parent was signaled",
+          cleanup: "keep",
+          collect: true,
+          queued: true,
+        });
+      }
+      const queueClearedBeforeAcpWait = getFollowupQueueDepth(sessionKey) === 0;
+      native.complete();
+      replacement = createReplyOperation({
+        sessionKey,
+        sessionId: "replacement-session",
+        resetTriggered: false,
+      });
+      replacement.attachBackend({ kind: "embedded", cancel: () => {}, isStreaming: () => true });
+      proceed.resolve();
+      await pending;
+      expect(
+        signaledBeforeAcpWait,
+        "native parent must be signaled before the independent ACP await",
+      ).toBe(true);
+      expect(queueClearedBeforeAcpWait).toBe(true);
+      expect(
+        replacement.abortSignal.aborted,
+        "do not rediscover a replacement parent after ACP settles",
+      ).toBe(false);
+      expect(getSubagentRunByChildSessionKey("agent:main:subagent:during-acp-wait")).toBeNull();
+    } finally {
+      proceed.resolve();
+      await pending;
+      native.complete();
+      replacement?.complete();
+    }
+  });
+
+  it.each([undefined, "agent:main:main"])(
+    "propagates a zero-child callback failure for requester %s",
+    async (requesterSessionKey) => {
+      const beforeKill = vi.fn(() => {
+        throw new Error("parent cancellation failed");
+      });
+      await expect(
+        stopSubagentsForRequester({ cfg: {}, requesterSessionKey, beforeKill }),
+      ).rejects.toThrow("parent cancellation failed");
+      expect(beforeKill).toHaveBeenCalledOnce();
+      expect(runtimeAbortMocks.abortEmbeddedAgentRun).not.toHaveBeenCalled();
+    },
+  );
+
+  it("fast-abort of an ACP target also aborts the bound source dispatch lane", async () => {
+    const sourceSessionKey = "agent:main:discord:channel:C1";
+    const acpSessionKey = "agent:codex:acp:bound-session";
+    const { root, cfg } = await createAbortConfig({
+      sessionIdsByKey: {
+        [sourceSessionKey]: "source-store-session",
+        [acpSessionKey]: "acp-store-session",
+      },
+    });
+    const sourceOperation = createReplyOperation({
+      sessionKey: sourceSessionKey,
+      sessionId: "source-active-session",
+      resetTriggered: false,
+    });
+    enqueueQueuedFollowupRun({
+      root,
+      cfg,
+      sessionId: "source-active-session",
+      sessionKey: sourceSessionKey,
+    });
+    enqueueQueuedFollowupRun({
+      root,
+      cfg,
+      sessionId: "acp-store-session",
+      sessionKey: acpSessionKey,
+    });
+    bindAcpSessionForTest(acpSessionKey);
+    acpManagerMocks.resolveSession.mockReturnValue({
+      kind: "ready",
+      sessionKey: acpSessionKey,
+      meta: {} as never,
+    });
+
+    const result = await runStopCommand({
+      cfg,
+      sessionKey: sourceSessionKey,
+      from: "discord:C1",
+      to: "discord:C1",
+      targetSessionKey: acpSessionKey,
+      commandSource: "native",
+    });
+
+    expect(result.handled).toBe(true);
+    expect(sourceOperation.result).toEqual({ kind: "aborted", code: "aborted_by_user" });
+    expect(replyRunRegistry.isActive(sourceSessionKey)).toBe(false);
+    expect(getFollowupQueueDepth(sourceSessionKey)).toBe(0);
+    expect(getFollowupQueueDepth(acpSessionKey)).toBe(0);
+    expectSessionLaneCleared(sourceSessionKey);
+    expectSessionLaneCleared(acpSessionKey);
+    expect(acpManagerMocks.cancelSession).toHaveBeenCalledWith({
+      cfg,
+      sessionKey: acpSessionKey,
+      reason: "fast-abort",
+    });
+  });
+
+  it("does not report /stop success after the active backend freezes its outcome", async () => {
+    const sessionKey = "agent:main:telegram:direct:finalizing";
+    const sessionId = "session-finalizing";
+    const { cfg } = await createAbortConfig({
+      sessionIdsByKey: { [sessionKey]: sessionId },
+    });
+    const cancel = vi.fn();
+    const operation = createReplyOperation({
+      sessionKey,
+      sessionId,
+      resetTriggered: false,
+    });
+    operation.attachBackend({
+      kind: "embedded",
+      cancel,
+      isStreaming: () => false,
+      isAbortable: () => false,
+    });
+    operation.setPhase("running");
+    runtimeAbortMocks.abortEmbeddedAgentRun.mockReturnValue(false);
+    runtimeAbortMocks.resolveActiveEmbeddedRunSessionId.mockReturnValue(sessionId);
+    vi.mocked(markSessionAbortTarget).mockClear();
+
+    const result = await runStopCommand({
+      cfg,
+      sessionKey,
+      from: "telegram:finalizing",
+      to: "telegram:finalizing",
+    });
+
+    expect(result).toMatchObject({
+      handled: true,
+      aborted: false,
+      rejectionReason: "finalizing",
+    });
+    expect(operation.result).toBeNull();
+    expect(replyRunRegistry.isActive(sessionKey)).toBe(true);
+    expect(cancel).not.toHaveBeenCalled();
+    expect(markSessionAbortTarget).not.toHaveBeenCalled();
+    expect(getAbortMemory(sessionKey)).toBeUndefined();
+    expect(formatAbortReplyText(undefined, result.rejectionReason)).toBe(
+      "Agent reply is already finalizing and can no longer be aborted.",
+    );
+    expect(formatAbortReplyText(0, undefined, 1)).toBe(
+      "⚙️ Agent was aborted. Cancellation was incomplete for 1 sub-agent. Retry /stop.",
+    );
+    operation.complete();
+  });
+
+  it("fast-abort of an ACP target aborts the source stored session when no source reply operation is registered", async () => {
+    const sourceSessionKey = "agent:main:discord:channel:C2";
+    const acpSessionKey = "agent:codex:acp:bound-session-stored-source";
+    const { root, cfg } = await createAbortConfig({
+      sessionIdsByKey: {
+        [sourceSessionKey]: "source-store-session",
+        [acpSessionKey]: "acp-store-session",
+      },
+    });
+    enqueueQueuedFollowupRun({
+      root,
+      cfg,
+      sessionId: "source-store-session",
+      sessionKey: sourceSessionKey,
+    });
+    enqueueQueuedFollowupRun({
+      root,
+      cfg,
+      sessionId: "acp-store-session",
+      sessionKey: acpSessionKey,
+    });
+    bindAcpSessionForTest(acpSessionKey);
+    acpManagerMocks.resolveSession.mockReturnValue({
+      kind: "ready",
+      sessionKey: acpSessionKey,
+      meta: {} as never,
+    });
+
+    const result = await runStopCommand({
+      cfg,
+      sessionKey: sourceSessionKey,
+      from: "discord:C2",
+      to: "discord:C2",
+      targetSessionKey: acpSessionKey,
+      commandSource: "native",
+    });
+
+    expect(result.handled).toBe(true);
+    expect(runtimeAbortMocks.abortEmbeddedAgentRun).toHaveBeenCalledWith("source-store-session");
+    expect(getFollowupQueueDepth(sourceSessionKey)).toBe(0);
+    expect(getFollowupQueueDepth(acpSessionKey)).toBe(0);
+    expectSessionLaneCleared(sourceSessionKey);
+    expectSessionLaneCleared(acpSessionKey);
+  });
+
+  it("does not abort the caller source lane for an unbound explicit ACP target", async () => {
+    const sourceSessionKey = "agent:main:discord:channel:C3";
+    const acpSessionKey = "agent:codex:acp:unbound-explicit-target";
+    const { cfg } = await createAbortConfig({
+      sessionIdsByKey: {
+        [sourceSessionKey]: "source-store-session",
+        [acpSessionKey]: "acp-store-session",
+      },
+    });
+    const sourceOperation = createReplyOperation({
+      sessionKey: sourceSessionKey,
+      sessionId: "source-active-session",
+      resetTriggered: false,
+    });
+    acpManagerMocks.resolveSession.mockReturnValue({
+      kind: "ready",
+      sessionKey: acpSessionKey,
+      meta: {} as never,
+    });
+
+    const result = await runStopCommand({
+      cfg,
+      sessionKey: sourceSessionKey,
+      from: "discord:C3",
+      to: "discord:C3",
+      targetSessionKey: acpSessionKey,
+      commandSource: "native",
+    });
+
+    expect(result.handled).toBe(true);
+    expect(sourceOperation.result).toBeNull();
+    expect(replyRunRegistry.isActive(sourceSessionKey)).toBe(true);
+    expect(acpManagerMocks.cancelSession).toHaveBeenCalledWith({
+      cfg,
+      sessionKey: acpSessionKey,
+      reason: "fast-abort",
+    });
+    sourceOperation.complete();
+  });
+
+  it("uses ParentSessionKey as the source lane for a bound explicit ACP target", async () => {
+    const sourceSessionKey = "agent:main:discord:channel:C4";
+    const acpSessionKey = "agent:codex:acp:bound-parent-source";
+    const { cfg } = await createAbortConfig({
+      sessionIdsByKey: {
+        [sourceSessionKey]: "source-store-session",
+        [acpSessionKey]: "acp-store-session",
+      },
+    });
+    const sourceOperation = createReplyOperation({
+      sessionKey: sourceSessionKey,
+      sessionId: "source-active-session",
+      resetTriggered: false,
+    });
+    bindAcpSessionForTest(acpSessionKey);
+    acpManagerMocks.resolveSession.mockReturnValue({
+      kind: "ready",
+      sessionKey: acpSessionKey,
+      meta: {} as never,
+    });
+
+    const result = await runStopCommand({
+      cfg,
+      parentSessionKey: sourceSessionKey,
+      from: "discord:C4",
+      to: "discord:C4",
+      targetSessionKey: acpSessionKey,
+      commandSource: "native",
+    });
+
+    expect(result.handled).toBe(true);
+    expect(sourceOperation.result).toEqual({ kind: "aborted", code: "aborted_by_user" });
+    expect(replyRunRegistry.isActive(sourceSessionKey)).toBe(false);
+  });
+
+  it("fast-abort from an ACP-bound source conversation aborts source and bound ACP lanes", async () => {
+    const sourceSessionKey = "agent:main:telegram:direct:source-1";
+    const acpSessionKey = "agent:codex:acp:bound-source-stop";
+    const { root, storePath, cfg } = await createAbortConfig({
+      sessionIdsByKey: {
+        [sourceSessionKey]: "source-store-session",
+        [acpSessionKey]: "acp-store-session",
+      },
+    });
+    const sourceOperation = createReplyOperation({
+      sessionKey: sourceSessionKey,
+      sessionId: "source-active-session",
+      resetTriggered: false,
+    });
+    const acpOperation = createReplyOperation({
+      sessionKey: acpSessionKey,
+      sessionId: "acp-active-session",
+      resetTriggered: false,
+    });
+    enqueueQueuedFollowupRun({
+      root,
+      cfg,
+      sessionId: "source-active-session",
+      sessionKey: sourceSessionKey,
+    });
+    enqueueQueuedFollowupRun({
+      root,
+      cfg,
+      sessionId: "acp-active-session",
+      sessionKey: acpSessionKey,
+    });
+    bindAcpSessionForTest(acpSessionKey);
+    acpManagerMocks.resolveSession.mockReturnValue({
+      kind: "ready",
+      sessionKey: acpSessionKey,
+      meta: {} as never,
+    });
+
+    const result = await runStopCommand({
+      cfg,
+      sessionKey: sourceSessionKey,
+      from: "telegram:source-1",
+      to: "telegram:source-1",
+      messageSid: "77",
+      timestamp: 1234567890000,
+    });
+
+    expect(result.handled).toBe(true);
+    expect(sourceOperation.result).toEqual({ kind: "aborted", code: "aborted_by_user" });
+    expect(acpOperation.result).toEqual({ kind: "aborted", code: "aborted_by_user" });
+    expect(replyRunRegistry.isActive(sourceSessionKey)).toBe(false);
+    expect(replyRunRegistry.isActive(acpSessionKey)).toBe(false);
+    expect(getFollowupQueueDepth(sourceSessionKey)).toBe(0);
+    expect(getFollowupQueueDepth(acpSessionKey)).toBe(0);
+    expectSessionLaneCleared(sourceSessionKey);
+    expectSessionLaneCleared(acpSessionKey);
+    expect(acpManagerMocks.cancelSession).toHaveBeenCalledWith({
+      cfg,
+      sessionKey: acpSessionKey,
+      reason: "fast-abort",
+    });
+    const sourceEntry = readAbortSessionEntry(storePath, sourceSessionKey);
+    const acpEntry = readAbortSessionEntry(storePath, acpSessionKey);
+    expect(sourceEntry?.abortCutoffMessageSid).toBe("77");
+    expect(sourceEntry?.abortCutoffTimestamp).toBe(1234567890000);
+    expect(acpEntry?.abortCutoffMessageSid).toBeUndefined();
+    expect(acpEntry?.abortCutoffTimestamp).toBeUndefined();
+  });
+
+  it("persists abort cutoff metadata on /stop when command and target session match", async () => {
+    const sessionKey = "telegram:123";
+    const sessionId = "session-123";
+    const { storePath, cfg } = await createAbortConfig({
+      sessionIdsByKey: { [sessionKey]: sessionId },
+    });
+
+    const result = await runStopCommand({
+      cfg,
+      sessionKey,
+      from: "telegram:123",
+      to: "telegram:123",
+      messageSid: "55",
+      timestamp: 1234567890000,
+    });
+
+    expect(result.handled).toBe(true);
+    const entry = readAbortSessionEntry(storePath, sessionKey);
+    expect(entry?.abortedLastRun).toBe(true);
+    expect(entry?.abortCutoffMessageSid).toBe("55");
+    expect(entry?.abortCutoffTimestamp).toBe(1234567890000);
+  });
+
+  it("persists abort cutoff metadata when only ParentSessionKey identifies the command session", async () => {
+    const sessionKey = "telegram:parent-only";
+    const sessionId = "session-parent-only";
+    const { storePath, cfg } = await createAbortConfig({
+      sessionIdsByKey: { [sessionKey]: sessionId },
+    });
+
+    const result = await runStopCommand({
+      cfg,
+      parentSessionKey: sessionKey,
+      from: "telegram:parent-only",
+      to: "telegram:parent-only",
+      messageSid: "56",
+      timestamp: 1234567890001,
+    });
+
+    expect(result.handled).toBe(true);
+    const entry = readAbortSessionEntry(storePath, sessionKey);
+    expect(entry?.abortedLastRun).toBe(true);
+    expect(entry?.abortCutoffMessageSid).toBe("56");
+    expect(entry?.abortCutoffTimestamp).toBe(1234567890001);
+  });
+
+  it("does not persist cutoff metadata when native /stop targets a different session", async () => {
+    const slashSessionKey = "telegram:slash:123";
+    const targetSessionKey = "agent:main:telegram:group:123";
+    const targetSessionId = "session-target";
+    const { storePath, cfg } = await createAbortConfig({
+      sessionIdsByKey: { [targetSessionKey]: targetSessionId },
+    });
+
+    const result = await runStopCommand({
+      cfg,
+      sessionKey: slashSessionKey,
+      from: "telegram:123",
+      to: "telegram:123",
+      targetSessionKey,
+      messageSid: "999",
+      timestamp: 1234567890000,
+    });
+
+    expect(result.handled).toBe(true);
+    const entry = readAbortSessionEntry(storePath, targetSessionKey);
+    expect(entry?.abortedLastRun).toBe(true);
+    expect(entry?.abortCutoffMessageSid).toBeUndefined();
+    expect(entry?.abortCutoffTimestamp).toBeUndefined();
+  });
+
+  it("fast-abort stops active subagent runs for requester session", async () => {
+    const sessionKey = "telegram:parent";
+    const childKey = "agent:main:subagent:child-1";
+    const sessionId = "session-parent";
+    const childSessionId = "session-child";
+    const { cfg } = await createAbortConfig({
+      sessionIdsByKey: {
+        [sessionKey]: sessionId,
+        [childKey]: childSessionId,
+      },
+    });
+
+    addSubagentFixture({
+      runId: "run-1",
+      childSessionKey: childKey,
+      requesterSessionKey: sessionKey,
+      requesterDisplayKey: "telegram:parent",
+      task: "do work",
+      cleanup: "keep",
+      createdAt: Date.now(),
+    });
+
+    const result = await runStopCommand({
+      cfg,
+      sessionKey,
+      from: "telegram:parent",
+      to: "telegram:parent",
+    });
+
+    expect(result.stoppedSubagents).toBe(1);
+    expectSessionLaneCleared(childKey);
+  });
+
+  it("continues stopping siblings when one termination persistence write fails", async () => {
+    const sessionKey = "telegram:persistence-failure-parent";
+    const firstChildKey = "agent:main:subagent:persistence-failure-first";
+    const secondChildKey = "agent:main:subagent:persistence-failure-second";
+    const run = (runId: string, childSessionKey: string): SubagentRunFixture => ({
+      runId,
+      childSessionKey,
+      requesterSessionKey: sessionKey,
+      requesterDisplayKey: sessionKey,
+      task: "stop despite persistence failure",
+      cleanup: "keep",
+      createdAt: Date.now(),
+    });
+    for (const fixture of [
+      run("run-persistence-failure-first", firstChildKey),
+      run("run-persistence-failure-second", secondChildKey),
+    ]) {
+      addSubagentFixture(fixture);
+    }
+    let failedTombstone = false;
+    subagentRegistryTesting.setDepsForTest({
+      persistSubagentRunsToDiskOrThrow: (runs, changedRunIds) => {
+        const first = runs.get("run-persistence-failure-first");
+        if (
+          !failedTombstone &&
+          changedRunIds?.includes("run-persistence-failure-first") &&
+          first?.execution.status === "terminal" &&
+          first.endedReason === "subagent-killed"
+        ) {
+          failedTombstone = true;
+          throw new Error("sqlite busy");
+        }
+      },
+    });
+
+    await expect(
+      stopSubagentsForRequester({
+        cfg: {} as OpenClawConfig,
+        requesterSessionKey: sessionKey,
+      }),
+    ).resolves.toEqual({ stopped: 1, failed: 1 });
+    expect(failedTombstone).toBe(true);
+    expect(getSubagentRunByChildSessionKey(firstChildKey)?.killIntent).toBeDefined();
+    expect(getSubagentRunByChildSessionKey(secondChildKey)?.endedReason).toBe("subagent-killed");
+    expectSessionLaneCleared(firstChildKey);
+    expectSessionLaneCleared(secondChildKey);
+  });
+
+  it("cascade stop kills depth-2 children when stopping depth-1 agent", async () => {
+    const sessionKey = "telegram:parent";
+    const depth1Key = "agent:main:subagent:child-1";
+    const depth2Key = "agent:main:subagent:child-1:subagent:grandchild-1";
+    const sessionId = "session-parent";
+    const depth1SessionId = "session-child";
+    const depth2SessionId = "session-grandchild";
+    const { cfg } = await createAbortConfig({
+      sessionIdsByKey: {
+        [sessionKey]: sessionId,
+        [depth1Key]: depth1SessionId,
+        [depth2Key]: depth2SessionId,
+      },
+    });
+
+    addSubagentFixture({
+      runId: "run-1",
+      childSessionKey: depth1Key,
+      requesterSessionKey: sessionKey,
+      requesterDisplayKey: "telegram:parent",
+      task: "orchestrator",
+      cleanup: "keep",
+      createdAt: Date.now(),
+    });
+    addSubagentFixture({
+      runId: "run-2",
+      childSessionKey: depth2Key,
+      requesterSessionKey: depth1Key,
+      requesterDisplayKey: depth1Key,
+      task: "leaf worker",
+      cleanup: "keep",
+      createdAt: Date.now(),
+    });
+
+    const result = await runStopCommand({
+      cfg,
+      sessionKey,
+      from: "telegram:parent",
+      to: "telegram:parent",
+    });
+
+    // Should stop both depth-1 and depth-2 agents (cascade)
+    expect(result.stoppedSubagents).toBe(2);
+    expectSessionLaneCleared(depth1Key);
+    expectSessionLaneCleared(depth2Key);
+  });
+
+  it("stops a subagent that is paused after yielding", async () => {
+    const sessionKey = "telegram:yield-parent";
+    const childKey = "agent:main:subagent:yield-child";
+    const now = Date.now();
+    addSubagentFixture({
+      runId: "run-yield-child",
+      childSessionKey: childKey,
+      requesterSessionKey: sessionKey,
+      requesterDisplayKey: sessionKey,
+      task: "paused worker",
+      cleanup: "keep",
+      createdAt: now - 1_000,
+      endedAt: now - 500,
+      pauseReason: "sessions_yield",
+    });
+
+    const result = await stopSubagentsForRequester({
+      cfg: {} as OpenClawConfig,
+      requesterSessionKey: sessionKey,
+    });
+
+    expect(result).toEqual({ stopped: 1, failed: 0 });
+    expectSessionLaneCleared(childKey);
+    expect(getSubagentRunByChildSessionKey(childKey)).toMatchObject({
+      endedReason: "subagent-killed",
+      killReconciliation: { suppressTaskDelivery: true },
+    });
+  });
+
+  it("cascade stop traverses ended depth-1 parents to stop active depth-2 children", async () => {
+    const sessionKey = "telegram:parent";
+    const depth1Key = "agent:main:subagent:child-ended";
+    const depth2Key = "agent:main:subagent:child-ended:subagent:grandchild-active";
+    const now = Date.now();
+    const { cfg } = await createAbortConfig({
+      nowMs: now,
+      sessionIdsByKey: {
+        [sessionKey]: "session-parent",
+        [depth1Key]: "session-child-ended",
+        [depth2Key]: "session-grandchild-active",
+      },
+    });
+
+    addSubagentFixture({
+      runId: "run-1",
+      childSessionKey: depth1Key,
+      requesterSessionKey: sessionKey,
+      requesterDisplayKey: "telegram:parent",
+      task: "orchestrator",
+      cleanup: "keep",
+      createdAt: now - 1_000,
+      endedAt: now - 500,
+      outcome: { status: "ok" },
+    });
+    addSubagentFixture({
+      runId: "run-2",
+      childSessionKey: depth2Key,
+      requesterSessionKey: depth1Key,
+      requesterDisplayKey: depth1Key,
+      task: "leaf worker",
+      cleanup: "keep",
+      createdAt: now - 500,
+    });
+
+    const result = await runStopCommand({
+      cfg,
+      sessionKey,
+      from: "telegram:parent",
+      to: "telegram:parent",
+    });
+
+    // Should skip killing the ended depth-1 run itself, but still kill depth-2.
+    expect(result.stoppedSubagents).toBe(1);
+    expectSessionLaneCleared(depth2Key);
+    expect(getSubagentRunByChildSessionKey(depth1Key)?.endedReason).not.toBe("subagent-killed");
+    expect(getSubagentRunByChildSessionKey(depth2Key)?.endedReason).toBe("subagent-killed");
+  });
+
+  it("cascade stop still traverses an ended current parent when a stale older active row exists", async () => {
+    const sessionKey = "telegram:parent";
+    const depth1Key = "agent:main:subagent:child-ended-stale";
+    const depth2Key = "agent:main:subagent:child-ended-stale:subagent:grandchild-active";
+    const now = Date.now();
+    const { cfg } = await createAbortConfig({
+      nowMs: now,
+      sessionIdsByKey: {
+        [sessionKey]: "session-parent",
+        [depth1Key]: "session-child-ended-stale",
+        [depth2Key]: "session-grandchild-active",
+      },
+    });
+
+    for (const fixture of [
+      {
+        runId: "run-stale-parent",
+        childSessionKey: depth1Key,
+        requesterSessionKey: sessionKey,
+        requesterDisplayKey: "telegram:parent",
+        task: "stale orchestrator",
+        cleanup: "keep",
+        createdAt: now - 2_000,
+        startedAt: now - 1_900,
+      },
+      {
+        runId: "run-current-parent",
+        childSessionKey: depth1Key,
+        requesterSessionKey: sessionKey,
+        requesterDisplayKey: "telegram:parent",
+        task: "current orchestrator",
+        cleanup: "keep",
+        createdAt: now - 1_000,
+        startedAt: now - 900,
+        endedAt: now - 500,
+        outcome: { status: "ok" },
+      },
+    ] satisfies SubagentRunFixture[]) {
+      addSubagentFixture(fixture);
+    }
+    addSubagentFixture({
+      runId: "run-active-child",
+      childSessionKey: depth2Key,
+      requesterSessionKey: depth1Key,
+      requesterDisplayKey: depth1Key,
+      task: "leaf worker",
+      cleanup: "keep",
+      createdAt: now - 400,
+    });
+
+    const result = await runStopCommand({
+      cfg,
+      sessionKey,
+      from: "telegram:parent",
+      to: "telegram:parent",
+    });
+
+    expect(result.stoppedSubagents).toBe(1);
+    expectSessionLaneCleared(depth2Key);
+    expect(getSubagentRunByChildSessionKey(depth1Key)?.endedReason).not.toBe("subagent-killed");
+    expect(getSubagentRunByChildSessionKey(depth2Key)?.endedReason).toBe("subagent-killed");
+  });
+
+  it("stopSubagentsForRequester does not traverse a child that moved to a newer parent", async () => {
+    const oldParentKey = "agent:main:subagent:old-parent";
+    const newParentKey = "agent:main:subagent:new-parent";
+    const childKey = "agent:main:subagent:shared-child";
+    const leafKey = `${childKey}:subagent:leaf`;
+    const now = Date.now();
+
+    addSubagentFixture({
+      runId: "run-shared-child-stale-parent",
+      childSessionKey: childKey,
+      requesterSessionKey: oldParentKey,
+      controllerSessionKey: oldParentKey,
+      requesterDisplayKey: oldParentKey,
+      task: "shared child stale parent",
+      cleanup: "keep",
+      createdAt: now - 2_000,
+      endedAt: now - 1_000,
+      outcome: { status: "ok" },
+    });
+    addSubagentFixture({
+      runId: "run-leaf-active",
+      childSessionKey: leafKey,
+      requesterSessionKey: childKey,
+      controllerSessionKey: childKey,
+      requesterDisplayKey: childKey,
+      task: "leaf worker",
+      cleanup: "keep",
+      createdAt: now - 500,
+    });
+    addSubagentFixture({
+      runId: "run-shared-child-current-parent",
+      childSessionKey: childKey,
+      requesterSessionKey: newParentKey,
+      controllerSessionKey: newParentKey,
+      requesterDisplayKey: newParentKey,
+      task: "shared child current parent",
+      cleanup: "keep",
+      createdAt: now - 250,
+    });
+
+    const result = await stopSubagentsForRequester({
+      cfg: {} as OpenClawConfig,
+      requesterSessionKey: oldParentKey,
+    });
+
+    expect(result).toEqual({ stopped: 0, failed: 0 });
+    expect(getSubagentRunByChildSessionKey(childKey)?.execution.endedAt).toBeUndefined();
+    expect(getSubagentRunByChildSessionKey(leafKey)?.execution.endedAt).toBeUndefined();
+  });
+});
+/* oxlint-disable max-lines -- TODO: split this grandfathered oversized file. */

src/auto-reply/reply/abort.ts

@@ -0,0 +1,86 @@
+// Recognizes stop requests before loading active-run cancellation machinery.
+import {
+  normalizeOptionalLowercaseString,
+  normalizeOptionalString,
+} from "@openclaw/normalization-core/string-coerce";
+import { resolveSessionAgentId } from "../../agents/agent-scope.js";
+import type { OpenClawConfig } from "../../config/types.openclaw.js";
+import type { FinalizedRuntimeMsgContext } from "../templating.js";
+import { isAbortRequestText } from "./abort-primitives.js";
+import { stripMentions, stripStructuralPrefixes } from "./mentions.js";
+
+export type FastAbortRequestParams = {
+  ctx: FinalizedRuntimeMsgContext;
+  cfg: OpenClawConfig;
+  isCommandTargetCurrent?: () => boolean;
+};
+
+export type FastAbortResult = {
+  handled: boolean;
+  aborted: boolean;
+  rejectionReason?: "finalizing";
+  stoppedSubagents?: number;
+  failedSubagents?: number;
+};
+
+export function formatAbortReplyText(
+  stoppedSubagents?: number,
+  rejectionReason?: "finalizing",
+  failedSubagents?: number,
+): string {
+  const failureSuffix =
+    typeof failedSubagents === "number" && failedSubagents > 0
+      ? ` Cancellation was incomplete for ${failedSubagents} sub-agent${failedSubagents === 1 ? "" : "s"}. Retry /stop.`
+      : "";
+  if (rejectionReason === "finalizing") {
+    const base = "Agent reply is already finalizing and can no longer be aborted.";
+    if (typeof stoppedSubagents !== "number" || stoppedSubagents <= 0) {
+      return `${base}${failureSuffix}`;
+    }
+    const label = stoppedSubagents === 1 ? "sub-agent" : "sub-agents";
+    return `${base} Stopped ${stoppedSubagents} ${label}.${failureSuffix}`;
+  }
+  if (typeof stoppedSubagents !== "number" || stoppedSubagents <= 0) {
+    return `⚙️ Agent was aborted.${failureSuffix}`;
+  }
+  const label = stoppedSubagents === 1 ? "sub-agent" : "sub-agents";
+  return `⚙️ Agent was aborted. Stopped ${stoppedSubagents} ${label}.${failureSuffix}`;
+}
+
+/** Normalize ingress once; current authorization belongs to the loaded operation. */
+function resolveFastAbortRequest(params: FastAbortRequestParams) {
+  const { ctx, cfg } = params;
+  const commandSessionKey =
+    normalizeOptionalString(ctx.SessionKey) ?? normalizeOptionalString(ctx.ParentSessionKey);
+  const targetKey = normalizeOptionalString(ctx.CommandTargetSessionKey) ?? commandSessionKey;
+  const resolveTargetAgentId = () =>
+    resolveSessionAgentId({
+      sessionKey: targetKey ?? ctx.SessionKey ?? "",
+      config: cfg,
+      fallbackAgentId: ctx.AgentId,
+    });
+  const raw = stripStructuralPrefixes(ctx.commandText);
+  const isGroup = normalizeOptionalLowercaseString(ctx.ChatType) === "group";
+  const stripped = isGroup ? stripMentions(raw, ctx, cfg, resolveTargetAgentId()) : raw;
+  const abortRequested = isAbortRequestText(stripped);
+  if (!abortRequested) {
+    return undefined;
+  }
+
+  return { commandSessionKey, targetKey, resolveTargetAgentId };
+}
+
+export type PreparedFastAbortRequest = NonNullable<ReturnType<typeof resolveFastAbortRequest>>;
+
+export async function tryFastAbortFromMessage(
+  params: FastAbortRequestParams,
+): Promise<FastAbortResult> {
+  const request = resolveFastAbortRequest(params);
+  if (!request) {
+    return { handled: false, aborted: false };
+  }
+  // Normalized ingress is not authority. The operation resolves authorization
+  // and retains current-target validation after loading cancellation machinery.
+  const { executeFastAbortRequest } = await import("./abort-operation.js");
+  return executeFastAbortRequest(params, request);
+}

src/auto-reply/reply/acp-elicitation-handler-lazy.ts

@@ -0,0 +1,15 @@
+import type { AcpElicitationHandler } from "@openclaw/acp-core/runtime/types";
+import type { AcpElicitationHandlerParams } from "./acp-elicitation-handler.js";
+
+/** Defers the structured-input stack while preserving one exact handler per turn. */
+export function createLazyAcpElicitationHandler(
+  params: AcpElicitationHandlerParams,
+): AcpElicitationHandler {
+  let handler: Promise<AcpElicitationHandler> | undefined;
+  return async (request, context) => {
+    handler ??= import("./acp-elicitation-handler.js").then(({ createAcpElicitationHandler }) =>
+      createAcpElicitationHandler(params),
+    );
+    return (await handler)(request, context);
+  };
+}

src/auto-reply/reply/acp-elicitation-handler.test.ts

@@ -0,0 +1,240 @@
+import type { AcpElicitationRequest } from "@openclaw/acp-core/runtime/types";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { claimPendingAgentQuestionAnswer } from "../../agents/harness/gateway-question.js";
+
+const gatewayCallMock = vi.hoisted(() => vi.fn());
+
+vi.mock("../../agents/tools/gateway.js", () => ({ callGatewayTool: gatewayCallMock }));
+
+import { createAcpElicitationHandler } from "./acp-elicitation-handler.js";
+
+type GatewayQuestion = { questionId: string; options?: Array<{ label: string }> };
+type GatewayRequest = {
+  id: string;
+  questions: GatewayQuestion[];
+  sessionKey?: string;
+  runId?: string;
+};
+
+function formRequest(
+  properties: Record<string, unknown>,
+  required: string[] = [],
+): AcpElicitationRequest {
+  return {
+    mode: "form",
+    sessionId: "acp-session",
+    toolCallId: "tool-call",
+    message: "ACP needs input",
+    requestedSchema: { type: "object", properties, required },
+  } as AcpElicitationRequest;
+}
+
+function urlRequest(overrides: Partial<Record<string, unknown>> = {}): AcpElicitationRequest {
+  return {
+    mode: "url",
+    sessionId: "acp-session",
+    toolCallId: "tool-call",
+    message: "Authenticate",
+    elicitationId: "login-1",
+    url: "https://example.com/login",
+    ...overrides,
+  } as AcpElicitationRequest;
+}
+
+function createFixture() {
+  const delivered: string[] = [];
+  let active = true;
+  const handler = createAcpElicitationHandler({
+    sourceSessionKey: "agent:main:source",
+    targetSessionKey: "agent:codex:acp:target",
+    outerRequestId: "outer-turn",
+    agentId: "main",
+    runId: "run-1",
+    delivery: {
+      deliver: vi.fn(async (_kind, payload) => {
+        if (payload.text) {
+          delivered.push(payload.text);
+        }
+        return true;
+      }),
+    },
+    isActive: () => active,
+  });
+  return {
+    delivered,
+    handler,
+    deactivate: () => {
+      active = false;
+    },
+  };
+}
+
+function answerGateway(
+  answer: (questions: GatewayQuestion[]) => Record<string, string[]>,
+): GatewayRequest[] {
+  const requests = new Map<string, GatewayRequest>();
+  const ordered: GatewayRequest[] = [];
+  gatewayCallMock.mockImplementation(async (method: string, _opts: unknown, rawParams: unknown) => {
+    const params = rawParams as GatewayRequest;
+    if (method === "question.request") {
+      requests.set(params.id, params);
+      ordered.push(params);
+      return { id: params.id };
+    }
+    if (method === "question.waitAnswer") {
+      const request = requests.get(params.id);
+      if (!request) {
+        throw new Error("missing question registration");
+      }
+      return { status: "answered", answers: { answers: answer(request.questions) } };
+    }
+    if (method === "question.resolve") {
+      return { status: "cancelled" };
+    }
+    throw new Error(`unexpected gateway method ${method}`);
+  });
+  return ordered;
+}
+
+describe("ACP elicitation delivery", () => {
+  beforeEach(() => {
+    gatewayCallMock.mockReset();
+  });
+
+  it("rejects accessor-backed request objects without invoking the accessor", async () => {
+    let reads = 0;
+    const request = Object.defineProperty(
+      {
+        mode: "form",
+        sessionId: "acp-session",
+        message: "Input",
+      },
+      "requestedSchema",
+      {
+        enumerable: true,
+        get() {
+          reads += 1;
+          return { type: "object", properties: { value: { type: "string" } } };
+        },
+      },
+    ) as AcpElicitationRequest;
+    const { delivered, handler } = createFixture();
+
+    const response = await handler(request, {
+      requestId: "accessor",
+      signal: new AbortController().signal,
+    });
+
+    expect(response.action).toBe("decline");
+    expect(reads).toBe(0);
+    expect(delivered.join("\n")).toContain("malformed");
+  });
+
+  it("uses outer, scope, session, and tool-call correlation in Gateway records", async () => {
+    const requests = answerGateway((questions) => ({ [questions[0]!.questionId]: ["Continue"] }));
+    const { handler } = createFixture();
+
+    await handler(urlRequest(), {
+      requestId: 1,
+      signal: new AbortController().signal,
+    });
+    await handler(
+      {
+        mode: "url",
+        requestId: "auth-request",
+        message: "Authenticate",
+        elicitationId: "login-2",
+        url: "https://example.com/login",
+      },
+      { requestId: 2, signal: new AbortController().signal },
+    );
+
+    expect(requests).toHaveLength(2);
+    expect(requests[0]?.id).toMatch(/^acp_[a-f0-9]{24}_0$/u);
+    expect(requests[1]?.id).toMatch(/^acp_[a-f0-9]{24}_0$/u);
+    expect(requests[0]?.id).not.toBe(requests[1]?.id);
+    expect(requests[0]).toMatchObject({
+      sessionKey: "agent:codex:acp:target",
+      runId: "run-1",
+    });
+  });
+
+  it("cancels an aborted request and rejects a late Gateway answer", async () => {
+    let registered = false;
+    gatewayCallMock.mockImplementation(
+      async (
+        method: string,
+        _opts: unknown,
+        rawParams: unknown,
+        extra?: { signal?: AbortSignal },
+      ) => {
+        if (method === "question.request") {
+          registered = true;
+          return { id: (rawParams as { id: string }).id };
+        }
+        if (method === "question.waitAnswer") {
+          return await new Promise((_, reject) => {
+            extra?.signal?.addEventListener("abort", () => reject(new Error("late answer")), {
+              once: true,
+            });
+          });
+        }
+        return { status: "cancelled" };
+      },
+    );
+    const controller = new AbortController();
+    const { handler } = createFixture();
+    const response = handler(urlRequest(), { requestId: "abort", signal: controller.signal });
+    await vi.waitFor(() => expect(registered).toBe(true));
+
+    controller.abort();
+
+    await expect(response).resolves.toMatchObject({ action: "cancel" });
+  });
+
+  it("keeps explicitly marked Codex secrets out of Gateway question records", async () => {
+    gatewayCallMock.mockRejectedValue(new Error("secret must not reach Gateway questions"));
+    const { delivered, handler } = createFixture();
+    const response = handler(
+      formRequest(
+        {
+          token: {
+            type: "string",
+            title: "Token",
+            _meta: { codex: { isSecret: true } },
+          },
+        },
+        ["token"],
+      ),
+      { requestId: "secret", signal: new AbortController().signal },
+    );
+    await vi.waitFor(() => expect(delivered.join("\n")).toContain("may show your reply"));
+
+    await expect(
+      claimPendingAgentQuestionAnswer({
+        sessionKey: "agent:codex:acp:target",
+        text: "private-value",
+      }),
+    ).resolves.toBe(true);
+
+    await expect(response).resolves.toEqual({
+      action: "accept",
+      content: { token: "private-value" },
+    });
+    expect(gatewayCallMock).not.toHaveBeenCalled();
+  });
+
+  it("accepts an ACP form elicitation with an empty schema instead of declining it", async () => {
+    const { handler } = createFixture();
+
+    const response = handler(formRequest({}), {
+      requestId: "empty-form",
+      signal: new AbortController().signal,
+    });
+
+    await expect(response).resolves.toEqual({
+      action: "accept",
+      content: {},
+    });
+  });
+});

src/auto-reply/reply/acp-elicitation-handler.ts

@@ -0,0 +1,110 @@
+import { createHash } from "node:crypto";
+import type {
+  AcpElicitationHandler,
+  AcpElicitationResponse,
+  AcpJsonRpcId,
+} from "@openclaw/acp-core/runtime/types";
+import { runStructuredInput } from "../../agents/harness/structured-input-execution.js";
+import type { ReplyPayload } from "../types.js";
+import { parseAcpElicitationRequest } from "./acp-elicitation.js";
+
+const DEFAULT_ELICITATION_TIMEOUT_MS = 15 * 60_000;
+const MAX_REQUEST_ID_TEXT = 128;
+
+type AcpElicitationDelivery = {
+  deliver: (kind: "block", payload: ReplyPayload) => Promise<boolean>;
+};
+
+export type AcpElicitationHandlerParams = {
+  sourceSessionKey: string;
+  targetSessionKey: string;
+  outerRequestId: string;
+  agentId: string;
+  runId: string;
+  delivery: AcpElicitationDelivery;
+  isActive: () => boolean;
+};
+
+function questionId(params: {
+  contextRequestId: AcpJsonRpcId;
+  correlation: unknown;
+  sourceSessionKey: string;
+  targetSessionKey: string;
+  outerRequestId: string;
+  batch: number;
+}): string {
+  const digest = createHash("sha256").update(JSON.stringify(params)).digest("hex").slice(0, 24);
+  return `acp_${digest}_${params.batch}`;
+}
+
+function cancellation(message: string): AcpElicitationResponse {
+  return { action: "cancel", _meta: { message } };
+}
+
+function decline(message?: string): AcpElicitationResponse {
+  return { action: "decline", ...(message ? { _meta: { message } } : {}) };
+}
+
+function isContextRequestIdValid(value: AcpJsonRpcId): boolean {
+  return (
+    value === null ||
+    (typeof value === "number" && Number.isFinite(value)) ||
+    (typeof value === "string" && value.length > 0 && value.length <= MAX_REQUEST_ID_TEXT)
+  );
+}
+
+/** Creates the turn-owned ACP form/URL bridge used by channel delivery. */
+export function createAcpElicitationHandler(
+  params: AcpElicitationHandlerParams,
+): AcpElicitationHandler {
+  const delivery = {
+    onBlockReply: async (payload: ReplyPayload) => {
+      await params.delivery.deliver("block", payload);
+    },
+  };
+  return async (request, context) => {
+    if (
+      !isContextRequestIdValid(context.requestId) ||
+      context.signal.aborted ||
+      !params.isActive()
+    ) {
+      return cancellation("ACP input request is no longer active.");
+    }
+    const parsed = parseAcpElicitationRequest(request);
+    const result = await runStructuredInput({
+      input: parsed.input,
+      sessionKey: params.targetSessionKey,
+      agentId: params.agentId,
+      runId: params.runId,
+      timeoutMs: DEFAULT_ELICITATION_TIMEOUT_MS,
+      delivery,
+      signal: context.signal,
+      isActive: params.isActive,
+      questionId: (batch) =>
+        questionId({
+          contextRequestId: context.requestId,
+          correlation: parsed.correlation,
+          sourceSessionKey: params.sourceSessionKey,
+          targetSessionKey: params.targetSessionKey,
+          outerRequestId: params.outerRequestId,
+          batch,
+        }),
+      promptOptions: {
+        unsupportedIntro: "ACP input request could not be shown:",
+        urlIntro: "ACP needs confirmation:",
+      },
+    });
+    if (result.status === "answered") {
+      return parsed.input.kind === "ready" && parsed.input.plan.kind === "url"
+        ? { action: "accept" }
+        : { action: "accept", content: result.content };
+    }
+    if (result.status === "declined") {
+      return decline(result.message);
+    }
+    if (result.status === "unsupported") {
+      return decline(result.message);
+    }
+    return cancellation(result.message ?? "ACP input request was cancelled.");
+  };
+}

src/auto-reply/reply/acp-elicitation.ts

@@ -0,0 +1,136 @@
+import type { AcpElicitationRequest } from "@openclaw/acp-core/runtime/types";
+import {
+  compileStructuredInputForm,
+  compileStructuredInputUrl,
+  isStructuredInputRecord,
+  snapshotStructuredInput,
+  type StructuredInputCompileResult,
+  type StructuredInputRecord,
+  type StructuredInputValue,
+} from "../../agents/harness/structured-input.js";
+
+const MAX_CORRELATION_TEXT = 128;
+
+type ParsedAcpElicitationRequest = {
+  input: StructuredInputCompileResult;
+  correlation?:
+    | { sessionId: string; toolCallId?: string | null }
+    | { requestId: string | number | null };
+};
+
+/** Adapts ACP wire scope and codex-acp metadata into the shared structured-input compiler. */
+export function parseAcpElicitationRequest(
+  request: AcpElicitationRequest,
+): ParsedAcpElicitationRequest {
+  const snapshot = snapshotStructuredInput(request);
+  if (!isStructuredInputRecord(snapshot)) {
+    return unsupported("OpenClaw declined a malformed or over-limit ACP input request.");
+  }
+  const correlation = readScope(snapshot);
+  if (typeof correlation === "string") {
+    return unsupported(correlation);
+  }
+  const mode = readAcpElicitationString(snapshot, "mode");
+  if (mode === "url") {
+    return {
+      correlation,
+      input: compileStructuredInputUrl({
+        url: readValue(snapshot, "url"),
+        elicitationId: readValue(snapshot, "elicitationId"),
+        message: readValue(snapshot, "message"),
+        fallbackMessage: "ACP provided a URL",
+        protocolName: "ACP",
+      }),
+    };
+  }
+  if (mode !== "form") {
+    return unsupported(
+      `OpenClaw does not support ACP elicitation mode ${JSON.stringify(mode ?? "unknown")}.`,
+    );
+  }
+  return {
+    correlation,
+    input: compileStructuredInputForm({
+      schema: readValue(snapshot, "requestedSchema"),
+      message: readAcpElicitationString(snapshot, "message"),
+      fallbackMessage: "ACP needs input",
+      options: {
+        protocolName: "ACP",
+        allowEmptyForm: true,
+        minimumChoiceCount: 2,
+        booleanLabels: ["True", "False"],
+        metadata: {
+          secretPath: ["_meta", "codex", "isSecret"],
+          otherAnswerPath: ["_meta", "codex", "isOtherAnswer"],
+          otherQuestionIdPath: ["_meta", "codex", "questionId"],
+        },
+      },
+    }),
+  };
+}
+
+function readScope(
+  request: StructuredInputRecord,
+): ParsedAcpElicitationRequest["correlation"] | string {
+  const sessionId = readValue(request, "sessionId");
+  const requestId = readValue(request, "requestId");
+  const hasSession = sessionId !== undefined;
+  const hasRequest = requestId !== undefined;
+  if (hasSession === hasRequest) {
+    return "OpenClaw declined an ACP input request with an invalid or ambiguous scope.";
+  }
+  if (hasSession) {
+    const normalizedSessionId = readCorrelationText(sessionId);
+    if (!normalizedSessionId) {
+      return "OpenClaw declined an ACP input request with an invalid session id.";
+    }
+    const toolCallId = readValue(request, "toolCallId");
+    const normalizedToolCallId =
+      toolCallId === undefined || toolCallId === null
+        ? toolCallId
+        : readCorrelationText(toolCallId);
+    if (toolCallId !== undefined && toolCallId !== null && !normalizedToolCallId) {
+      return "OpenClaw declined an ACP input request with an invalid tool-call id.";
+    }
+    return {
+      sessionId: normalizedSessionId,
+      ...(toolCallId === undefined ? {} : { toolCallId: normalizedToolCallId ?? null }),
+    };
+  }
+  if (requestId === null) {
+    return { requestId };
+  }
+  if (typeof requestId === "number") {
+    return { requestId };
+  }
+  const normalizedRequestId = readCorrelationText(requestId);
+  return normalizedRequestId
+    ? { requestId: normalizedRequestId }
+    : "OpenClaw declined an ACP input request with an invalid request scope.";
+}
+
+function readCorrelationText(value: unknown): string | undefined {
+  if (typeof value !== "string" || value.length === 0 || value.length > MAX_CORRELATION_TEXT) {
+    return undefined;
+  }
+  for (const character of value) {
+    const codePoint = character.codePointAt(0) ?? 0;
+    if (codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f)) {
+      return undefined;
+    }
+  }
+  return value;
+}
+
+function readValue(record: StructuredInputRecord, key: string): StructuredInputValue | undefined {
+  return Object.hasOwn(record, key) ? record[key] : undefined;
+}
+
+function readAcpElicitationString(record: StructuredInputRecord, key: string): string | undefined {
+  const value = readValue(record, key);
+  return typeof value === "string" ? value : undefined;
+}
+
+function unsupported(message: string): ParsedAcpElicitationRequest {
+  return { input: { kind: "unsupported", message } };
+}

src/auto-reply/reply/acp-projector.test.ts

@@ -0,0 +1,688 @@
+// Tests ACP event projection into session updates and reply payloads.
+import { describe, expect, it, vi } from "vitest";
+import { prefixSystemMessage } from "../../infra/system-message.js";
+import { createAcpReplyProjector } from "./acp-projector.js";
+import { createAcpTestConfig as createCfg } from "./test-fixtures/acp-runtime.js";
+
+type Delivery = { kind: string; text?: string };
+
+function countMatching<T>(items: readonly T[], predicate: (item: T) => boolean): number {
+  let count = 0;
+  for (const item of items) {
+    if (predicate(item)) {
+      count += 1;
+    }
+  }
+  return count;
+}
+
+function createProjectorHarness(
+  cfgOverrides?: Parameters<typeof createCfg>[0],
+  opts?: {
+    onProgress?: () => void;
+    shouldSendToolSummaries?: boolean;
+    shouldSendToolSummariesNow?: () => boolean;
+    shouldSendFullToolDetails?: boolean;
+    getConversationContext?: () => string | undefined;
+  },
+) {
+  const deliveries: Delivery[] = [];
+  const projector = createAcpReplyProjector({
+    cfg: createCfg(cfgOverrides),
+    shouldSendToolSummaries: opts?.shouldSendToolSummaries ?? true,
+    shouldSendToolSummariesNow: opts?.shouldSendToolSummariesNow,
+    shouldSendFullToolDetails: opts?.shouldSendFullToolDetails ?? false,
+    deliver: async (kind, payload) => {
+      deliveries.push({ kind, text: payload.text });
+      return true;
+    },
+    getConversationContext: opts?.getConversationContext,
+    onProgress: opts?.onProgress,
+  });
+  return { deliveries, projector };
+}
+
+function createStreamHarness(
+  deliveryMode: "live" | "final_only",
+  streamOverrides: Record<string, unknown> = {},
+  opts?: Parameters<typeof createProjectorHarness>[1],
+) {
+  return createProjectorHarness(
+    {
+      acp: { enabled: true, stream: { deliveryMode, ...streamOverrides } },
+    } as Parameters<typeof createCfg>[0],
+    opts,
+  );
+}
+
+function blockDeliveries(deliveries: Delivery[]) {
+  return deliveries.filter((entry) => entry.kind === "block");
+}
+
+function combinedBlockText(deliveries: Delivery[]) {
+  return blockDeliveries(deliveries)
+    .map((entry) => entry.text ?? "")
+    .join("");
+}
+
+function expectToolCallSummary(delivery: Delivery | undefined) {
+  expect(delivery?.kind).toBe("tool");
+  expect(delivery?.text).toContain("Tool Call");
+}
+
+const statusAndToolTagVisibility = { available_commands_update: true, tool_call: true };
+
+function createFinalOnlyStatusToolHarness(opts?: Parameters<typeof createProjectorHarness>[1]) {
+  return createStreamHarness("final_only", { tagVisibility: statusAndToolTagVisibility }, opts);
+}
+
+function createLiveToolLifecycleHarness(params?: {
+  repeatSuppression?: boolean;
+  includeStatus?: boolean;
+}) {
+  const { includeStatus = false, ...streamOverrides } = params ?? {};
+  return createStreamHarness("live", {
+    ...streamOverrides,
+    tagVisibility: {
+      ...(includeStatus ? { available_commands_update: true } : {}),
+      tool_call: true,
+      tool_call_update: true,
+    },
+  });
+}
+
+type Projector = ReturnType<typeof createProjectorHarness>["projector"];
+type ProjectorEvent = Parameters<Projector["onEvent"]>[0];
+type EventOf<T extends ProjectorEvent["type"]> = Extract<ProjectorEvent, { type: T }>;
+
+function emitText(
+  projector: Projector,
+  text: string,
+  overrides: Partial<Omit<EventOf<"text_delta">, "type" | "text">> = {},
+) {
+  return projector.onEvent({ type: "text_delta", text, tag: "agent_message_chunk", ...overrides });
+}
+
+function emitStatus(
+  projector: Projector,
+  text: string,
+  tag: EventOf<"status">["tag"],
+  overrides: Partial<Omit<EventOf<"status">, "type" | "text" | "tag">> = {},
+) {
+  return projector.onEvent({ type: "status", text, tag, ...overrides });
+}
+
+function emitTool(projector: Projector, event: Omit<EventOf<"tool_call">, "type">) {
+  return projector.onEvent({ type: "tool_call", ...event });
+}
+
+async function runHiddenBoundaryCase(params: {
+  streamOverrides?: Record<string, unknown>;
+  toolCallId: string;
+  includeNonTerminalUpdate?: boolean;
+  firstText?: string;
+  secondText?: string;
+  expectedText: string;
+}) {
+  const { deliveries, projector } = createStreamHarness("live", params.streamOverrides);
+  await emitText(projector, params.firstText ?? "fallback.");
+  await emitTool(projector, {
+    tag: "tool_call",
+    toolCallId: params.toolCallId,
+    status: "in_progress",
+    title: "Run test",
+    text: "Run test (in_progress)",
+  });
+  if (params.includeNonTerminalUpdate) {
+    await emitTool(projector, {
+      tag: "tool_call_update",
+      toolCallId: params.toolCallId,
+      status: "in_progress",
+      title: "Run test",
+      text: "Run test (in_progress)",
+    });
+  }
+  await emitText(projector, params.secondText ?? "I don't");
+  await projector.flush(true);
+
+  expect(combinedBlockText(deliveries)).toBe(params.expectedText);
+}
+
+describe("createAcpReplyProjector", () => {
+  it("shows execute details only in full verbose mode", async () => {
+    const summary = createLiveToolLifecycleHarness();
+    await emitTool(summary.projector, {
+      tag: "tool_call",
+      toolCallId: "call_execute_summary",
+      kind: "execute",
+      status: "in_progress",
+      title: "exec: cat /private/operator-file",
+      text: "exec: cat /private/operator-file (in_progress)",
+    });
+    expect(summary.deliveries[0]?.text).not.toContain("cat /private/operator-file");
+    expect(summary.deliveries[0]?.text).toContain("status=in_progress");
+
+    const full = createStreamHarness(
+      "live",
+      { tagVisibility: { tool_call: true } },
+      { shouldSendFullToolDetails: true },
+    );
+    await emitTool(full.projector, {
+      tag: "tool_call",
+      toolCallId: "call_execute_full",
+      kind: "execute",
+      status: "in_progress",
+      title: "exec: cat /private/operator-file",
+      text: "exec: cat /private/operator-file (in_progress)",
+    });
+    expect(full.deliveries[0]?.text).toContain("cat /private/operator-file");
+  });
+
+  it("reports progress for ACP runtime events before delivery filtering", async () => {
+    const onProgress = vi.fn();
+    const { projector } = createProjectorHarness(undefined, { onProgress });
+
+    await emitText(projector, "hidden reasoning", { stream: "thought" });
+    await emitTool(projector, {
+      tag: "tool_call",
+      toolCallId: "tool-1",
+      status: "in_progress",
+      title: "Run command",
+      text: "Run command",
+    });
+
+    expect(onProgress).toHaveBeenCalledTimes(2);
+  });
+
+  it("buffers default final-only text into one final reply", async () => {
+    const { deliveries, projector } = createProjectorHarness();
+
+    await emitText(projector, "a".repeat(70));
+    await projector.flush(true);
+
+    expect(deliveries).toEqual([{ kind: "final", text: "a".repeat(70) }]);
+  });
+
+  it.each(["live", "final_only"] as const)(
+    "uses finalized and refreshed owner context to redact split private prompts in %s mode",
+    async (deliveryMode) => {
+      const marker = "[Current message - respond to this]";
+      let conversationContext = "";
+      const { deliveries, projector } = createStreamHarness(
+        deliveryMode,
+        {},
+        {
+          getConversationContext: () => conversationContext,
+        },
+      );
+      conversationContext = `${marker}\nPrivate secret. Keep hidden.`;
+
+      await emitText(projector, "Visible answer before. ");
+      conversationContext = `${marker}\nPrivate updated context. Keep hidden.`;
+      await emitText(projector, `${marker}\nPrivate updated context. `);
+      await emitText(projector, "Keep hidden. Visible answer after.");
+      await projector.flush(true);
+
+      expect(deliveries.map((delivery) => delivery.text).join("")).toBe(
+        "Visible answer before.  Visible answer after.",
+      );
+    },
+  );
+
+  it("rechecks the dynamic tool-summary gate for each ACP event", async () => {
+    let allowToolSummaries = false;
+    const { deliveries, projector } = createStreamHarness(
+      "live",
+      {
+        tagVisibility: {
+          tool_call: true,
+        },
+      },
+      {
+        shouldSendToolSummaries: false,
+        shouldSendToolSummariesNow: () => allowToolSummaries,
+      },
+    );
+
+    await emitTool(projector, {
+      tag: "tool_call",
+      toolCallId: "tool-1",
+      status: "in_progress",
+      title: "Run hidden command",
+      text: "Run hidden command",
+    });
+    expect(deliveries).toEqual([]);
+
+    allowToolSummaries = true;
+    await emitTool(projector, {
+      tag: "tool_call",
+      toolCallId: "tool-2",
+      status: "in_progress",
+      title: "Run visible command",
+      text: "Run visible command",
+    });
+
+    expectToolCallSummary(deliveries[0]);
+  });
+
+  it("drops buffered final-only tool summaries when the dynamic gate turns off before flush", async () => {
+    let allowToolSummaries = true;
+    const { deliveries, projector } = createFinalOnlyStatusToolHarness({
+      shouldSendToolSummariesNow: () => allowToolSummaries,
+    });
+
+    await emitStatus(projector, "available commands updated (7)", "available_commands_update");
+    await emitTool(projector, {
+      tag: "tool_call",
+      toolCallId: "tool-1",
+      status: "in_progress",
+      title: "Run hidden command",
+      text: "Run hidden command",
+    });
+    await emitText(projector, "done");
+    allowToolSummaries = false;
+
+    await projector.flush(true);
+
+    expect(deliveries).toEqual([{ kind: "final", text: "done" }]);
+  });
+
+  it("preserves final-only text boundary when a buffered tool summary is dropped", async () => {
+    let allowToolSummaries = true;
+    const { deliveries, projector } = createStreamHarness(
+      "final_only",
+      {
+        tagVisibility: {
+          tool_call: true,
+        },
+      },
+      { shouldSendToolSummariesNow: () => allowToolSummaries },
+    );
+
+    await emitText(projector, "fallback.");
+    await emitTool(projector, {
+      tag: "tool_call",
+      toolCallId: "tool-dropped-before-flush",
+      status: "in_progress",
+      title: "Run test",
+      text: "Run test (in_progress)",
+    });
+    await emitText(projector, "I don't");
+    allowToolSummaries = false;
+
+    await projector.flush(true);
+
+    expect(deliveries).toEqual([{ kind: "final", text: "fallback.\n\nI don't" }]);
+  });
+
+  it("flushes staggered live text deltas after idle gaps", async () => {
+    vi.useFakeTimers();
+    try {
+      const { deliveries, projector } = createStreamHarness("live");
+
+      await emitText(projector, "A");
+      await vi.advanceTimersByTimeAsync(760);
+      await projector.flush(false);
+
+      await emitText(projector, "B");
+      await vi.advanceTimersByTimeAsync(760);
+      await projector.flush(false);
+
+      await emitText(projector, "C");
+      await vi.advanceTimersByTimeAsync(760);
+      await projector.flush(false);
+
+      expect(blockDeliveries(deliveries)).toEqual([
+        { kind: "block", text: "A" },
+        { kind: "block", text: "B" },
+        { kind: "block", text: "C" },
+      ]);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("does not flush short live fragments mid-phrase on idle", async () => {
+    vi.useFakeTimers();
+    try {
+      const { deliveries, projector } = createStreamHarness("live");
+
+      await emitText(projector, "Yes. Send me the term(s), and I’ll run ");
+
+      await vi.advanceTimersByTimeAsync(1200);
+      expect(deliveries).toStrictEqual([]);
+
+      await emitText(projector, "`wd-cli` searches right away. ");
+      await projector.flush(false);
+
+      expect(deliveries).toEqual([
+        {
+          kind: "block",
+          text: "Yes. Send me the term(s), and I’ll run `wd-cli` searches right away. ",
+        },
+      ]);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("supports deliveryMode=final_only by buffering all projected output until done", async () => {
+    const { deliveries, projector } = createFinalOnlyStatusToolHarness();
+
+    await emitText(projector, "What");
+    await emitStatus(projector, "available commands updated (7)", "available_commands_update");
+    await emitTool(projector, {
+      tag: "tool_call",
+      toolCallId: "call_1",
+      status: "in_progress",
+      title: "List files",
+      text: "List files (in_progress)",
+    });
+    await emitText(projector, " now?");
+    expect(deliveries).toStrictEqual([]);
+
+    await projector.flush(true);
+    expect(deliveries).toHaveLength(3);
+    expect(deliveries[0]).toEqual({
+      kind: "tool",
+      text: prefixSystemMessage("available commands updated (7)"),
+    });
+    expectToolCallSummary(deliveries[1]);
+    expect(deliveries[2]).toEqual({ kind: "final", text: "What now?" });
+  });
+
+  it("flushes buffered status/tool output on error in deliveryMode=final_only", async () => {
+    const { deliveries, projector } = createFinalOnlyStatusToolHarness();
+
+    await emitStatus(projector, "available commands updated (7)", "available_commands_update");
+    await emitTool(projector, {
+      tag: "tool_call",
+      toolCallId: "call_2",
+      status: "in_progress",
+      title: "Run tests",
+      text: "Run tests (in_progress)",
+    });
+    expect(deliveries).toStrictEqual([]);
+
+    await projector.flush(true);
+    expect(deliveries).toHaveLength(2);
+    expect(deliveries[0]).toEqual({
+      kind: "tool",
+      text: prefixSystemMessage("available commands updated (7)"),
+    });
+    expectToolCallSummary(deliveries[1]);
+  });
+
+  it("suppresses usage_update by default and allows deduped usage when tag-visible", async () => {
+    const { deliveries: hidden, projector: hiddenProjector } = createProjectorHarness();
+    await emitStatus(hiddenProjector, "usage updated: 10/100", "usage_update", {
+      used: 10,
+      size: 100,
+    });
+    expect(hidden).toStrictEqual([]);
+
+    const { deliveries: shown, projector: shownProjector } = createStreamHarness("live", {
+      tagVisibility: {
+        usage_update: true,
+      },
+    });
+
+    await emitStatus(shownProjector, "usage updated: 10/100", "usage_update", {
+      used: 10,
+      size: 100,
+    });
+    await emitStatus(shownProjector, "usage updated: 10/100", "usage_update", {
+      used: 10,
+      size: 100,
+    });
+    await emitStatus(shownProjector, "usage updated: 11/100", "usage_update", {
+      used: 11,
+      size: 100,
+    });
+
+    expect(shown).toEqual([
+      { kind: "tool", text: prefixSystemMessage("usage updated: 10/100") },
+      { kind: "tool", text: prefixSystemMessage("usage updated: 11/100") },
+    ]);
+  });
+
+  it("hides available_commands_update by default", async () => {
+    const { deliveries, projector } = createProjectorHarness();
+    await emitStatus(projector, "available commands updated (7)", "available_commands_update");
+
+    expect(deliveries).toStrictEqual([]);
+  });
+
+  it("dedupes repeated tool lifecycle updates when repeatSuppression is enabled", async () => {
+    const { deliveries, projector } = createLiveToolLifecycleHarness();
+
+    await emitTool(projector, {
+      tag: "tool_call",
+      toolCallId: "call_1",
+      status: "in_progress",
+      title: "List files",
+      text: "List files (in_progress)",
+    });
+    await emitTool(projector, {
+      tag: "tool_call_update",
+      toolCallId: "call_1",
+      status: "in_progress",
+      title: "List files",
+      text: "List files (in_progress)",
+    });
+    await emitTool(projector, {
+      tag: "tool_call_update",
+      toolCallId: "call_1",
+      status: "completed",
+      title: "List files",
+      text: "List files (completed)",
+    });
+    await emitTool(projector, {
+      tag: "tool_call_update",
+      toolCallId: "call_1",
+      status: "completed",
+      title: "List files",
+      text: "List files (completed)",
+    });
+
+    expect(deliveries.length).toBe(2);
+    expectToolCallSummary(deliveries[0]);
+    expectToolCallSummary(deliveries[1]);
+  });
+
+  it("keeps terminal tool updates even when rendered summaries are truncated", async () => {
+    const { deliveries, projector } = createLiveToolLifecycleHarness({});
+
+    const longTitle =
+      "Run an intentionally long command title that truncates before lifecycle status is visible";
+    await emitTool(projector, {
+      tag: "tool_call",
+      toolCallId: "call_truncated_status",
+      status: "in_progress",
+      title: longTitle,
+      text: `${longTitle} (in_progress)`,
+    });
+    await emitTool(projector, {
+      tag: "tool_call_update",
+      toolCallId: "call_truncated_status",
+      status: "completed",
+      title: longTitle,
+      text: `${longTitle} (completed)`,
+    });
+
+    expect(deliveries.length).toBe(2);
+    expectToolCallSummary(deliveries[0]);
+    expectToolCallSummary(deliveries[1]);
+  });
+
+  it("renders fallback tool labels without leaking call ids as primary label", async () => {
+    const { deliveries, projector } = createLiveToolLifecycleHarness();
+
+    await emitTool(projector, {
+      tag: "tool_call",
+      toolCallId: "call_ABC123",
+      status: "in_progress",
+      text: "call_ABC123 (in_progress)",
+    });
+
+    expectToolCallSummary(deliveries[0]);
+    expect(deliveries[0]?.text).not.toContain("call_ABC123 (");
+  });
+
+  it("allows repeated status/tool summaries when repeatSuppression is disabled", async () => {
+    const { deliveries, projector } = createLiveToolLifecycleHarness({
+      repeatSuppression: false,
+      includeStatus: true,
+    });
+
+    await emitStatus(projector, "available commands updated", "available_commands_update");
+    await emitStatus(projector, "available commands updated", "available_commands_update");
+    await emitTool(projector, {
+      text: "tool call",
+      tag: "tool_call",
+      toolCallId: "x",
+      status: "in_progress",
+    });
+    await emitTool(projector, {
+      text: "tool call",
+      tag: "tool_call_update",
+      toolCallId: "x",
+      status: "in_progress",
+    });
+    await emitText(projector, "hello");
+    await projector.flush(true);
+
+    expect(countMatching(deliveries, (entry) => entry.kind === "tool")).toBe(4);
+    expect(deliveries[0]).toEqual({
+      kind: "tool",
+      text: prefixSystemMessage("available commands updated"),
+    });
+    expect(deliveries[1]).toEqual({
+      kind: "tool",
+      text: prefixSystemMessage("available commands updated"),
+    });
+    expectToolCallSummary(deliveries[2]);
+    expectToolCallSummary(deliveries[3]);
+    expect(deliveries[4]).toEqual({ kind: "block", text: "hello" });
+  });
+
+  it("suppresses exact duplicate status updates when repeatSuppression is enabled", async () => {
+    const { deliveries, projector } = createStreamHarness("live", {
+      tagVisibility: {
+        available_commands_update: true,
+      },
+    });
+
+    await emitStatus(projector, "available commands updated (7)", "available_commands_update");
+    await emitStatus(projector, "available commands updated (7)", "available_commands_update");
+    await emitStatus(projector, "available commands updated (8)", "available_commands_update");
+
+    expect(deliveries).toEqual([
+      { kind: "tool", text: prefixSystemMessage("available commands updated (7)") },
+      { kind: "tool", text: prefixSystemMessage("available commands updated (8)") },
+    ]);
+  });
+
+  it("supports tagVisibility overrides for tool updates", async () => {
+    const { deliveries, projector } = createStreamHarness("live", {
+      tagVisibility: {
+        tool_call: true,
+        tool_call_update: false,
+      },
+    });
+
+    await emitTool(projector, {
+      tag: "tool_call",
+      toolCallId: "c1",
+      status: "in_progress",
+      title: "Run tests",
+      text: "Run tests (in_progress)",
+    });
+    await emitTool(projector, {
+      tag: "tool_call_update",
+      toolCallId: "c1",
+      status: "completed",
+      title: "Run tests",
+      text: "Run tests (completed)",
+    });
+
+    expect(deliveries.length).toBe(1);
+    expectToolCallSummary(deliveries[0]);
+  });
+
+  it("inserts a space boundary before visible text after hidden tool updates by default", async () => {
+    await runHiddenBoundaryCase({
+      toolCallId: "call_hidden_1",
+      expectedText: "fallback. I don't",
+    });
+  });
+
+  it("preserves hidden boundary when the dynamic tool-summary gate hides a visible tool event", async () => {
+    const { deliveries, projector } = createStreamHarness(
+      "live",
+      {
+        tagVisibility: {
+          tool_call: true,
+        },
+      },
+      {
+        shouldSendToolSummaries: false,
+        shouldSendToolSummariesNow: () => false,
+      },
+    );
+
+    await emitText(projector, "fallback.");
+    await emitTool(projector, {
+      tag: "tool_call",
+      toolCallId: "call_dynamic_hidden",
+      status: "in_progress",
+      title: "Run test",
+      text: "Run test (in_progress)",
+    });
+    await emitText(projector, "I don't");
+    await projector.flush(true);
+
+    expect(combinedBlockText(deliveries)).toBe("fallback. I don't");
+    expect(deliveries.some((delivery) => delivery.kind === "tool")).toBe(false);
+  });
+
+  it("preserves hidden boundary across nonterminal hidden tool updates", async () => {
+    await runHiddenBoundaryCase({
+      streamOverrides: {
+        tagVisibility: {
+          tool_call: false,
+          tool_call_update: false,
+        },
+      },
+      toolCallId: "hidden_boundary_1",
+      includeNonTerminalUpdate: true,
+      expectedText: "fallback. I don't",
+    });
+  });
+
+  it("uses the built-in space separator for hidden live boundaries", async () => {
+    await runHiddenBoundaryCase({
+      toolCallId: "call_hidden_2",
+      expectedText: "fallback. I don't",
+    });
+  });
+
+  it("does not duplicate newlines when previous visible text already ends with newline", async () => {
+    await runHiddenBoundaryCase({
+      toolCallId: "call_hidden_4",
+      firstText: "fallback.\n",
+      expectedText: "fallback.\nI don't",
+    });
+  });
+
+  it("does not insert boundary separator for hidden non-tool status updates", async () => {
+    const { deliveries, projector } = createStreamHarness("live");
+
+    await emitText(projector, "A");
+    await emitStatus(projector, "available commands updated", "available_commands_update");
+    await emitText(projector, "B");
+    await projector.flush(true);
+
+    expect(combinedBlockText(deliveries)).toBe("AB");
+  });
+});

src/auto-reply/reply/acp-projector.ts

@@ -0,0 +1,510 @@
+// Projects ACP runtime events into OpenClaw-visible session update records.
+import type { AcpRuntimeEvent, AcpSessionUpdateTag } from "@openclaw/acp-core/runtime/types";
+import {
+  normalizeOptionalLowercaseString,
+  normalizeOptionalString,
+} from "@openclaw/normalization-core/string-coerce";
+import { truncateUtf16Safe } from "@openclaw/normalization-core/utf16-slice";
+import { resolveAcpToolTerminalOutcome } from "../../acp/tool-status.js";
+import { EmbeddedBlockChunker } from "../../agents/embedded-agent-block-chunker.js";
+import { createVerifiedConversationContextStreamFilter } from "../../agents/embedded-agent-helpers/sanitize-user-facing-text.js";
+import { formatToolSummary, resolveToolDisplay } from "../../agents/tool-display.js";
+import type { OpenClawConfig } from "../../config/types.openclaw.js";
+import { prefixSystemMessage } from "../../infra/system-message.js";
+import { truncateUtf16WithEllipsis as truncateText } from "../../shared/text-truncate.js";
+import type { ReplyPayload } from "../types.js";
+import {
+  type AcpHiddenBoundarySeparator,
+  isAcpTagVisible,
+  resolveAcpProjectionSettings,
+  resolveAcpStreamingConfig,
+} from "./acp-stream-settings.js";
+import { createBlockReplyPipeline } from "./block-reply-pipeline.js";
+import type { ReplyDispatchKind } from "./reply-dispatcher.types.js";
+
+const ACP_BLOCK_REPLY_TIMEOUT_MS = 15_000;
+const ACP_LIVE_IDLE_FLUSH_FLOOR_MS = 750;
+const ACP_LIVE_IDLE_MIN_CHARS = 80;
+const ACP_LIVE_SOFT_FLUSH_CHARS = 220;
+const ACP_LIVE_HARD_FLUSH_CHARS = 480;
+
+const HIDDEN_BOUNDARY_TAGS = new Set<AcpSessionUpdateTag>(["tool_call", "tool_call_update"]);
+
+type AcpProjectedDeliveryMeta = {
+  tag?: AcpSessionUpdateTag;
+  toolCallId?: string;
+  toolStatus?: string;
+  allowEdit?: boolean;
+};
+
+type ToolLifecycleState = {
+  started: boolean;
+  terminal: boolean;
+  lastRenderedHash?: string;
+};
+
+type BufferedToolDelivery = {
+  payload: ReplyPayload;
+  meta?: AcpProjectedDeliveryMeta;
+};
+
+function hashText(text: string): string {
+  return text.trim();
+}
+
+function normalizeToolStatus(status: string | undefined): string | undefined {
+  const normalized = normalizeOptionalLowercaseString(status);
+  return normalized || undefined;
+}
+
+function resolveHiddenBoundarySeparatorText(mode: AcpHiddenBoundarySeparator): string {
+  if (mode === "space") {
+    return " ";
+  }
+  if (mode === "newline") {
+    return "\n";
+  }
+  if (mode === "paragraph") {
+    return "\n\n";
+  }
+  return "";
+}
+
+function shouldInsertSeparator(params: {
+  separator: string;
+  previousTail: string | undefined;
+  nextText: string;
+}): boolean {
+  if (!params.separator) {
+    return false;
+  }
+  if (!params.nextText) {
+    return false;
+  }
+  const firstChar = params.nextText[0];
+  if (typeof firstChar === "string" && /\s/.test(firstChar)) {
+    return false;
+  }
+  const tail = params.previousTail ?? "";
+  if (!tail) {
+    return false;
+  }
+  if (params.separator === " " && /\s$/.test(tail)) {
+    return false;
+  }
+  if ((params.separator === "\n" || params.separator === "\n\n") && tail.endsWith("\n")) {
+    return false;
+  }
+  return true;
+}
+
+function shouldFlushLiveBufferOnBoundary(text: string): boolean {
+  if (!text) {
+    return false;
+  }
+  if (text.length >= ACP_LIVE_HARD_FLUSH_CHARS) {
+    return true;
+  }
+  if (text.endsWith("\n\n")) {
+    return true;
+  }
+  if (/[.!?][)"'`]*\s$/.test(text)) {
+    return true;
+  }
+  if (text.length >= ACP_LIVE_SOFT_FLUSH_CHARS && /\s$/.test(text)) {
+    return true;
+  }
+  return false;
+}
+
+function shouldFlushLiveBufferOnIdle(text: string): boolean {
+  if (!text) {
+    return false;
+  }
+  if (text.length >= ACP_LIVE_IDLE_MIN_CHARS) {
+    return true;
+  }
+  if (/[.!?][)"'`]*$/.test(text.trimEnd())) {
+    return true;
+  }
+  if (text.includes("\n")) {
+    return true;
+  }
+  return false;
+}
+
+function renderToolSummaryText(
+  event: Extract<AcpRuntimeEvent, { type: "tool_call" }>,
+  shouldSendFullToolDetails: boolean,
+): string {
+  const detailParts: string[] = [];
+  const commandBearing = normalizeOptionalLowercaseString(event.kind) === "execute";
+  const title =
+    shouldSendFullToolDetails || !commandBearing ? normalizeOptionalString(event.title) : undefined;
+  if (title) {
+    detailParts.push(title);
+  }
+  const status = normalizeOptionalString(event.status);
+  if (status) {
+    detailParts.push(`status=${status}`);
+  }
+  const fallback =
+    shouldSendFullToolDetails || !commandBearing ? normalizeOptionalString(event.text) : undefined;
+  if (detailParts.length === 0 && fallback) {
+    detailParts.push(fallback);
+  }
+  const display = resolveToolDisplay({
+    name: "tool_call",
+    meta: detailParts.join(" · ") || "tool call",
+  });
+  return formatToolSummary(display);
+}
+
+type AcpReplyProjector = {
+  onEvent: (event: AcpRuntimeEvent) => Promise<void>;
+  flush: (force?: boolean) => Promise<void>;
+};
+
+export function createAcpReplyProjector(params: {
+  cfg: OpenClawConfig;
+  shouldSendToolSummaries: boolean;
+  shouldSendToolSummariesNow?: () => boolean;
+  shouldSendFullToolDetails: boolean;
+  deliver: (
+    kind: ReplyDispatchKind,
+    payload: ReplyPayload,
+    meta?: AcpProjectedDeliveryMeta,
+  ) => Promise<boolean>;
+  getConversationContext?: () => string | undefined;
+  onProgress?: () => void;
+  provider?: string;
+  accountId?: string;
+}): AcpReplyProjector {
+  const settings = resolveAcpProjectionSettings(params.cfg);
+  const streaming = resolveAcpStreamingConfig({
+    cfg: params.cfg,
+    provider: params.provider,
+    accountId: params.accountId,
+    deliveryMode: settings.deliveryMode,
+  });
+  const blockReplyPipeline = createBlockReplyPipeline({
+    onBlockReply: async (payload) => {
+      await params.deliver("block", payload);
+    },
+    timeoutMs: ACP_BLOCK_REPLY_TIMEOUT_MS,
+    coalescing: settings.deliveryMode === "live" ? undefined : streaming.coalescing,
+  });
+  const chunker = new EmbeddedBlockChunker(streaming.chunking);
+  const filterConversationContext = createVerifiedConversationContextStreamFilter(
+    params.getConversationContext,
+  );
+  const liveIdleFlushMs = Math.max(streaming.coalescing.idleMs, ACP_LIVE_IDLE_FLUSH_FLOOR_MS);
+
+  let emittedOutputChars = 0;
+  let truncationNoticeEmitted = false;
+  let lastStatusHash: string | undefined;
+  let lastToolHash: string | undefined;
+  let lastUsageTuple: string | undefined;
+  let lastVisibleOutputTail: string | undefined;
+  let pendingHiddenBoundary = false;
+  let liveBufferText = "";
+  let finalOnlyOutputText = "";
+  let liveIdleTimer: NodeJS.Timeout | undefined;
+  const pendingToolDeliveries: BufferedToolDelivery[] = [];
+  const toolLifecycleById = new Map<string, ToolLifecycleState>();
+
+  const shouldSendToolSummaries = () =>
+    params.shouldSendToolSummariesNow?.() ?? params.shouldSendToolSummaries;
+
+  const clearLiveIdleTimer = () => {
+    if (!liveIdleTimer) {
+      return;
+    }
+    clearTimeout(liveIdleTimer);
+    liveIdleTimer = undefined;
+  };
+
+  const drainChunker = (force: boolean) => {
+    if (settings.deliveryMode === "final_only" && !force) {
+      return;
+    }
+    chunker.drain({
+      force,
+      emit: (chunk) => {
+        blockReplyPipeline.enqueue({ text: chunk });
+      },
+    });
+  };
+
+  const flushLiveBuffer = (opts?: { force?: boolean; idle?: boolean }) => {
+    if (settings.deliveryMode !== "live") {
+      return;
+    }
+    if (!liveBufferText) {
+      return;
+    }
+    if (opts?.idle && !shouldFlushLiveBufferOnIdle(liveBufferText)) {
+      return;
+    }
+    const text = liveBufferText;
+    liveBufferText = "";
+    chunker.append(text);
+    drainChunker(opts?.force === true);
+  };
+
+  const scheduleLiveIdleFlush = () => {
+    if (settings.deliveryMode !== "live") {
+      return;
+    }
+    if (liveIdleFlushMs <= 0 || !liveBufferText) {
+      return;
+    }
+    clearLiveIdleTimer();
+    liveIdleTimer = setTimeout(() => {
+      flushLiveBuffer({ force: true, idle: true });
+      if (liveBufferText) {
+        scheduleLiveIdleFlush();
+      }
+    }, liveIdleFlushMs);
+  };
+
+  const flushBufferedToolDeliveries = async (force: boolean) => {
+    if (!(settings.deliveryMode === "final_only" && force)) {
+      return;
+    }
+    if (!shouldSendToolSummaries()) {
+      pendingToolDeliveries.length = 0;
+      return;
+    }
+    for (const entry of pendingToolDeliveries.splice(0)) {
+      await params.deliver("tool", entry.payload, entry.meta);
+    }
+  };
+
+  const flush = async (force = false): Promise<void> => {
+    if (settings.deliveryMode === "live") {
+      clearLiveIdleTimer();
+      flushLiveBuffer({ force: true });
+    }
+    await flushBufferedToolDeliveries(force);
+    if (settings.deliveryMode === "final_only") {
+      if (force && finalOnlyOutputText.trim().length > 0) {
+        const text = finalOnlyOutputText;
+        finalOnlyOutputText = "";
+        await params.deliver("final", { text });
+      }
+    } else {
+      drainChunker(force);
+    }
+    await blockReplyPipeline.flush({ force });
+  };
+
+  const emitSystemStatus = async (
+    text: string,
+    meta?: AcpProjectedDeliveryMeta,
+    opts?: { dedupe?: boolean },
+  ) => {
+    if (!shouldSendToolSummaries()) {
+      return;
+    }
+    const bounded = truncateText(text.trim(), settings.maxSessionUpdateChars);
+    if (!bounded) {
+      return;
+    }
+    const formatted = prefixSystemMessage(bounded);
+    const hash = hashText(formatted);
+    const shouldDedupe = settings.repeatSuppression && opts?.dedupe !== false;
+    if (shouldDedupe && lastStatusHash === hash) {
+      return;
+    }
+    if (settings.deliveryMode === "final_only") {
+      pendingToolDeliveries.push({
+        payload: { text: formatted },
+        meta,
+      });
+    } else {
+      await flush(true);
+      await params.deliver("tool", { text: formatted }, meta);
+    }
+    lastStatusHash = hash;
+  };
+
+  const markHiddenToolBoundary = (event: Extract<AcpRuntimeEvent, { type: "tool_call" }>) => {
+    if (!event.tag || !HIDDEN_BOUNDARY_TAGS.has(event.tag)) {
+      return;
+    }
+    const status = normalizeToolStatus(event.status);
+    const isTerminal = resolveAcpToolTerminalOutcome(status) !== undefined;
+    pendingHiddenBoundary = pendingHiddenBoundary || event.tag === "tool_call" || isTerminal;
+  };
+
+  const emitToolSummary = async (event: Extract<AcpRuntimeEvent, { type: "tool_call" }>) => {
+    if (!shouldSendToolSummaries()) {
+      markHiddenToolBoundary(event);
+      return;
+    }
+    if (!isAcpTagVisible(settings, event.tag)) {
+      return;
+    }
+
+    const renderedToolSummary = renderToolSummaryText(event, params.shouldSendFullToolDetails);
+    const toolSummary = truncateText(renderedToolSummary, settings.maxSessionUpdateChars);
+    const hash = hashText(renderedToolSummary);
+    const toolCallId = normalizeOptionalString(event.toolCallId);
+    const status = normalizeToolStatus(event.status);
+    const isTerminal = resolveAcpToolTerminalOutcome(status) !== undefined;
+    const isStart = status === "in_progress" || event.tag === "tool_call";
+
+    if (settings.repeatSuppression) {
+      if (toolCallId) {
+        const state = toolLifecycleById.get(toolCallId) ?? {
+          started: false,
+          terminal: false,
+        };
+        if (isTerminal && state.terminal) {
+          return;
+        }
+        if (isStart && state.started) {
+          return;
+        }
+        if (state.lastRenderedHash === hash) {
+          return;
+        }
+        if (isStart) {
+          state.started = true;
+        }
+        if (isTerminal) {
+          state.terminal = true;
+        }
+        state.lastRenderedHash = hash;
+        toolLifecycleById.set(toolCallId, state);
+      } else if (lastToolHash === hash) {
+        return;
+      }
+    }
+
+    const deliveryMeta: AcpProjectedDeliveryMeta = {
+      ...(event.tag ? { tag: event.tag } : {}),
+      ...(toolCallId ? { toolCallId } : {}),
+      ...(status ? { toolStatus: status } : {}),
+      allowEdit: Boolean(toolCallId && event.tag === "tool_call_update"),
+    };
+    if (settings.deliveryMode === "final_only") {
+      pendingToolDeliveries.push({
+        payload: { text: toolSummary },
+        meta: deliveryMeta,
+      });
+      markHiddenToolBoundary(event);
+    } else {
+      await flush(true);
+      await params.deliver("tool", { text: toolSummary }, deliveryMeta);
+    }
+    lastToolHash = hash;
+  };
+
+  const emitTruncationNotice = async () => {
+    if (truncationNoticeEmitted) {
+      return;
+    }
+    truncationNoticeEmitted = true;
+    await emitSystemStatus(
+      "output truncated",
+      {
+        tag: "session_info_update",
+      },
+      {
+        dedupe: false,
+      },
+    );
+  };
+
+  // One projector serves one dispatch; terminal settlement belongs to tryDispatchAcpReply.
+  const onEvent = async (event: AcpRuntimeEvent): Promise<void> => {
+    params.onProgress?.();
+    if (event.type === "text_delta") {
+      if (event.stream && event.stream !== "output") {
+        return;
+      }
+      if (!isAcpTagVisible(settings, event.tag)) {
+        return;
+      }
+      let text = event.text;
+      if (!text) {
+        return;
+      }
+      if (
+        pendingHiddenBoundary &&
+        shouldInsertSeparator({
+          separator: resolveHiddenBoundarySeparatorText(settings.hiddenBoundarySeparator),
+          previousTail: lastVisibleOutputTail,
+          nextText: text,
+        })
+      ) {
+        text = `${resolveHiddenBoundarySeparatorText(settings.hiddenBoundarySeparator)}${text}`;
+      }
+      pendingHiddenBoundary = false;
+      if (emittedOutputChars >= settings.maxOutputChars) {
+        await emitTruncationNotice();
+        return;
+      }
+      const remaining = settings.maxOutputChars - emittedOutputChars;
+      const accepted = remaining < text.length ? truncateUtf16Safe(text, remaining) : text;
+      if (accepted.length > 0) {
+        emittedOutputChars += accepted.length;
+        const safeText = filterConversationContext(accepted);
+        lastVisibleOutputTail = safeText.slice(-1) || lastVisibleOutputTail;
+        if (settings.deliveryMode === "live") {
+          liveBufferText += safeText;
+          if (shouldFlushLiveBufferOnBoundary(liveBufferText)) {
+            clearLiveIdleTimer();
+            flushLiveBuffer({ force: true });
+          } else {
+            scheduleLiveIdleFlush();
+          }
+        } else {
+          finalOnlyOutputText += safeText;
+        }
+      }
+      if (accepted.length < text.length) {
+        // A split code point can leave the accepted prefix shorter than the remaining budget.
+        // Exhaust it after any drop so later deltas cannot skip past omitted text.
+        emittedOutputChars = settings.maxOutputChars;
+        await emitTruncationNotice();
+      }
+      return;
+    }
+
+    if (event.type === "status") {
+      if (!isAcpTagVisible(settings, event.tag)) {
+        return;
+      }
+      if (event.tag === "usage_update" && settings.repeatSuppression) {
+        const usageTuple =
+          typeof event.used === "number" && typeof event.size === "number"
+            ? `${event.used}/${event.size}`
+            : hashText(event.text);
+        if (usageTuple === lastUsageTuple) {
+          return;
+        }
+        lastUsageTuple = usageTuple;
+      }
+      await emitSystemStatus(event.text, event.tag ? { tag: event.tag } : undefined, {
+        dedupe: true,
+      });
+      return;
+    }
+
+    if (event.type === "tool_call") {
+      if (!isAcpTagVisible(settings, event.tag)) {
+        markHiddenToolBoundary(event);
+        return;
+      }
+      await emitToolSummary(event);
+    }
+  };
+
+  return {
+    onEvent,
+    flush,
+  };
+}

src/auto-reply/reply/acp-reset-target.ts

@@ -0,0 +1,163 @@
+// Resolves ACP reset targets from sessions and command directives.
+import {
+  normalizeLowercaseStringOrEmpty,
+  normalizeOptionalString,
+} from "@openclaw/normalization-core/string-coerce";
+import {
+  buildConfiguredAcpSessionKey,
+  normalizeBindingConfig,
+  type ConfiguredAcpBindingChannel,
+} from "../../acp/persistent-bindings.types.js";
+import { resolveConfiguredBindingRecord } from "../../channels/plugins/configured-binding-registry.js";
+import { listAcpBindings } from "../../config/bindings.js";
+import type { OpenClawConfig } from "../../config/types.openclaw.js";
+import { getSessionBindingService } from "../../infra/outbound/session-binding-service.js";
+import { DEFAULT_ACCOUNT_ID, isAcpSessionKey } from "../../routing/session-key.js";
+
+function resolveResetTargetAccountId(params: {
+  cfg: OpenClawConfig;
+  channel: string;
+  accountId?: string | null;
+}): string {
+  const explicit = normalizeOptionalString(params.accountId) ?? "";
+  if (explicit) {
+    return explicit;
+  }
+
+  const channelCfg = (
+    params.cfg.channels as Record<string, { defaultAccount?: unknown } | undefined>
+  )[params.channel];
+  const configuredDefault = channelCfg?.defaultAccount;
+  return normalizeOptionalString(configuredDefault) ?? DEFAULT_ACCOUNT_ID;
+}
+
+function resolveRawConfiguredAcpSessionKey(params: {
+  cfg: OpenClawConfig;
+  channel: string;
+  accountId: string;
+  conversationId: string;
+  parentConversationId?: string;
+}): string | undefined {
+  for (const binding of listAcpBindings(params.cfg)) {
+    const bindingChannel = normalizeLowercaseStringOrEmpty(
+      normalizeOptionalString(binding.match.channel),
+    );
+    if (!bindingChannel || bindingChannel !== params.channel) {
+      continue;
+    }
+
+    const bindingAccountId = normalizeOptionalString(binding.match.accountId) ?? "";
+    if (bindingAccountId && bindingAccountId !== "*" && bindingAccountId !== params.accountId) {
+      continue;
+    }
+
+    const peerId = normalizeOptionalString(binding.match.peer?.id) ?? "";
+    const matchedConversationId =
+      peerId === params.conversationId
+        ? params.conversationId
+        : peerId && peerId === params.parentConversationId
+          ? params.parentConversationId
+          : undefined;
+    if (!matchedConversationId) {
+      continue;
+    }
+
+    const acp = normalizeBindingConfig(binding.acp);
+    return buildConfiguredAcpSessionKey({
+      channel: params.channel as ConfiguredAcpBindingChannel,
+      accountId: bindingAccountId && bindingAccountId !== "*" ? bindingAccountId : params.accountId,
+      conversationId: matchedConversationId,
+      ...(params.parentConversationId ? { parentConversationId: params.parentConversationId } : {}),
+      agentId: binding.agentId,
+      mode: acp.mode === "oneshot" ? "oneshot" : "persistent",
+      ...(acp.cwd ? { cwd: acp.cwd } : {}),
+      ...(acp.backend ? { backend: acp.backend } : {}),
+      ...(acp.label ? { label: acp.label } : {}),
+    });
+  }
+
+  return undefined;
+}
+
+export function resolveEffectiveResetTargetSessionKey(params: {
+  cfg: OpenClawConfig;
+  channel?: string | null;
+  accountId?: string | null;
+  conversationId?: string | null;
+  parentConversationId?: string | null;
+  activeSessionKey?: string | null;
+  allowNonAcpBindingSessionKey?: boolean;
+  skipConfiguredFallbackWhenActiveSessionNonAcp?: boolean;
+  fallbackToActiveAcpWhenUnbound?: boolean;
+}): string | undefined {
+  const activeSessionKey = normalizeOptionalString(params.activeSessionKey);
+  const activeAcpSessionKey =
+    activeSessionKey && isAcpSessionKey(activeSessionKey) ? activeSessionKey : undefined;
+  const activeIsNonAcp = Boolean(activeSessionKey) && !activeAcpSessionKey;
+
+  const channel = normalizeLowercaseStringOrEmpty(normalizeOptionalString(params.channel));
+  const conversationId = normalizeOptionalString(params.conversationId) ?? "";
+  if (!channel || !conversationId) {
+    return activeAcpSessionKey;
+  }
+  const accountId = resolveResetTargetAccountId({
+    cfg: params.cfg,
+    channel,
+    accountId: params.accountId,
+  });
+  const parentConversationId = normalizeOptionalString(params.parentConversationId) || undefined;
+  const allowNonAcpBindingSessionKey = Boolean(params.allowNonAcpBindingSessionKey);
+
+  const serviceBinding = getSessionBindingService().resolveByConversation({
+    channel,
+    accountId,
+    conversationId,
+    parentConversationId,
+  });
+  const serviceSessionKey =
+    serviceBinding?.targetKind === "session" ? serviceBinding.targetSessionKey.trim() : "";
+  if (serviceSessionKey) {
+    if (allowNonAcpBindingSessionKey) {
+      return serviceSessionKey;
+    }
+    return isAcpSessionKey(serviceSessionKey) ? serviceSessionKey : undefined;
+  }
+
+  if (activeIsNonAcp && params.skipConfiguredFallbackWhenActiveSessionNonAcp) {
+    return undefined;
+  }
+
+  const configuredBinding = resolveConfiguredBindingRecord({
+    cfg: params.cfg,
+    channel,
+    accountId,
+    conversationId,
+    parentConversationId,
+  });
+  const configuredSessionKey =
+    configuredBinding?.record.targetKind === "session"
+      ? configuredBinding.record.targetSessionKey.trim()
+      : "";
+  if (configuredSessionKey) {
+    if (allowNonAcpBindingSessionKey) {
+      return configuredSessionKey;
+    }
+    return isAcpSessionKey(configuredSessionKey) ? configuredSessionKey : undefined;
+  }
+
+  const rawConfiguredSessionKey = resolveRawConfiguredAcpSessionKey({
+    cfg: params.cfg,
+    channel,
+    accountId,
+    conversationId,
+    ...(parentConversationId ? { parentConversationId } : {}),
+  });
+  if (rawConfiguredSessionKey) {
+    return rawConfiguredSessionKey;
+  }
+
+  if (params.fallbackToActiveAcpWhenUnbound === false) {
+    return undefined;
+  }
+  return activeAcpSessionKey;
+}

src/auto-reply/reply/acp-stream-settings.test.ts

@@ -0,0 +1,112 @@
+/** Tests ACP stream settings normalization from config. */
+import { describe, expect, it } from "vitest";
+import {
+  isAcpTagVisible,
+  resolveAcpProjectionSettings,
+  resolveAcpStreamingConfig,
+} from "./acp-stream-settings.js";
+import { createAcpTestConfig } from "./test-fixtures/acp-runtime.js";
+
+describe("acp stream settings", () => {
+  it("resolves stable defaults", () => {
+    const settings = resolveAcpProjectionSettings(createAcpTestConfig());
+    expect(settings.deliveryMode).toBe("final_only");
+    expect(settings.hiddenBoundarySeparator).toBe("paragraph");
+    expect(settings.repeatSuppression).toBe(true);
+    expect(settings.maxOutputChars).toBe(24_000);
+    expect(settings.maxSessionUpdateChars).toBe(320);
+  });
+
+  it("applies retained stream overrides while preserving built-in tuning", () => {
+    const settings = resolveAcpProjectionSettings(
+      createAcpTestConfig({
+        acp: {
+          enabled: true,
+          stream: {
+            deliveryMode: "final_only",
+            repeatSuppression: false,
+            tagVisibility: {
+              usage_update: true,
+            },
+          },
+        },
+      }),
+    );
+    expect(settings.deliveryMode).toBe("final_only");
+    expect(settings.hiddenBoundarySeparator).toBe("paragraph");
+    expect(settings.repeatSuppression).toBe(false);
+    expect(settings.maxOutputChars).toBe(24_000);
+    expect(settings.maxSessionUpdateChars).toBe(320);
+    expect(settings.tagVisibility.usage_update).toBe(true);
+  });
+
+  it("accepts explicit deliveryMode=live override", () => {
+    const settings = resolveAcpProjectionSettings(
+      createAcpTestConfig({
+        acp: {
+          enabled: true,
+          stream: {
+            deliveryMode: "live",
+          },
+        },
+      }),
+    );
+    expect(settings.deliveryMode).toBe("live");
+    expect(settings.hiddenBoundarySeparator).toBe("space");
+  });
+
+  it("uses default tag visibility when no override is provided", () => {
+    const settings = resolveAcpProjectionSettings(createAcpTestConfig());
+    expect(isAcpTagVisible(settings, "tool_call")).toBe(false);
+    expect(isAcpTagVisible(settings, "tool_call_update")).toBe(false);
+    expect(isAcpTagVisible(settings, "usage_update")).toBe(false);
+  });
+
+  it("respects tag visibility overrides", () => {
+    const settings = resolveAcpProjectionSettings(
+      createAcpTestConfig({
+        acp: {
+          enabled: true,
+          stream: {
+            tagVisibility: {
+              usage_update: true,
+              tool_call: false,
+            },
+          },
+        },
+      }),
+    );
+    expect(isAcpTagVisible(settings, "usage_update")).toBe(true);
+    expect(isAcpTagVisible(settings, "tool_call")).toBe(false);
+  });
+
+  it("resolves built-in ACP chunking and coalescing", () => {
+    const streaming = resolveAcpStreamingConfig({
+      cfg: createAcpTestConfig(),
+      provider: "quietchat",
+    });
+    expect(streaming.chunking.maxChars).toBe(1800);
+    expect(streaming.coalescing.idleMs).toBe(350);
+  });
+
+  it("applies live-mode delivery with built-in streaming tuning", () => {
+    const streaming = resolveAcpStreamingConfig({
+      cfg: createAcpTestConfig({
+        acp: {
+          enabled: true,
+          stream: {
+            deliveryMode: "live",
+          },
+        },
+      }),
+      provider: "quietchat",
+      deliveryMode: "live",
+    });
+    expect(streaming.chunking.minChars).toBe(1);
+    expect(streaming.chunking.maxChars).toBe(1800);
+    expect(streaming.coalescing.minChars).toBe(1);
+    expect(streaming.coalescing.maxChars).toBe(1800);
+    expect(streaming.coalescing.joiner).toBe("");
+    expect(streaming.coalescing.idleMs).toBe(350);
+  });
+});

src/auto-reply/reply/acp-stream-settings.ts

@@ -0,0 +1,134 @@
+/** ACP streaming and projection settings derived from config. */
+import type { AcpSessionUpdateTag } from "@openclaw/acp-core/runtime/types";
+import type { OpenClawConfig } from "../../config/types.openclaw.js";
+import { resolveEffectiveBlockStreamingConfig } from "./block-streaming.js";
+
+const DEFAULT_ACP_STREAM_COALESCE_IDLE_MS = 350;
+const DEFAULT_ACP_STREAM_MAX_CHUNK_CHARS = 1800;
+const DEFAULT_ACP_REPEAT_SUPPRESSION = true;
+const DEFAULT_ACP_DELIVERY_MODE = "final_only";
+const DEFAULT_ACP_HIDDEN_BOUNDARY_SEPARATOR = "paragraph";
+const DEFAULT_ACP_HIDDEN_BOUNDARY_SEPARATOR_LIVE = "space";
+const DEFAULT_ACP_MAX_OUTPUT_CHARS = 24_000;
+const DEFAULT_ACP_MAX_SESSION_UPDATE_CHARS = 320;
+
+const ACP_TAG_VISIBILITY_DEFAULTS: Record<AcpSessionUpdateTag, boolean> = {
+  agent_message_chunk: true,
+  tool_call: false,
+  tool_call_update: false,
+  usage_update: false,
+  available_commands_update: false,
+  current_mode_update: false,
+  config_option_update: false,
+  session_info_update: false,
+  plan: false,
+  agent_thought_chunk: false,
+};
+
+function isAcpSessionUpdateTag(tag: string): tag is AcpSessionUpdateTag {
+  return Object.hasOwn(ACP_TAG_VISIBILITY_DEFAULTS, tag);
+}
+
+/** ACP delivery strategy for projected assistant output. */
+type AcpDeliveryMode = "live" | "final_only";
+export type AcpHiddenBoundarySeparator = "none" | "space" | "newline" | "paragraph";
+
+/** Normalized ACP projection settings consumed by stream projectors. */
+export type AcpProjectionSettings = {
+  deliveryMode: AcpDeliveryMode;
+  hiddenBoundarySeparator: AcpHiddenBoundarySeparator;
+  repeatSuppression: boolean;
+  maxOutputChars: number;
+  maxSessionUpdateChars: number;
+  tagVisibility: Partial<Record<AcpSessionUpdateTag, boolean>>;
+};
+
+function clampBoolean(value: unknown, fallback: boolean): boolean {
+  return typeof value === "boolean" ? value : fallback;
+}
+
+function resolveAcpDeliveryMode(value: unknown): AcpDeliveryMode {
+  if (value === "live" || value === "final_only") {
+    return value;
+  }
+  return DEFAULT_ACP_DELIVERY_MODE;
+}
+
+function resolveAcpStreamCoalesceIdleMs(): number {
+  return DEFAULT_ACP_STREAM_COALESCE_IDLE_MS;
+}
+
+function resolveAcpStreamMaxChunkChars(): number {
+  return DEFAULT_ACP_STREAM_MAX_CHUNK_CHARS;
+}
+
+/** Resolves ACP projection settings with bounded defaults. */
+export function resolveAcpProjectionSettings(cfg: OpenClawConfig): AcpProjectionSettings {
+  const stream = cfg.acp?.stream;
+  const deliveryMode = resolveAcpDeliveryMode(stream?.deliveryMode);
+  const hiddenBoundaryFallback: AcpHiddenBoundarySeparator =
+    deliveryMode === "live"
+      ? DEFAULT_ACP_HIDDEN_BOUNDARY_SEPARATOR_LIVE
+      : DEFAULT_ACP_HIDDEN_BOUNDARY_SEPARATOR;
+  return {
+    deliveryMode,
+    hiddenBoundarySeparator: hiddenBoundaryFallback,
+    repeatSuppression: clampBoolean(stream?.repeatSuppression, DEFAULT_ACP_REPEAT_SUPPRESSION),
+    maxOutputChars: DEFAULT_ACP_MAX_OUTPUT_CHARS,
+    maxSessionUpdateChars: DEFAULT_ACP_MAX_SESSION_UPDATE_CHARS,
+    tagVisibility: stream?.tagVisibility ?? {},
+  };
+}
+
+/** Resolves ACP streaming chunk/coalescing settings. */
+export function resolveAcpStreamingConfig(params: {
+  cfg: OpenClawConfig;
+  provider?: string;
+  accountId?: string;
+  deliveryMode?: AcpDeliveryMode;
+}) {
+  const resolved = resolveEffectiveBlockStreamingConfig({
+    cfg: params.cfg,
+    provider: params.provider,
+    accountId: params.accountId,
+    maxChunkChars: resolveAcpStreamMaxChunkChars(),
+    coalesceIdleMs: resolveAcpStreamCoalesceIdleMs(),
+  });
+
+  // In live mode, ACP text deltas should flush promptly and never be held
+  // behind large generic min-char thresholds.
+  if (params.deliveryMode === "live") {
+    return {
+      chunking: {
+        ...resolved.chunking,
+        minChars: 1,
+      },
+      coalescing: {
+        ...resolved.coalescing,
+        minChars: 1,
+        // ACP delta streams already carry spacing/newlines; preserve exact text.
+        joiner: "",
+      },
+    };
+  }
+
+  return resolved;
+}
+
+export function isAcpTagVisible(settings: AcpProjectionSettings, tag: string | undefined): boolean {
+  if (!tag) {
+    return true;
+  }
+  if (!isAcpSessionUpdateTag(tag)) {
+    return true;
+  }
+  const override = settings.tagVisibility[tag];
+  if (typeof override === "boolean") {
+    return override;
+  }
+  const defaultVisibility = ACP_TAG_VISIBILITY_DEFAULTS[tag];
+  if (defaultVisibility === undefined) {
+    throw new Error(`Missing ACP visibility default for ${tag}`);
+  }
+  return defaultVisibility;
+}

src/auto-reply/reply/agent-event-bridge.test.ts

@@ -0,0 +1,136 @@
+// Covers the shared CLI delivery bridge's subscription scope. Every concurrent
+// CLI run builds up to eight of these bridges, so a bridge that subscribes
+// globally and discards foreign runs makes per-delta cost grow with agent count.
+import { beforeEach, describe, expect, test } from "vitest";
+import { emitAgentEvent, onAgentEvent, resetAgentEventsForTest } from "../../infra/agent-events.js";
+import { registerAgentRunContext } from "../../infra/agent-run-registry.js";
+import { createAgentEventBridge } from "./agent-event-bridge.js";
+
+function textBridge(runId: string, sink: string[]) {
+  return createAgentEventBridge<string>({
+    runId,
+    read: (evt) => (typeof evt.data.text === "string" ? evt.data.text : undefined),
+    deliver: async (text) => {
+      sink.push(text);
+    },
+  });
+}
+
+describe("agent event delivery bridge", () => {
+  beforeEach(() => {
+    resetAgentEventsForTest();
+  });
+
+  test.each([1, 4, 16, 64])(
+    "isolates every delivery bridge while %s CLI runs stream interleaved events",
+    async (runs) => {
+      let predicateReads = 0;
+      const bridges = Array.from({ length: runs }, (_, runIndex) => {
+        const runId = `run-${runIndex}`;
+        registerAgentRunContext(runId, { sessionKey: `session-${runIndex}` });
+        return Array.from({ length: 8 }, (_bridge, bridgeIndex) => {
+          const delivered: string[] = [];
+          const bridge = createAgentEventBridge<string>({
+            get runId() {
+              predicateReads++;
+              return runId;
+            },
+            read: (event) => (typeof event.data.text === "string" ? event.data.text : undefined),
+            deliver: async (text) => {
+              delivered.push(text);
+            },
+          });
+          return { ...bridge, delivered, runIndex, bridgeIndex };
+        });
+      }).flat();
+      try {
+        predicateReads = 0;
+        emitAgentEvent({ runId: "run-0", stream: "assistant", data: { text: "a1" } });
+        // Source-pinned work measurement only: hoisting the filter can change this
+        // count without changing dispatch complexity. Output assertions own the test.
+        console.info("bridge predicate-read diagnostic (not latency)", {
+          runs,
+          bridgesPerRun: 8,
+          predicateReads,
+        });
+        emitAgentEvent({ runId: "run-1", stream: "assistant", data: { text: "b1" } });
+        emitAgentEvent({ runId: "run-0", stream: "assistant", data: { text: "a2" } });
+        await Promise.all(bridges.map((bridge) => bridge.drain()));
+        for (const { delivered, runIndex, bridgeIndex } of bridges) {
+          expect(delivered, `run-${runIndex}/bridge-${bridgeIndex}`).toEqual(
+            runIndex === 0 ? ["a1", "a2"] : runIndex === 1 ? ["b1"] : [],
+          );
+        }
+      } finally {
+        for (const bridge of bridges) {
+          bridge.unsubscribe();
+        }
+      }
+    },
+  );
+
+  test("keeps stream delivery order when a later global listener emits another event", async () => {
+    registerAgentRunContext("run-nested", { sessionKey: "session-nested" });
+    const delivered: string[] = [];
+    const bridge = textBridge("run-nested", delivered);
+    const stopGlobal = onAgentEvent((evt) => {
+      if (evt.runId === "run-nested" && evt.data.text === "outer") {
+        emitAgentEvent({ runId: "run-nested", stream: "assistant", data: { text: "inner" } });
+      }
+    });
+    try {
+      emitAgentEvent({ runId: "run-nested", stream: "assistant", data: { text: "outer" } });
+      await bridge.drain();
+      expect(delivered).toEqual(["outer", "inner"]);
+    } finally {
+      stopGlobal();
+      bridge.unsubscribe();
+    }
+  });
+
+  test("delivers the current event before a later global listener unsubscribes the bridge", async () => {
+    registerAgentRunContext("run-unsubscribe", { sessionKey: "session-unsubscribe" });
+    const delivered: string[] = [];
+    const bridge = textBridge("run-unsubscribe", delivered);
+    const stopGlobal = onAgentEvent((evt) => {
+      if (evt.runId === "run-unsubscribe") {
+        bridge.unsubscribe();
+      }
+    });
+    try {
+      emitAgentEvent({ runId: "run-unsubscribe", stream: "assistant", data: { text: "first" } });
+      emitAgentEvent({ runId: "run-unsubscribe", stream: "assistant", data: { text: "second" } });
+      await bridge.drain();
+      expect(delivered).toEqual(["first"]);
+    } finally {
+      stopGlobal();
+      bridge.unsubscribe();
+    }
+  });
+
+  test("routes a changed event identity only to later matching bridges", async () => {
+    registerAgentRunContext("run-a", { sessionKey: "session-a" });
+    registerAgentRunContext("run-b", { sessionKey: "session-b" });
+    const earlierB: string[] = [];
+    const laterB: string[] = [];
+    const laterA: string[] = [];
+    const first = textBridge("run-b", earlierB);
+    const stopGlobal = onAgentEvent((event) => {
+      event.runId = "run-b";
+    });
+    const second = textBridge("run-b", laterB);
+    const third = textBridge("run-a", laterA);
+    try {
+      emitAgentEvent({ runId: "run-a", stream: "assistant", data: { text: "changed" } });
+      await Promise.all([first.drain(), second.drain(), third.drain()]);
+      expect(earlierB).toEqual([]);
+      expect(laterB).toEqual(["changed"]);
+      expect(laterA).toEqual([]);
+    } finally {
+      stopGlobal();
+      first.unsubscribe();
+      second.unsubscribe();
+      third.unsubscribe();
+    }
+  });
+});

src/auto-reply/reply/agent-event-bridge.ts

@@ -0,0 +1,79 @@
+// Generic agent-event bridge machinery shared by the CLI runner's per-stream
+// delivery bridges (assistant, reasoning, commentary, plan).
+import { type AgentEventPayload, onAgentEventForRun } from "../../infra/agent-events.js";
+
+export type AgentEventDeliveryStartOrder = {
+  schedule: (deliver: () => Promise<unknown>) => Promise<void>;
+};
+
+export function createAgentEventDeliveryStartOrder(): AgentEventDeliveryStartOrder {
+  let startTail = Promise.resolve();
+  return {
+    schedule: async (deliver) => {
+      // Reserve at raw event receipt, then release at callback invocation. CLI streams drain
+      // independently, so waiting for callback completion here would reorder later streams.
+      const previousStart = startTail;
+      let releaseStart: (() => void) | undefined;
+      startTail = new Promise<void>((resolve) => {
+        releaseStart = resolve;
+      });
+      await previousStart;
+      let delivery: Promise<unknown>;
+      try {
+        delivery = deliver();
+      } finally {
+        releaseStart?.();
+      }
+      await delivery;
+    },
+  };
+}
+
+export function createAgentEventBridge<T>(params: {
+  runId: string;
+  suppressed?: boolean;
+  read: (evt: AgentEventPayload) => T | undefined;
+  deliver?: (payload: T) => Promise<unknown>;
+  startOrder?: AgentEventDeliveryStartOrder;
+}) {
+  const deliver = params.deliver;
+  if (!deliver) {
+    return {
+      unsubscribe: () => undefined,
+      drain: async (): Promise<void> => undefined,
+    };
+  }
+  let unsubscribed = false;
+  let delivery: Promise<unknown> = Promise.resolve();
+  const rawUnsubscribe = onAgentEventForRun(params.runId, (evt) => {
+    if (evt.runId !== params.runId) {
+      return;
+    }
+    if (params.suppressed) {
+      return;
+    }
+    const payload = params.read(evt);
+    if (payload === undefined) {
+      return;
+    }
+    if (!params.startOrder) {
+      delivery = delivery.then(() => deliver(payload)).catch(() => undefined);
+      return;
+    }
+    const scheduled = params.startOrder.schedule(() => deliver(payload)).catch(() => undefined);
+    // Start ordering stays global; each bridge still owns and drains its callback completion.
+    delivery = Promise.all([delivery, scheduled]).then(() => undefined);
+  });
+  return {
+    unsubscribe() {
+      if (unsubscribed) {
+        return;
+      }
+      unsubscribed = true;
+      rawUnsubscribe();
+    },
+    async drain(): Promise<void> {
+      await delivery;
+    },
+  };
+}

src/auto-reply/reply/agent-lifecycle-terminal.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it, vi } from "vitest";
+import { OAuthRefreshFailureError } from "../../agents/auth-profiles/oauth-refresh-failure.js";
+import { FailoverError } from "../../agents/failover-error.js";
+import { renderFailoverCodeUserCopy } from "../../agents/failover/user-copy.js";
+import * as providerFailover from "../../plugins/provider-failover.js";
+import { createAgentLifecycleTerminalBackstop } from "./agent-lifecycle-terminal.js";
+
+const { emitAgentEvent } = vi.hoisted(() => ({ emitAgentEvent: vi.fn() }));
+
+vi.mock("../../infra/agent-events.js", () => ({ emitAgentEvent }));
+
+describe("createAgentLifecycleTerminalBackstop", () => {
+  it.each([false, true])("keeps only the selected attempt receipt (retry=%s)", (retry) => {
+    emitAgentEvent.mockClear();
+    const terminal = createAgentLifecycleTerminalBackstop({
+      runId: "run",
+      getLifecycleGeneration: () => "generation",
+      resolveTerminationFields: () => ({}),
+    });
+    terminal.note({
+      stream: "lifecycle",
+      data: {
+        phase: "finishing",
+        error: "first failure",
+        assistantTranscriptIdempotencyKey: "saved-A",
+      },
+    });
+    terminal.capture("error", new Error("first failure"));
+    expect(emitAgentEvent).not.toHaveBeenCalled();
+    if (retry) {
+      // Preparation fails before the next lifecycle start can be emitted.
+      terminal.beginAttempt();
+    }
+    terminal.emit("error", new Error(retry ? "preparation failed" : "first failure"));
+    expect(emitAgentEvent).toHaveBeenCalledOnce();
+    const data = emitAgentEvent.mock.calls[0]?.[0]?.data;
+    expect(data.assistantTranscriptIdempotencyKey).toBe(retry ? undefined : "saved-A");
+    expect(data.error).toBe(retry ? "preparation failed" : "first failure");
+    expect(data.executionSettled).toBe(true);
+  });
+
+  it("publishes the provider-owned OAuth summary instead of the wrapped diagnostic", () => {
+    emitAgentEvent.mockClear();
+    const summary =
+      "Your refresh token has already been used to generate a new access token. Please try signing in again.";
+    const rawDiagnostic = `OAuth token refresh failed for openai: {"error":{"message":"${summary}"}}`;
+    const oauthError = new OAuthRefreshFailureError({
+      provider: "openai",
+      message: rawDiagnostic,
+      errorType: "invalid_request_error",
+      reason: "refresh_token_reused",
+      status: 401,
+      summary,
+    });
+    const error = new Error("wrapped OAuth refresh failure", { cause: oauthError });
+    const terminal = createAgentLifecycleTerminalBackstop({
+      runId: "oauth-refresh-failure",
+      getLifecycleGeneration: () => "test-generation",
+      resolveTerminationFields: () => ({}),
+    });
+
+    terminal.emit("error", error);
+
+    const event = emitAgentEvent.mock.calls[0]?.[0];
+    expect(event.data.error).toBe(`⚠️ ${summary}`);
+    expect(event.data.errorObservation).toEqual({
+      provider: "openai",
+      failoverReason: "refresh_token_reused",
+      providerRuntimeFailureKind: "auth_refresh",
+      providerErrorType: "invalid_request_error",
+      httpStatus: 401,
+    });
+    expect(JSON.stringify(event)).not.toContain(rawDiagnostic);
+  });
+
+  it.each(["typed", "raw"] as const)(
+    "publishes bounded selected-profile recovery from %s failures without discovering providers",
+    (kind) => {
+      const classifyProvider = vi
+        .spyOn(providerFailover, "classifyProviderFailoverSignalWithPlugin")
+        .mockImplementation(() => {
+          throw new Error("Terminal presentation must not discover providers");
+        });
+      emitAgentEvent.mockClear();
+      try {
+        const profileId = "openai:private-profile";
+        const rawCause = `Codex app-server auth profile "${profileId}" was not found`;
+        const terminal = createAgentLifecycleTerminalBackstop({
+          runId: "missing-selected-profile",
+          sessionKey: "agent:main:test",
+          getLifecycleGeneration: () => "test-generation",
+          resolveTerminationFields: () => ({}),
+        });
+
+        const error =
+          kind === "typed"
+            ? new FailoverError(rawCause, {
+                reason: "auth",
+                code: "selected_auth_profile_unavailable",
+                profileId,
+                cause: new Error(rawCause),
+              })
+            : Object.assign(new Error(rawCause), {
+                code: "selected_auth_profile_unavailable",
+              });
+        terminal.emit("error", error);
+
+        const event = emitAgentEvent.mock.calls[0]?.[0];
+        expect(event.data.error).toBe(
+          renderFailoverCodeUserCopy("selected_auth_profile_unavailable"),
+        );
+        expect(JSON.stringify(event)).not.toContain(profileId);
+        expect(JSON.stringify(event)).not.toContain(rawCause);
+        expect(classifyProvider).not.toHaveBeenCalled();
+      } finally {
+        classifyProvider.mockRestore();
+      }
+    },
+  );
+});

src/auto-reply/reply/agent-lifecycle-terminal.ts

@@ -0,0 +1,192 @@
+import { readStringValue } from "@openclaw/normalization-core/string-coerce";
+import { classifyOAuthRefreshFailureError } from "../../agents/auth-profiles/oauth-refresh-failure.js";
+import { getFailoverErrorCode } from "../../agents/failover/error.js";
+import { renderFailoverCodeUserCopy } from "../../agents/failover/user-copy.js";
+import { AGENT_RUN_RESTART_ABORT_STOP_REASON } from "../../agents/run-termination.js";
+import { emitAgentEvent } from "../../infra/agent-events.js";
+import { formatErrorMessage } from "../../infra/errors.js";
+
+export type AgentLifecycleTerminalBackstop = {
+  beginAttempt: () => void;
+  capture: AgentLifecycleTerminalBackstop["emit"];
+  emit: (
+    phase: "end" | "error",
+    resultOrError: unknown,
+    extraData?: Record<string, unknown>,
+  ) => void;
+  getDeferredError: () => string | undefined;
+  note: (evt: { stream: string; data: Record<string, unknown> }) => void;
+};
+
+type PendingLifecycleTerminal = {
+  kind: "pending";
+  deferredError?: string;
+  metadata: Record<string, unknown>;
+};
+
+type LifecycleTerminalState =
+  | PendingLifecycleTerminal
+  | { kind: "captured"; event: Parameters<typeof emitAgentEvent>[0] }
+  | { kind: "emitted" };
+
+const DEFERRED_TERMINAL_METADATA_KEYS = [
+  "stopReason",
+  "yielded",
+  "timeoutPhase",
+  "providerStarted",
+  "aborted",
+  "livenessState",
+  "replayInvalid",
+  "errorObservation",
+  "assistantTranscriptIdempotencyKey",
+] as const;
+
+export function resolveAgentLifecycleTerminalMetadata(meta: unknown): Record<string, unknown> {
+  const metadata: Record<string, unknown> = {};
+  if (!meta || typeof meta !== "object") {
+    return metadata;
+  }
+  const record = meta as Record<string, unknown>;
+  for (const key of DEFERRED_TERMINAL_METADATA_KEYS) {
+    if (Object.hasOwn(record, key)) {
+      metadata[key] = record[key];
+    }
+  }
+  return metadata;
+}
+
+export function createAgentLifecycleTerminalBackstop(params: {
+  runId: string;
+  sessionKey?: string;
+  startedAt?: number;
+  getLifecycleGeneration: () => string;
+  onTerminalEvent?: (event: Parameters<typeof emitAgentEvent>[0]) => void;
+  resolveTerminationFields: (error?: unknown) => {
+    aborted?: true;
+    stopReason?: string;
+    timeoutPhase?: string;
+  };
+}): AgentLifecycleTerminalBackstop {
+  let state: LifecycleTerminalState = { kind: "pending", metadata: {} };
+  // Preparation can fail before a lifecycle start. Capture its real boundary
+  // without signaling readiness; an observed model start replaces it below.
+  let startedAt = params.startedAt ?? Date.now();
+  const beginAttempt = () => {
+    if (state.kind !== "emitted") {
+      state = { kind: "pending", metadata: {} };
+    }
+  };
+
+  const note = (evt: { stream: string; data: Record<string, unknown> }) => {
+    if (state.kind === "emitted" || evt.stream !== "lifecycle") {
+      return;
+    }
+    const phase = readStringValue(evt.data.phase);
+    if (phase === "start") {
+      beginAttempt();
+      if (typeof evt.data.startedAt === "number") {
+        startedAt = evt.data.startedAt;
+      }
+    }
+    if (phase === "finishing" && state.kind === "pending") {
+      state.deferredError = readStringValue(evt.data.error) ?? state.deferredError;
+      Object.assign(state.metadata, resolveAgentLifecycleTerminalMetadata(evt.data));
+    }
+    if (phase === "end" || phase === "error") {
+      state = { kind: "emitted" };
+    }
+  };
+
+  const prepareTerminal = (
+    pending: PendingLifecycleTerminal,
+    phase: "end" | "error",
+    resultOrError: unknown,
+    extraData?: Record<string, unknown>,
+  ): Parameters<typeof emitAgentEvent>[0] => {
+    const terminationFields = params.resolveTerminationFields(
+      phase === "error" ? resultOrError : undefined,
+    );
+    const restartAbort = terminationFields.stopReason === AGENT_RUN_RESTART_ABORT_STOP_REASON;
+    const data: Record<string, unknown> = {
+      ...pending.metadata,
+      phase: restartAbort ? "end" : phase,
+      endedAt: Date.now(),
+      startedAt,
+    };
+    if (restartAbort) {
+      data.aborted = true;
+      data.stopReason = AGENT_RUN_RESTART_ABORT_STOP_REASON;
+    } else if (phase === "error") {
+      const oauthFailure = classifyOAuthRefreshFailureError(resultOrError);
+      data.error =
+        renderFailoverCodeUserCopy(getFailoverErrorCode(resultOrError)) ??
+        (oauthFailure?.summary ? `⚠️ ${oauthFailure.summary}` : undefined) ??
+        formatErrorMessage(resultOrError);
+      if (oauthFailure?.summary) {
+        data.errorObservation = {
+          ...(oauthFailure.provider ? { provider: oauthFailure.provider } : {}),
+          ...(oauthFailure.reason ? { failoverReason: oauthFailure.reason } : {}),
+          providerRuntimeFailureKind: "auth_refresh",
+          ...(oauthFailure.errorType ? { providerErrorType: oauthFailure.errorType } : {}),
+          ...(oauthFailure.status ? { httpStatus: oauthFailure.status } : {}),
+        };
+      }
+      Object.assign(data, terminationFields);
+    } else {
+      const meta =
+        resultOrError && typeof resultOrError === "object" && "meta" in resultOrError
+          ? (resultOrError as { meta?: Record<string, unknown> }).meta
+          : undefined;
+      Object.assign(data, resolveAgentLifecycleTerminalMetadata(meta));
+      if (terminationFields.aborted === true) {
+        data.aborted = true;
+      }
+      if (terminationFields.stopReason && !readStringValue(data.stopReason)) {
+        data.stopReason = terminationFields.stopReason;
+      }
+    }
+    if (extraData) {
+      Object.assign(data, extraData);
+    }
+    return {
+      runId: params.runId,
+      lifecycleGeneration: params.getLifecycleGeneration(),
+      ...(params.sessionKey ? { sessionKey: params.sessionKey } : {}),
+      stream: "lifecycle",
+      data,
+    };
+  };
+
+  const capture: AgentLifecycleTerminalBackstop["capture"] = (phase, resultOrError, extraData) => {
+    if (state.kind === "pending") {
+      // Record bounded terminal facts before awaited bookkeeping can change
+      // the abort signal, lifecycle generation, or subsequent workflow outcome.
+      const event = prepareTerminal(state, phase, resultOrError, extraData);
+      state = { kind: "captured", event };
+    }
+  };
+  const emit: AgentLifecycleTerminalBackstop["emit"] = (phase, resultOrError, extraData) => {
+    const current = state;
+    if (current.kind === "emitted") {
+      return;
+    }
+    state = { kind: "emitted" };
+    const event =
+      current.kind === "captured"
+        ? current.event
+        : prepareTerminal(current, phase, resultOrError, extraData);
+    // Captured candidates can still be replaced by retries. Only publication
+    // settles execution; delivery and yielded-parent continuation remain separate.
+    const settled = { ...event, data: { ...event.data, executionSettled: true } };
+    emitAgentEvent(settled);
+    params.onTerminalEvent?.(settled);
+  };
+
+  return {
+    beginAttempt,
+    capture,
+    emit,
+    getDeferredError: () => (state.kind === "pending" ? state.deferredError : undefined),
+    note,
+  };
+}

src/auto-reply/reply/agent-runner-auth-profile.ts

@@ -0,0 +1,76 @@
+// Resolves auth profile settings that agent runner forwards to providers.
+import { normalizeProviderId } from "@openclaw/model-catalog-core/provider-id";
+import {
+  resolveProviderIdForAuth,
+  type ProviderAuthAliasLookupParams,
+} from "../../agents/provider-auth-aliases.js";
+import type { FollowupRun } from "./queue.js";
+
+/** Keeps an auth profile only when the current provider shares the primary auth scope. */
+export function resolveProviderScopedAuthProfile(params: {
+  provider: string;
+  primaryProvider: string;
+  authProfileId?: string;
+  authProfileIdSource?: "auto" | "user";
+  config?: ProviderAuthAliasLookupParams["config"];
+  workspaceDir?: ProviderAuthAliasLookupParams["workspaceDir"];
+}): { authProfileId?: string; authProfileIdSource?: "auto" | "user" } {
+  const aliasParams = { config: params.config, workspaceDir: params.workspaceDir };
+  const providerId = normalizeProviderId(params.provider);
+  const primaryProviderId = normalizeProviderId(params.primaryProvider);
+  const sharesAuthScope =
+    (providerId !== "" && providerId === primaryProviderId) ||
+    resolveProviderIdForAuth(params.provider, aliasParams) ===
+      resolveProviderIdForAuth(params.primaryProvider, aliasParams);
+  const authProfileId = sharesAuthScope ? params.authProfileId : undefined;
+  return {
+    authProfileId,
+    authProfileIdSource: authProfileId ? params.authProfileIdSource : undefined,
+  };
+}
+
+/** Resolves the auth profile override for a queued follow-up run. */
+export function resolveRunAuthProfile(
+  run: FollowupRun["run"],
+  provider: string,
+  params?: { config?: ProviderAuthAliasLookupParams["config"] },
+) {
+  return resolveProviderScopedAuthProfile({
+    provider,
+    primaryProvider: run.provider,
+    authProfileId: run.authProfileId,
+    authProfileIdSource: run.authProfileIdSource,
+    config: params?.config ?? run.config,
+    workspaceDir: run.workspaceDir,
+  });
+}
+
+/** Applies an auto-fallback probe's pinned auth to its fallback candidate. */
+export function resolveFallbackCandidateRun(
+  run: FollowupRun["run"],
+  provider: string,
+  model: string,
+): FollowupRun["run"] {
+  const probe = run.autoFallbackPrimaryProbe;
+  const isPrimaryProbeCandidate = probe && provider === probe.provider && model === probe.model;
+  if (
+    !probe ||
+    provider !== probe.fallbackProvider ||
+    isPrimaryProbeCandidate ||
+    !probe.fallbackAuthProfileId
+  ) {
+    return run;
+  }
+  const candidateRun: FollowupRun["run"] = {
+    ...run,
+    provider,
+    model,
+    authProfileId: probe.fallbackAuthProfileId,
+  };
+  if (probe.fallbackAuthProfileIdSource) {
+    candidateRun.authProfileIdSource = probe.fallbackAuthProfileIdSource;
+  } else {
+    delete candidateRun.authProfileIdSource;
+  }
+  return candidateRun;
+}

src/auto-reply/reply/agent-runner-auto-fallback.test.ts

@@ -0,0 +1,427 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { SessionEntry } from "../../config/sessions.js";
+import type { FollowupRun } from "./queue.js";
+
+const state = vi.hoisted(() => ({
+  updateSessionEntryMock: vi.fn(),
+}));
+
+vi.mock("../../config/sessions/session-accessor.js", () => ({
+  updateSessionEntry: (...args: unknown[]) => state.updateSessionEntryMock(...args),
+}));
+
+import { clearRecoveredAutoFallbackPrimaryProbeSelection } from "./agent-runner-auto-fallback.js";
+
+describe("clearRecoveredAutoFallbackPrimaryProbeSelection", () => {
+  beforeEach(() => {
+    state.updateSessionEntryMock.mockReset();
+  });
+
+  it("refreshes the local selection when the persisted comparison rejects the probe", async () => {
+    const probe = {
+      provider: "anthropic",
+      model: "claude-sonnet-4-6",
+      fallbackProvider: "openai",
+      fallbackModel: "gpt-5.4",
+    };
+    const staleAutoEntry: SessionEntry = {
+      sessionId: "session",
+      updatedAt: 1,
+      providerOverride: probe.fallbackProvider,
+      modelOverride: probe.fallbackModel,
+      modelOverrideSource: "auto",
+      modelOverrideFallbackOriginProvider: probe.provider,
+      modelOverrideFallbackOriginModel: probe.model,
+    };
+    const newerUserEntry: SessionEntry = {
+      sessionId: "newer-session",
+      updatedAt: 2,
+      providerOverride: "openai",
+      modelOverride: "gpt-5.5",
+      modelOverrideSource: "user",
+    };
+    const activeSessionStore = { main: staleAutoEntry };
+    state.updateSessionEntryMock.mockImplementationOnce(
+      async (_scope: unknown, update: (entry: SessionEntry) => unknown) => {
+        expect(await update(newerUserEntry)).toBeNull();
+        return null;
+      },
+    );
+
+    await clearRecoveredAutoFallbackPrimaryProbeSelection({
+      run: {
+        provider: probe.provider,
+        model: probe.model,
+        autoFallbackPrimaryProbe: probe,
+      } as FollowupRun["run"],
+      provider: probe.provider,
+      model: probe.model,
+      sessionKey: "main",
+      activeSessionStore,
+      getActiveSessionEntry: () => staleAutoEntry,
+      storePath: "/tmp/sessions.sqlite",
+    });
+
+    expect(activeSessionStore.main).toBe(newerUserEntry);
+    expect(activeSessionStore.main).toMatchObject({
+      sessionId: "newer-session",
+      providerOverride: "openai",
+      modelOverride: "gpt-5.5",
+      modelOverrideSource: "user",
+    });
+  });
+
+  it("preserves an identically reselected persisted fallback generation", async () => {
+    const probe = {
+      provider: "anthropic",
+      model: "claude-sonnet-4-6",
+      fallbackProvider: "openai",
+      fallbackModel: "gpt-5.4",
+    };
+    const staleAutoEntry: SessionEntry = {
+      sessionId: "session",
+      updatedAt: 1,
+      providerOverride: probe.fallbackProvider,
+      modelOverride: probe.fallbackModel,
+      modelOverrideSource: "auto",
+      modelOverrideFallbackOriginProvider: probe.provider,
+      modelOverrideFallbackOriginModel: probe.model,
+    };
+    const newerAutoEntry: SessionEntry = {
+      ...staleAutoEntry,
+      updatedAt: 2,
+    };
+    const activeSessionStore = { main: staleAutoEntry };
+    state.updateSessionEntryMock.mockImplementationOnce(
+      async (_scope: unknown, update: (entry: SessionEntry) => unknown) => {
+        expect(await update(newerAutoEntry)).toBeNull();
+        return null;
+      },
+    );
+
+    await clearRecoveredAutoFallbackPrimaryProbeSelection({
+      run: {
+        provider: probe.provider,
+        model: probe.model,
+        autoFallbackPrimaryProbe: probe,
+      } as FollowupRun["run"],
+      provider: probe.provider,
+      model: probe.model,
+      sessionKey: "main",
+      activeSessionStore,
+      getActiveSessionEntry: () => staleAutoEntry,
+      storePath: "/tmp/sessions.sqlite",
+    });
+
+    expect(activeSessionStore.main).toBe(newerAutoEntry);
+    expect(activeSessionStore.main).toMatchObject({
+      providerOverride: probe.fallbackProvider,
+      modelOverride: probe.fallbackModel,
+      modelOverrideSource: "auto",
+      updatedAt: 2,
+    });
+  });
+
+  it("keeps a newer local selection installed while persistence is pending", async () => {
+    const probe = {
+      provider: "anthropic",
+      model: "claude-sonnet-4-6",
+      fallbackProvider: "openai",
+      fallbackModel: "gpt-5.4",
+    };
+    const staleAutoEntry: SessionEntry = {
+      sessionId: "session",
+      updatedAt: 1,
+      providerOverride: probe.fallbackProvider,
+      modelOverride: probe.fallbackModel,
+      modelOverrideSource: "auto",
+      modelOverrideFallbackOriginProvider: probe.provider,
+      modelOverrideFallbackOriginModel: probe.model,
+    };
+    const newerUserEntry: SessionEntry = {
+      sessionId: "session",
+      updatedAt: 2,
+      providerOverride: "openai",
+      modelOverride: "gpt-5.5",
+      modelOverrideSource: "user",
+    };
+    const activeSessionStore = { main: staleAutoEntry };
+    state.updateSessionEntryMock.mockImplementationOnce(
+      async (_scope: unknown, update: (entry: SessionEntry) => unknown) => {
+        const persistedEntry = { ...staleAutoEntry };
+        const patch = await update(persistedEntry);
+        activeSessionStore.main = newerUserEntry;
+        return { ...persistedEntry, ...(patch as Partial<SessionEntry>) };
+      },
+    );
+
+    await clearRecoveredAutoFallbackPrimaryProbeSelection({
+      run: {
+        provider: probe.provider,
+        model: probe.model,
+        autoFallbackPrimaryProbe: probe,
+      } as FollowupRun["run"],
+      provider: probe.provider,
+      model: probe.model,
+      sessionKey: "main",
+      activeSessionStore,
+      getActiveSessionEntry: () => staleAutoEntry,
+      storePath: "/tmp/sessions.sqlite",
+    });
+
+    expect(activeSessionStore.main).toBe(newerUserEntry);
+  });
+
+  it("preserves an in-place auth selection while applying persisted probe cleanup", async () => {
+    const probe = {
+      provider: "anthropic",
+      model: "claude-sonnet-4-6",
+      fallbackProvider: "openai",
+      fallbackModel: "gpt-5.4",
+    };
+    const staleAutoEntry: SessionEntry = {
+      sessionId: "session",
+      updatedAt: 1,
+      providerOverride: probe.fallbackProvider,
+      modelOverride: probe.fallbackModel,
+      modelOverrideSource: "auto",
+      modelOverrideFallbackOriginProvider: probe.provider,
+      modelOverrideFallbackOriginModel: probe.model,
+      authProfileOverride: "openai:fallback",
+      authProfileOverrideSource: "auto",
+    };
+    const activeSessionStore = { main: staleAutoEntry };
+    state.updateSessionEntryMock.mockImplementationOnce(
+      async (_scope: unknown, update: (entry: SessionEntry) => unknown) => {
+        const persistedEntry = { ...staleAutoEntry };
+        const patch = await update(persistedEntry);
+        Object.assign(staleAutoEntry, {
+          authProfileOverrideSource: "user",
+          updatedAt: 3,
+        });
+        return { ...persistedEntry, ...(patch as Partial<SessionEntry>) };
+      },
+    );
+
+    await clearRecoveredAutoFallbackPrimaryProbeSelection({
+      run: {
+        provider: probe.provider,
+        model: probe.model,
+        autoFallbackPrimaryProbe: probe,
+      } as FollowupRun["run"],
+      provider: probe.provider,
+      model: probe.model,
+      sessionKey: "main",
+      activeSessionStore,
+      getActiveSessionEntry: () => staleAutoEntry,
+      storePath: "/tmp/sessions.sqlite",
+    });
+
+    expect(activeSessionStore.main).not.toBe(staleAutoEntry);
+    expect(activeSessionStore.main).toMatchObject({
+      authProfileOverride: "openai:fallback",
+      authProfileOverrideSource: "user",
+      providerOverride: probe.fallbackProvider,
+      modelOverride: probe.fallbackModel,
+    });
+    expect(activeSessionStore.main.updatedAt).toBeGreaterThanOrEqual(3);
+  });
+
+  it("preserves a value-identical same-session cache replacement", async () => {
+    const probe = {
+      provider: "anthropic",
+      model: "claude-sonnet-4-6",
+      fallbackProvider: "openai",
+      fallbackModel: "gpt-5.4",
+    };
+    const staleAutoEntry: SessionEntry = {
+      sessionId: "session",
+      updatedAt: 1,
+      providerOverride: probe.fallbackProvider,
+      modelOverride: probe.fallbackModel,
+      modelOverrideSource: "auto",
+      modelOverrideFallbackOriginProvider: probe.provider,
+      modelOverrideFallbackOriginModel: probe.model,
+      authProfileOverride: "openai:fallback",
+      authProfileOverrideSource: "auto",
+    };
+    const replacementEntry: SessionEntry = {
+      ...staleAutoEntry,
+      updatedAt: 3,
+    };
+    const activeSessionStore = { main: staleAutoEntry };
+    state.updateSessionEntryMock.mockImplementationOnce(
+      async (_scope: unknown, update: (entry: SessionEntry) => unknown) => {
+        const persistedEntry = { ...staleAutoEntry };
+        const patch = await update(persistedEntry);
+        activeSessionStore.main = replacementEntry;
+        return { ...persistedEntry, ...(patch as Partial<SessionEntry>) };
+      },
+    );
+
+    await clearRecoveredAutoFallbackPrimaryProbeSelection({
+      run: {
+        provider: probe.provider,
+        model: probe.model,
+        autoFallbackPrimaryProbe: probe,
+      } as FollowupRun["run"],
+      provider: probe.provider,
+      model: probe.model,
+      sessionKey: "main",
+      activeSessionStore,
+      getActiveSessionEntry: () => staleAutoEntry,
+      storePath: "/tmp/sessions.sqlite",
+    });
+
+    expect(activeSessionStore.main).toBe(replacementEntry);
+    expect(activeSessionStore.main).toMatchObject({
+      authProfileOverride: "openai:fallback",
+      authProfileOverrideSource: "auto",
+      providerOverride: probe.fallbackProvider,
+      modelOverride: probe.fallbackModel,
+      updatedAt: 3,
+    });
+  });
+
+  it("preserves a same-session cache replacement when persistence has no row", async () => {
+    const probe = {
+      provider: "anthropic",
+      model: "claude-sonnet-4-6",
+      fallbackProvider: "openai",
+      fallbackModel: "gpt-5.4",
+    };
+    const staleAutoEntry: SessionEntry = {
+      sessionId: "session",
+      updatedAt: 1,
+      providerOverride: probe.fallbackProvider,
+      modelOverride: probe.fallbackModel,
+      modelOverrideSource: "auto",
+      modelOverrideFallbackOriginProvider: probe.provider,
+      modelOverrideFallbackOriginModel: probe.model,
+    };
+    const replacementEntry: SessionEntry = {
+      ...staleAutoEntry,
+      updatedAt: 2,
+    };
+    const activeSessionStore = { main: staleAutoEntry };
+    state.updateSessionEntryMock.mockImplementationOnce(async () => {
+      activeSessionStore.main = replacementEntry;
+      return undefined;
+    });
+
+    await clearRecoveredAutoFallbackPrimaryProbeSelection({
+      run: {
+        provider: probe.provider,
+        model: probe.model,
+        autoFallbackPrimaryProbe: probe,
+      } as FollowupRun["run"],
+      provider: probe.provider,
+      model: probe.model,
+      sessionKey: "main",
+      activeSessionStore,
+      getActiveSessionEntry: () => staleAutoEntry,
+      storePath: "/tmp/sessions.sqlite",
+    });
+
+    expect(activeSessionStore.main).toBe(replacementEntry);
+  });
+
+  it("preserves an in-place cache update when persistence has no row", async () => {
+    const probe = {
+      provider: "anthropic",
+      model: "claude-sonnet-4-6",
+      fallbackProvider: "openai",
+      fallbackModel: "gpt-5.4",
+    };
+    const staleAutoEntry: SessionEntry = {
+      sessionId: "session",
+      updatedAt: 1,
+      providerOverride: probe.fallbackProvider,
+      modelOverride: probe.fallbackModel,
+      modelOverrideSource: "auto",
+      modelOverrideFallbackOriginProvider: probe.provider,
+      modelOverrideFallbackOriginModel: probe.model,
+      authProfileOverride: "openai:fallback",
+      authProfileOverrideSource: "auto",
+    };
+    const activeSessionStore = { main: staleAutoEntry };
+    state.updateSessionEntryMock.mockImplementationOnce(async () => {
+      Object.assign(staleAutoEntry, {
+        authProfileOverrideSource: "user",
+        updatedAt: 2,
+      });
+      return undefined;
+    });
+
+    await clearRecoveredAutoFallbackPrimaryProbeSelection({
+      run: {
+        provider: probe.provider,
+        model: probe.model,
+        autoFallbackPrimaryProbe: probe,
+      } as FollowupRun["run"],
+      provider: probe.provider,
+      model: probe.model,
+      sessionKey: "main",
+      activeSessionStore,
+      getActiveSessionEntry: () => staleAutoEntry,
+      storePath: "/tmp/sessions.sqlite",
+    });
+
+    expect(activeSessionStore.main).toBe(staleAutoEntry);
+    expect(activeSessionStore.main).toMatchObject({
+      authProfileOverride: "openai:fallback",
+      authProfileOverrideSource: "user",
+      updatedAt: 2,
+    });
+  });
+
+  it("preserves an in-place nested cache update", async () => {
+    const probe = {
+      provider: "anthropic",
+      model: "claude-sonnet-4-6",
+      fallbackProvider: "openai",
+      fallbackModel: "gpt-5.4",
+    };
+    const staleAutoEntry: SessionEntry = {
+      sessionId: "session",
+      updatedAt: 1,
+      providerOverride: probe.fallbackProvider,
+      modelOverride: probe.fallbackModel,
+      modelOverrideSource: "auto",
+      modelOverrideFallbackOriginProvider: probe.provider,
+      modelOverrideFallbackOriginModel: probe.model,
+      cliSessionBindings: {
+        codex: { sessionId: "old-cli-session" },
+      },
+    };
+    const activeSessionStore = { main: staleAutoEntry };
+    state.updateSessionEntryMock.mockImplementationOnce(
+      async (_scope: unknown, update: (entry: SessionEntry) => unknown) => {
+        const persistedEntry = structuredClone(staleAutoEntry);
+        const patch = await update(persistedEntry);
+        staleAutoEntry.cliSessionBindings!.codex!.sessionId = "new-cli-session";
+        staleAutoEntry.updatedAt = 2;
+        return { ...persistedEntry, ...(patch as Partial<SessionEntry>) };
+      },
+    );
+
+    await clearRecoveredAutoFallbackPrimaryProbeSelection({
+      run: {
+        provider: probe.provider,
+        model: probe.model,
+        autoFallbackPrimaryProbe: probe,
+      } as FollowupRun["run"],
+      provider: probe.provider,
+      model: probe.model,
+      sessionKey: "main",
+      activeSessionStore,
+      getActiveSessionEntry: () => staleAutoEntry,
+      storePath: "/tmp/sessions.sqlite",
+    });
+
+    expect(activeSessionStore.main).not.toBe(staleAutoEntry);
+    expect(activeSessionStore.main.cliSessionBindings?.codex?.sessionId).toBe("new-cli-session");
+    expect(activeSessionStore.main.updatedAt).toBeGreaterThanOrEqual(2);
+    expect(activeSessionStore.main.modelOverride).toBeUndefined();
+  });
+});

src/auto-reply/reply/agent-runner-auto-fallback.ts

@@ -0,0 +1,203 @@
+import { isDeepStrictEqual } from "node:util";
+import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
+import {
+  clearAutoFallbackPrimaryProbeSelection,
+  entryMatchesAutoFallbackPrimaryProbe,
+  hasSessionAutoModelFallbackProvenance,
+  resolveAutoFallbackPrimaryProbe,
+} from "../../agents/agent-scope.js";
+import { resolvePersistedOverrideModelRef } from "../../agents/model-selection.js";
+import type { SessionEntry } from "../../config/sessions.js";
+import {
+  resolveCollapsedSessionAuthPinSource,
+  resolveSessionAuthProfileOverrideSource,
+} from "../../config/sessions/auth-profile-override-provenance.js";
+import { resolveSessionModelOverrideRouteResolution } from "../../config/sessions/model-override-provenance.js";
+import { updateSessionEntry } from "../../config/sessions/session-accessor.js";
+import { mergeSessionSnapshotChanges } from "../../config/sessions/session-snapshot-merge.js";
+import { shouldPreserveUserFacingSessionStateForInputProvenance } from "../../sessions/input-provenance.js";
+import type { FollowupRun } from "./queue.js";
+
+function sessionEntryMatchesSnapshot(entry: SessionEntry, snapshot: SessionEntry): boolean {
+  return isDeepStrictEqual(entry, snapshot);
+}
+
+function sessionEntryOnlyUpdatedAtChanged(entry: SessionEntry, snapshot: SessionEntry): boolean {
+  if (entry.updatedAt === snapshot.updatedAt) {
+    return false;
+  }
+  const entryWithoutUpdatedAt = { ...entry, updatedAt: snapshot.updatedAt };
+  return isDeepStrictEqual(entryWithoutUpdatedAt, snapshot);
+}
+
+/** Decides whether to retry after rechecking auto-fallback primary probe state. */
+export function resolveRunAfterAutoFallbackPrimaryProbeRecheck(params: {
+  run: FollowupRun["run"];
+  entry?: SessionEntry;
+  sessionKey?: string;
+}): FollowupRun["run"] {
+  const probe = params.run.autoFallbackPrimaryProbe;
+  if (!probe || !params.sessionKey || !params.entry) {
+    return params.run;
+  }
+  const resolveEntrySelectionRun = (): FollowupRun["run"] => {
+    const entryRef = resolvePersistedOverrideModelRef({
+      defaultProvider: params.run.provider,
+      overrideProvider: params.entry?.providerOverride,
+      overrideModel: params.entry?.modelOverride,
+    });
+    const hasEntryModelOverride = Boolean(entryRef);
+    const authProfileId = normalizeOptionalString(params.entry?.authProfileOverride);
+    const fallbackRun: FollowupRun["run"] = {
+      ...params.run,
+      provider: entryRef?.provider ?? params.run.provider,
+      model: entryRef?.model ?? params.run.model,
+      requestedRouteResolution: entryRef
+        ? resolveSessionModelOverrideRouteResolution(params.entry)
+        : params.run.requestedRouteResolution,
+      autoFallbackPrimaryProbe: undefined,
+    };
+    if (hasEntryModelOverride) {
+      fallbackRun.hasSessionModelOverride = true;
+      fallbackRun.hasAutoFallbackProvenance =
+        hasSessionAutoModelFallbackProvenance(params.entry) || undefined;
+    } else {
+      delete fallbackRun.hasSessionModelOverride;
+      delete fallbackRun.hasAutoFallbackProvenance;
+    }
+    const modelOverrideSource = params.entry?.modelOverrideSource;
+    if (hasEntryModelOverride && modelOverrideSource && modelOverrideSource !== "default") {
+      fallbackRun.modelOverrideSource = modelOverrideSource;
+    } else {
+      delete fallbackRun.modelOverrideSource;
+    }
+    if (hasEntryModelOverride && authProfileId) {
+      fallbackRun.authProfileId = authProfileId;
+      const authProfileIdSource = resolveCollapsedSessionAuthPinSource(params.entry);
+      if (authProfileIdSource) {
+        fallbackRun.authProfileIdSource = authProfileIdSource;
+      } else {
+        delete fallbackRun.authProfileIdSource;
+      }
+    } else if (hasEntryModelOverride) {
+      delete fallbackRun.authProfileId;
+      delete fallbackRun.authProfileIdSource;
+    }
+    return fallbackRun;
+  };
+  const refreshedProbe = resolveAutoFallbackPrimaryProbe({
+    entry: params.entry,
+    sessionKey: params.sessionKey,
+    primaryProvider: probe.provider,
+    primaryModel: probe.model,
+  });
+  if (!refreshedProbe) {
+    return resolveEntrySelectionRun();
+  }
+  return {
+    ...params.run,
+    provider: refreshedProbe.provider,
+    model: refreshedProbe.model,
+    requestedRouteResolution: "resolved",
+    autoFallbackPrimaryProbe: refreshedProbe,
+  };
+}
+
+/** Clears a recovered primary probe without overwriting a newer session selection. */
+export async function clearRecoveredAutoFallbackPrimaryProbeSelection(params: {
+  run: FollowupRun["run"];
+  provider: string;
+  model: string;
+  sessionKey?: string;
+  activeSessionStore?: Record<string, SessionEntry>;
+  getActiveSessionEntry: () => SessionEntry | undefined;
+  storePath?: string;
+}): Promise<void> {
+  if (shouldPreserveUserFacingSessionStateForInputProvenance(params.run.inputProvenance)) {
+    return;
+  }
+  const probe = params.run.autoFallbackPrimaryProbe;
+  if (!probe || params.provider !== probe.provider || params.model !== probe.model) {
+    return;
+  }
+  if (!params.sessionKey || !params.activeSessionStore) {
+    return;
+  }
+  const cachedSessionEntry = params.activeSessionStore[params.sessionKey];
+  const activeSessionEntry = cachedSessionEntry ?? params.getActiveSessionEntry();
+  if (!activeSessionEntry || !entryMatchesAutoFallbackPrimaryProbe(activeSessionEntry, probe)) {
+    return;
+  }
+  const activeSessionEntryBeforeUpdate = structuredClone(activeSessionEntry);
+  if (!params.storePath) {
+    clearAutoFallbackPrimaryProbeSelection(activeSessionEntry);
+    params.activeSessionStore[params.sessionKey] = activeSessionEntry;
+    return;
+  }
+  let comparedEntry: SessionEntry | undefined;
+  const updatedEntry = await updateSessionEntry(
+    { storePath: params.storePath, sessionKey: params.sessionKey },
+    (persistedEntry) => {
+      comparedEntry = persistedEntry;
+      if (
+        persistedEntry.sessionId !== activeSessionEntryBeforeUpdate.sessionId ||
+        persistedEntry.updatedAt !== activeSessionEntryBeforeUpdate.updatedAt ||
+        !entryMatchesAutoFallbackPrimaryProbe(persistedEntry, probe)
+      ) {
+        return null;
+      }
+      const shouldClearAuthProfile =
+        resolveSessionAuthProfileOverrideSource(persistedEntry) === "auto";
+      clearAutoFallbackPrimaryProbeSelection(persistedEntry);
+      return {
+        providerOverride: undefined,
+        modelOverride: undefined,
+        modelOverrideSource: undefined,
+        modelOverrideRouteResolution: undefined,
+        modelOverrideFallbackOriginProvider: undefined,
+        modelOverrideFallbackOriginModel: undefined,
+        ...(shouldClearAuthProfile
+          ? {
+              authProfileOverride: undefined,
+              authProfileOverrideSource: undefined,
+              authProfileOverrideCompactionCount: undefined,
+            }
+          : {}),
+        fallbackNotice: undefined,
+        updatedAt: persistedEntry.updatedAt,
+      };
+    },
+  );
+  // The persisted comparison owns selection freshness. Publish its updated
+  // result, or refresh the cache from the entry that rejected this probe.
+  const authoritativeEntry = updatedEntry ?? comparedEntry;
+  const currentCachedEntry = params.activeSessionStore[params.sessionKey];
+  // Object replacement is a new cache generation even when values match.
+  // Preserve it to avoid clearing an identically reselected fallback.
+  if (currentCachedEntry !== cachedSessionEntry) {
+    return;
+  }
+  const currentEntry = currentCachedEntry ?? (cachedSessionEntry ? undefined : activeSessionEntry);
+  if (!currentEntry) {
+    return;
+  }
+  if (authoritativeEntry) {
+    if (sessionEntryMatchesSnapshot(currentEntry, activeSessionEntryBeforeUpdate)) {
+      params.activeSessionStore[params.sessionKey] = authoritativeEntry;
+      return;
+    }
+    if (
+      currentEntry.sessionId !== activeSessionEntryBeforeUpdate.sessionId ||
+      sessionEntryOnlyUpdatedAtChanged(currentEntry, activeSessionEntryBeforeUpdate)
+    ) {
+      return;
+    }
+    params.activeSessionStore[params.sessionKey] = mergeSessionSnapshotChanges({
+      initial: activeSessionEntryBeforeUpdate,
+      next: authoritativeEntry,
+      current: currentEntry,
+    });
+  } else if (sessionEntryMatchesSnapshot(currentEntry, activeSessionEntryBeforeUpdate)) {
+    delete params.activeSessionStore[params.sessionKey];
+  }
+}

src/auto-reply/reply/agent-runner-cli-candidate.ts

@@ -0,0 +1,514 @@
+import { resolveBootstrapWarningSignaturesSeen } from "../../agents/bootstrap-budget.js";
+import {
+  cliBackendAcceptsAuthProfileForwarding,
+  resolveCliExecutionAuthProfileId,
+} from "../../agents/cli-execution-auth.js";
+import { buildCliMcpDelegationCapabilityBinding } from "../../agents/cli-runner/mcp-grant-context.js";
+import {
+  clearCliSessionInStore,
+  persistCliSessionBindingResult,
+  settleCliSessionResult,
+} from "../../agents/cli-session-store.js";
+import {
+  getCliSessionBinding,
+  shouldClearFailedCliSessionBinding,
+} from "../../agents/cli-session.js";
+import { resolveDelegationCapability } from "../../agents/delegation-capability.js";
+import type { EmbeddedAgentRunResult } from "../../agents/embedded-agent-runner/types.js";
+import { findModelInCatalog } from "../../agents/model-catalog-lookup.js";
+import type { ModelFallbackResultClassification } from "../../agents/model-fallback-attempt.js";
+import { createAgentRunSupersededAbortError } from "../../agents/run-termination.js";
+import { withLocalSessionPlacementTurnSettlement } from "../../agents/session-placement-admission.js";
+import { normalizeChatType } from "../../channels/chat-type.js";
+import { loadSessionEntry } from "../../config/sessions/session-accessor.js";
+import { shouldPreserveUserFacingSessionStateForInputProvenance } from "../../sessions/input-provenance.js";
+import {
+  getGeneratedMediaTaskIdsForSessionKey,
+  hasNewGeneratedMediaTaskForSessionKey,
+} from "../../tasks/task-status-access.js";
+import { createAgentLifecycleTerminalBackstop } from "./agent-lifecycle-terminal.js";
+import { resolveRunAuthProfile } from "./agent-runner-auth-profile.js";
+import {
+  createCliReasoningStreamBridge,
+  createCliToolSummaryTracker,
+  keepCliSessionBindingOnlyWhenReused,
+  runCliAgentWithLifecycle,
+} from "./agent-runner-cli-dispatch.js";
+import { buildCommandOutputFromToolResultEvent } from "./agent-runner-command-output.js";
+import type { AgentFallbackCandidateCommonParams } from "./agent-runner-fallback-cycle.types.js";
+import { resolveRunModelHasVision } from "./agent-runner-run-params.js";
+import { shouldBridgeCliPreambleEvents } from "./get-reply.types.js";
+import { hasInboundAudio } from "./inbound-media.js";
+import { resolveOriginMessageProvider } from "./origin-routing.js";
+import { resolveReplyOperationTerminationFields } from "./reply-operation-abort.js";
+
+export async function runCliFallbackCandidate(
+  params: AgentFallbackCandidateCommonParams & {
+    cliExecutionProvider: string;
+    classifyResult: (result: EmbeddedAgentRunResult) => ModelFallbackResultClassification;
+    lifecycleGeneration: string;
+  },
+): Promise<{
+  result: Awaited<ReturnType<typeof runCliAgentWithLifecycle>>;
+  bootstrapPromptWarningSignaturesSeen: string[];
+}> {
+  const turn = params.turn;
+  const expectedLifecycleRevision = turn.getActiveSessionEntry()?.lifecycleRevision;
+  const selectedModelEntry = findModelInCatalog(
+    params.candidateRun.thinkingCatalog ?? [],
+    params.provider,
+    params.model,
+  );
+  const modelHasVision = await resolveRunModelHasVision({
+    run: params.candidateRun,
+    provider: params.provider,
+    model: params.model,
+  });
+  const sessionKey = turn.sessionKey ?? turn.followupRun.run.sessionKey;
+  const sessionTarget =
+    sessionKey && turn.storePath
+      ? {
+          agentId: turn.followupRun.run.agentId,
+          sessionId: turn.followupRun.run.sessionId,
+          sessionKey,
+          storePath: turn.storePath,
+        }
+      : undefined;
+  const cliLifecycleStartedAt = Date.now();
+  const lifecycleBackstop = createAgentLifecycleTerminalBackstop({
+    runId: params.runId,
+    sessionKey: turn.sessionKey,
+    startedAt: cliLifecycleStartedAt,
+    getLifecycleGeneration: () => params.lifecycleGeneration,
+    resolveTerminationFields: (error) =>
+      resolveReplyOperationTerminationFields(error, params.runAbortSignal, turn.replyOperation),
+  });
+  params.onLifecycleBackstop(lifecycleBackstop);
+  const allowCliAuthProfileForwarding = cliBackendAcceptsAuthProfileForwarding({
+    provider: params.cliExecutionProvider,
+    config: params.runtimeConfig,
+    agentId: params.candidateRun.agentId,
+  });
+  const hookMessageProvider = resolveOriginMessageProvider({
+    originatingChannel: turn.followupRun.originatingChannel,
+    provider: turn.sessionCtx.Provider,
+  });
+  const cliCurrentThreadId =
+    turn.followupRun.originatingThreadId ?? turn.sessionCtx.MessageThreadId;
+  const isRestartSentinelContinuation =
+    turn.sessionCtx.InputProvenance?.kind === "internal_system" &&
+    turn.sessionCtx.InputProvenance.sourceTool === "restart-sentinel";
+  const cliCurrentMessageId = isRestartSentinelContinuation
+    ? turn.sessionCtx.ReplyToId
+    : (turn.sessionCtx.MessageSidFull ?? turn.sessionCtx.MessageSid);
+  const commandDetailsVisible = turn.resolvedVerboseLevel === "full";
+  const cliToolSummaryTracker = createCliToolSummaryTracker({
+    detailMode: turn.toolProgressDetail,
+    commandDetailsVisible,
+    shouldEmitToolResult: turn.shouldEmitToolResult,
+    shouldEmitToolOutput: turn.shouldEmitToolOutput,
+    deliver: async (payload) => {
+      await turn.opts?.onToolResult?.(payload);
+    },
+  });
+  // CLI backends report a tool's outcome on the result event and never repeat it,
+  // so the terminal fact has to be projected here. The embedded path gets this
+  // from the shared agent-event handler; without it a failed CLI command renders
+  // exactly like one that succeeded.
+  const deliverCliCommandOutcome = async (
+    payload: {
+      name: string | undefined;
+      phase: "start" | "update" | "result";
+      args: Record<string, unknown> | undefined;
+      toolCallId?: string;
+      isError?: boolean;
+      result?: unknown;
+    },
+    commandBearing: boolean,
+  ) => {
+    const onCommandOutput = turn.opts?.onCommandOutput;
+    if (!onCommandOutput) {
+      return;
+    }
+    const commandOutput = buildCommandOutputFromToolResultEvent({
+      stream: "tool",
+      data: { ...payload, commandBearing },
+    });
+    if (commandOutput) {
+      await onCommandOutput(commandOutput);
+    }
+  };
+  const bridgeCliPreambleProgress =
+    Boolean(turn.opts?.onItemEvent) && shouldBridgeCliPreambleEvents(turn.opts);
+  const bridgeCliDurableCommentary =
+    Boolean(params.presentation.blockReplyHandler) &&
+    (turn.blockStreamingEnabled || turn.opts?.commentaryPayloadsEnabled === true);
+  const toolAuthorityRoute = { provider: params.provider, model: params.model };
+  const toolAuthorityFingerprint = turn.replyOperation?.bindToolAuthorityRoute(toolAuthorityRoute);
+  const result = await params.timing.measure("cli_run", () =>
+    withLocalSessionPlacementTurnSettlement(
+      {
+        sessionId: turn.followupRun.run.sessionId,
+        sessionKey,
+        agentId: turn.followupRun.run.agentId,
+        runId: params.runId,
+      },
+      async (assertSettlementCurrent) => {
+        // Placement admission may wait behind an older turn. Snapshot placement,
+        // permission, and native resume identity only after this turn owns it.
+        const sessionEntry = sessionTarget
+          ? loadSessionEntry({ ...sessionTarget, readConsistency: "latest" })
+          : turn.getActiveSessionEntry();
+        if (
+          sessionTarget &&
+          (sessionEntry?.sessionId !== sessionTarget.sessionId ||
+            sessionEntry.lifecycleRevision !== expectedLifecycleRevision)
+        ) {
+          throw createAgentRunSupersededAbortError();
+        }
+        const cliSessionBinding = getCliSessionBinding(sessionEntry, params.cliExecutionProvider);
+        // The CLI owner must see explicit pins before provider scoping can discard them.
+        const authProfileId = allowCliAuthProfileForwarding
+          ? resolveCliExecutionAuthProfileId({
+              cliExecutionProvider: params.cliExecutionProvider,
+              authProfileProvider: params.provider,
+              config: params.runtimeConfig,
+              agentDir: params.candidateRun.agentDir,
+              selected: params.candidateRun,
+              sessionBinding: cliSessionBinding,
+            })
+          : resolveRunAuthProfile(params.candidateRun, params.cliExecutionProvider, {
+              config: params.runtimeConfig,
+            }).authProfileId;
+        const diagnosticOwner = params.deferredLifecycle.handoffToCli();
+        const mediaTaskIdsBefore = getGeneratedMediaTaskIdsForSessionKey(turn.sessionKey);
+        let droppedCliSessionReplacement = false;
+        const candidateResult = await runCliAgentWithLifecycle({
+          runId: params.runId,
+          lifecycleGeneration: params.lifecycleGeneration,
+          provider: params.cliExecutionProvider,
+          startedAt: cliLifecycleStartedAt,
+          emitLifecycleTerminal: false,
+          onAgentRunStart: params.notifyAgentRunStart,
+          suppressAssistantBridge: turn.followupRun.run.silentExpected,
+          onActivity: () => turn.replyOperation?.recordActivity(),
+          onErrorBeforeLifecycle:
+            params.cliExecutionProvider === "claude-cli" && cliSessionBinding?.sessionId
+              ? async (error) => {
+                  if (
+                    !shouldClearFailedCliSessionBinding({
+                      error,
+                      binding: cliSessionBinding,
+                      hasNewGeneratedMediaTask: hasNewGeneratedMediaTaskForSessionKey(
+                        turn.sessionKey,
+                        mediaTaskIdsBefore,
+                      ),
+                    })
+                  ) {
+                    return;
+                  }
+                  await clearCliSessionInStore({
+                    provider: params.cliExecutionProvider,
+                    expectedCliSessionId: cliSessionBinding.sessionId,
+                    expectedSessionId: sessionEntry?.sessionId,
+                    assertCommitAllowed: assertSettlementCurrent,
+                    sessionKey: turn.sessionKey,
+                    sessionStore: turn.activeSessionStore,
+                    storePath: turn.storePath,
+                    activeSessionEntry: sessionEntry,
+                  });
+                }
+              : undefined,
+          preserveProgressCallbackStartOrder: params.preserveProgressCallbackStartOrder,
+          onAssistantText: async (text) => {
+            const classified = params.presentation.classifyStreamingPartial({ text });
+            if (classified.skip || !classified.text) {
+              return;
+            }
+            const textForTyping = classified.text;
+            const sanitized = params.presentation.sanitizeStreamingText(textForTyping, false);
+            const onPartialReply = turn.opts?.onPartialReply;
+            return await params.presentation.presentWithTyping(
+              turn.typingSignals.signalTextDelta(textForTyping),
+              () =>
+                sanitized.skip || !sanitized.text || !onPartialReply
+                  ? false
+                  : onPartialReply({ text: sanitized.text }),
+            );
+          },
+          onReasoningText: createCliReasoningStreamBridge(turn.opts?.onReasoningStream),
+          onPlanUpdate: turn.opts?.onPlanUpdate,
+          onReasoningProgress: async (payload) => {
+            await turn.opts?.onReasoningProgress?.(payload);
+          },
+          onCompactionStart: turn.opts?.onCompactionStart,
+          onCompactionEnd: turn.opts?.onCompactionEnd,
+          onToolEvent: async (payload) => {
+            if (!params.preserveProgressCallbackStartOrder) {
+              const commandBearing = await cliToolSummaryTracker.noteToolEvent(payload);
+              if (payload.phase === "result") {
+                await deliverCliCommandOutcome(payload, commandBearing);
+                return;
+              }
+              const { name, phase, args, toolCallId } = payload;
+              await Promise.all([
+                turn.typingSignals.signalToolStart(),
+                turn.opts?.onToolStart?.({
+                  ...(toolCallId ? { toolCallId } : {}),
+                  name,
+                  phase,
+                  args,
+                  detailMode: turn.toolProgressDetail,
+                }),
+              ]);
+              return;
+            }
+            const summaryPromise = cliToolSummaryTracker.noteToolEvent(payload);
+            if (payload.phase === "result") {
+              const commandBearing = await summaryPromise;
+              await deliverCliCommandOutcome(payload, commandBearing);
+              return;
+            }
+            const { name, phase, args, toolCallId } = payload;
+            // Tool and assistant bridges drain independently. Preserve source order.
+            await Promise.all([
+              summaryPromise,
+              params.presentation.presentWithTyping(
+                turn.typingSignals.signalToolStart(),
+                async () => {
+                  await turn.opts?.onToolStart?.({
+                    ...(toolCallId ? { toolCallId } : {}),
+                    name,
+                    phase,
+                    args,
+                    detailMode: turn.toolProgressDetail,
+                  });
+                },
+              ),
+            ]);
+          },
+          onCommentaryText:
+            bridgeCliPreambleProgress || bridgeCliDurableCommentary
+              ? async (payload) => {
+                  const deliveries: unknown[] = [];
+                  if (bridgeCliPreambleProgress) {
+                    deliveries.push(
+                      turn.opts?.onItemEvent?.({
+                        itemId: payload.itemId,
+                        kind: "preamble",
+                        progressText: payload.text,
+                        // The block bridge owns durability; this event remains a progress preview.
+                        ...(bridgeCliDurableCommentary ? { suppressDurableProgress: true } : {}),
+                      }),
+                    );
+                  }
+                  if (bridgeCliDurableCommentary) {
+                    // Block mode treats completed CLI text as an ordinary answer block so
+                    // the existing pipeline owns coalescing and final-payload dedupe.
+                    deliveries.push(
+                      params.presentation.blockReplyHandler?.({
+                        text: payload.text,
+                        ...(turn.blockStreamingEnabled ? {} : { isCommentary: true }),
+                      }),
+                    );
+                  }
+                  await Promise.all(deliveries);
+                }
+              : undefined,
+          onFastModeAutoProgress: async (payload) => {
+            await turn.opts?.onToolResult?.(payload);
+          },
+          transformResult:
+            turn.followupRun.currentInboundEventKind === "room_event"
+              ? (resultLocal) =>
+                  keepCliSessionBindingOnlyWhenReused({
+                    result: resultLocal,
+                    existingSessionId: cliSessionBinding?.sessionId,
+                    onDroppedReplacement: () => {
+                      droppedCliSessionReplacement = true;
+                    },
+                  })
+              : undefined,
+          runParams: {
+            preparedRunAdmission: params.preparedRunAdmission,
+            messageActionTurnCapability: params.messageActionTurnCapability,
+            diagnosticOwner,
+            sessionId: turn.followupRun.run.sessionId,
+            sessionKey,
+            sessionTarget,
+            sessionEntry,
+            chatType:
+              normalizeChatType(turn.followupRun.originatingChatType) ??
+              normalizeChatType(turn.sessionCtx.ChatType) ??
+              params.candidateRun.chatType,
+            runtimePolicySessionKey:
+              turn.followupRun.run.runtimePolicySessionKey ?? turn.runtimePolicySessionKey,
+            agentId: turn.followupRun.run.agentId,
+            trigger: turn.isHeartbeat ? "heartbeat" : "user",
+            sessionFile: turn.followupRun.run.sessionFile,
+            workspaceDir: turn.followupRun.run.workspaceDir,
+            cwd: turn.followupRun.run.cwd,
+            config: params.runtimeConfig,
+            toolOverrides: turn.followupRun.run.toolOverrides,
+            prompt: turn.commandBody,
+            transcriptPrompt: turn.transcriptCommandBody,
+            media: turn.followupRun.media,
+            suppressNextUserMessagePersistence: params.suppressQueuedUserPersistenceForCandidate,
+            userTurnTranscriptRecorder: params.userTurnTranscriptRecorder,
+            contextEngineLogicalTurnLease: params.contextEngineLogicalTurnLease,
+            onContextEngineTurnCandidate: params.onContextEngineTurnCandidate,
+            onUserMessagePersisted: params.notifyUserMessagePersisted,
+            prepareAssistantTranscriptMessage: turn.opts?.prepareAssistantTranscriptMessage,
+            persistAssistantTranscript:
+              turn.followupRun.currentInboundEventKind !== "room_event" &&
+              turn.followupRun.run.suppressTranscriptOnlyAssistantPersistence !== true,
+            storePath: turn.storePath,
+            currentInboundEventKind: turn.followupRun.currentInboundEventKind,
+            currentInboundContext: turn.followupRun.currentInboundContext,
+            inputProvenance: turn.followupRun.run.inputProvenance,
+            // Candidate zero is the primary attempt; later candidates are
+            // fallbacks. Carry the runner-owned fact instead of inferring from
+            // this shared dispatch path, or primary CLI runs lose delegation.
+            ...buildCliMcpDelegationCapabilityBinding(
+              resolveDelegationCapability({
+                fallbackActive: params.isFallbackRetry,
+                inputProvenance: turn.followupRun.run.inputProvenance,
+                disableTools: turn.opts?.disableTools,
+                toolsAllow: turn.opts?.toolsAllow,
+              }),
+            ),
+            modelProvider: params.provider,
+            requesterModel: { provider: params.provider, model: params.model },
+            modelHasVision,
+            modelContextWindow: selectedModelEntry?.contextWindow,
+            modelContextTokens: selectedModelEntry?.contextTokens,
+            contextWindow: sessionEntry?.contextWindow,
+            provider: params.cliExecutionProvider,
+            execOverrides: turn.followupRun.run.execOverrides,
+            bashElevated: turn.followupRun.run.bashElevated,
+            model: params.model,
+            thinkLevel: params.candidateThinkLevel,
+            fastMode: params.candidateFastMode.fastMode,
+            fastModeStartedAtMs: params.fastModeStartedAtMs,
+            fastModeAutoOnSeconds: params.candidateFastMode.fastModeAutoOnSeconds,
+            fastModeAutoProgressState: params.fastModeAutoProgressState,
+            isFinalFallbackAttempt: params.isFinalFallbackAttempt,
+            timeoutMs: turn.followupRun.run.timeoutMs,
+            runTimeoutOverrideMs: turn.followupRun.run.runTimeoutOverrideMs,
+            runId: params.runId,
+            lane: params.runLane,
+            extraSystemPrompt: turn.followupRun.run.extraSystemPrompt,
+            sourceReplyDeliveryMode: turn.followupRun.run.sourceReplyDeliveryMode,
+            taskSuggestionDeliveryMode: turn.followupRun.run.taskSuggestionDeliveryMode,
+            // Heartbeat ambient routes are never implicit message recipients.
+            ...(turn.isHeartbeat ? { requireExplicitMessageTarget: true } : {}),
+            cleanupBundleMcpOnRunEnd: turn.opts?.cleanupBundleMcpOnRunEnd,
+            silentReplyPromptMode: turn.followupRun.run.silentReplyPromptMode,
+            allowEmptyAssistantReplyAsSilent: turn.followupRun.run.allowEmptyAssistantReplyAsSilent,
+            extraSystemPromptStatic: turn.followupRun.run.extraSystemPromptStatic,
+            cliSessionBindingFacts: turn.followupRun.run.cliSessionBindingFacts,
+            ownerNumbers: turn.followupRun.run.ownerNumbers,
+            cliSessionId: cliSessionBinding?.sessionId,
+            cliSessionBinding,
+            authProfileId,
+            bootstrapContextMode: turn.opts?.bootstrapContextMode,
+            bootstrapContextRunKind: params.bootstrapContextRunKind,
+            bootstrapPromptWarningSignaturesSeen: params.bootstrapPromptWarningSignaturesSeen,
+            bootstrapPromptWarningSignature:
+              params.bootstrapPromptWarningSignaturesSeen[
+                params.bootstrapPromptWarningSignaturesSeen.length - 1
+              ],
+            images: params.currentTurnImages.images,
+            imageOrder: params.currentTurnImages.imageOrder,
+            mediaImageLayout: params.currentTurnImages.mediaImageLayout,
+            skillsSnapshot: turn.followupRun.run.skillsSnapshot,
+            messageChannel: turn.followupRun.originatingChannel ?? undefined,
+            messageProvider: hookMessageProvider,
+            clientCaps: turn.followupRun.run.clientCaps,
+            gatewayUiCommandTarget: turn.followupRun.run.gatewayUiCommandTarget,
+            currentChannelId:
+              turn.followupRun.originatingTo ?? turn.sessionCtx.OriginatingTo ?? turn.sessionCtx.To,
+            senderId: turn.followupRun.run.senderId,
+            senderName: turn.followupRun.run.senderName,
+            senderUsername: turn.followupRun.run.senderUsername,
+            senderE164: turn.followupRun.run.senderE164,
+            groupId: turn.followupRun.run.groupId,
+            groupChannel: turn.followupRun.run.groupChannel,
+            groupSpace: turn.followupRun.run.groupSpace,
+            spawnedBy: turn.followupRun.run.spawnedBy,
+            chatId: turn.followupRun.originatingChatId,
+            channelContext: turn.followupRun.run.channelContext,
+            currentThreadTs: cliCurrentThreadId != null ? String(cliCurrentThreadId) : undefined,
+            currentMessageId: cliCurrentMessageId,
+            replyToMode: turn.followupRun.originatingReplyToMode ?? turn.sessionCtx.ReplyToMode,
+            currentInboundAudio: hasInboundAudio(turn.sessionCtx),
+            agentAccountId: turn.followupRun.run.agentAccountId,
+            senderIsOwner: turn.followupRun.run.senderIsOwner,
+            approvalReviewerDeviceId: turn.followupRun.run.approvalReviewerDeviceId,
+            toolsAllow: turn.opts?.toolsAllow,
+            skillWorkshopProposalRevision: params.candidateRun.skillWorkshopProposalRevision,
+            skillLibraryAuthoring: params.candidateRun.skillLibraryAuthoring,
+            disableTools: turn.opts?.disableTools,
+            toolAuthorityFingerprint,
+            abortSignal: params.runAbortSignal,
+            // Native input is already host-authored. Keep its stable delivery
+            // context out of the model-output normalization wrapper.
+            onBlockReply: turn.opts?.onBlockReply,
+            onPartialReply: turn.opts?.onPartialReply,
+            onExecutionPhase: params.signalExecutionPhaseForTyping,
+            replyOperation: turn.replyOperation,
+          },
+        });
+        if (droppedCliSessionReplacement) {
+          // The room-event transform removed native continuity; only its guarded
+          // invalidation remains, and failure must retain the returned turn.
+          return await settleCliSessionResult(candidateResult, async () => {
+            await clearCliSessionInStore({
+              provider: params.cliExecutionProvider,
+              expectedCliSessionId: cliSessionBinding?.sessionId,
+              expectedSessionId: sessionEntry?.sessionId,
+              assertCommitAllowed: assertSettlementCurrent,
+              sessionKey: turn.sessionKey,
+              sessionStore: turn.activeSessionStore,
+              storePath: turn.storePath,
+              activeSessionEntry: sessionEntry,
+            });
+            params.classifyResult(candidateResult);
+          });
+        }
+        const classification = params.classifyResult(candidateResult);
+        if (
+          (!classification || candidateResult.meta.agentMeta?.clearCliSessionBinding === true) &&
+          !shouldPreserveUserFacingSessionStateForInputProvenance(
+            turn.followupRun.run.inputProvenance,
+          )
+        ) {
+          return await persistCliSessionBindingResult({
+            provider: params.cliExecutionProvider,
+            result: candidateResult,
+            sessionKey,
+            storePath: turn.storePath,
+            sessionStore: turn.activeSessionStore,
+            expectedSession: sessionEntry,
+            assertSettlementCurrent,
+            abortSignal: params.runAbortSignal,
+          });
+        }
+        return candidateResult;
+      },
+      {
+        preparedRunAdmission: params.preparedRunAdmission,
+        lifecycleGeneration: params.lifecycleGeneration,
+        abortSignal: params.runAbortSignal,
+        trigger: turn.isHeartbeat ? "heartbeat" : "user",
+        inputProvenance: turn.followupRun.run.inputProvenance,
+      },
+    ),
+  );
+  return {
+    result,
+    bootstrapPromptWarningSignaturesSeen: resolveBootstrapWarningSignaturesSeen(
+      result.meta?.systemPromptReport,
+    ),
+  };
+}

src/auto-reply/reply/agent-runner-cli-dispatch.test.ts

@@ -0,0 +1,1051 @@
+// Tests CLI dispatch arguments and runtime selection for agent runner turns.
+import path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { useAutoCleanupTempDirTracker } from "../../../test/helpers/temp-dir.js";
+import { withTestAdmittedRunContext } from "../../agents/admitted-run-context.test-support.js";
+import { createCliTimeoutError } from "../../agents/cli-runner/no-output-timeout-policy.js";
+import { clearCliSessionInStore } from "../../agents/cli-session-store.js";
+import type { EmbeddedAgentRunResult } from "../../agents/embedded-agent-runner/types.js";
+import { createAgentRunRestartAbortError } from "../../agents/run-termination.js";
+import { loadSessionEntry, replaceSessionEntry } from "../../config/sessions/session-accessor.js";
+import {
+  emitAgentEvent,
+  getAgentEventLifecycleGeneration,
+  onAgentEvent,
+  resetAgentEventsForTest,
+} from "../../infra/agent-events.js";
+import {
+  createCliToolSummaryTracker,
+  keepCliSessionBindingOnlyWhenReused,
+  runCliAgentWithLifecycle as runCliAgentWithLifecycleProduction,
+} from "./agent-runner-cli-dispatch.js";
+
+type ProductionLifecycleParams = Parameters<typeof runCliAgentWithLifecycleProduction>[0];
+type RunCliAgentWithLifecycleParams = Omit<ProductionLifecycleParams, "runParams"> & {
+  runParams: Omit<ProductionLifecycleParams["runParams"], "admittedRunContext">;
+};
+const runCliAgentWithLifecycle = (params: RunCliAgentWithLifecycleParams) =>
+  runCliAgentWithLifecycleProduction({
+    ...params,
+    runParams: withTestAdmittedRunContext(params.runParams),
+  });
+type ReasoningTextPayload = Parameters<
+  NonNullable<RunCliAgentWithLifecycleParams["onReasoningText"]>
+>[0];
+type ReasoningProgressPayload = Parameters<
+  NonNullable<RunCliAgentWithLifecycleParams["onReasoningProgress"]>
+>[0];
+
+const cliDispatchState = vi.hoisted(() => ({
+  runCliAgentMock: vi.fn(),
+}));
+const tempDirs = useAutoCleanupTempDirTracker(afterEach);
+
+vi.mock("../../agents/cli-runner.js", () => ({
+  runCliAgent: (...args: unknown[]) => cliDispatchState.runCliAgentMock(...args),
+}));
+
+afterEach(() => {
+  vi.useRealTimers();
+  resetAgentEventsForTest();
+  cliDispatchState.runCliAgentMock.mockReset();
+});
+
+describe("runCliAgentWithLifecycle", () => {
+  it("bridges completed CLI compaction lifecycles to reply callbacks", async () => {
+    cliDispatchState.runCliAgentMock.mockImplementationOnce(async (params: { runId: string }) => {
+      emitAgentEvent({
+        runId: params.runId,
+        stream: "compaction",
+        data: { phase: "start", backend: "claude-cli" },
+      });
+      emitAgentEvent({
+        runId: params.runId,
+        stream: "compaction",
+        data: { phase: "end", backend: "claude-cli", completed: false },
+      });
+      emitAgentEvent({
+        runId: params.runId,
+        stream: "compaction",
+        data: { phase: "start", backend: "claude-cli" },
+      });
+      emitAgentEvent({
+        runId: params.runId,
+        stream: "compaction",
+        data: { phase: "end", backend: "claude-cli", completed: true },
+      });
+      return { payloads: [], meta: { durationMs: 1 } };
+    });
+    const callbacks: string[] = [];
+
+    await runCliAgentWithLifecycle({
+      runId: "run-compaction-bridge",
+      provider: "claude-cli",
+      onCompactionStart: async () => {
+        callbacks.push("start");
+      },
+      onCompactionEnd: async (payload) => {
+        callbacks.push(payload?.completed === false ? "incomplete" : "end");
+      },
+      runParams: {
+        sessionId: "session-1",
+        sessionFile: "/tmp/session.jsonl",
+        workspaceDir: "/tmp/workspace",
+        prompt: "hello",
+        provider: "claude-cli",
+        model: "claude-opus-4-8",
+        thinkLevel: "high",
+        timeoutMs: 1_000,
+        runId: "run-compaction-bridge",
+      },
+    });
+
+    expect(callbacks).toEqual(["start", "incomplete", "start", "end"]);
+  });
+
+  it("bridges typed CLI plan events", async () => {
+    cliDispatchState.runCliAgentMock.mockImplementationOnce(async (params: { runId: string }) => {
+      emitAgentEvent({
+        runId: params.runId,
+        stream: "plan",
+        data: {
+          phase: "update",
+          title: "Plan updated",
+          source: "codex-exec",
+          steps: [
+            { step: "Inspect", status: "completed" },
+            { step: "Patch", status: "pending" },
+          ],
+        },
+      });
+      return { payloads: [], meta: { durationMs: 1 } };
+    });
+    const onPlanUpdate = vi.fn(async () => undefined);
+
+    await runCliAgentWithLifecycle({
+      runId: "run-plan-bridge",
+      provider: "codex-cli",
+      onPlanUpdate,
+      runParams: {
+        sessionId: "session-1",
+        sessionFile: "/tmp/session.jsonl",
+        workspaceDir: "/tmp/workspace",
+        prompt: "hello",
+        provider: "codex-cli",
+        model: "codex",
+        thinkLevel: "high",
+        timeoutMs: 1_000,
+        runId: "run-plan-bridge",
+      },
+    });
+
+    expect(onPlanUpdate).toHaveBeenCalledWith({
+      phase: "update",
+      title: "Plan updated",
+      explanation: undefined,
+      source: "codex-exec",
+      steps: [
+        { step: "Inspect", status: "completed" },
+        { step: "Patch", status: "pending" },
+      ],
+    });
+  });
+
+  it("normalizes shipped string-step plan events to pending typed steps", async () => {
+    cliDispatchState.runCliAgentMock.mockImplementationOnce(async (params: { runId: string }) => {
+      emitAgentEvent({
+        runId: params.runId,
+        stream: "plan",
+        data: {
+          phase: "update",
+          title: "Plan updated",
+          source: "codex-exec",
+          steps: ["Inspect", "  ", "Patch"],
+        },
+      });
+      return { payloads: [], meta: { durationMs: 1 } };
+    });
+    const onPlanUpdate = vi.fn(async () => undefined);
+
+    await runCliAgentWithLifecycle({
+      runId: "run-plan-legacy",
+      provider: "codex-cli",
+      onPlanUpdate,
+      runParams: {
+        sessionId: "session-1",
+        sessionFile: "/tmp/session.jsonl",
+        workspaceDir: "/tmp/workspace",
+        prompt: "hello",
+        provider: "codex-cli",
+        model: "codex",
+        thinkLevel: "high",
+        timeoutMs: 1_000,
+        runId: "run-plan-legacy",
+      },
+    });
+
+    expect(onPlanUpdate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        steps: [
+          { step: "Inspect", status: "pending" },
+          { step: "Patch", status: "pending" },
+        ],
+      }),
+    );
+  });
+
+  it("bridges thinking events to reasoning text and dedupes identical snapshots", async () => {
+    cliDispatchState.runCliAgentMock.mockImplementationOnce(async (params: { runId: string }) => {
+      emitAgentEvent({
+        runId: params.runId,
+        stream: "thinking",
+        data: { text: "Thinking", delta: "Thinking", isReasoningSnapshot: true },
+      });
+      emitAgentEvent({
+        runId: params.runId,
+        stream: "thinking",
+        data: { text: "Thinking", delta: "", isReasoningSnapshot: true },
+      });
+      emitAgentEvent({
+        runId: params.runId,
+        stream: "thinking",
+        data: { text: "Thinking more", delta: " more", isReasoningSnapshot: true },
+      });
+      emitAgentEvent({
+        runId: params.runId,
+        stream: "assistant",
+        data: { text: "Visible answer", delta: "Visible answer" },
+      });
+      return { payloads: [{ text: "Visible answer" }], meta: { durationMs: 1 } };
+    });
+    const onReasoningText = vi.fn<(payload: ReasoningTextPayload) => Promise<void>>(
+      async () => undefined,
+    );
+
+    const result = await runCliAgentWithLifecycle({
+      runId: "run-thinking-bridge",
+      provider: "claude-cli",
+      onReasoningText,
+      runParams: {
+        sessionId: "session-1",
+        sessionFile: "/tmp/session.jsonl",
+        workspaceDir: "/tmp/workspace",
+        prompt: "hello",
+        provider: "claude-cli",
+        model: "claude",
+        thinkLevel: "high",
+        timeoutMs: 1_000,
+        runId: "run-thinking-bridge",
+      },
+    });
+
+    expect(onReasoningText).toHaveBeenCalledTimes(2);
+    expect(onReasoningText.mock.calls.map((call) => call[0])).toEqual([
+      { text: "Thinking", isReasoningSnapshot: true },
+      { text: "Thinking more", isReasoningSnapshot: true },
+    ]);
+    expect(result.payloads).toEqual([
+      { text: "Thinking more", isReasoning: true },
+      { text: "Visible answer" },
+    ]);
+  });
+
+  it("keeps durable reasoning when the CLI has no visible final answer", async () => {
+    cliDispatchState.runCliAgentMock.mockImplementationOnce(async (params: { runId: string }) => {
+      emitAgentEvent({
+        runId: params.runId,
+        stream: "thinking",
+        data: { text: "Only thinking", delta: "Only thinking", isReasoningSnapshot: true },
+      });
+      emitAgentEvent({
+        runId: params.runId,
+        stream: "thinking",
+        data: { text: "Only thinking more", delta: " more", isReasoningSnapshot: true },
+      });
+      return { payloads: [], meta: { durationMs: 1 } };
+    });
+
+    const result = await runCliAgentWithLifecycle({
+      runId: "run-thinking-without-answer",
+      provider: "claude-cli",
+      runParams: {
+        sessionId: "session-1",
+        sessionFile: "/tmp/session.jsonl",
+        workspaceDir: "/tmp/workspace",
+        prompt: "hello",
+        provider: "claude-cli",
+        model: "claude",
+        thinkLevel: "high",
+        timeoutMs: 1_000,
+        runId: "run-thinking-without-answer",
+      },
+    });
+
+    expect(result.payloads).toEqual([{ text: "Only thinking more", isReasoning: true }]);
+  });
+
+  it("bridges thinking token progress without adding durable reasoning", async () => {
+    cliDispatchState.runCliAgentMock.mockImplementationOnce(async (params: { runId: string }) => {
+      emitAgentEvent({
+        runId: params.runId,
+        stream: "thinking",
+        data: { progressTokens: 50 },
+      });
+      emitAgentEvent({
+        runId: params.runId,
+        stream: "thinking",
+        data: { progressTokens: 50 },
+      });
+      emitAgentEvent({
+        runId: params.runId,
+        stream: "thinking",
+        data: { progressTokens: 200 },
+      });
+      return { payloads: [{ text: "Visible answer" }], meta: { durationMs: 1 } };
+    });
+    const onReasoningProgress = vi.fn<(payload: ReasoningProgressPayload) => Promise<void>>(
+      async () => undefined,
+    );
+
+    const result = await runCliAgentWithLifecycle({
+      runId: "run-thinking-progress",
+      provider: "claude-cli",
+      onReasoningProgress,
+      runParams: {
+        sessionId: "session-1",
+        sessionFile: "/tmp/session.jsonl",
+        workspaceDir: "/tmp/workspace",
+        prompt: "hello",
+        provider: "claude-cli",
+        model: "claude",
+        thinkLevel: "high",
+        timeoutMs: 1_000,
+        runId: "run-thinking-progress",
+      },
+    });
+
+    expect(onReasoningProgress.mock.calls.map((call) => call[0])).toEqual([
+      { progressTokens: 50 },
+      { progressTokens: 200 },
+    ]);
+    expect(result.payloads).toEqual([{ text: "Visible answer" }]);
+  });
+
+  it("stamps onActivity for every delivered bridge event, including reasoning-only progress", async () => {
+    cliDispatchState.runCliAgentMock.mockImplementationOnce(async (params: { runId: string }) => {
+      emitAgentEvent({
+        runId: params.runId,
+        stream: "thinking",
+        data: { progressTokens: 50 },
+      });
+      emitAgentEvent({
+        runId: params.runId,
+        stream: "thinking",
+        data: { progressTokens: 50 },
+      });
+      emitAgentEvent({
+        runId: params.runId,
+        stream: "thinking",
+        data: { progressTokens: 200 },
+      });
+      return { payloads: [], meta: { durationMs: 1 } };
+    });
+    const onActivity = vi.fn();
+    const onReasoningProgress = vi.fn<(payload: ReasoningProgressPayload) => Promise<void>>(
+      async () => undefined,
+    );
+
+    await runCliAgentWithLifecycle({
+      runId: "run-activity-reasoning-progress",
+      provider: "claude-cli",
+      onActivity,
+      onReasoningProgress,
+      runParams: {
+        sessionId: "session-1",
+        sessionFile: "/tmp/session.jsonl",
+        workspaceDir: "/tmp/workspace",
+        prompt: "hello",
+        provider: "claude-cli",
+        model: "claude",
+        thinkLevel: "high",
+        timeoutMs: 1_000,
+        runId: "run-activity-reasoning-progress",
+      },
+    });
+
+    // A run in a long pure-reasoning stretch must keep stamping activity, or
+    // stale-takeover reclaims it while it is visibly thinking. Stamps are
+    // per-event (delivery-independent), so dedupe downstream does not matter.
+    expect(onReasoningProgress).toHaveBeenCalledTimes(2);
+    expect(onActivity).toHaveBeenCalledTimes(3);
+  });
+
+  it("keeps stamping onActivity when bridges are suppressed for silent runs", async () => {
+    cliDispatchState.runCliAgentMock.mockImplementationOnce(async (params: { runId: string }) => {
+      emitAgentEvent({
+        runId: params.runId,
+        stream: "thinking",
+        data: { progressTokens: 50 },
+      });
+      emitAgentEvent({
+        runId: params.runId,
+        stream: "assistant",
+        data: { text: "Silent answer", delta: "Silent answer" },
+      });
+      return { payloads: [], meta: { durationMs: 1 } };
+    });
+    const onActivity = vi.fn();
+    const onAssistantText = vi.fn<(text: string) => Promise<void>>(async () => undefined);
+    const onReasoningProgress = vi.fn<(payload: ReasoningProgressPayload) => Promise<void>>(
+      async () => undefined,
+    );
+
+    await runCliAgentWithLifecycle({
+      runId: "run-activity-suppressed",
+      provider: "claude-cli",
+      suppressAssistantBridge: true,
+      onActivity,
+      onAssistantText,
+      onReasoningProgress,
+      runParams: {
+        sessionId: "session-1",
+        sessionFile: "/tmp/session.jsonl",
+        workspaceDir: "/tmp/workspace",
+        prompt: "hello",
+        provider: "claude-cli",
+        model: "claude",
+        thinkLevel: "high",
+        timeoutMs: 1_000,
+        runId: "run-activity-suppressed",
+      },
+    });
+
+    // silentExpected runs suppress deliveries, but their events are still real
+    // liveness evidence — without these stamps a healthy silent run would be
+    // reclaimed as run_stalled at the takeover window.
+    expect(onAssistantText).not.toHaveBeenCalled();
+    expect(onReasoningProgress).not.toHaveBeenCalled();
+    expect(onActivity).toHaveBeenCalledTimes(2);
+  });
+
+  it("stamps onActivity for assistant text without caller callbacks for that stream", async () => {
+    cliDispatchState.runCliAgentMock.mockImplementationOnce(async (params: { runId: string }) => {
+      emitAgentEvent({
+        runId: params.runId,
+        stream: "thinking",
+        data: { text: "Deep thought", delta: "Deep thought", isReasoningSnapshot: true },
+      });
+      emitAgentEvent({
+        runId: params.runId,
+        stream: "assistant",
+        data: { text: "Visible answer", delta: "Visible answer" },
+      });
+      return { payloads: [{ text: "Visible answer" }], meta: { durationMs: 1 } };
+    });
+    const onActivity = vi.fn();
+    const onAssistantText = vi.fn<(text: string) => Promise<void>>(async () => undefined);
+
+    await runCliAgentWithLifecycle({
+      runId: "run-activity-assistant",
+      provider: "claude-cli",
+      onActivity,
+      onAssistantText,
+      runParams: {
+        sessionId: "session-1",
+        sessionFile: "/tmp/session.jsonl",
+        workspaceDir: "/tmp/workspace",
+        prompt: "hello",
+        provider: "claude-cli",
+        model: "claude",
+        thinkLevel: "high",
+        timeoutMs: 1_000,
+        runId: "run-activity-assistant",
+      },
+    });
+
+    // Every real event stamps, independent of which callbacks are registered.
+    expect(onAssistantText).toHaveBeenCalledTimes(1);
+    expect(onActivity).toHaveBeenCalledTimes(2);
+  });
+
+  it("does not add a durable reasoning payload when the CLI emits no thinking", async () => {
+    cliDispatchState.runCliAgentMock.mockResolvedValueOnce({
+      payloads: [{ text: "Visible answer" }],
+      meta: { durationMs: 1 },
+    } satisfies EmbeddedAgentRunResult);
+
+    const result = await runCliAgentWithLifecycle({
+      runId: "run-no-thinking",
+      provider: "claude-cli",
+      runParams: {
+        sessionId: "session-1",
+        sessionFile: "/tmp/session.jsonl",
+        workspaceDir: "/tmp/workspace",
+        prompt: "hello",
+        provider: "claude-cli",
+        model: "claude",
+        thinkLevel: "high",
+        timeoutMs: 1_000,
+        runId: "run-no-thinking",
+      },
+    });
+
+    expect(result.payloads).toEqual([{ text: "Visible answer" }]);
+  });
+
+  it("keeps the captured lifecycle generation on start and terminal events", async () => {
+    const events: Array<{
+      stream?: string;
+      lifecycleGeneration?: string;
+      agentId?: string;
+      data?: Record<string, unknown>;
+    }> = [];
+    const lifecycleGeneration = getAgentEventLifecycleGeneration();
+    const stop = onAgentEvent((event) => {
+      if (event.runId === "run-before-restart") {
+        events.push(event);
+      }
+    });
+    cliDispatchState.runCliAgentMock.mockResolvedValueOnce({
+      payloads: [],
+      meta: { durationMs: 1 },
+    } satisfies EmbeddedAgentRunResult);
+
+    try {
+      await runCliAgentWithLifecycle({
+        runId: "run-before-restart",
+        lifecycleGeneration,
+        startedAt: 1_000,
+        provider: "claude-cli",
+        runParams: {
+          sessionId: "session-1",
+          agentId: "support",
+          sessionFile: "/tmp/session.jsonl",
+          workspaceDir: "/tmp/workspace",
+          prompt: "hello",
+          provider: "claude-cli",
+          model: "claude",
+          thinkLevel: "off",
+          timeoutMs: 1_000,
+          runId: "run-before-restart",
+        },
+      });
+    } finally {
+      stop();
+    }
+
+    const lifecycleEvents = events.filter((event) => event.stream === "lifecycle");
+    expect(lifecycleEvents).toHaveLength(2);
+    expect(
+      lifecycleEvents.every((event) => event.lifecycleGeneration === lifecycleGeneration),
+    ).toBe(true);
+    expect(lifecycleEvents.every((event) => event.agentId === "support")).toBe(true);
+    expect(lifecycleEvents.every((event) => event.data?.startedAt === 1_000)).toBe(true);
+  });
+
+  it("preserves restart ownership when the CLI resolves after cancellation", async () => {
+    const events: Array<{ stream?: string; data?: Record<string, unknown> }> = [];
+    const stop = onAgentEvent((event) => {
+      if (event.runId === "run-restart") {
+        events.push(event);
+      }
+    });
+    const controller = new AbortController();
+    cliDispatchState.runCliAgentMock.mockImplementationOnce(async () => {
+      controller.abort(createAgentRunRestartAbortError());
+      return {
+        payloads: [{ text: "stale result" }],
+        meta: { durationMs: 1 },
+      } satisfies EmbeddedAgentRunResult;
+    });
+
+    await expect(
+      runCliAgentWithLifecycle({
+        runId: "run-restart",
+        provider: "claude-cli",
+        runParams: {
+          sessionId: "session-1",
+          sessionFile: "/tmp/session.jsonl",
+          workspaceDir: "/tmp/workspace",
+          prompt: "hello",
+          provider: "claude-cli",
+          model: "claude",
+          thinkLevel: "off",
+          timeoutMs: 1_000,
+          runId: "run-restart",
+          abortSignal: controller.signal,
+        },
+      }),
+    ).rejects.toThrow("agent run aborted for restart");
+    stop();
+
+    const terminal = events.find(
+      (event) => event.stream === "lifecycle" && event.data?.phase === "error",
+    );
+    expect(terminal?.data).toMatchObject({
+      aborted: true,
+      stopReason: "restart",
+    });
+    expect(events.some((event) => event.stream === "assistant")).toBe(false);
+  });
+
+  it("attributes a structured CLI watchdog timeout on the terminal event", async () => {
+    const events: Array<{ stream?: string; data?: Record<string, unknown> }> = [];
+    const stop = onAgentEvent((event) => {
+      if (event.runId === "run-timeout") {
+        events.push(event);
+      }
+    });
+    cliDispatchState.runCliAgentMock.mockRejectedValueOnce(
+      createCliTimeoutError(
+        { provider: "claude-cli", model: "claude", sessionId: "session-1" },
+        {
+          mode: "no-output",
+          timeoutSeconds: 1,
+          observedActivity: false,
+          activeToolCount: 0,
+          backgroundTaskCount: 0,
+        },
+      ),
+    );
+
+    await expect(
+      runCliAgentWithLifecycle({
+        runId: "run-timeout",
+        provider: "claude-cli",
+        runParams: {
+          sessionId: "session-1",
+          sessionFile: "/tmp/session.jsonl",
+          workspaceDir: "/tmp/workspace",
+          prompt: "hello",
+          provider: "claude-cli",
+          model: "claude",
+          thinkLevel: "off",
+          timeoutMs: 1_000,
+          runId: "run-timeout",
+        },
+      }),
+    ).rejects.toThrow("CLI produced no output");
+    stop();
+
+    expect(
+      events.find((event) => event.stream === "lifecycle" && event.data?.phase === "error")?.data,
+    ).toMatchObject({
+      stopReason: "timeout",
+      timeoutPhase: "provider",
+    });
+  });
+
+  it("propagates yielded result metadata on lifecycle end", async () => {
+    const events: Array<{ stream?: string; data?: Record<string, unknown> }> = [];
+    const stop = onAgentEvent((event) => {
+      if (event.runId === "run-yielded") {
+        events.push(event);
+      }
+    });
+    cliDispatchState.runCliAgentMock.mockResolvedValueOnce({
+      payloads: [],
+      meta: {
+        durationMs: 1,
+        yielded: true,
+        livenessState: "paused",
+        stopReason: "end_turn",
+      },
+    } satisfies EmbeddedAgentRunResult);
+
+    try {
+      await runCliAgentWithLifecycle({
+        runId: "run-yielded",
+        provider: "claude-cli",
+        runParams: {
+          sessionId: "session-1",
+          sessionFile: "/tmp/session.jsonl",
+          workspaceDir: "/tmp/workspace",
+          prompt: "hello",
+          provider: "claude-cli",
+          model: "claude",
+          thinkLevel: "off",
+          timeoutMs: 1_000,
+          runId: "run-yielded",
+        },
+      });
+    } finally {
+      stop();
+    }
+
+    const terminal = events.find(
+      (event) => event.stream === "lifecycle" && event.data?.phase === "end",
+    );
+    expect(terminal?.data).toMatchObject({
+      yielded: true,
+      livenessState: "paused",
+      stopReason: "end_turn",
+    });
+  });
+});
+
+describe("keepCliSessionBindingOnlyWhenReused", () => {
+  it("keeps the first room-event CLI binding when no binding exists yet", () => {
+    const result = {
+      payloads: [],
+      meta: {
+        durationMs: 1,
+        agentMeta: {
+          sessionId: "new-cli-session",
+          provider: "claude-cli",
+          model: "claude-opus-4-8",
+          cliSessionBinding: {
+            sessionId: "new-cli-session",
+            authProfileId: "profile",
+          },
+        },
+      },
+    } satisfies EmbeddedAgentRunResult;
+
+    expect(keepCliSessionBindingOnlyWhenReused({ result })).toBe(result);
+  });
+
+  it("drops a replacement room-event CLI binding when an existing binding was reused", () => {
+    const onDroppedReplacement = vi.fn();
+    const result = keepCliSessionBindingOnlyWhenReused({
+      existingSessionId: "existing-cli-session",
+      onDroppedReplacement,
+      result: {
+        payloads: [],
+        meta: {
+          durationMs: 1,
+          agentMeta: {
+            sessionId: "replacement-cli-session",
+            provider: "claude-cli",
+            model: "claude-opus-4-8",
+            cliSessionBinding: {
+              sessionId: "replacement-cli-session",
+              authProfileId: "profile",
+            },
+          },
+        },
+      } satisfies EmbeddedAgentRunResult,
+    });
+
+    expect(onDroppedReplacement).toHaveBeenCalledOnce();
+    expect(result.meta.agentMeta?.sessionId).toBe("");
+    expect(result.meta.agentMeta?.cliSessionBinding).toBeUndefined();
+  });
+});
+
+describe("clearCliSessionInStore", () => {
+  it.each(["current", "closed"])(
+    "clears active and stored entries only for a %s owner",
+    async (owner) => {
+      const activeEntry = {
+        sessionId: "openclaw-active",
+        updatedAt: 1,
+        cliSessionBindings: { "claude-cli": { sessionId: "stale-session" } },
+        cliSessionIds: { "claude-cli": "stale-session" },
+        claudeCliSessionId: "stale-session",
+      };
+      const storedEntry = structuredClone(activeEntry);
+      const storePath = path.join(tempDirs.make("cli-session-cleanup-"), "sessions.json");
+      await replaceSessionEntry({ storePath, sessionKey: "main" }, structuredClone(activeEntry));
+
+      let open = true;
+      const clear = clearCliSessionInStore({
+        provider: "claude-cli",
+        expectedCliSessionId: "stale-session",
+        expectedSessionId: activeEntry.sessionId,
+        sessionKey: "main",
+        sessionStore: { main: storedEntry },
+        storePath,
+        activeSessionEntry: activeEntry,
+        assertCommitAllowed: () => {
+          if (!open) {
+            throw new Error("owner closed");
+          }
+        },
+      });
+      if (owner === "closed") {
+        open = false;
+        await expect(clear).rejects.toThrow("owner closed");
+        for (const entry of [
+          activeEntry,
+          storedEntry,
+          loadSessionEntry({ storePath, sessionKey: "main" }),
+        ]) {
+          expect(entry?.cliSessionBindings?.["claude-cli"]?.sessionId).toBe("stale-session");
+        }
+        return;
+      }
+      await clear;
+
+      for (const entry of [activeEntry, storedEntry]) {
+        expect(entry.cliSessionBindings?.["claude-cli"]).toBeUndefined();
+        expect(entry.cliSessionIds?.["claude-cli"]).toBeUndefined();
+        expect(entry.claudeCliSessionId).toBeUndefined();
+        expect(entry.updatedAt).toBeGreaterThan(1);
+      }
+      const persisted = loadSessionEntry({ storePath, sessionKey: "main" });
+      expect(persisted?.cliSessionBindings?.["claude-cli"]).toBeUndefined();
+      expect(persisted?.cliSessionIds?.["claude-cli"]).toBeUndefined();
+      expect(persisted?.claudeCliSessionId).toBeUndefined();
+    },
+  );
+
+  it("does not clear a replacement binding adopted by another turn", async () => {
+    const entry = {
+      sessionId: "openclaw-active",
+      updatedAt: 1,
+      cliSessionBindings: { "claude-cli": { sessionId: "replacement-session" } },
+      cliSessionIds: { "claude-cli": "replacement-session" },
+      claudeCliSessionId: "replacement-session",
+    };
+
+    await clearCliSessionInStore({
+      provider: "claude-cli",
+      expectedCliSessionId: "stale-session",
+      activeSessionEntry: entry,
+    });
+
+    expect(entry.cliSessionBindings["claude-cli"].sessionId).toBe("replacement-session");
+    expect(entry.cliSessionIds["claude-cli"]).toBe("replacement-session");
+    expect(entry.claudeCliSessionId).toBe("replacement-session");
+    expect(entry.updatedAt).toBe(1);
+  });
+});
+
+describe("createCliToolSummaryTracker", () => {
+  const startEvent = {
+    name: "exec",
+    phase: "start" as const,
+    args: { command: "date -u" },
+    toolCallId: "tool-1",
+  };
+  const resultEvent = {
+    name: "exec",
+    phase: "result" as const,
+    args: undefined,
+    toolCallId: "tool-1",
+    isError: false,
+    result: { content: [{ type: "text", text: "Wed Jun 10 2026" }] },
+  };
+
+  it.each(["exec", "server.exec"])(
+    "delivers a safe %s summary using metadata captured at start",
+    async (name) => {
+      const deliver = vi.fn();
+      const tracker = createCliToolSummaryTracker({
+        commandDetailsVisible: false,
+        shouldEmitToolResult: () => true,
+        shouldEmitToolOutput: () => false,
+        deliver,
+      });
+      await tracker.noteToolEvent({ ...startEvent, name });
+      const commandBearing = await tracker.noteToolEvent({ ...resultEvent, name });
+      expect(commandBearing).toBe(true);
+      expect(deliver).toHaveBeenCalledTimes(1);
+      const payload = deliver.mock.calls[0]?.[0] as { text: string; isError?: boolean };
+      expect(payload.text).toContain(name === "exec" ? "Exec" : "Server.exec");
+      expect(payload.text).not.toContain("date -u");
+      expect(payload.text).not.toContain("Wed Jun 10 2026");
+      expect(payload.isError).toBeUndefined();
+    },
+  );
+
+  it("appends the tool output block when full verbose output is enabled", async () => {
+    const deliver = vi.fn();
+    const tracker = createCliToolSummaryTracker({
+      commandDetailsVisible: true,
+      shouldEmitToolResult: () => true,
+      shouldEmitToolOutput: () => true,
+      deliver,
+    });
+    await tracker.noteToolEvent(startEvent);
+    await tracker.noteToolEvent(resultEvent);
+    const payload = deliver.mock.calls[0]?.[0] as { text: string };
+    expect(payload.text).toContain("```txt");
+    expect(payload.text).toContain("Wed Jun 10 2026");
+  });
+
+  it("renders top-level structured CLI results in full verbose output", async () => {
+    const deliver = vi.fn();
+    const tracker = createCliToolSummaryTracker({
+      commandDetailsVisible: true,
+      shouldEmitToolResult: () => true,
+      shouldEmitToolOutput: () => true,
+      deliver,
+    });
+    await tracker.noteToolEvent(startEvent);
+    await tracker.noteToolEvent({
+      ...resultEvent,
+      result: [{ type: "web_search_result", title: "OpenClaw", url: "https://example.com" }],
+    });
+
+    const payload = deliver.mock.calls[0]?.[0] as { text: string };
+    expect(payload.text).toContain('"type":"web_search_result"');
+    expect(payload.text).toContain('"title":"OpenClaw"');
+  });
+
+  it("emits nothing while tool summaries are disabled", async () => {
+    const deliver = vi.fn();
+    const tracker = createCliToolSummaryTracker({
+      commandDetailsVisible: false,
+      shouldEmitToolResult: () => false,
+      shouldEmitToolOutput: () => false,
+      deliver,
+    });
+    await tracker.noteToolEvent(startEvent);
+    await tracker.noteToolEvent(resultEvent);
+    expect(deliver).not.toHaveBeenCalled();
+  });
+
+  it("leaves plan tools to the authoritative plan event instead of summarizing arguments", async () => {
+    const deliver = vi.fn();
+    const tracker = createCliToolSummaryTracker({
+      commandDetailsVisible: true,
+      shouldEmitToolResult: () => true,
+      shouldEmitToolOutput: () => true,
+      deliver,
+    });
+    await tracker.noteToolEvent({
+      name: "progress_card",
+      phase: "start",
+      args: {
+        markdown: '<progress aria-label="CI · 2/3" value="2" max="3"></progress>',
+      },
+      toolCallId: "plan-1",
+    });
+    await tracker.noteToolEvent({
+      name: "progress_card",
+      phase: "result",
+      args: undefined,
+      toolCallId: "plan-1",
+      isError: false,
+      result: { content: [{ type: "text", text: "Progress card updated" }] },
+    });
+
+    expect(deliver).not.toHaveBeenCalled();
+  });
+
+  it.each([false, true])(
+    "keeps card errors visible without arguments (full output: %s)",
+    async (fullOutput) => {
+      const deliver = vi.fn();
+      const tracker = createCliToolSummaryTracker({
+        commandDetailsVisible: false,
+        shouldEmitToolResult: () => true,
+        shouldEmitToolOutput: () => fullOutput,
+        deliver,
+      });
+      await tracker.noteToolEvent({
+        name: "progress_card",
+        phase: "start",
+        args: { markdown: '<progress aria-label="private" value="1" max="2"></progress>' },
+        toolCallId: "plan-error",
+      });
+      await tracker.noteToolEvent({
+        name: undefined,
+        phase: "result",
+        args: undefined,
+        toolCallId: "plan-error",
+        isError: true,
+        result: { content: [{ type: "text", text: "write failed" }] },
+      });
+
+      expect(deliver).toHaveBeenCalledWith({
+        text: fullOutput ? "🗺️ Progress Card\n```txt\nwrite failed\n```" : "🗺️ Progress Card",
+        isError: true,
+      });
+    },
+  );
+
+  it("propagates tool errors on the summary payload", async () => {
+    const deliver = vi.fn();
+    const tracker = createCliToolSummaryTracker({
+      commandDetailsVisible: false,
+      shouldEmitToolResult: () => true,
+      shouldEmitToolOutput: () => false,
+      deliver,
+    });
+    await tracker.noteToolEvent(startEvent);
+    await tracker.noteToolEvent({ ...resultEvent, isError: true });
+    const payload = deliver.mock.calls[0]?.[0] as { isError?: boolean };
+    expect(payload.isError).toBe(true);
+  });
+
+  it("summarizes results without a tracked start event", async () => {
+    const deliver = vi.fn();
+    const tracker = createCliToolSummaryTracker({
+      commandDetailsVisible: false,
+      shouldEmitToolResult: () => true,
+      shouldEmitToolOutput: () => false,
+      deliver,
+    });
+    await tracker.noteToolEvent({ ...resultEvent, toolCallId: "unseen" });
+    expect(deliver).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("runCliAgentWithLifecycle fast auto progress", () => {
+  it("emits auto-off after the first CLI tool boundary past the threshold", async () => {
+    vi.useFakeTimers();
+    vi.setSystemTime(1_000);
+    const events: Array<{ stream: string; data: Record<string, unknown> }> = [];
+    const stop = onAgentEvent((evt) => {
+      if (evt.runId === "run-fast-cli") {
+        events.push({ stream: evt.stream, data: evt.data });
+      }
+    });
+    const progressPayloads: string[] = [];
+    cliDispatchState.runCliAgentMock.mockImplementation(async () => {
+      emitAgentEvent({
+        runId: "run-fast-cli",
+        stream: "tool",
+        data: { phase: "start", name: "bash", toolCallId: "call-1" },
+      });
+      vi.setSystemTime(7_100);
+      emitAgentEvent({
+        runId: "run-fast-cli",
+        stream: "tool",
+        data: { phase: "result", name: "bash", toolCallId: "call-1" },
+      });
+      return {
+        payloads: [{ text: "done" }],
+        meta: {
+          durationMs: 7_100,
+          agentMeta: { sessionId: "session-1", provider: "codex-cli", model: "gpt-5.5" },
+        },
+      } satisfies EmbeddedAgentRunResult;
+    });
+
+    await runCliAgentWithLifecycle({
+      runId: "run-fast-cli",
+      provider: "codex-cli",
+      runParams: {
+        sessionId: "session-1",
+        sessionKey: "agent:main:cli-fast",
+        sessionFile: "/tmp/session.jsonl",
+        workspaceDir: "/tmp/workspace",
+        prompt: "run one tool",
+        provider: "codex-cli",
+        model: "gpt-5.5",
+        timeoutMs: 60_000,
+        runId: "run-fast-cli",
+        fastMode: "auto",
+        fastModeStartedAtMs: 1_000,
+        fastModeAutoOnSeconds: 5,
+      },
+      onFastModeAutoProgress: async (payload) => {
+        if (payload.text) {
+          progressPayloads.push(payload.text);
+        }
+      },
+    });
+    stop();
+
+    const summaries = events
+      .filter((event) => event.stream === "item")
+      .map((event) => event.data.summary);
+    expect(summaries).toContain("💨Fast: auto-off(6s>=5s)");
+    expect(summaries).toContain("💨Fast: auto-on");
+    expect(progressPayloads).toEqual(["💨Fast: auto-off(6s>=5s)", "💨Fast: auto-on"]);
+  });
+});

src/auto-reply/reply/agent-runner-cli-dispatch.ts

@@ -0,0 +1,705 @@
+// Builds CLI runtime dispatch inputs for agent runner executions.
+import { isRecord } from "@openclaw/normalization-core/record-coerce";
+import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
+import { runCliAgent } from "../../agents/cli-runner.js";
+import type { RunCliAgentParams } from "../../agents/cli-runner/types.js";
+import type { MediaImageLayout } from "../../agents/embedded-agent-runner/run/prompt-image-metadata.js";
+import { extractToolResultText } from "../../agents/embedded-agent-tool-results.js";
+import type { EmbeddedAgentRunResult } from "../../agents/embedded-agent.js";
+import {
+  DEFAULT_FAST_MODE_AUTO_ON_SECONDS,
+  formatFastModeAutoProgressText,
+  resolveFastModeForElapsed,
+  type FastModeAutoProgressState,
+} from "../../agents/fast-mode.js";
+import {
+  isAgentRunRestartAbortReason,
+  resolveAgentRunAbortLifecycleFields,
+  resolveAgentRunErrorLifecycleFields,
+} from "../../agents/run-termination.js";
+import { inferToolMetaFromArgsCore, isCommandBearingToolCall } from "../../agents/tool-display.js";
+import { normalizeAgentPlanSteps } from "../../channels/streaming.js";
+import type { AgentEventPayload } from "../../infra/agent-events.js";
+import { emitAgentEvent, withAgentRunLifecycleGeneration } from "../../infra/agent-events.js";
+import { isAgentPlanProgressToolName } from "../../session-cards/progress-card-channel-summary.js";
+import { FAST_MODE_AUTO_PROGRESS_KIND, type ReplyPayload } from "../reply-payload.js";
+import { formatToolAggregate } from "../tool-meta.js";
+import type { GetReplyOptions } from "../types.js";
+import {
+  type AgentEventDeliveryStartOrder,
+  createAgentEventBridge,
+  createAgentEventDeliveryStartOrder,
+} from "./agent-event-bridge.js";
+import { resolveAgentLifecycleTerminalMetadata } from "./agent-lifecycle-terminal.js";
+
+type RunCliAgentInternalParams = RunCliAgentParams & {
+  mediaImageLayout?: MediaImageLayout;
+};
+
+type AgentEventBridge = {
+  unsubscribe: () => void;
+  drain: () => Promise<void>;
+};
+
+async function stopAgentEventBridges(bridges: readonly AgentEventBridge[]): Promise<void> {
+  for (const bridge of bridges) {
+    bridge.unsubscribe();
+  }
+  for (const bridge of bridges) {
+    await bridge.drain();
+  }
+}
+
+function createAssistantTextBridge(params: {
+  runId: string;
+  suppressed?: boolean;
+  deliver?: (text: string) => Promise<boolean | void>;
+  startOrder?: AgentEventDeliveryStartOrder;
+}) {
+  let lastText: string | undefined;
+  return createAgentEventBridge({
+    runId: params.runId,
+    suppressed: params.suppressed,
+    deliver: params.deliver,
+    startOrder: params.startOrder,
+    read: (evt) => {
+      if (evt.stream !== "assistant") {
+        return undefined;
+      }
+      const text = typeof evt.data.text === "string" ? evt.data.text : undefined;
+      if (text === undefined || text === lastText) {
+        return undefined;
+      }
+      lastText = text;
+      return text;
+    },
+  });
+}
+
+type ReasoningTextPayload = {
+  text: string;
+  isReasoningSnapshot?: boolean;
+};
+
+type ReasoningProgressPayload = {
+  progressTokens: number;
+};
+
+export function createCliReasoningStreamBridge(
+  onReasoningStream: GetReplyOptions["onReasoningStream"] | undefined,
+): ((payload: ReasoningTextPayload) => Promise<void>) | undefined {
+  if (!onReasoningStream) {
+    return undefined;
+  }
+  return async ({ text, isReasoningSnapshot }) => {
+    await onReasoningStream({
+      text,
+      ...(isReasoningSnapshot ? { isReasoningSnapshot } : {}),
+      requiresReasoningProgressOptIn: true,
+    });
+  };
+}
+
+function createReasoningTextBridge(params: {
+  runId: string;
+  suppressed?: boolean;
+  deliver?: (payload: ReasoningTextPayload) => Promise<void>;
+  startOrder?: AgentEventDeliveryStartOrder;
+}) {
+  let lastText: string | undefined;
+  return createAgentEventBridge({
+    runId: params.runId,
+    suppressed: params.suppressed,
+    deliver: params.deliver,
+    startOrder: params.startOrder,
+    read: (evt) => {
+      if (evt.stream !== "thinking") {
+        return undefined;
+      }
+      const text = typeof evt.data.text === "string" ? evt.data.text : undefined;
+      if (text === undefined || text === lastText) {
+        return undefined;
+      }
+      lastText = text;
+      return {
+        text,
+        ...(evt.data.isReasoningSnapshot === true ? { isReasoningSnapshot: true } : {}),
+      };
+    },
+  });
+}
+
+function createReasoningProgressBridge(params: {
+  runId: string;
+  suppressed?: boolean;
+  deliver?: (payload: ReasoningProgressPayload) => Promise<void>;
+  startOrder?: AgentEventDeliveryStartOrder;
+}) {
+  let lastProgressTokens: number | undefined;
+  return createAgentEventBridge({
+    runId: params.runId,
+    suppressed: params.suppressed,
+    deliver: params.deliver,
+    startOrder: params.startOrder,
+    read: (evt) => {
+      if (evt.stream !== "thinking") {
+        return undefined;
+      }
+      const progressTokens = evt.data.progressTokens;
+      if (
+        typeof progressTokens !== "number" ||
+        !Number.isFinite(progressTokens) ||
+        progressTokens <= 0 ||
+        progressTokens === lastProgressTokens
+      ) {
+        return undefined;
+      }
+      lastProgressTokens = progressTokens;
+      return { progressTokens };
+    },
+  });
+}
+
+type CommentaryTextPayload = {
+  text: string;
+  itemId?: string;
+};
+
+function readCommentaryTextPayload(evt: AgentEventPayload): CommentaryTextPayload | undefined {
+  if (evt.stream !== "item" || evt.data.kind !== "preamble") {
+    return undefined;
+  }
+  const text = typeof evt.data.progressText === "string" ? evt.data.progressText.trim() : "";
+  if (!text) {
+    return undefined;
+  }
+  return {
+    text,
+    ...(typeof evt.data.itemId === "string" ? { itemId: evt.data.itemId } : {}),
+  };
+}
+
+type CliToolEventPayload = {
+  name: string | undefined;
+  phase: "start" | "update" | "result";
+  args: Record<string, unknown> | undefined;
+  toolCallId?: string;
+  isError?: boolean;
+  result?: unknown;
+};
+
+export function keepCliSessionBindingOnlyWhenReused(params: {
+  result: EmbeddedAgentRunResult;
+  existingSessionId?: string;
+  onDroppedReplacement?: () => void;
+}): EmbeddedAgentRunResult {
+  const existingSessionId = normalizeOptionalString(params.existingSessionId);
+  const agentMeta = params.result.meta.agentMeta;
+  const returnedSessionId = normalizeOptionalString(agentMeta?.cliSessionBinding?.sessionId);
+  const shouldClearStoredSession = agentMeta?.clearCliSessionBinding === true;
+  if (
+    agentMeta === undefined ||
+    (!shouldClearStoredSession && existingSessionId === undefined) ||
+    returnedSessionId === existingSessionId
+  ) {
+    return params.result;
+  }
+  if (returnedSessionId || shouldClearStoredSession) {
+    params.onDroppedReplacement?.();
+  }
+  return {
+    ...params.result,
+    meta: {
+      ...params.result.meta,
+      agentMeta: {
+        ...agentMeta,
+        sessionId: "",
+        cliSessionBinding: undefined,
+        clearCliSessionBinding: undefined,
+      },
+    },
+  };
+}
+
+function createToolEventBridge(params: {
+  runId: string;
+  suppressed?: boolean;
+  deliver?: (payload: CliToolEventPayload) => Promise<void>;
+  startOrder?: AgentEventDeliveryStartOrder;
+}) {
+  return createAgentEventBridge({
+    runId: params.runId,
+    suppressed: params.suppressed,
+    deliver: params.deliver,
+    startOrder: params.startOrder,
+    read: (evt) => {
+      if (evt.stream !== "tool") {
+        return undefined;
+      }
+      const phaseValue = evt.data.phase;
+      if (phaseValue !== "start" && phaseValue !== "update" && phaseValue !== "result") {
+        return undefined;
+      }
+      const phase: CliToolEventPayload["phase"] =
+        phaseValue === "start" ? "start" : phaseValue === "update" ? "update" : "result";
+      return {
+        name: typeof evt.data.name === "string" ? evt.data.name : undefined,
+        phase,
+        args: isRecord(evt.data.args) ? evt.data.args : undefined,
+        toolCallId: typeof evt.data.toolCallId === "string" ? evt.data.toolCallId : undefined,
+        ...(phase === "result"
+          ? {
+              isError: evt.data.isError === true,
+              result: evt.data.result,
+            }
+          : {}),
+      };
+    },
+  });
+}
+
+/**
+ * Tracks CLI tool start/result events and renders the same durable tool
+ * summaries the embedded runner emits: a formatToolAggregate line per result
+ * (args-derived meta captured at start), plus the output block under full
+ * verbose. Keeps CLI runs at tool-summary parity with embedded runs.
+ */
+export function createCliToolSummaryTracker(params: {
+  detailMode?: "explain" | "raw";
+  commandDetailsVisible: boolean;
+  shouldEmitToolResult: () => boolean;
+  shouldEmitToolOutput: () => boolean;
+  deliver: (payload: { text: string; isError?: boolean }) => Promise<void> | void;
+}) {
+  const toolByCallId = new Map<string, { name: string; meta?: string; commandBearing: boolean }>();
+  return {
+    noteToolEvent: async (payload: CliToolEventPayload): Promise<boolean> => {
+      if (payload.phase === "start") {
+        if (payload.toolCallId && payload.name) {
+          toolByCallId.set(payload.toolCallId, {
+            name: payload.name,
+            meta: inferToolMetaFromArgsCore(payload.name, payload.args, {
+              detailMode: params.detailMode ?? "explain",
+            }),
+            commandBearing: isCommandBearingToolCall(payload.name, payload.args),
+          });
+        }
+        return false;
+      }
+      if (payload.phase !== "result") {
+        return false;
+      }
+      const storedTool = payload.toolCallId ? toolByCallId.get(payload.toolCallId) : undefined;
+      const toolName = payload.name ?? storedTool?.name;
+      const meta =
+        params.commandDetailsVisible || !storedTool?.commandBearing ? storedTool?.meta : undefined;
+      if (payload.toolCallId) {
+        toolByCallId.delete(payload.toolCallId);
+      }
+      if (payload.isError !== true && isAgentPlanProgressToolName(toolName)) {
+        return false;
+      }
+      if (!params.shouldEmitToolResult()) {
+        return storedTool?.commandBearing === true;
+      }
+      const aggregate = formatToolAggregate(toolName, meta ? [meta] : undefined, {
+        markdown: true,
+      });
+      let text = aggregate;
+      if (params.shouldEmitToolOutput()) {
+        const output = extractToolResultText(payload.result)?.trim();
+        if (output) {
+          text = `${aggregate}\n\`\`\`txt\n${output}\n\`\`\``;
+        }
+      }
+      if (!text.trim()) {
+        return storedTool?.commandBearing === true;
+      }
+      await params.deliver({ text, ...(payload.isError === true ? { isError: true } : {}) });
+      return storedTool?.commandBearing === true;
+    },
+  };
+}
+
+function createCommentaryEventBridge(params: {
+  runId: string;
+  suppressed?: boolean;
+  deliver?: (payload: CommentaryTextPayload) => Promise<void>;
+  startOrder?: AgentEventDeliveryStartOrder;
+}) {
+  return createAgentEventBridge({
+    runId: params.runId,
+    suppressed: params.suppressed,
+    deliver: params.deliver,
+    startOrder: params.startOrder,
+    read: readCommentaryTextPayload,
+  });
+}
+
+function createPlanUpdateBridge(params: {
+  runId: string;
+  suppressed?: boolean;
+  deliver?: GetReplyOptions["onPlanUpdate"];
+  startOrder?: AgentEventDeliveryStartOrder;
+}) {
+  const deliver = params.deliver;
+  return createAgentEventBridge({
+    runId: params.runId,
+    suppressed: params.suppressed,
+    // GetReplyOptions callbacks may return void; the bridge awaits promises.
+    deliver: deliver
+      ? async (payload: Parameters<NonNullable<GetReplyOptions["onPlanUpdate"]>>[0]) => {
+          await deliver(payload);
+        }
+      : undefined,
+    startOrder: params.startOrder,
+    read: (evt) => {
+      if (evt.stream !== "plan") {
+        return undefined;
+      }
+      return {
+        phase: normalizeOptionalString(evt.data.phase),
+        title: normalizeOptionalString(evt.data.title),
+        explanation: normalizeOptionalString(evt.data.explanation),
+        ...(evt.data.explanationFormat === "plain" ? { explanationFormat: "plain" as const } : {}),
+        steps: normalizeAgentPlanSteps(evt.data.steps),
+        source: normalizeOptionalString(evt.data.source),
+      };
+    },
+  });
+}
+
+function createToolBoundaryBridge(params: {
+  runId: string;
+  suppressed?: boolean;
+  deliver?: () => Promise<void>;
+}) {
+  return createAgentEventBridge({
+    runId: params.runId,
+    suppressed: params.suppressed,
+    deliver: params.deliver,
+    read: (evt) => {
+      if (evt.stream !== "tool") {
+        return undefined;
+      }
+      const phase = typeof evt.data.phase === "string" ? evt.data.phase : "";
+      return ["completed", "end", "error", "result"].includes(phase) ? true : undefined;
+    },
+  });
+}
+
+type RunCliAgentWithLifecycleParams = {
+  runId: string;
+  lifecycleGeneration?: string;
+  provider: string;
+  runParams: RunCliAgentInternalParams;
+  startedAt?: number;
+  emitLifecycleTerminal?: boolean;
+  onAgentRunStart?: () => void;
+  suppressAssistantBridge?: boolean;
+  /**
+   * Stamped before every delivered CLI progress event (assistant, reasoning,
+   * tool, commentary, fast-mode). Callers wire this to the reply operation's
+   * activity evidence; per-callback stamps at call sites drift and a missed
+   * stamp lets stale-takeover reclaim a healthy run.
+   */
+  onActivity?: () => void;
+  preserveProgressCallbackStartOrder?: boolean;
+  onAssistantText?: (text: string) => Promise<boolean | void>;
+  onReasoningText?: (payload: ReasoningTextPayload) => Promise<void>;
+  onReasoningProgress?: (payload: ReasoningProgressPayload) => Promise<void>;
+  onCompactionStart?: GetReplyOptions["onCompactionStart"];
+  onCompactionEnd?: GetReplyOptions["onCompactionEnd"];
+  onToolEvent?: (payload: CliToolEventPayload) => Promise<void>;
+  onCommentaryText?: (payload: CommentaryTextPayload) => Promise<void>;
+  onPlanUpdate?: GetReplyOptions["onPlanUpdate"];
+  onFastModeAutoProgress?: (payload: ReplyPayload) => Promise<void>;
+  onErrorBeforeLifecycle?: (err: unknown) => Promise<void>;
+  transformResult?: (result: EmbeddedAgentRunResult) => EmbeddedAgentRunResult;
+};
+
+export function runCliAgentWithLifecycle(
+  params: RunCliAgentWithLifecycleParams,
+): Promise<EmbeddedAgentRunResult> {
+  if (!params.lifecycleGeneration) {
+    return runCliAgentWithLifecycleInternal(params);
+  }
+  return withAgentRunLifecycleGeneration(params.lifecycleGeneration, () =>
+    runCliAgentWithLifecycleInternal(params),
+  );
+}
+
+async function runCliAgentWithLifecycleInternal(
+  params: RunCliAgentWithLifecycleParams,
+): Promise<EmbeddedAgentRunResult> {
+  const startedAt = params.startedAt ?? Date.now();
+  const fastModeStartedAtMs = params.runParams.fastModeStartedAtMs ?? startedAt;
+  const fastModeAutoOnSeconds =
+    params.runParams.fastModeAutoOnSeconds ?? DEFAULT_FAST_MODE_AUTO_ON_SECONDS;
+  const fastModeAutoProgressState: FastModeAutoProgressState = params.runParams
+    .fastModeAutoProgressState ?? {
+    offAnnounced: false,
+    resetAnnounced: false,
+  };
+  const emitFastModeAutoProgress = async (payload: {
+    enabled: boolean;
+    elapsedSeconds: number;
+    fastAutoOnSeconds?: number;
+  }) => {
+    const summary = formatFastModeAutoProgressText(payload);
+    emitAgentEvent({
+      runId: params.runId,
+      stream: "item",
+      data: {
+        kind: "status",
+        title: "Fast",
+        phase: "update",
+        summary,
+      },
+      ...(params.runParams.sessionKey ? { sessionKey: params.runParams.sessionKey } : {}),
+    });
+    try {
+      await params.onFastModeAutoProgress?.({
+        text: summary,
+        channelData: { openclawProgressKind: FAST_MODE_AUTO_PROGRESS_KIND },
+      });
+    } catch {
+      // Progress hints are best-effort; a channel failure must not fail the agent turn.
+    }
+  };
+  const maybeAnnounceFastModeAutoOff = async () => {
+    if (params.runParams.fastMode !== "auto" || fastModeAutoProgressState.offAnnounced) {
+      return;
+    }
+    const next = resolveFastModeForElapsed({
+      mode: "auto",
+      startedAtMs: fastModeStartedAtMs,
+      fastAutoOnSeconds: fastModeAutoOnSeconds,
+    });
+    if (next.enabled) {
+      return;
+    }
+    fastModeAutoProgressState.offAnnounced = true;
+    await emitFastModeAutoProgress(next);
+  };
+  const maybeEmitFastModeAutoReset = async () => {
+    if (
+      params.runParams.fastMode !== "auto" ||
+      !fastModeAutoProgressState.offAnnounced ||
+      fastModeAutoProgressState.resetAnnounced
+    ) {
+      return;
+    }
+    fastModeAutoProgressState.resetAnnounced = true;
+    await emitFastModeAutoProgress({
+      enabled: true,
+      elapsedSeconds: 0,
+      fastAutoOnSeconds: fastModeAutoOnSeconds,
+    });
+  };
+  const emitLifecycleTerminal = params.emitLifecycleTerminal ?? true;
+  params.onAgentRunStart?.();
+  emitAgentEvent({
+    runId: params.runId,
+    ...(params.runParams.agentId ? { agentId: params.runParams.agentId } : {}),
+    ...(params.runParams.sessionKey ? { sessionKey: params.runParams.sessionKey } : {}),
+    ...(params.runParams.sessionId ? { sessionId: params.runParams.sessionId } : {}),
+    ...(params.lifecycleGeneration ? { lifecycleGeneration: params.lifecycleGeneration } : {}),
+    stream: "lifecycle",
+    data: {
+      phase: "start",
+      startedAt,
+    },
+  });
+  // One delivery-independent activity seam for every CLI agent event.
+  // Suppressed (silentExpected) runs still emit real events and must keep
+  // stamping, or a healthy silent stream looks stale to the takeover window.
+  const activityBridge = params.onActivity
+    ? createAgentEventBridge<Record<string, never>>({
+        runId: params.runId,
+        read: () => ({}),
+        deliver: async () => {
+          params.onActivity?.();
+        },
+      })
+    : undefined;
+  const progressStartOrder = params.preserveProgressCallbackStartOrder
+    ? createAgentEventDeliveryStartOrder()
+    : undefined;
+  const assistantBridge = createAssistantTextBridge({
+    runId: params.runId,
+    suppressed: params.suppressAssistantBridge,
+    deliver: params.onAssistantText,
+    startOrder: progressStartOrder,
+  });
+  let finalReasoningText: string | undefined;
+  const reasoningBridge = createReasoningTextBridge({
+    runId: params.runId,
+    suppressed: params.suppressAssistantBridge,
+    startOrder: progressStartOrder,
+    deliver: async (payload: ReasoningTextPayload) => {
+      finalReasoningText = normalizeOptionalString(payload.text);
+      await params.onReasoningText?.(payload);
+    },
+  });
+  const reasoningProgressBridge = createReasoningProgressBridge({
+    runId: params.runId,
+    suppressed: params.suppressAssistantBridge,
+    deliver: params.onReasoningProgress,
+    startOrder: progressStartOrder,
+  });
+  const compactionBridge = createAgentEventBridge<
+    { phase: "start" } | { completed: boolean; phase: "end" }
+  >({
+    runId: params.runId,
+    suppressed: params.suppressAssistantBridge,
+    startOrder: progressStartOrder,
+    deliver: async (event) => {
+      if (event.phase === "start") {
+        await params.onCompactionStart?.();
+      } else {
+        await params.onCompactionEnd?.({ completed: event.completed });
+      }
+    },
+    read: (evt) => {
+      if (evt.stream !== "compaction") {
+        return undefined;
+      }
+      if (evt.data.phase === "start") {
+        return { phase: "start" };
+      }
+      return evt.data.phase === "end"
+        ? { phase: "end", completed: evt.data.completed === true }
+        : undefined;
+    },
+  });
+  const toolBridge = createToolEventBridge({
+    runId: params.runId,
+    suppressed: params.suppressAssistantBridge,
+    deliver: params.onToolEvent,
+    startOrder: progressStartOrder,
+  });
+  const commentaryBridge = createCommentaryEventBridge({
+    runId: params.runId,
+    suppressed: params.suppressAssistantBridge,
+    deliver: params.onCommentaryText,
+    startOrder: progressStartOrder,
+  });
+  const planBridge = createPlanUpdateBridge({
+    runId: params.runId,
+    suppressed: params.suppressAssistantBridge,
+    deliver: params.onPlanUpdate,
+    startOrder: progressStartOrder,
+  });
+  const toolBoundaryBridge = createToolBoundaryBridge({
+    runId: params.runId,
+    suppressed: params.suppressAssistantBridge,
+    deliver: maybeAnnounceFastModeAutoOff,
+  });
+  const bridges = [
+    activityBridge,
+    assistantBridge,
+    reasoningBridge,
+    reasoningProgressBridge,
+    compactionBridge,
+    toolBridge,
+    commentaryBridge,
+    planBridge,
+    toolBoundaryBridge,
+  ].filter((bridge): bridge is AgentEventBridge => bridge !== undefined);
+  let lifecycleTerminalEmitted = false;
+  try {
+    const rawResult = await runCliAgent({
+      ...params.runParams,
+      emitCommentaryText: params.runParams.emitCommentaryText ?? Boolean(params.onCommentaryText),
+    });
+    const restartAbortReason = params.runParams.abortSignal?.reason;
+    if (isAgentRunRestartAbortReason(restartAbortReason)) {
+      throw restartAbortReason;
+    }
+    const result = params.transformResult?.(rawResult) ?? rawResult;
+    await stopAgentEventBridges(bridges);
+
+    const cliText = normalizeOptionalString(result.payloads?.[0]?.text);
+    const durableReasoningText = normalizeOptionalString(finalReasoningText);
+    const resultWithReasoning = durableReasoningText
+      ? {
+          ...result,
+          payloads: [{ text: durableReasoningText, isReasoning: true }, ...(result.payloads ?? [])],
+        }
+      : result;
+    if (cliText) {
+      emitAgentEvent({
+        runId: params.runId,
+        stream: "assistant",
+        data: { text: cliText },
+      });
+    }
+
+    if (emitLifecycleTerminal) {
+      emitAgentEvent({
+        runId: params.runId,
+        ...(params.runParams.agentId ? { agentId: params.runParams.agentId } : {}),
+        ...(params.runParams.sessionKey ? { sessionKey: params.runParams.sessionKey } : {}),
+        ...(params.runParams.sessionId ? { sessionId: params.runParams.sessionId } : {}),
+        ...(params.lifecycleGeneration ? { lifecycleGeneration: params.lifecycleGeneration } : {}),
+        stream: "lifecycle",
+        data: {
+          phase: "end",
+          startedAt,
+          endedAt: Date.now(),
+          ...resolveAgentLifecycleTerminalMetadata(result.meta),
+          ...resolveAgentRunAbortLifecycleFields(params.runParams.abortSignal),
+        },
+      });
+      lifecycleTerminalEmitted = true;
+    }
+    return resultWithReasoning;
+  } catch (err) {
+    await stopAgentEventBridges(bridges);
+    await params.onErrorBeforeLifecycle?.(err);
+    if (emitLifecycleTerminal) {
+      emitAgentEvent({
+        runId: params.runId,
+        ...(params.runParams.agentId ? { agentId: params.runParams.agentId } : {}),
+        ...(params.runParams.sessionKey ? { sessionKey: params.runParams.sessionKey } : {}),
+        ...(params.runParams.sessionId ? { sessionId: params.runParams.sessionId } : {}),
+        ...(params.lifecycleGeneration ? { lifecycleGeneration: params.lifecycleGeneration } : {}),
+        stream: "lifecycle",
+        data: {
+          phase: "error",
+          startedAt,
+          endedAt: Date.now(),
+          error: String(err),
+          ...resolveAgentRunErrorLifecycleFields(err, params.runParams.abortSignal),
+        },
+      });
+      lifecycleTerminalEmitted = true;
+    }
+    throw err;
+  } finally {
+    for (const bridge of bridges) {
+      bridge.unsubscribe();
+    }
+    if (params.runParams.isFinalFallbackAttempt !== false) {
+      await maybeEmitFastModeAutoReset();
+    }
+    if (emitLifecycleTerminal && !lifecycleTerminalEmitted) {
+      emitAgentEvent({
+        runId: params.runId,
+        ...(params.runParams.agentId ? { agentId: params.runParams.agentId } : {}),
+        ...(params.runParams.sessionKey ? { sessionKey: params.runParams.sessionKey } : {}),
+        ...(params.runParams.sessionId ? { sessionId: params.runParams.sessionId } : {}),
+        ...(params.lifecycleGeneration ? { lifecycleGeneration: params.lifecycleGeneration } : {}),
+        stream: "lifecycle",
+        data: {
+          phase: "error",
+          startedAt,
+          endedAt: Date.now(),
+          error: "CLI run completed without lifecycle terminal event",
+          ...resolveAgentRunAbortLifecycleFields(params.runParams.abortSignal),
+        },
+      });
+    }
+  }
+}

src/auto-reply/reply/agent-runner-command-output.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it } from "vitest";
+import { buildCommandOutputFromToolResultEvent } from "./agent-runner-command-output.js";
+
+const BASH_ARGS = { command: "nope-not-a-command", description: "run missing binary" };
+
+function buildFromCliResult(overrides: Record<string, unknown>) {
+  return buildCommandOutputFromToolResultEvent({
+    stream: "tool",
+    data: { phase: "result", name: "Bash", toolCallId: "call-1", args: BASH_ARGS, ...overrides },
+  });
+}
+
+describe("buildCommandOutputFromToolResultEvent", () => {
+  it("reports a CLI command failure whose result is only text", () => {
+    // CLI backends report the outcome plus raw content, never a structured
+    // record, so requiring a structured field dropped the failure entirely.
+    const built = buildFromCliResult({
+      isError: true,
+      result: "bash: nope-not-a-command: command not found",
+    });
+
+    expect(built?.status).toBe("failed");
+    expect(built?.output).toBe("bash: nope-not-a-command: command not found");
+  });
+
+  it("reads the outcome from streamed text blocks", () => {
+    const built = buildFromCliResult({
+      isError: true,
+      result: [
+        { type: "text", text: "line one" },
+        { type: "text", text: "line two" },
+      ],
+    });
+
+    expect(built?.status).toBe("failed");
+    expect(built?.output).toBe("line one\nline two");
+  });
+
+  it("describes the command that ran instead of what it printed", () => {
+    const built = buildFromCliResult({ isError: true, result: "some noisy stderr" });
+
+    // The title drives the visible progress line; without it the line would
+    // replace the request with the tool's output.
+    expect(built?.title).toContain("nope-not-a-command");
+  });
+
+  it("marks a successful CLI command completed", () => {
+    expect(buildFromCliResult({ isError: false, result: "alpha" })?.status).toBe("completed");
+  });
+
+  it("projects a safe terminal state from a namespaced command-bearing result", () => {
+    const built = buildCommandOutputFromToolResultEvent({
+      stream: "tool",
+      data: {
+        phase: "result",
+        name: "server.exec",
+        toolCallId: "call-1",
+        commandBearing: true,
+        isError: false,
+      },
+    });
+
+    expect(built).toMatchObject({
+      name: "server.exec",
+      status: "completed",
+      toolCallId: "call-1",
+    });
+  });
+
+  it("prefers an explicit status and structured fields when present", () => {
+    const built = buildCommandOutputFromToolResultEvent({
+      stream: "tool",
+      data: {
+        phase: "result",
+        name: "exec",
+        toolCallId: "call-1",
+        title: "false",
+        isError: true,
+        result: { exitCode: 2, output: "structured output", status: "exit 2" },
+      },
+    });
+
+    expect(built).toMatchObject({
+      status: "exit 2",
+      exitCode: 2,
+      output: "structured output",
+      title: "false",
+    });
+  });
+
+  it("ignores events that carry no outcome and no content", () => {
+    expect(
+      buildCommandOutputFromToolResultEvent({
+        stream: "tool",
+        data: { phase: "result", name: "Bash", toolCallId: "call-1" },
+      }),
+    ).toBeUndefined();
+  });
+
+  it("ignores non-command tools and non-result phases", () => {
+    expect(
+      buildCommandOutputFromToolResultEvent({
+        stream: "tool",
+        data: { phase: "result", name: "Read", toolCallId: "call-1", isError: true },
+      }),
+    ).toBeUndefined();
+    expect(buildFromCliResult({ phase: "start", isError: true })).toBeUndefined();
+  });
+});

src/auto-reply/reply/agent-runner-command-output.ts

@@ -0,0 +1,104 @@
+import { asFiniteNumber as readFiniteNumberValue } from "@openclaw/normalization-core/number-coercion";
+import { asOptionalRecord as readRecordValue } from "@openclaw/normalization-core/record-coerce";
+import { readStringValue } from "@openclaw/normalization-core/string-coerce";
+import type { EmbeddedAgentEvent } from "../../agents/embedded-agent-subscribe.shared-types.js";
+import { inferToolMetaFromArgsCore } from "../../agents/tool-display.js";
+import type { GetReplyOptions } from "../types.js";
+
+/**
+ * CLI backends report a tool result as its raw content: a string, or the text
+ * blocks the harness streamed. Structured runners send a record instead, so the
+ * command projection has to read both or every CLI command result is dropped.
+ */
+function readToolResultText(value: unknown): string | undefined {
+  const direct = readStringValue(value);
+  if (direct !== undefined) {
+    return direct;
+  }
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+  const text = value
+    .map((block) => readStringValue(readRecordValue(block)?.text))
+    .filter((part): part is string => part !== undefined)
+    .join("\n")
+    .trim();
+  return text || undefined;
+}
+
+function readNullableNumberValue(value: unknown): number | null | undefined {
+  if (value === null) {
+    return null;
+  }
+  return readFiniteNumberValue(value);
+}
+
+function isCommandToolName(name: string | undefined): boolean {
+  const normalized = name?.trim().toLowerCase();
+  return normalized === "exec" || normalized === "bash" || normalized === "shell";
+}
+
+/** Projects a completed command-tool event into the channel command-output contract. */
+export function buildCommandOutputFromToolResultEvent(
+  evt: EmbeddedAgentEvent,
+): Parameters<NonNullable<GetReplyOptions["onCommandOutput"]>>[0] | undefined {
+  if (evt.stream !== "tool" || evt.data.phase !== "result") {
+    return undefined;
+  }
+  const name = evt.data.name;
+  const commandBearing = evt.data.commandBearing === true;
+  if (!name || (!commandBearing && !isCommandToolName(name))) {
+    return undefined;
+  }
+  const result = readRecordValue(evt.data.result);
+  const details = readRecordValue(result?.details);
+  const output =
+    evt.data.output ??
+    readStringValue(result?.output) ??
+    readStringValue(details?.output) ??
+    readToolResultText(evt.data.result);
+  const explicitStatus =
+    evt.data.status ?? readStringValue(result?.status) ?? readStringValue(details?.status);
+  const exitCode = readNullableNumberValue(
+    result?.exitCode ?? details?.exitCode ?? evt.data.exitCode,
+  );
+  const durationMs = readFiniteNumberValue(
+    result?.durationMs ?? details?.durationMs ?? evt.data.durationMs,
+  );
+  const cwd = evt.data.cwd;
+  const errorStatus =
+    evt.data.isError === true ? "failed" : evt.data.isError === false ? "completed" : undefined;
+  // A bare result carries no outcome of its own: runners that report one send a
+  // separate command_output event, and synthesizing here would duplicate it.
+  // A CLI result is different because its content *is* the outcome, which
+  // readToolResultText surfaces as output above.
+  const hasConcreteCommandResult =
+    output !== undefined ||
+    explicitStatus !== undefined ||
+    exitCode !== undefined ||
+    durationMs !== undefined ||
+    cwd !== undefined ||
+    (commandBearing && typeof evt.data.isError === "boolean") ||
+    (result !== undefined && Object.keys(result).length > 0);
+  if (!hasConcreteCommandResult) {
+    return undefined;
+  }
+  // Keep the line describing the command, not its output: without a title the
+  // terminal line would replace the request with whatever the tool printed.
+  const args = evt.data.args;
+  const title =
+    evt.data.title ??
+    (args ? inferToolMetaFromArgsCore(name, args, { detailMode: "explain" }) : undefined);
+  return {
+    itemId: evt.data.itemId,
+    phase: "end",
+    title,
+    toolCallId: evt.data.toolCallId,
+    name,
+    output,
+    status: explicitStatus ?? errorStatus,
+    exitCode,
+    durationMs,
+    cwd,
+  };
+}

src/auto-reply/reply/agent-runner-compaction-accounting.ts

@@ -0,0 +1,58 @@
+import type {
+  CompactionAccountingFact,
+  CompactionAccountingTarget,
+} from "../../agents/embedded-agent-runner/run/internal-params.js";
+import type { AgentTurnCompaction } from "./agent-runner-execution.types.js";
+
+export function hasSameCompactionWriter(
+  previous: CompactionAccountingTarget | undefined,
+  current: CompactionAccountingTarget,
+): boolean {
+  // Physical session IDs may rotate while the binding and retained writer stay fixed.
+  return (
+    previous !== undefined &&
+    previous.agentId === current.agentId &&
+    previous.sessionKey === current.sessionKey &&
+    previous.storePath === current.storePath &&
+    previous.lifecycleRevision === current.lifecycleRevision &&
+    previous.activeWriterRunId === current.activeWriterRunId
+  );
+}
+
+/** A later opaque candidate may lose freshness, but must never fabricate it. */
+export function invalidateTurnCompactionContext(compaction: AgentTurnCompaction): void {
+  compaction.durable = compaction.durable.map((fact) => ({
+    ...fact,
+    currentContextSnapshot: { tokens: undefined },
+  }));
+}
+
+/** Fold same-writer facts; only an ordered snapshot may refresh context. */
+export function recordTurnCompaction(
+  compaction: AgentTurnCompaction,
+  fact: CompactionAccountingFact,
+): void {
+  if (fact.count < 0) {
+    return;
+  }
+  compaction.count += fact.count;
+  if (fact.kind !== "durable") {
+    return;
+  }
+  const index = compaction.durable.findIndex(({ target }) =>
+    hasSameCompactionWriter(target, fact.target),
+  );
+  const previous = compaction.durable[index];
+  if (!previous && fact.count === 0) {
+    return;
+  }
+  if (previous) {
+    compaction.durable.splice(index, 1);
+  }
+  // Custody without an observation cannot erase the prior candidate's explicit invalidation.
+  compaction.durable.push({
+    ...fact,
+    count: (previous?.count ?? 0) + fact.count,
+    currentContextSnapshot: fact.currentContextSnapshot ?? previous?.currentContextSnapshot,
+  });
+}

src/auto-reply/reply/agent-runner-context-recovery.test.ts

@@ -0,0 +1,142 @@
+import { describe, expect, it } from "vitest";
+import type { ModelDefinitionConfig } from "../../config/types.models.js";
+import { buildContextOverflowRecoveryText } from "./agent-runner-context-recovery.js";
+
+function makeTestModel(id: string, contextTokens: number): ModelDefinitionConfig {
+  return {
+    id,
+    name: id,
+    reasoning: false,
+    input: ["text"],
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    contextWindow: contextTokens,
+    contextTokens,
+    maxTokens: 4096,
+  };
+}
+
+describe("buildContextOverflowRecoveryText", () => {
+  it("uses the built-in recovery hint without heartbeat model evidence", () => {
+    const text = buildContextOverflowRecoveryText({
+      cfg: {},
+      primaryProvider: "openrouter",
+      primaryModel: "qwen3.6-plus",
+    });
+
+    expect(text).toContain("fresh session or using a model with a larger context window");
+    expect(text).not.toContain("reserveTokensFloor");
+    expect(text).not.toContain("heartbeat model bleed");
+  });
+
+  it("keeps the preserved-session copy with the built-in recovery hint", () => {
+    const text = buildContextOverflowRecoveryText({
+      preserveSessionMapping: true,
+      cfg: {},
+      primaryProvider: "openrouter",
+      primaryModel: "qwen3.6-plus",
+    });
+
+    expect(text).toContain("kept this conversation mapped to the current session");
+    expect(text).toContain("fresh session or using a model with a larger context window");
+    expect(text).not.toContain("reset our conversation");
+  });
+
+  it("does not use stale heartbeat hints for a different explicit runtime model", () => {
+    const text = buildContextOverflowRecoveryText({
+      cfg: {
+        agents: {
+          defaults: {
+            heartbeat: { model: "ollama/qwen3.5-9b-32k:latest" },
+          },
+        },
+      },
+      primaryProvider: "openrouter",
+      primaryModel: "qwen3.6-plus",
+      runtimeProvider: "custom",
+      runtimeModel: "uncataloged-32k",
+      activeSessionEntry: {
+        sessionId: "session",
+        updatedAt: 1,
+        modelProvider: "ollama",
+        model: "qwen3.5-9b-32k:latest",
+        contextTokens: 32_768,
+      },
+    });
+
+    expect(text).toContain("fresh session or using a model with a larger context window");
+    expect(text).not.toContain("heartbeat model bleed");
+  });
+
+  it("points to heartbeat model bleed when the session model matches heartbeat.model", () => {
+    const text = buildContextOverflowRecoveryText({
+      cfg: {
+        models: {
+          providers: {
+            openrouter: {
+              baseUrl: "https://openrouter.test",
+              models: [makeTestModel("qwen3.6-plus", 1_000_000)],
+            },
+            ollama: {
+              baseUrl: "http://ollama.test",
+              models: [makeTestModel("qwen3.5-9b-32k:latest", 32_768)],
+            },
+          },
+        },
+        agents: {
+          defaults: {
+            heartbeat: { model: "ollama/qwen3.5-9b-32k:latest" },
+          },
+        },
+      },
+      agentId: "agent",
+      primaryProvider: "openrouter",
+      primaryModel: "qwen3.6-plus",
+      activeSessionEntry: {
+        sessionId: "session",
+        updatedAt: 1,
+        modelProvider: "ollama",
+        model: "qwen3.5-9b-32k:latest",
+        contextTokens: 32_768,
+      },
+    });
+
+    expect(text).toContain("ollama/qwen3.5-9b-32k:latest (32k context)");
+    expect(text).toContain("openrouter/qwen3.6-plus");
+    expect(text).toContain("heartbeat model bleed");
+    expect(text).toContain("heartbeat.isolatedSession");
+  });
+
+  it("uses the stored context window for an uncataloged heartbeat model", () => {
+    const text = buildContextOverflowRecoveryText({
+      cfg: {
+        models: {
+          providers: {
+            openrouter: {
+              baseUrl: "https://openrouter.test",
+              models: [makeTestModel("qwen3.6-plus", 1_000_000)],
+            },
+          },
+        },
+        agents: {
+          defaults: {
+            heartbeat: { model: "ollama/custom-32k" },
+          },
+        },
+      },
+      agentId: "agent",
+      primaryProvider: "openrouter",
+      primaryModel: "qwen3.6-plus",
+      activeSessionEntry: {
+        sessionId: "session",
+        updatedAt: 1,
+        modelProvider: "ollama",
+        model: "custom-32k",
+        contextTokens: 32_768,
+      },
+    });
+
+    expect(text).toContain("ollama/custom-32k (32k context)");
+    expect(text).not.toContain("ollama/custom-32k (98k context)");
+    expect(text).toContain("heartbeat model bleed");
+  });
+});

src/auto-reply/reply/agent-runner-context-recovery.ts

@@ -0,0 +1,183 @@
+import {
+  normalizeLowercaseStringOrEmpty,
+  normalizeOptionalString,
+} from "@openclaw/normalization-core/string-coerce";
+import { resolveAgentConfig } from "../../agents/agent-scope-config.js";
+import { resolveContextTokensForModel } from "../../agents/context.js";
+import { resolveModelRefFromString } from "../../agents/model-selection.js";
+import type { SessionEntry } from "../../config/sessions.js";
+import type { FollowupRun } from "./queue.js";
+
+function buildContextOverflowResetHint(): string {
+  return "\n\nTry starting a fresh session or using a model with a larger context window.";
+}
+
+type ModelRefLike = {
+  provider: string;
+  model: string;
+};
+
+function resolveAgentHeartbeatModelRaw(params: {
+  cfg: FollowupRun["run"]["config"];
+  agentId?: string;
+}): string | undefined {
+  const defaultModel = normalizeOptionalString(params.cfg.agents?.defaults?.heartbeat?.model);
+  const agentId = normalizeLowercaseStringOrEmpty(params.agentId);
+  const agentModel = agentId
+    ? normalizeOptionalString(resolveAgentConfig(params.cfg, agentId)?.heartbeat?.model)
+    : undefined;
+  return agentModel ?? defaultModel;
+}
+
+function normalizeModelRefForCompare(ref: ModelRefLike | undefined) {
+  if (!ref) {
+    return undefined;
+  }
+  const provider = normalizeLowercaseStringOrEmpty(ref.provider);
+  const model = normalizeLowercaseStringOrEmpty(ref.model);
+  return provider && model ? { provider, model } : undefined;
+}
+
+function modelRefsEqual(left: ModelRefLike | undefined, right: ModelRefLike | undefined) {
+  const normalizedLeft = normalizeModelRefForCompare(left);
+  const normalizedRight = normalizeModelRefForCompare(right);
+  return (
+    normalizedLeft !== undefined &&
+    normalizedRight !== undefined &&
+    normalizedLeft.provider === normalizedRight.provider &&
+    normalizedLeft.model === normalizedRight.model
+  );
+}
+
+function formatContextWindowLabel(tokens: number): string {
+  if (tokens >= 1_000_000) {
+    return `${Math.round((tokens / 1_000_000) * 10) / 10}M`;
+  }
+  return `${Math.round(tokens / 1024)}k`;
+}
+
+function normalizePositiveContextTokens(value: unknown): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    return undefined;
+  }
+  return Math.floor(value);
+}
+
+function resolveContextWindowForHint(params: {
+  cfg: FollowupRun["run"]["config"];
+  agentId?: string;
+  ref: ModelRefLike;
+  activeSessionEntry?: SessionEntry;
+}) {
+  const sessionContextTokens = normalizePositiveContextTokens(
+    params.activeSessionEntry?.contextTokens,
+  );
+  const modelContextTokens = resolveContextTokensForModel({
+    cfg: params.cfg,
+    provider: params.ref.provider,
+    model: params.ref.model,
+    allowAsyncLoad: false,
+  });
+  return modelContextTokens ?? sessionContextTokens;
+}
+
+function resolveHeartbeatBleedHint(params: {
+  cfg: FollowupRun["run"]["config"];
+  agentId?: string;
+  primaryProvider?: string;
+  primaryModel?: string;
+  activeSessionEntry?: SessionEntry;
+}): string | undefined {
+  const primaryProvider = normalizeOptionalString(params.primaryProvider);
+  const primaryModel = normalizeOptionalString(params.primaryModel);
+  const runtimeProvider = normalizeOptionalString(params.activeSessionEntry?.modelProvider);
+  const runtimeModel = normalizeOptionalString(params.activeSessionEntry?.model);
+  if (!primaryProvider || !primaryModel || !runtimeProvider || !runtimeModel) {
+    return undefined;
+  }
+
+  const primaryRef = { provider: primaryProvider, model: primaryModel };
+  const runtimeRef = { provider: runtimeProvider, model: runtimeModel };
+  if (modelRefsEqual(primaryRef, runtimeRef)) {
+    return undefined;
+  }
+  const heartbeatModelRaw = resolveAgentHeartbeatModelRaw({
+    cfg: params.cfg,
+    agentId: params.agentId,
+  });
+  const heartbeatRef = heartbeatModelRaw
+    ? resolveModelRefFromString({
+        cfg: params.cfg,
+        raw: heartbeatModelRaw,
+        defaultProvider: primaryProvider,
+      })?.ref
+    : undefined;
+  if (!modelRefsEqual(runtimeRef, heartbeatRef)) {
+    return undefined;
+  }
+
+  const runtimeWindow = resolveContextWindowForHint({
+    cfg: params.cfg,
+    agentId: params.agentId,
+    ref: runtimeRef,
+    activeSessionEntry: params.activeSessionEntry,
+  });
+  const primaryWindow = resolveContextWindowForHint({
+    cfg: params.cfg,
+    agentId: params.agentId,
+    ref: primaryRef,
+  });
+  if (
+    typeof runtimeWindow === "number" &&
+    typeof primaryWindow === "number" &&
+    runtimeWindow >= primaryWindow
+  ) {
+    return undefined;
+  }
+
+  const runtimeLabel =
+    typeof runtimeWindow === "number" && runtimeWindow > 0
+      ? ` (${formatContextWindowLabel(runtimeWindow)} context)`
+      : "";
+  return (
+    `\n\nThe previous heartbeat turn left this session on ${runtimeProvider}/${runtimeModel}` +
+    `${runtimeLabel} instead of ${primaryProvider}/${primaryModel}. This matches the configured ` +
+    "`heartbeat.model`, so the overflow is likely heartbeat model bleed rather than a " +
+    "compaction-buffer problem. Set `heartbeat.isolatedSession: true`, enable " +
+    "`heartbeat.lightContext: true`, or use a heartbeat model with a larger context window."
+  );
+}
+
+/** Builds recovery instructions for context-overflow failures. */
+export function buildContextOverflowRecoveryText(params: {
+  duringCompaction?: boolean;
+  preserveSessionMapping?: boolean;
+  cfg: FollowupRun["run"]["config"];
+  agentId?: string;
+  primaryProvider?: string;
+  primaryModel?: string;
+  runtimeProvider?: string;
+  runtimeModel?: string;
+  activeSessionEntry?: SessionEntry;
+}): string {
+  const prefix = params.preserveSessionMapping
+    ? "⚠️ Auto-compaction could not recover this turn. I kept this conversation mapped to the current session. Please try again, use /compact, or use /new to start a fresh session."
+    : params.duringCompaction
+      ? "⚠️ Context limit exceeded during compaction. I've reset our conversation to start fresh - please try again."
+      : "⚠️ Context limit exceeded. I've reset our conversation to start fresh - please try again.";
+  const explicitRuntimeMatchesSession =
+    !params.runtimeProvider ||
+    !params.runtimeModel ||
+    (params.runtimeProvider === params.activeSessionEntry?.modelProvider &&
+      params.runtimeModel === params.activeSessionEntry?.model);
+  const heartbeatBleedHint = explicitRuntimeMatchesSession
+    ? resolveHeartbeatBleedHint({
+        cfg: params.cfg,
+        agentId: params.agentId,
+        primaryProvider: params.primaryProvider,
+        primaryModel: params.primaryModel,
+        activeSessionEntry: params.activeSessionEntry,
+      })
+    : undefined;
+  return prefix + (heartbeatBleedHint ?? buildContextOverflowResetHint());
+}

src/auto-reply/reply/agent-runner-core.test.ts

@@ -0,0 +1,231 @@
+import { describe, expect, it, onTestFinished } from "vitest";
+import { testing as cliBackendsTesting } from "../../agents/cli-backends.test-support.js";
+import { resolveFallbackTransition } from "../fallback-state.js";
+import type { TemplateContext } from "../templating.js";
+import {
+  buildSilentFallbackFailurePayload,
+  resolveAdmittedRunSessionFile,
+  resolveReplyRunDeliveryContext,
+} from "./agent-runner-core.js";
+import type { RuntimeFallbackAttempt } from "./agent-runner-execution.types.js";
+
+describe("resolveAdmittedRunSessionFile", () => {
+  it("uses the scoped session key when one is available", () => {
+    expect(
+      resolveAdmittedRunSessionFile({
+        agentId: "main",
+        sessionId: "session",
+        sessionFile: "legacy-target",
+        sessionKey: " agent:main:session ",
+        storePath: "/tmp/sessions.json",
+      }),
+    ).toBe("agent:main:session");
+  });
+
+  it("preserves the admitted fallback when a persisted run has no session key", () => {
+    expect(
+      resolveAdmittedRunSessionFile({
+        agentId: "main",
+        sessionId: "session",
+        sessionFile: "legacy-target",
+        storePath: "/tmp/sessions.json",
+      }),
+    ).toBe("legacy-target");
+  });
+});
+
+describe("resolveReplyRunDeliveryContext", () => {
+  it.each([
+    { name: "numeric message topic", messageThreadId: 99, threadId: 99 },
+    { name: "numeric transport topic", transportThreadId: 99, threadId: 99 },
+    { name: "message topic precedence", messageThreadId: 99, transportThreadId: 77, threadId: 99 },
+    { name: "string message topic", messageThreadId: "99", threadId: "99" },
+    { name: "session identity fallback", threadId: "12345:99" },
+  ])("preserves the $name", ({ messageThreadId, transportThreadId, threadId }) => {
+    expect(
+      resolveReplyRunDeliveryContext({
+        cfg: {},
+        sessionCtx: {
+          Provider: "telegram",
+          OriginatingChannel: "telegram",
+          OriginatingTo: "telegram:12345",
+          AccountId: "work",
+          MessageThreadId: messageThreadId,
+          TransportThreadId: transportThreadId,
+          SessionKey: "agent:main:telegram:direct:12345:thread:12345:99",
+        } as TemplateContext,
+        sessionKey: "agent:main:telegram:direct:12345:thread:12345:99",
+      }),
+    ).toEqual({
+      channel: "telegram",
+      to: "telegram:12345",
+      accountId: "work",
+      threadId,
+    });
+  });
+});
+
+describe("buildSilentFallbackFailurePayload", () => {
+  const selected = { provider: "openrouter", model: "z-ai/glm-5.3" };
+  const other = { provider: "amazon-bedrock", model: "claude-haiku" };
+  const transition = resolveFallbackTransition({
+    selectedProvider: selected.provider,
+    selectedModel: selected.model,
+    activeProvider: other.provider,
+    activeModel: other.model,
+    attempts: [],
+  });
+  const base = {
+    fallbackTransition: transition,
+    fallbackFailureKnown: true,
+    cfg: {},
+    isHeartbeat: false,
+    hasSuccessfulTerminalDelivery: false,
+  };
+  const attempt = (
+    reason: RuntimeFallbackAttempt["reason"],
+    identity: Partial<RuntimeFallbackAttempt> = {},
+  ): RuntimeFallbackAttempt => ({ ...selected, error: "provider failed", reason, ...identity });
+
+  it.each(["timeout", "server_error", "overloaded", "tls_certificate"] as const)(
+    "uses unreachable wording for selected-backend %s evidence",
+    (reason) => {
+      const payload = buildSilentFallbackFailurePayload({
+        ...base,
+        fallbackAttempts: [attempt(reason)],
+      });
+      expect(payload?.text).toContain("couldn't reach the configured model backend");
+      expect(payload?.text).toContain(transition.selectedModelRef);
+      expect(payload?.text).toContain(transition.activeModelRef);
+      expect(payload?.isError).toBe(true);
+    },
+  );
+
+  it.each(["format", "empty_response"] as const)(
+    "uses response wording for selected-backend %s evidence",
+    (reason) => {
+      const payload = buildSilentFallbackFailurePayload({
+        ...base,
+        fallbackAttempts: [attempt(reason)],
+      });
+      expect(payload?.text).toContain("responded but produced no usable reply");
+      expect(payload?.text).not.toContain("couldn't reach");
+    },
+  );
+
+  it.each([
+    { label: "empty evidence", attempts: [] },
+    { label: "unknown reason", attempts: [attempt("unknown")] },
+    { label: "auth skip", attempts: [attempt("auth")] },
+    { label: "auth with synthesized status", attempts: [attempt("auth", { status: 401 })] },
+    { label: "permanent auth", attempts: [attempt("auth_permanent")] },
+    { label: "billing", attempts: [attempt("billing")] },
+    { label: "rate limit", attempts: [attempt("rate_limit")] },
+    ...(["timeout", "overloaded", "format", "empty_response"] as const).map((reason) => ({
+      label: `local skip retaining ${reason}`,
+      attempts: [attempt(reason, { code: "MODEL_FALLBACK_SKIPPED" })],
+    })),
+    {
+      label: "local skip beside a response",
+      attempts: [attempt("format"), attempt("format", { code: "MODEL_FALLBACK_SKIPPED" })],
+    },
+    { label: "transport then response", attempts: [attempt("timeout"), attempt("format")] },
+    { label: "response then transport", attempts: [attempt("format"), attempt("timeout")] },
+    { label: "other backend only", attempts: [attempt("format", other)] },
+    { label: "other model only", attempts: [attempt("format", { model: "different" })] },
+    { label: "unattributed response", attempts: [attempt("format", { provider: "", model: "" })] },
+    {
+      label: "unattributed transport",
+      attempts: [attempt("timeout", { provider: "", model: "" })],
+    },
+    {
+      label: "incomplete evidence beside response",
+      attempts: [attempt("format"), attempt("timeout", { provider: "" })],
+    },
+    {
+      label: "incomplete evidence beside transport",
+      attempts: [attempt("timeout"), attempt("format", { model: " " })],
+    },
+  ])("keeps $label cause-neutral", ({ attempts }) => {
+    const payload = buildSilentFallbackFailurePayload({ ...base, fallbackAttempts: attempts });
+    expect(payload?.text).toContain("produced no usable reply");
+    expect(payload?.text).not.toContain("responded");
+    expect(payload?.text).not.toContain("couldn't reach");
+  });
+
+  it.each([
+    {
+      selectedReason: "format",
+      otherReason: "timeout",
+      expected: "responded but produced no usable reply",
+    },
+    {
+      selectedReason: "timeout",
+      otherReason: "format",
+      expected: "couldn't reach the configured model backend",
+    },
+  ] as const)(
+    "ignores another backend's $otherReason evidence",
+    ({ selectedReason, otherReason, expected }) => {
+      const payload = buildSilentFallbackFailurePayload({
+        ...base,
+        fallbackAttempts: [attempt(otherReason, other), attempt(selectedReason)],
+      });
+      expect(payload?.text).toContain(expected);
+    },
+  );
+
+  it("uses the configured runtime alias when attributing a response", () => {
+    // Exercise attribution with setup metadata; the plugin registration test owns
+    // the real Claude CLI descriptor and its canonical provider binding.
+    onTestFinished(() => cliBackendsTesting.resetDepsForTest());
+    cliBackendsTesting.setDepsForTest({
+      resolveRuntimeCliBackends: () => [],
+      resolvePluginSetupCliBackend: ({ backend }) =>
+        backend === "claude-cli"
+          ? {
+              pluginId: "anthropic",
+              backend: {
+                id: "claude-cli",
+                modelProvider: "anthropic",
+                config: { command: "claude" },
+              },
+            }
+          : undefined,
+    });
+    const cfg = { plugins: { allow: ["anthropic"], entries: { anthropic: { enabled: true } } } };
+    const fallbackTransition = resolveFallbackTransition({
+      selectedProvider: "anthropic",
+      selectedModel: "claude-sonnet-4-6",
+      activeProvider: "openai",
+      activeModel: "gpt-5.5",
+      attempts: [],
+      cfg,
+    });
+    const payload = buildSilentFallbackFailurePayload({
+      ...base,
+      cfg,
+      fallbackTransition,
+      fallbackAttempts: [attempt("format", { provider: "claude-cli", model: "claude-sonnet-4-6" })],
+    });
+    expect(payload?.text).toContain("responded but produced no usable reply");
+  });
+
+  it.each([
+    { isHeartbeat: true },
+    { hasSuccessfulTerminalDelivery: true },
+    { allowEmptyAssistantReplyAsSilent: true },
+    { silentExpected: true },
+    { hasExplicitSilentReply: true },
+    { fallbackFailureKnown: false },
+    { fallbackTransition: { ...transition, fallbackActive: false } },
+  ])("preserves warning suppression %j", (suppression) => {
+    expect(
+      buildSilentFallbackFailurePayload({
+        ...base,
+        ...suppression,
+        fallbackAttempts: [attempt("format")],
+      }),
+    ).toBeUndefined();
+  });
+});

src/auto-reply/reply/agent-runner-core.ts

@@ -0,0 +1,510 @@
+import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
+import { hasSessionAutoModelFallbackProvenance } from "../../agents/agent-scope.js";
+import { hasVisibleCommittedMessagingToolDeliveryEvidence } from "../../agents/embedded-agent-runner/delivery-evidence.js";
+import { MODEL_FALLBACK_SKIPPED_CODE } from "../../agents/model-fallback.types.js";
+import type { ModelRef } from "../../agents/model-ref-shared.js";
+import { areRuntimeModelRefsEquivalent } from "../../agents/model-runtime-aliases.js";
+import type { OpenClawConfig } from "../../config/config.js";
+import {
+  resolveSessionPluginStatusLines,
+  resolveSessionPluginTraceLines,
+  type SessionEntry,
+} from "../../config/sessions.js";
+import { loadSessionEntryReadOnly } from "../../config/sessions/session-accessor.js";
+import type { TypingMode } from "../../config/types.js";
+import { logVerbose } from "../../globals.js";
+import { CommandLaneClearedError, GatewayDrainingError } from "../../process/command-queue.js";
+import { resolveSendPolicy } from "../../sessions/send-policy.js";
+import {
+  sessionDeliveryChannel,
+  type DeliveryContext,
+  normalizeDeliveryContext,
+} from "../../utils/delivery-context.shared.js";
+import { resolveFallbackTransition } from "../fallback-state.js";
+import {
+  isReplyPayloadTerminalContent,
+  markReplyPayloadForSourceSuppressionDelivery,
+  setReplyPayloadMetadata,
+} from "../reply-payload.js";
+import type { TemplateContext } from "../templating.js";
+import type { VerboseLevel } from "../thinking.js";
+import { SILENT_REPLY_TOKEN } from "../tokens.js";
+import type { GetReplyOptions, ReplyPayload } from "../types.js";
+import type { RuntimeFallbackAttempt } from "./agent-runner-execution.types.js";
+import {
+  buildKnownAgentRunFailureReplyPayload,
+  buildTerminalAgentRunFailureReplyPayload,
+} from "./agent-runner-failure-reply.js";
+import type { BlockReplyPipeline } from "./block-reply-pipeline.js";
+import { resolveEffectiveReplyRoute } from "./effective-reply-route.js";
+import type { InternalGetReplyOptions } from "./get-reply.types.js";
+import { normalizeReplyPayload } from "./normalize-reply.js";
+import { sanitizePendingFinalDeliveryText } from "./pending-final-delivery-state.js";
+import { type FollowupRun, type QueueSettings, scheduleFollowupDrain } from "./queue.js";
+import { normalizeReplyPayloadDirectives, type DirectBlockDelivery } from "./reply-delivery.js";
+import { isReplyOperationSuperseded } from "./reply-operation-abort.js";
+import { type ReplyOperation, runAfterReplyOperationClear } from "./reply-run-registry.js";
+import { resolveRoutedDeliveryThreadId } from "./routed-delivery-thread.js";
+import { resolveSourceReplyVisibilityPolicy } from "./source-reply-delivery-mode.js";
+import type { TypingController } from "./typing.js";
+export const BLOCK_REPLY_SEND_TIMEOUT_MS = 15_000;
+
+const RESTART_LIFECYCLE_REPLY_TEXT =
+  "⚠️ Gateway is restarting. Please wait a few seconds and try again.";
+
+export function scheduleFollowupDrainAfterReplyOperationClear(params: {
+  operation: ReplyOperation;
+  queueKey: string;
+  runFollowup: (run: FollowupRun) => Promise<void>;
+}): void {
+  runAfterReplyOperationClear(params.operation, (admissionSessionId) => {
+    const completedSessionId = params.operation.sessionId;
+    const runFollowupAfterClear =
+      admissionSessionId === completedSessionId
+        ? params.runFollowup
+        : (queued: FollowupRun) =>
+            params.runFollowup(
+              queued.run.sessionId === completedSessionId
+                ? { ...queued, admissionSessionId }
+                : queued,
+            );
+    scheduleFollowupDrain(params.queueKey, runFollowupAfterClear);
+  });
+}
+
+export function markBeforeAgentRunBlockedPayloads(payloads: ReplyPayload[]): ReplyPayload[] {
+  return payloads.map((payload) =>
+    setReplyPayloadMetadata(payload, { beforeAgentRunBlocked: true }),
+  );
+}
+
+export function buildSilentFallbackFailurePayload(params: {
+  fallbackTransition: ReturnType<typeof resolveFallbackTransition>;
+  fallbackFailureKnown: boolean;
+  fallbackAttempts: readonly RuntimeFallbackAttempt[];
+  cfg: OpenClawConfig;
+  isHeartbeat: boolean;
+  hasSuccessfulTerminalDelivery: boolean;
+  allowEmptyAssistantReplyAsSilent?: boolean;
+  silentExpected?: boolean;
+  hasExplicitSilentReply?: boolean;
+}): ReplyPayload | undefined {
+  if (
+    params.isHeartbeat ||
+    params.allowEmptyAssistantReplyAsSilent === true ||
+    params.silentExpected === true ||
+    params.hasExplicitSilentReply === true ||
+    params.hasSuccessfulTerminalDelivery ||
+    !params.fallbackTransition.fallbackActive ||
+    !params.fallbackFailureKnown
+  ) {
+    return undefined;
+  }
+  const selected = params.fallbackTransition.selectedModelRef;
+  const active = params.fallbackTransition.activeModelRef;
+  const attempts = params.fallbackAttempts;
+  const selectedAttempts = attempts.filter((attempt) =>
+    areRuntimeModelRefsEquivalent(`${attempt.provider}/${attempt.model}`, selected, {
+      config: params.cfg,
+    }),
+  );
+  let primary = `⚠️ The configured model backend ${selected} produced no usable reply. `;
+  // Local skips retain old failure reasons, not evidence of a new backend attempt.
+  if (
+    selectedAttempts.length > 0 &&
+    selectedAttempts.every((attempt) => attempt.code !== MODEL_FALLBACK_SKIPPED_CODE) &&
+    attempts.every((attempt) => attempt.provider.trim() && attempt.model.trim())
+  ) {
+    if (
+      selectedAttempts.every(({ reason }) =>
+        ["timeout", "server_error", "overloaded", "tls_certificate"].includes(reason),
+      )
+    ) {
+      primary = `⚠️ I couldn't reach the configured model backend ${selected}. `;
+    } else if (
+      selectedAttempts.every(({ reason }) => reason === "format" || reason === "empty_response")
+    ) {
+      primary = `⚠️ The configured model backend ${selected} responded but produced no usable reply. `;
+    }
+  }
+  return markReplyPayloadForSourceSuppressionDelivery({
+    text: `${primary}Fallback used ${active}, but it produced no visible reply.`,
+    isError: true,
+  });
+}
+
+export function resolveSourceReplyPolicy(params: {
+  cfg: OpenClawConfig;
+  sessionCtx: TemplateContext;
+  sessionEntry?: SessionEntry;
+  sessionKey: string;
+  runtimePolicySessionKey?: string;
+  opts?: GetReplyOptions;
+}): ReturnType<typeof resolveSourceReplyVisibilityPolicy> {
+  const sendPolicy = resolveSendPolicy({
+    cfg: params.cfg,
+    entry: params.sessionEntry,
+    sessionKey: params.runtimePolicySessionKey ?? params.sessionKey,
+    channel:
+      params.sessionCtx.OriginatingChannel ??
+      params.sessionCtx.Surface ??
+      params.sessionCtx.Provider ??
+      sessionDeliveryChannel(params.sessionEntry),
+    chatType: params.sessionEntry?.chatType,
+  });
+  return resolveSourceReplyVisibilityPolicy({
+    cfg: params.cfg,
+    ctx: params.sessionCtx,
+    requested: params.opts?.sourceReplyDeliveryMode,
+    sendPolicy,
+  });
+}
+
+export function resolveReplyRunDeliveryContext(params: {
+  cfg: OpenClawConfig;
+  sessionCtx: TemplateContext;
+  sessionEntry?: SessionEntry;
+  sessionKey: string;
+  runtimePolicySessionKey?: string;
+  opts?: GetReplyOptions;
+}): DeliveryContext | undefined {
+  const sourceReplyPolicy = resolveSourceReplyPolicy(params);
+  if (
+    params.sessionCtx.InboundEventKind === "room_event" ||
+    sourceReplyPolicy.sendPolicyDenied ||
+    (sourceReplyPolicy.suppressDelivery &&
+      sourceReplyPolicy.sourceReplyDeliveryMode !== "message_tool_only")
+  ) {
+    return undefined;
+  }
+  return normalizeDeliveryContext({
+    ...resolveEffectiveReplyRoute({
+      ctx: params.sessionCtx,
+      entry: params.sessionEntry,
+    }),
+    threadId: resolveRoutedDeliveryThreadId({
+      ctx: params.sessionCtx,
+      sessionKey: params.sessionCtx.SessionKey ?? params.sessionKey,
+    }),
+  });
+}
+
+export function hasSuccessfulSourceReplyDelivery(params: {
+  blockReplyPipeline: { didStream: () => boolean; isAborted: () => boolean } | null;
+  directlySentBlockKeys?: Set<string>;
+  messagingToolSentTexts?: string[];
+  messagingToolSentMediaUrls?: string[];
+  messagingToolSentTargets?: unknown[];
+}): boolean {
+  return (
+    params.blockReplyPipeline?.didStream() ||
+    (params.directlySentBlockKeys?.size ?? 0) > 0 ||
+    hasVisibleCommittedMessagingToolDeliveryEvidence(params)
+  );
+}
+
+export function hasSuccessfulTerminalSourceReplyDelivery(params: {
+  blockReplyPipeline: {
+    didStreamTerminalReply?: () => boolean;
+    isAborted: () => boolean;
+  } | null;
+  directBlockDeliveries?: DirectBlockDelivery[];
+}): boolean {
+  const sentTerminalBlock = params.directBlockDeliveries?.some(
+    ({ payload, outcome, pending, source }) =>
+      outcome === "delivered" &&
+      !pending &&
+      source?.complete !== false &&
+      isReplyPayloadTerminalContent(payload) &&
+      normalizeReplyPayload(payload, { applyChannelTransforms: false }) !== null,
+  );
+  return (
+    params.blockReplyPipeline?.didStreamTerminalReply?.() === true || sentTerminalBlock === true
+  );
+}
+
+export function resolveFallbackOriginModel(params: {
+  run: FollowupRun["run"];
+  fallbackStateEntry?: SessionEntry;
+  runtimeModelSelection?: ModelRef;
+}): { provider: string; model: string; persistedAutoFallback: boolean } {
+  // Runtime-owned selection is not a fallback from the caller's nominal model.
+  if (params.runtimeModelSelection) {
+    return { ...params.runtimeModelSelection, persistedAutoFallback: false };
+  }
+  const entry = params.fallbackStateEntry;
+  const isAutoFallbackOverride =
+    entry?.modelOverrideSource === "auto" ||
+    (entry !== undefined &&
+      entry.modelOverrideSource === undefined &&
+      hasSessionAutoModelFallbackProvenance(entry));
+  if (isAutoFallbackOverride && entry !== undefined) {
+    const originProvider = normalizeOptionalString(entry.modelOverrideFallbackOriginProvider);
+    const originModel = normalizeOptionalString(entry.modelOverrideFallbackOriginModel);
+    if (originProvider && originModel) {
+      return { provider: originProvider, model: originModel, persistedAutoFallback: true };
+    }
+  }
+  return {
+    provider: params.run.provider,
+    model: params.run.model,
+    persistedAutoFallback: false,
+  };
+}
+
+export function buildInlinePluginStatusPayload(params: {
+  entry: SessionEntry | undefined;
+  includeStatusLines: boolean;
+  includeTraceLines: boolean;
+}): ReplyPayload | undefined {
+  const statusLines = params.includeStatusLines
+    ? resolveSessionPluginStatusLines(params.entry)
+    : [];
+  const traceLines = params.includeTraceLines ? resolveSessionPluginTraceLines(params.entry) : [];
+  const lines = [...statusLines, ...traceLines];
+  if (lines.length === 0) {
+    return undefined;
+  }
+  return { text: lines.join("\n") };
+}
+
+export function normalizeAssistantFinalDeliveryText(text: string): string {
+  const parsed = normalizeReplyPayloadDirectives({
+    payload: { text },
+    trimLeadingWhitespace: true,
+    parseMode: "auto",
+  });
+  return sanitizePendingFinalDeliveryText(parsed.payload.text ?? "");
+}
+
+export function refreshSessionEntryFromStore(params: {
+  storePath?: string;
+  sessionKey?: string;
+  fallbackEntry?: SessionEntry;
+  activeSessionStore?: Record<string, SessionEntry>;
+  expectedGeneration?: Pick<SessionEntry, "sessionId" | "lifecycleRevision">;
+}): SessionEntry | undefined {
+  const { storePath, sessionKey, fallbackEntry, activeSessionStore } = params;
+  if (!storePath || !sessionKey) {
+    return fallbackEntry;
+  }
+  try {
+    const latestEntry = loadSessionEntryReadOnly({
+      storePath,
+      sessionKey,
+    });
+    if (!latestEntry) {
+      return fallbackEntry;
+    }
+    // Completion may refresh facts, but only admission can adopt a replacement generation.
+    if (
+      params.expectedGeneration &&
+      (latestEntry.sessionId !== params.expectedGeneration.sessionId ||
+        latestEntry.lifecycleRevision !== params.expectedGeneration.lifecycleRevision)
+    ) {
+      return fallbackEntry;
+    }
+    if (activeSessionStore) {
+      activeSessionStore[sessionKey] = latestEntry;
+    }
+    return latestEntry;
+  } catch {
+    return fallbackEntry;
+  }
+}
+
+export function resolveAdmittedRunSessionFile(params: {
+  agentId: string;
+  sessionId: string;
+  sessionFile?: string;
+  sessionKey?: string;
+  storePath?: string;
+}): string | undefined {
+  if (params.sessionKey?.trim()) {
+    return params.sessionKey.trim();
+  }
+  return params.sessionFile;
+}
+
+export async function handleReplyAgentRunError(
+  error: unknown,
+  context: {
+    cfg: OpenClawConfig;
+    resolveVisibleReplyDelivery: () => Promise<boolean>;
+    isHeartbeat: boolean;
+    isRestartRecoveryArmed: () => boolean;
+    replyOperation: ReplyOperation;
+    resolvedVerboseLevel: VerboseLevel;
+    returnWithQueuedFollowupDrain: <T>(value: T) => T;
+    sessionCtx: TemplateContext;
+  },
+): Promise<ReplyPayload | undefined> {
+  const {
+    cfg,
+    resolveVisibleReplyDelivery,
+    isHeartbeat,
+    isRestartRecoveryArmed,
+    replyOperation,
+    resolvedVerboseLevel,
+    returnWithQueuedFollowupDrain,
+    sessionCtx,
+  } = context;
+
+  if (isReplyOperationSuperseded(replyOperation)) {
+    return { text: SILENT_REPLY_TOKEN };
+  }
+  if (
+    replyOperation.result?.kind === "aborted" &&
+    replyOperation.result.code === "aborted_by_user"
+  ) {
+    return returnWithQueuedFollowupDrain({ text: SILENT_REPLY_TOKEN });
+  }
+  if (
+    replyOperation.result?.kind === "aborted" &&
+    replyOperation.result.code === "aborted_for_restart"
+  ) {
+    if (isRestartRecoveryArmed()) {
+      return returnWithQueuedFollowupDrain({ text: SILENT_REPLY_TOKEN });
+    }
+    return returnWithQueuedFollowupDrain(
+      markReplyPayloadForSourceSuppressionDelivery({
+        text: RESTART_LIFECYCLE_REPLY_TEXT,
+      }),
+    );
+  }
+  if (error instanceof GatewayDrainingError) {
+    replyOperation.fail("gateway_draining", error);
+    return returnWithQueuedFollowupDrain(
+      markReplyPayloadForSourceSuppressionDelivery({
+        text: RESTART_LIFECYCLE_REPLY_TEXT,
+      }),
+    );
+  }
+  if (error instanceof CommandLaneClearedError) {
+    replyOperation.fail("command_lane_cleared", error);
+    return returnWithQueuedFollowupDrain(
+      markReplyPayloadForSourceSuppressionDelivery({
+        text: RESTART_LIFECYCLE_REPLY_TEXT,
+      }),
+    );
+  }
+  const knownFailurePayload = buildKnownAgentRunFailureReplyPayload({
+    err: error,
+    sessionCtx,
+    resolvedVerboseLevel,
+    cfg,
+  });
+  if (knownFailurePayload) {
+    replyOperation.fail("run_failed", error);
+    return returnWithQueuedFollowupDrain(knownFailurePayload);
+  }
+  const visibleReplyDelivered = await resolveVisibleReplyDelivery();
+  if (!isHeartbeat && visibleReplyDelivered && !replyOperation.abortSignal.aborted) {
+    replyOperation.fail("run_failed", error);
+    return returnWithQueuedFollowupDrain(
+      buildTerminalAgentRunFailureReplyPayload({
+        visibleReplyDelivered: true,
+        sessionCtx,
+        cfg,
+      }),
+    );
+  }
+  replyOperation.fail("run_failed", error);
+  // Keep the followup queue moving even when an unexpected exception escapes
+  // the run path; the caller still receives the original error.
+  returnWithQueuedFollowupDrain(undefined);
+  throw error;
+}
+
+export async function cleanupReplyAgentRun(context: {
+  blockReplyPipeline: BlockReplyPipeline | null;
+  clearRestartRecoveryDeliveryClaim: () => Promise<void>;
+  providedReplyOperation: ReplyOperation | undefined;
+  queueKey: string;
+  replyOperation: ReplyOperation;
+  runFollowupTurn: (queued: FollowupRun) => Promise<void>;
+  sessionKey: string | undefined;
+  shouldDrainQueuedFollowupsAfterClear: boolean;
+  typing: TypingController;
+}): Promise<void> {
+  const {
+    blockReplyPipeline,
+    clearRestartRecoveryDeliveryClaim,
+    providedReplyOperation,
+    queueKey,
+    replyOperation,
+    runFollowupTurn,
+    sessionKey,
+    shouldDrainQueuedFollowupsAfterClear,
+    typing,
+  } = context;
+
+  try {
+    await clearRestartRecoveryDeliveryClaim();
+  } catch (error) {
+    logVerbose(
+      `failed to clear restart recovery delivery context for ${sessionKey ?? "unknown"}: ${String(
+        error,
+      )}`,
+    );
+  }
+  if (shouldDrainQueuedFollowupsAfterClear) {
+    scheduleFollowupDrainAfterReplyOperationClear({
+      operation: replyOperation,
+      queueKey,
+      runFollowup: runFollowupTurn,
+    });
+    if (!providedReplyOperation) {
+      replyOperation.complete();
+    }
+  } else if (!providedReplyOperation) {
+    replyOperation.complete();
+  }
+  blockReplyPipeline?.stop();
+  typing.markRunComplete();
+  // Safety net: the dispatcher's onIdle callback normally fires
+  // markDispatchIdle(), but if the dispatcher exits early, errors,
+  // or the reply path doesn't go through it cleanly, the second
+  // signal never fires and the typing keepalive loop runs forever.
+  // Repeated completion signals are harmless: cleanup() is guarded by
+  // the typing controller's sealed flag.
+  typing.markDispatchIdle();
+}
+
+export type RunReplyAgentParams = {
+  commandBody: string;
+  transcriptCommandBody?: string;
+  followupRun: FollowupRun;
+  queueKey: string;
+  resolvedQueue: QueueSettings;
+  shouldSteer: boolean;
+  shouldFollowup: boolean;
+  queueAdmissionState?: "empty" | "steering" | "ready";
+  isActive: boolean;
+  isRunActive?: () => boolean;
+  opts?: InternalGetReplyOptions;
+  typing: TypingController;
+  sessionEntry?: SessionEntry;
+  sessionStore?: Record<string, SessionEntry>;
+  sessionKey?: string;
+  runtimePolicySessionKey?: string;
+  storePath?: string;
+  defaultModel: string;
+  resolvedVerboseLevel: VerboseLevel;
+  toolProgressDetail?: "explain" | "raw";
+  isNewSession: boolean;
+  blockStreamingEnabled: boolean;
+  blockReplyChunking?: {
+    minChars: number;
+    maxChars: number;
+    breakPreference: "paragraph" | "newline" | "sentence";
+    flushOnParagraph?: boolean;
+  };
+  resolvedBlockStreamingBreak: "text_end" | "message_end";
+  sessionCtx: TemplateContext;
+  shouldInjectGroupIntro: boolean;
+  typingMode: TypingMode;
+  resetTriggered?: boolean;
+  replyThreadingOverride?: TemplateContext["ReplyThreading"];
+  replyOperation?: ReplyOperation;
+};

src/auto-reply/reply/agent-runner-direct-runtime-config.test.ts

@@ -0,0 +1,716 @@
+// Tests direct runtime config overrides passed into agent runner execution.
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { OAuthRefreshFailureError } from "../../agents/auth-profiles/oauth-refresh-failure.js";
+import { FailoverError } from "../../agents/failover-error.js";
+import { SessionManager } from "../../agents/sessions/session-manager.js";
+import {
+  appendTranscriptMessage,
+  loadSessionEntry,
+  replaceSessionEntry,
+} from "../../config/sessions/session-accessor.js";
+import type { SessionEntry } from "../../config/sessions/types.js";
+import {
+  clearMemoryPluginState,
+  registerMemoryCapability,
+} from "../../plugins/memory-state.test-fixtures.js";
+import { withTestDir } from "../../test-helpers/temp-dir.js";
+import { withReplyDispatcher } from "../dispatch-dispatcher.js";
+import { getReplyPayloadMetadata } from "../reply-payload.js";
+import type { TemplateContext } from "../templating.js";
+import { SILENT_REPLY_TOKEN } from "../tokens.js";
+import type { ReplyPayload } from "../types.js";
+import { createTestFollowupRun, withTestModelContextTokens } from "./agent-runner.test-fixtures.js";
+import type { QueueSettings } from "./queue.js";
+import { createReplyDispatcher } from "./reply-dispatcher.js";
+import type { ReplyDispatchKind } from "./reply-dispatcher.types.js";
+import {
+  REPLY_OPERATION_RUN_STATE,
+  resolveReplyOperationAgentTurn,
+  type ReplyOperationRunState,
+} from "./reply-operation-run-state.js";
+import type { ReplyOperation } from "./reply-run-registry.js";
+import { createMockReplyOperation, createMockTypingController } from "./test-helpers.js";
+
+const freshCfg = { runtimeFresh: true };
+const staleCfg = {
+  runtimeFresh: false,
+  skills: {
+    entries: {
+      whisper: {
+        apiKey: { source: "env" as const, provider: "default", id: "OPENAI_API_KEY" },
+      },
+    },
+  },
+};
+const sentinelError = new Error("stop-after-preflight");
+
+const resolveQueuedReplyExecutionConfigMock = vi.fn();
+const resolveReplyToModeMock = vi.fn();
+const createReplyToModeFilterForChannelMock = vi.fn();
+const createReplyMediaContextMock = vi.fn();
+const createReplyMediaPathNormalizerMock = vi.fn();
+const runSessionCompactionIfNeededMock = vi.fn();
+const runMemoryFlushIfNeededMock = vi.fn();
+const executeAgentTurnMock = vi.fn();
+const resetReplyRunSessionMock = vi.fn();
+const enqueueFollowupRunMock = vi.fn();
+
+vi.mock("./agent-runner-utils.js", async () => {
+  const actual =
+    await vi.importActual<typeof import("./agent-runner-utils.js")>("./agent-runner-utils.js");
+  return {
+    ...actual,
+    resolveQueuedReplyExecutionConfig: (...args: unknown[]) =>
+      resolveQueuedReplyExecutionConfigMock(...args),
+  };
+});
+
+vi.mock("./reply-threading.js", async () => {
+  const actual =
+    await vi.importActual<typeof import("./reply-threading.js")>("./reply-threading.js");
+  return {
+    ...actual,
+    resolveReplyToMode: (...args: unknown[]) => resolveReplyToModeMock(...args),
+    createReplyToModeFilterForChannel: (...args: unknown[]) =>
+      createReplyToModeFilterForChannelMock(...args),
+  };
+});
+
+vi.mock("./reply-media-paths.js", () => ({
+  createReplyMediaContext: (...args: unknown[]) => {
+    createReplyMediaContextMock(...args);
+    return {
+      normalizePayload: createReplyMediaPathNormalizerMock(...args),
+    };
+  },
+  createReplyMediaPathNormalizer: (...args: unknown[]) =>
+    createReplyMediaPathNormalizerMock(...args),
+}));
+
+vi.mock("./agent-runner-memory.js", () => ({
+  runSessionCompactionIfNeeded: (...args: unknown[]) => runSessionCompactionIfNeededMock(...args),
+  runMemoryFlushIfNeeded: (...args: unknown[]) => runMemoryFlushIfNeededMock(...args),
+}));
+
+vi.mock("./agent-runner-execution.js", async () => {
+  const actual = await vi.importActual<typeof import("./agent-runner-execution.js")>(
+    "./agent-runner-execution.js",
+  );
+  return {
+    ...actual,
+    executeAgentTurn: (...args: unknown[]) => executeAgentTurnMock(...args),
+  };
+});
+
+vi.mock("./agent-runner-session-reset.js", async () => {
+  const actual = await vi.importActual<typeof import("./agent-runner-session-reset.js")>(
+    "./agent-runner-session-reset.js",
+  );
+  return {
+    ...actual,
+    resetReplyRunSession: (...args: unknown[]) => resetReplyRunSessionMock(...args),
+  };
+});
+
+vi.mock("./queue.js", async () => {
+  const actual = await vi.importActual<typeof import("./queue.js")>("./queue.js");
+  return {
+    ...actual,
+    enqueueFollowupRun: (...args: unknown[]) => enqueueFollowupRunMock(...args),
+  };
+});
+
+const { runReplyAgent } = await import("./agent-runner.js");
+
+function createTelegramSessionCtx(): TemplateContext {
+  return {
+    Provider: "telegram",
+    OriginatingChannel: "telegram",
+    OriginatingTo: "12345",
+    AccountId: "default",
+    ChatType: "dm",
+    MessageSid: "msg-1",
+  } as unknown as TemplateContext;
+}
+
+type TestReplyOperation = ReplyOperation & {
+  setPhase: ReturnType<typeof vi.fn<ReplyOperation["setPhase"]>>;
+};
+
+function createReplyOperation(): TestReplyOperation {
+  const { replyOperation } = createMockReplyOperation({ key: "test", sessionId: "session-1" });
+  return Object.assign(replyOperation, {
+    phase: "queued" as const,
+    setPhase: vi.fn<ReplyOperation["setPhase"]>(),
+    hasOwnedSessionId: vi.fn(() => false),
+    captureOwnedSessionIds: vi.fn(() => new Set()),
+  });
+}
+
+function createDirectRuntimeReplyParams({
+  shouldFollowup,
+  isActive,
+}: {
+  shouldFollowup: boolean;
+  isActive: boolean;
+}) {
+  const followupRun = createTestFollowupRun({
+    sessionId: "session-1",
+    sessionKey: "agent:main:telegram:default:direct:test",
+    messageProvider: "telegram",
+    config: staleCfg,
+    provider: "openai",
+    model: "gpt-5.4",
+  });
+  const resolvedQueue = { mode: "interrupt" } as QueueSettings;
+  const replyParams: Parameters<typeof runReplyAgent>[0] = {
+    commandBody: "hello",
+    followupRun,
+    queueKey: "main",
+    resolvedQueue,
+    shouldSteer: false,
+    shouldFollowup,
+    isActive,
+    typing: createMockTypingController(),
+    sessionCtx: createTelegramSessionCtx(),
+    defaultModel: "openai/gpt-5.4",
+    resolvedVerboseLevel: "off",
+    isNewSession: false,
+    blockStreamingEnabled: false,
+    resolvedBlockStreamingBreak: "message_end",
+    shouldInjectGroupIntro: false,
+    typingMode: "instant",
+  };
+
+  return { followupRun, resolvedQueue, replyParams };
+}
+
+function requireResolveQueuedReplyExecutionConfigCall(index = 0) {
+  const call = resolveQueuedReplyExecutionConfigMock.mock.calls[index] as
+    | [
+        unknown,
+        {
+          originatingChannel?: string;
+          messageProvider?: string;
+        },
+      ]
+    | undefined;
+  if (!call) {
+    throw new Error(`resolveQueuedReplyExecutionConfig call ${index} missing`);
+  }
+  return call;
+}
+
+type MockCallSource = {
+  mock: {
+    calls: unknown[][];
+  };
+};
+
+function requireMaintenanceCall(mock: MockCallSource, name: string, index = 0) {
+  const call = mock.mock.calls[index]?.[0] as
+    | {
+        cfg?: unknown;
+        followupRun?: unknown;
+        sessionKey?: string;
+        runtimePolicySessionKey?: string;
+      }
+    | undefined;
+  if (!call) {
+    throw new Error(`${name} call ${index} missing`);
+  }
+  return call;
+}
+
+type PreflightParams = Parameters<
+  typeof import("./agent-runner-memory.js").runSessionCompactionIfNeeded
+>[0];
+
+async function runRequiredCheckpoint(params: PreflightParams) {
+  if (!params.beforeCompaction) {
+    throw new Error("Expected the required preflight checkpoint");
+  }
+  return params.beforeCompaction(
+    params.sessionEntry ?? { sessionId: params.followupRun.run.sessionId, updatedAt: 1 },
+  );
+}
+
+describe("runReplyAgent runtime config", () => {
+  beforeEach(() => {
+    resolveQueuedReplyExecutionConfigMock.mockReset();
+    resolveReplyToModeMock.mockReset();
+    createReplyToModeFilterForChannelMock.mockReset();
+    createReplyMediaContextMock.mockReset();
+    createReplyMediaPathNormalizerMock.mockReset();
+    runSessionCompactionIfNeededMock.mockReset();
+    runMemoryFlushIfNeededMock.mockReset();
+    executeAgentTurnMock.mockReset();
+    resetReplyRunSessionMock.mockReset();
+    enqueueFollowupRunMock.mockReset();
+
+    resolveQueuedReplyExecutionConfigMock.mockResolvedValue(freshCfg);
+    resolveReplyToModeMock.mockReturnValue("all");
+    createReplyToModeFilterForChannelMock.mockReturnValue((payload: unknown) => payload);
+    createReplyMediaPathNormalizerMock.mockReturnValue((payload: unknown) => payload);
+    runSessionCompactionIfNeededMock.mockImplementation(async (params: PreflightParams) => {
+      await runRequiredCheckpoint(params);
+      throw sentinelError;
+    });
+    runMemoryFlushIfNeededMock.mockResolvedValue({ sessionEntry: undefined, outcome: "skipped" });
+    executeAgentTurnMock.mockResolvedValue({
+      runId: "runtime-config-test",
+      outcome: { kind: "rejected", payload: { text: "main reply" } },
+    });
+    resetReplyRunSessionMock.mockResolvedValue(false);
+  });
+
+  it("resolves direct reply runs before early helpers read config", async () => {
+    const { followupRun, replyParams } = createDirectRuntimeReplyParams({
+      shouldFollowup: false,
+      isActive: false,
+    });
+
+    await expect(runReplyAgent(replyParams)).rejects.toBe(sentinelError);
+
+    expect(followupRun.run.config).toBe(freshCfg);
+    expect(resolveQueuedReplyExecutionConfigMock).toHaveBeenCalledTimes(1);
+    const [configArg, configContextArg] = requireResolveQueuedReplyExecutionConfigCall();
+    expect(configArg).toBe(staleCfg);
+    expect(configContextArg.originatingChannel).toBe("telegram");
+    expect(configContextArg.messageProvider).toBe("telegram");
+    expect(resolveReplyToModeMock).toHaveBeenCalledWith(freshCfg, "telegram", "default", "dm");
+    expect(createReplyMediaContextMock).toHaveBeenCalledWith({
+      cfg: freshCfg,
+      agentId: "main",
+      sessionKey: undefined,
+      workspaceDir: followupRun.run.workspaceDir,
+      messageProvider: "telegram",
+      accountId: undefined,
+      groupId: undefined,
+      groupChannel: undefined,
+      groupSpace: undefined,
+      requesterSenderId: undefined,
+      requesterSenderName: undefined,
+      requesterSenderUsername: undefined,
+      requesterSenderE164: undefined,
+    });
+    expect(runSessionCompactionIfNeededMock).toHaveBeenCalledTimes(1);
+    expect(runMemoryFlushIfNeededMock).toHaveBeenCalledTimes(1);
+    expect(runSessionCompactionIfNeededMock.mock.invocationCallOrder[0]).toBeLessThan(
+      runMemoryFlushIfNeededMock.mock.invocationCallOrder[0] ?? Number.POSITIVE_INFINITY,
+    );
+    const memoryCall = requireMaintenanceCall(runMemoryFlushIfNeededMock, "runMemoryFlushIfNeeded");
+    expect(memoryCall.cfg).toBe(freshCfg);
+    expect(memoryCall.followupRun).toBe(followupRun);
+    const preflightCall = requireMaintenanceCall(
+      runSessionCompactionIfNeededMock,
+      "runSessionCompactionIfNeeded",
+    );
+    expect(preflightCall.cfg).toBe(freshCfg);
+    expect(preflightCall.followupRun).toBe(followupRun);
+  });
+
+  it("passes the derived runtime-policy key to pre-run maintenance", async () => {
+    const { followupRun, replyParams } = createDirectRuntimeReplyParams({
+      shouldFollowup: false,
+      isActive: false,
+    });
+    const runtimePolicySessionKey = "agent:main:telegram:default:direct:test";
+    followupRun.run.sessionKey = "agent:main:main";
+    followupRun.run.runtimePolicySessionKey = runtimePolicySessionKey;
+    replyParams.sessionKey = "agent:main:main";
+    replyParams.runtimePolicySessionKey = runtimePolicySessionKey;
+
+    await expect(runReplyAgent(replyParams)).rejects.toBe(sentinelError);
+
+    const preflightCall = requireMaintenanceCall(
+      runSessionCompactionIfNeededMock,
+      "runSessionCompactionIfNeeded",
+    );
+    expect(preflightCall.sessionKey).toBe("agent:main:main");
+    expect(preflightCall.runtimePolicySessionKey).toBe(runtimePolicySessionKey);
+    const memoryCall = requireMaintenanceCall(runMemoryFlushIfNeededMock, "runMemoryFlushIfNeeded");
+    expect(memoryCall.sessionKey).toBe("agent:main:main");
+    expect(memoryCall.runtimePolicySessionKey).toBe(runtimePolicySessionKey);
+  });
+
+  it("continues the main reply after a recorded memory-flush failure", async () => {
+    const { replyParams } = createDirectRuntimeReplyParams({
+      shouldFollowup: false,
+      isActive: false,
+    });
+    const onBlockReply = vi.fn();
+    const replyOperation = createReplyOperation();
+    replyParams.opts = { sourceReplyDeliveryMode: "message_tool_only", onBlockReply };
+    replyParams.replyOperation = replyOperation;
+    resolveQueuedReplyExecutionConfigMock.mockResolvedValue({
+      ...freshCfg,
+      agents: { defaults: { compaction: { notifyUser: true } } },
+    });
+    runSessionCompactionIfNeededMock.mockImplementation(runRequiredCheckpoint);
+    runMemoryFlushIfNeededMock.mockImplementation(
+      async (params: {
+        replyOperation: ReplyOperation;
+        onVisibleErrorPayloads?: (payloads: Array<{ text?: string; isError?: boolean }>) => void;
+      }) => {
+        params.replyOperation.setPhase("memory_flushing");
+        params.onVisibleErrorPayloads?.([
+          { text: "⚠️ memory flush preparation failed", isError: true },
+        ]);
+        return { sessionEntry: undefined, outcome: "failed" };
+      },
+    );
+
+    const result = await runReplyAgent(replyParams);
+
+    expect(result).toEqual({ text: "main reply" });
+    expect(onBlockReply).not.toHaveBeenCalled();
+    expect(executeAgentTurnMock).toHaveBeenCalledOnce();
+    expect(replyOperation.setPhase).toHaveBeenLastCalledWith("running");
+  });
+
+  it("preserves conversation without running byte-forced optional memory work before reply", async () => {
+    const memory = await vi.importActual<typeof import("./agent-runner-memory.js")>(
+      "./agent-runner-memory.js",
+    );
+    const reset = await vi.importActual<typeof import("./agent-runner-session-reset.js")>(
+      "./agent-runner-session-reset.js",
+    );
+    runMemoryFlushIfNeededMock.mockImplementation(memory.runMemoryFlushIfNeeded);
+    runSessionCompactionIfNeededMock.mockImplementation(memory.runSessionCompactionIfNeeded);
+    resetReplyRunSessionMock.mockImplementation(reset.resetReplyRunSession);
+    registerMemoryCapability("memory-core", {
+      flushPlanResolver: () => ({
+        softThresholdTokens: 4_000,
+        forceFlushTranscriptBytes: 1,
+        reserveTokensFloor: 20_000,
+        prompt: "Save durable notes. NO_REPLY",
+        systemPrompt: "Write memory to memory/notes.md.",
+        relativePath: "memory/notes.md",
+      }),
+    });
+    try {
+      await withTestDir({ prefix: "openclaw-direct-runtime-" }, async (tempDir) => {
+        const { replyParams, followupRun } = createDirectRuntimeReplyParams({
+          shouldFollowup: false,
+          isActive: false,
+        });
+        const sessionKey = "agent:main:telegram:default:direct:test";
+        const sessionEntry: SessionEntry = {
+          sessionId: "session-1",
+          lifecycleRevision: "before-maintenance",
+          updatedAt: 1,
+          totalTokens: 100,
+          totalTokensFresh: true,
+          totalTokensVersion: 1,
+          compactionCount: 4,
+          memoryFlush: { kind: "failed", failureCount: 2 },
+        };
+        const sessionStore = { [sessionKey]: sessionEntry };
+        const storePath = join(tempDir, "sessions.json");
+        const scope = { agentId: "main", sessionId: sessionEntry.sessionId, sessionKey, storePath };
+        await replaceSessionEntry(scope, sessionEntry);
+        const olderMessage = { role: "user", content: "Remember the older marker: amber-orchid" };
+        const messages = [
+          olderMessage,
+          { role: "assistant", content: "Noted." },
+          ...Array.from({ length: 3 }, (_, index) => [
+            { role: "user", content: `Recent question ${index}` },
+            { role: "assistant", content: `Recent answer ${index}` },
+          ]).flat(),
+        ];
+        for (const message of messages) {
+          await appendTranscriptMessage(scope, { message });
+        }
+        // A file blocks the memory directory: optional maintenance fails without token pressure.
+        await writeFile(join(tempDir, "memory"), "not a directory");
+        followupRun.run.workspaceDir = tempDir;
+        followupRun.run.provider = "anthropic";
+        followupRun.run.model = "claude-sonnet-4-6";
+        replyParams.sessionKey = sessionKey;
+        replyParams.storePath = storePath;
+        replyParams.sessionEntry = sessionEntry;
+        replyParams.sessionStore = sessionStore;
+        resolveQueuedReplyExecutionConfigMock.mockResolvedValue(
+          withTestModelContextTokens({
+            cfg: { agents: { defaults: { compaction: { notifyUser: true } } } },
+            followupRun,
+            defaultModel: replyParams.defaultModel,
+            contextTokens: 100_000,
+          }),
+        );
+        const onBlockReply = vi.fn();
+        replyParams.opts = { onBlockReply };
+        const replyOperation = createReplyOperation();
+        replyParams.replyOperation = replyOperation;
+        executeAgentTurnMock.mockImplementation(async () => {
+          expect(SessionManager.open(scope).buildSessionContext().messages).toEqual(
+            messages.map((message) => expect.objectContaining(message)),
+          );
+          return {
+            runId: "runtime-config-test",
+            outcome: { kind: "rejected", payload: { text: "main reply" } },
+          };
+        });
+
+        const result = await runReplyAgent(replyParams);
+
+        expect(result).toEqual({ text: "main reply" });
+        expect(resetReplyRunSessionMock).not.toHaveBeenCalled();
+        expect(followupRun.run.sessionId).toBe(sessionEntry.sessionId);
+        expect(replyOperation.sessionId).toBe(sessionEntry.sessionId);
+        expect(loadSessionEntry(scope)).toMatchObject({
+          sessionId: sessionEntry.sessionId,
+          lifecycleRevision: sessionEntry.lifecycleRevision,
+          compactionCount: 4,
+          totalTokens: 100,
+          totalTokensFresh: true,
+          memoryFlush: { kind: "failed", failureCount: 2 },
+        });
+        expect(sessionStore[sessionKey]).toMatchObject({
+          lifecycleRevision: sessionEntry.lifecycleRevision,
+          compactionCount: 4,
+          totalTokens: 100,
+        });
+        expect(runMemoryFlushIfNeededMock).not.toHaveBeenCalled();
+        expect(runSessionCompactionIfNeededMock).toHaveBeenCalledOnce();
+        expect(onBlockReply).not.toHaveBeenCalled();
+        expect(executeAgentTurnMock).toHaveBeenCalledOnce();
+      });
+    } finally {
+      clearMemoryPluginState();
+    }
+  });
+
+  it("keeps the compacted session when preflight recovers an exhausted memory flush", async () => {
+    const { replyParams } = createDirectRuntimeReplyParams({
+      shouldFollowup: false,
+      isActive: false,
+    });
+    const sessionEntry = {
+      sessionId: "session-1",
+      updatedAt: 1,
+      compactionCount: 4,
+    };
+    replyParams.sessionEntry = sessionEntry;
+    runMemoryFlushIfNeededMock.mockResolvedValue({
+      sessionEntry,
+      outcome: "exhausted",
+    });
+    runSessionCompactionIfNeededMock.mockImplementation(async (params: PreflightParams) => {
+      expect(params.sessionEntry?.sessionId).toBe("session-1");
+      const checkpointed = await runRequiredCheckpoint(params);
+      return { ...checkpointed, compactionCount: 5 };
+    });
+
+    await expect(runReplyAgent(replyParams)).resolves.toEqual({ text: "main reply" });
+
+    expect(resetReplyRunSessionMock).not.toHaveBeenCalled();
+    expect(executeAgentTurnMock).toHaveBeenCalledOnce();
+  });
+
+  it.each(["context_overflow", "auth profile mismatch"])(
+    "surfaces required preflight failure (%s) after memory exhaustion without resetting",
+    async (reason) => {
+      const { replyParams } = createDirectRuntimeReplyParams({
+        shouldFollowup: false,
+        isActive: false,
+      });
+      runMemoryFlushIfNeededMock.mockResolvedValue({
+        sessionEntry: { sessionId: "session-1", updatedAt: 1, compactionCount: 4 },
+        outcome: "exhausted",
+      });
+      runSessionCompactionIfNeededMock.mockImplementation(async (params: PreflightParams) => {
+        await runRequiredCheckpoint(params);
+        throw new Error(`Preflight compaction required but failed: ${reason}`);
+      });
+
+      const result = await runReplyAgent(replyParams);
+
+      if (!result || Array.isArray(result)) {
+        throw new Error("expected a single preflight compaction failure reply payload");
+      }
+      expect(result.text).toContain("auto-compaction could not recover");
+      expect(getReplyPayloadMetadata(result)?.deliverDespiteSourceReplySuppression).toBe(true);
+      expect(resetReplyRunSessionMock).not.toHaveBeenCalled();
+      expect(executeAgentTurnMock).not.toHaveBeenCalled();
+    },
+  );
+
+  it.each(["abortByUser", "abortForRestart"] as const)(
+    "records %s during memory flush as cancellation without starting the main turn",
+    async (abortMethod) => {
+      const { replyParams } = createDirectRuntimeReplyParams({
+        shouldFollowup: false,
+        isActive: false,
+      });
+      const runState: ReplyOperationRunState = {};
+      replyParams.opts = { [REPLY_OPERATION_RUN_STATE]: runState };
+      runSessionCompactionIfNeededMock.mockImplementation(runRequiredCheckpoint);
+      runMemoryFlushIfNeededMock.mockImplementation(
+        async (params: { replyOperation: ReplyOperation }) => {
+          expect(params.replyOperation[abortMethod]()).toBe(true);
+          return { sessionEntry: undefined, outcome: "failed" };
+        },
+      );
+
+      const result = await runReplyAgent(replyParams);
+
+      expect(result).toMatchObject({
+        text:
+          abortMethod === "abortByUser"
+            ? SILENT_REPLY_TOKEN
+            : "⚠️ Gateway is restarting. Please wait a few seconds and try again.",
+      });
+      expect(resolveReplyOperationAgentTurn(runState)).toBe("cancelled");
+      expect(executeAgentTurnMock).not.toHaveBeenCalled();
+    },
+  );
+
+  it.each(["user", "restart"] as const)(
+    "records an aborted %s agent turn as cancellation",
+    async (reason) => {
+      const { replyParams } = createDirectRuntimeReplyParams({
+        shouldFollowup: false,
+        isActive: false,
+      });
+      const runState: ReplyOperationRunState = {};
+      replyParams.opts = { [REPLY_OPERATION_RUN_STATE]: runState };
+      runSessionCompactionIfNeededMock.mockResolvedValue(undefined);
+      executeAgentTurnMock.mockResolvedValue({
+        runId: "cancelled-runtime-config-test",
+        outcome: { kind: "aborted", reason },
+      });
+
+      await runReplyAgent(replyParams);
+
+      expect(resolveReplyOperationAgentTurn(runState)).toBe("cancelled");
+    },
+  );
+
+  it("surfaces known pre-run Codex usage-limit failures instead of dropping the reply", async () => {
+    const { replyParams } = createDirectRuntimeReplyParams({
+      shouldFollowup: false,
+      isActive: false,
+    });
+    const codexMessage =
+      "You've reached your Codex subscription usage limit. Codex did not return a reset time for this limit. Run /codex account for current usage details.";
+    runSessionCompactionIfNeededMock.mockRejectedValue(
+      new FailoverError(codexMessage, {
+        reason: "rate_limit",
+        provider: "openai",
+        model: "gpt-5.5",
+      }),
+    );
+    runMemoryFlushIfNeededMock.mockResolvedValue({ sessionEntry: undefined, outcome: "skipped" });
+
+    const result = await runReplyAgent(replyParams);
+
+    if (!result || Array.isArray(result)) {
+      throw new Error("expected a single usage-limit reply payload");
+    }
+    expect(result.text).toBe(`⚠️ ${codexMessage}`);
+    const metadata = getReplyPayloadMetadata(result);
+    expect(metadata?.deliverDespiteSourceReplySuppression).toBe(true);
+  });
+
+  it("delivers known pre-run OAuth refresh failures instead of dropping the reply", async () => {
+    const { replyParams } = createDirectRuntimeReplyParams({
+      shouldFollowup: false,
+      isActive: false,
+    });
+    runSessionCompactionIfNeededMock.mockRejectedValue(
+      new OAuthRefreshFailureError({
+        provider: "openai",
+        message: "refresh_token_invalidated",
+      }),
+    );
+    const delivered = vi.fn<(payload: ReplyPayload, kind: ReplyDispatchKind) => void>();
+    const dispatcher = createReplyDispatcher({
+      deliver: async (payload, { kind }) => {
+        delivered(payload, kind);
+      },
+    });
+
+    const result = await withReplyDispatcher({
+      dispatcher,
+      run: async () => {
+        const payload = await runReplyAgent(replyParams);
+        if (!payload || Array.isArray(payload)) {
+          throw new Error("expected a single pre-run failure reply payload");
+        }
+        dispatcher.sendFinalReply(payload);
+        return payload;
+      },
+    });
+
+    const metadata = getReplyPayloadMetadata(result);
+    expect(metadata?.deliverDespiteSourceReplySuppression).toBe(true);
+    expect(executeAgentTurnMock).not.toHaveBeenCalled();
+    expect(delivered).toHaveBeenCalledExactlyOnceWith(
+      expect.objectContaining({ text: expect.stringContaining("/login openai"), isError: true }),
+      "final",
+    );
+    expect(delivered.mock.calls[0]?.[0].presentation).toEqual({
+      blocks: [
+        {
+          type: "buttons",
+          buttons: [
+            {
+              label: "Sign in",
+              action: { type: "command", command: "/login openai" },
+            },
+          ],
+        },
+      ],
+    });
+  });
+
+  it("surfaces preflight compaction failures before the agent starts", async () => {
+    const { replyParams } = createDirectRuntimeReplyParams({
+      shouldFollowup: false,
+      isActive: false,
+    });
+    runSessionCompactionIfNeededMock.mockRejectedValue(
+      new Error("Preflight compaction required but failed: auth profile mismatch"),
+    );
+    runMemoryFlushIfNeededMock.mockResolvedValue({ sessionEntry: undefined, outcome: "skipped" });
+
+    const result = await runReplyAgent(replyParams);
+
+    if (!result || Array.isArray(result)) {
+      throw new Error("expected a single preflight compaction failure reply payload");
+    }
+    expect(result.text).toContain("Context is too large");
+    expect(result.text).toContain("auto-compaction could not recover");
+    expect(result.text).toContain("/compact");
+    expect(result.text).toContain("/new");
+    const metadata = getReplyPayloadMetadata(result);
+    expect(metadata?.deliverDespiteSourceReplySuppression).toBe(true);
+  });
+
+  it("does not resolve secrets before the enqueue-followup queue path", async () => {
+    const { followupRun, resolvedQueue, replyParams } = createDirectRuntimeReplyParams({
+      shouldFollowup: true,
+      isActive: true,
+    });
+    const runState: ReplyOperationRunState = {};
+    replyParams.opts = { [REPLY_OPERATION_RUN_STATE]: runState };
+    enqueueFollowupRunMock.mockReturnValueOnce(true);
+
+    await expect(runReplyAgent(replyParams)).resolves.toBeUndefined();
+
+    expect(runState.admission).toEqual({ status: "accepted", mode: "followup" });
+    expect(resolveQueuedReplyExecutionConfigMock).not.toHaveBeenCalled();
+    expect(enqueueFollowupRunMock).toHaveBeenCalledTimes(1);
+    const enqueueCall = enqueueFollowupRunMock.mock.calls.at(0);
+    expect(enqueueCall?.[0]).toBe("main");
+    expect(enqueueCall?.[1]).toBe(followupRun);
+    expect(enqueueCall?.[2]).toBe(resolvedQueue);
+    expect(enqueueCall?.[3]).toBe("message-id");
+    expect(typeof enqueueCall?.[4]).toBe("function");
+    expect(enqueueCall?.[5]).toBe(false);
+  });
+});

src/auto-reply/reply/agent-runner-embedded-candidate.ts

@@ -0,0 +1,380 @@
+import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
+import { resolveBootstrapWarningSignaturesSeen } from "../../agents/bootstrap-budget.js";
+import type {
+  CompactionAccountingFact,
+  RunEmbeddedAgentInternalParams,
+} from "../../agents/embedded-agent-runner/run/internal-params.js";
+import { runEmbeddedAgent } from "../../agents/embedded-agent.js";
+import { resolveAgentHarnessPolicy } from "../../agents/harness/policy.js";
+import { resolveOpenAIRuntimeProvider } from "../../agents/openai-routing.js";
+import type { CompactionRequestBudget } from "../../agents/sessions/compaction/request-budget.js";
+import { resolveGroupSessionKey } from "../../config/sessions.js";
+import { logVerbose } from "../../globals.js";
+import { resolveSessionPinnedHarnessId } from "../../sessions/agent-harness-session-key.js";
+import {
+  isMarkdownCapableMessageChannel,
+  resolveMessageChannel,
+} from "../../utils/message-channel.js";
+import type { PartialReplyPayload } from "../get-reply-options.types.js";
+import type { ReplyPayload } from "../types.js";
+import { createAgentLifecycleTerminalBackstop } from "./agent-lifecycle-terminal.js";
+import {
+  createAgentRunEventHandler,
+  type MessageToolDeliveryState,
+} from "./agent-runner-event-handler.js";
+import type { CompletedAgentAuthSelection } from "./agent-runner-execution.types.js";
+import type { AgentFallbackCandidateCommonParams } from "./agent-runner-fallback-cycle.types.js";
+import { buildEmbeddedRunExecutionParams } from "./agent-runner-utils.js";
+import { resolveReplyOperationTerminationFields } from "./reply-operation-abort.js";
+import { markReplyOperationGlobalLaneWaitProgress } from "./reply-run-registry.js";
+import {
+  bindSourceReplyDeliveryRuntime,
+  readSourceReplyDeliveryRuntime,
+} from "./source-reply-delivery-runtime.js";
+
+export async function runEmbeddedFallbackCandidate(
+  params: AgentFallbackCandidateCommonParams & {
+    effectiveRun: AgentFallbackCandidateCommonParams["candidateRun"];
+    sessionRuntimeOverride?: string;
+    getLifecycleGeneration: () => string;
+    onLifecycleGeneration: (generation: string) => void;
+    allowTransientCooldownProbe?: boolean;
+    notifyUserAboutCompaction: boolean;
+    messageToolDeliveryState: MessageToolDeliveryState;
+    githubPublicationAvailable: boolean;
+    onCompactionFacts: (facts: {
+      accounting?: CompactionAccountingFact;
+      postCompactionModelAttempted: boolean;
+    }) => void;
+  },
+): Promise<{
+  result: Awaited<ReturnType<typeof runEmbeddedAgent>>;
+  maintenanceAuthProfile?: CompletedAgentAuthSelection;
+  compactionRequestBudget?: CompactionRequestBudget;
+  bootstrapPromptWarningSignaturesSeen: string[];
+}> {
+  const turn = params.turn;
+  let maintenanceAuthProfile: CompletedAgentAuthSelection | undefined;
+  let compactionRequestBudget: CompactionRequestBudget | undefined;
+  const sourceReplyDeliveryRuntime = readSourceReplyDeliveryRuntime(params.candidateRun);
+  const candidateRun = {
+    ...params.candidateRun,
+    ...params.candidateFastMode,
+    thinkLevel: params.candidateThinkLevel,
+  };
+  const { embeddedContext, senderContext, runBaseParams } = await buildEmbeddedRunExecutionParams({
+    run: candidateRun,
+    replyRoute: turn.followupRun,
+    sessionCtx: turn.sessionCtx,
+    hasRepliedRef: turn.opts?.hasRepliedRef,
+    provider: params.provider,
+    runId: params.runId,
+    promptCacheKey: turn.opts?.promptCacheKey,
+    allowTransientCooldownProbe: params.allowTransientCooldownProbe,
+    model: params.model,
+  });
+  if (sourceReplyDeliveryRuntime) {
+    bindSourceReplyDeliveryRuntime(runBaseParams, sourceReplyDeliveryRuntime);
+  }
+  const agentHarnessPolicy = params.sessionRuntimeOverride
+    ? ({ runtime: params.sessionRuntimeOverride, runtimeSource: "model" } as const)
+    : resolveAgentHarnessPolicy({
+        provider: params.provider,
+        modelId: params.model,
+        config: params.runtimeConfig,
+        agentId: turn.followupRun.run.agentId,
+        sessionKey: turn.followupRun.run.runtimePolicySessionKey ?? turn.sessionKey,
+      });
+  const embeddedRunProvider = resolveOpenAIRuntimeProvider({
+    provider: params.provider,
+    harnessRuntime: agentHarnessPolicy.runtime,
+    authProfileProvider: runBaseParams.authProfileId?.split(":", 1)[0],
+    authProfileId: runBaseParams.authProfileId,
+    config: params.runtimeConfig,
+    workspaceDir: turn.followupRun.run.workspaceDir,
+  });
+  const embeddedRunHarnessOverride =
+    params.sessionRuntimeOverride ??
+    (agentHarnessPolicy.runtime === "openclaw" && embeddedRunProvider !== params.provider
+      ? "openclaw"
+      : undefined);
+  let attemptCompactionCount = 0;
+  let postCompactionModelAttempted = false;
+  let compactionAccounting: CompactionAccountingFact | undefined;
+  const lifecycleBackstop = createAgentLifecycleTerminalBackstop({
+    runId: params.runId,
+    sessionKey: turn.sessionKey,
+    getLifecycleGeneration: params.getLifecycleGeneration,
+    resolveTerminationFields: (error) =>
+      resolveReplyOperationTerminationFields(error, params.runAbortSignal, turn.replyOperation),
+  });
+  params.onLifecycleBackstop(lifecycleBackstop);
+  try {
+    // Profiler milestone. Exposes pre-dispatch delay without normal-path logging.
+    params.timing.logMilestoneIfSlow({
+      runId: params.runId,
+      sessionId: turn.followupRun.run.sessionId,
+      sessionKey: turn.sessionKey,
+      milestone: "before_embedded_run",
+    });
+    let eventHandler: ReturnType<typeof createAgentRunEventHandler> | undefined;
+    const result = await params.timing.measure("embedded_run", () => {
+      const embeddedRunParams: RunEmbeddedAgentInternalParams = {
+        preparedRunAdmission: params.preparedRunAdmission,
+        githubPublicationAvailable: params.githubPublicationAvailable,
+        ...embeddedContext,
+        messageActionTurnCapability: params.messageActionTurnCapability,
+        lifecycleGeneration: params.getLifecycleGeneration(),
+        allowGatewaySubagentBinding: true,
+        trigger: turn.isHeartbeat ? "heartbeat" : "user",
+        cronCreatorAuthorityCapability: turn.opts?.cronCreatorAuthorityCapability,
+        cronCreatorAuthorityUnavailableReason:
+          turn.opts?.turnAdoptionLifecycle?.cronCreatorAuthorityUnavailable,
+        groupId: resolveGroupSessionKey(turn.sessionCtx)?.id,
+        groupChannel:
+          normalizeOptionalString(turn.sessionCtx.GroupChannel) ??
+          normalizeOptionalString(turn.sessionCtx.GroupSubject),
+        groupSpace: normalizeOptionalString(turn.sessionCtx.GroupSpace),
+        ...senderContext,
+        ...runBaseParams,
+        contextWindow: turn.getActiveSessionEntry()?.contextWindow,
+        lane: params.runLane,
+        provider: embeddedRunProvider,
+        agentHarnessId: resolveSessionPinnedHarnessId(turn.getActiveSessionEntry()),
+        agentHarnessRuntimeOverride: embeddedRunHarnessOverride,
+        agentHarnessRuntimePreparationHint:
+          agentHarnessPolicy.runtimeSource !== "implicit" ? agentHarnessPolicy.runtime : undefined,
+        fastModeStartedAtMs: params.fastModeStartedAtMs,
+        fastModeAutoProgressState: params.fastModeAutoProgressState,
+        isFinalFallbackAttempt: params.isFinalFallbackAttempt,
+        sandboxSessionKey: turn.runtimePolicySessionKey,
+        prompt: turn.commandBody,
+        transcriptPrompt: turn.transcriptCommandBody,
+        media: turn.followupRun.media,
+        userTurnTranscriptRecorder: params.userTurnTranscriptRecorder,
+        contextEngineLogicalTurnLease: params.contextEngineLogicalTurnLease,
+        onContextEngineTurnCandidate: params.onContextEngineTurnCandidate,
+        currentInboundEventKind: turn.followupRun.currentInboundEventKind,
+        currentInboundContext: turn.followupRun.currentInboundContext,
+        explicitSkillSelections: turn.followupRun.explicitSkillSelections,
+        extraSystemPrompt: turn.followupRun.run.extraSystemPrompt,
+        sourceReplyDeliveryMode: turn.followupRun.run.sourceReplyDeliveryMode,
+        forceMessageTool: turn.followupRun.run.sourceReplyDeliveryMode === "message_tool_only",
+        // Heartbeat ambient routes are delivery context, never implicit message recipients.
+        // Omit false so subagent sessions keep their downstream default.
+        ...(turn.isHeartbeat ? { requireExplicitMessageTarget: true } : {}),
+        cleanupBundleMcpOnRunEnd: turn.opts?.cleanupBundleMcpOnRunEnd,
+        silentReplyPromptMode: turn.followupRun.run.silentReplyPromptMode,
+        suppressNextUserMessagePersistence: params.suppressQueuedUserPersistenceForCandidate,
+        onUserMessagePersisted: params.notifyUserMessagePersisted,
+        suppressTranscriptOnlyAssistantPersistence:
+          turn.followupRun.run.suppressTranscriptOnlyAssistantPersistence,
+        assistantErrorTranscript: params.assistantErrorTranscript,
+        authProfileFailurePolicy: params.authProfileFailurePolicy,
+        prepareAssistantTranscriptMessage: turn.opts?.prepareAssistantTranscriptMessage,
+        onAutoCompactionSucceeded: (count) => {
+          attemptCompactionCount = Math.max(attemptCompactionCount, count);
+        },
+        toolResultFormat: (() => {
+          const channel = resolveMessageChannel(turn.sessionCtx.Surface, turn.sessionCtx.Provider);
+          return !channel || isMarkdownCapableMessageChannel(channel) ? "markdown" : "plain";
+        })(),
+        toolProgressDetail: turn.toolProgressDetail,
+        toolsAllow: turn.opts?.toolsAllow,
+        disableTools: turn.opts?.disableTools,
+        // Marks reply-owned policy; final attempt preparation binds its concrete route.
+        toolAuthorityFingerprint: turn.replyOperation?.toolAuthorityFingerprint,
+        enableHeartbeatTool: turn.opts?.enableHeartbeatTool,
+        forceHeartbeatTool: turn.opts?.forceHeartbeatTool,
+        bootstrapContextMode: turn.opts?.bootstrapContextMode,
+        bootstrapContextRunKind: params.bootstrapContextRunKind,
+        images: params.currentTurnImages.images,
+        imageOrder: params.currentTurnImages.imageOrder,
+        abortSignal: params.runAbortSignal,
+        replyOperation: turn.replyOperation,
+        deferTerminalLifecycle: true,
+        onAttemptStart: lifecycleBackstop.beginAttempt,
+        onCompactionAccounting: (fact) => {
+          compactionAccounting = fact;
+        },
+        onCompactionRequestBudget: (budget) => {
+          compactionRequestBudget = budget;
+        },
+        onDeferredLifecycleOwner: params.deferredLifecycle.adopt,
+        onDeferredLifecycleAbort: params.deferredLifecycle.abort,
+        onRetryWait: params.deferredLifecycle.beginRetryWait,
+        onExecutionStarted: (info) => {
+          if (info?.lifecycleGeneration) {
+            params.onLifecycleGeneration(info.lifecycleGeneration);
+          }
+        },
+        onExecutionPhase: (info) => {
+          if (info.phase === "model_call_started" && attemptCompactionCount > 0) {
+            postCompactionModelAttempted = true;
+          }
+          params.signalExecutionPhaseForTyping(info);
+        },
+        onLaneWait: ({ waiting }) => {
+          const replyOperation = turn.replyOperation;
+          if (waiting && replyOperation) {
+            markReplyOperationGlobalLaneWaitProgress(replyOperation);
+          }
+        },
+        blockReplyBreak: turn.resolvedBlockStreamingBreak,
+        blockReplyChunking: turn.blockReplyChunking,
+        // Subscriber callbacks are detached. Stage channel presentation before typing I/O.
+        onPartialReply: async (payload) => {
+          const classified = params.presentation.classifyStreamingPartial(payload);
+          if (classified.skip || !classified.text) {
+            return false;
+          }
+          const textForTyping = classified.text;
+          let didMaterialize = false;
+          let materializedText: string | undefined;
+          const partialPayload: PartialReplyPayload = {
+            get text() {
+              if (!didMaterialize) {
+                const sanitized = params.presentation.sanitizeStreamingText(textForTyping, false);
+                materializedText = sanitized.skip ? undefined : sanitized.text;
+                didMaterialize = true;
+              }
+              return materializedText;
+            },
+            mediaUrls: payload.mediaUrls,
+          };
+          const onPartialReply = turn.opts?.onPartialReply;
+          return await params.presentation.presentWithTyping(
+            turn.typingSignals.signalTextDelta(textForTyping),
+            () => (onPartialReply ? onPartialReply(partialPayload) : false),
+          );
+        },
+        onAssistantMessageStart: async () => {
+          await params.presentation.presentWithTyping(turn.typingSignals.signalMessageStart(), () =>
+            turn.opts?.onAssistantMessageStart?.(),
+          );
+        },
+        onReasoningStream:
+          turn.typingSignals.shouldStartOnReasoning || turn.opts?.onReasoningStream
+            ? async (payload) => {
+                if (turn.followupRun.run.silentExpected) {
+                  return;
+                }
+                await params.presentation.presentWithTyping(
+                  turn.typingSignals.signalReasoningDelta(),
+                  () =>
+                    turn.opts?.onReasoningStream?.({
+                      text: payload.text,
+                      mediaUrls: payload.mediaUrls,
+                      isReasoningSnapshot: payload.isReasoningSnapshot,
+                      requiresReasoningProgressOptIn: payload.requiresReasoningProgressOptIn,
+                    }),
+                );
+              }
+            : undefined,
+        streamReasoningInNonStreamModes: turn.opts?.streamReasoningInNonStreamModes,
+        onReasoningEnd: turn.opts?.onReasoningEnd
+          ? async () => {
+              await turn.opts?.onReasoningEnd?.();
+            }
+          : undefined,
+        onAgentEvent: (event) => {
+          eventHandler ??= createAgentRunEventHandler({
+            turn,
+            lifecycleBackstop,
+            notifyAgentRunStart: params.notifyAgentRunStart,
+            sourceRepliesAreToolOnly:
+              (sourceReplyDeliveryRuntime?.currentMode ??
+                turn.followupRun.run.sourceReplyDeliveryMode) === "message_tool_only",
+            messageToolDeliveryState: params.messageToolDeliveryState,
+            provider: params.provider,
+            model: params.model,
+            runId: params.runId,
+            effectiveSessionId: params.effectiveRun.sessionId,
+            notifyUserAboutCompaction: params.notifyUserAboutCompaction,
+            onCompactionCompleted: () => {
+              attemptCompactionCount += 1;
+              return attemptCompactionCount;
+            },
+          });
+          return eventHandler(event);
+        },
+        // Flush-before-tool requires a handler even when regular block streaming is off.
+        onBlockReply: params.presentation.blockReplyHandler,
+        onBlockReplyFlush:
+          turn.blockStreamingEnabled && turn.blockReplyPipeline
+            ? async () => {
+                await turn.blockReplyPipeline?.flush({ force: true });
+              }
+            : undefined,
+        shouldEmitToolResult: turn.shouldEmitToolResult,
+        shouldEmitToolOutput: turn.shouldEmitToolOutput,
+        bootstrapPromptWarningSignaturesSeen: params.bootstrapPromptWarningSignaturesSeen,
+        bootstrapPromptWarningSignature:
+          params.bootstrapPromptWarningSignaturesSeen[
+            params.bootstrapPromptWarningSignaturesSeen.length - 1
+          ],
+        onToolResult: turn.opts?.onToolResult
+          ? (() => {
+              // Serialized delivery preserves tool result order across detached callbacks.
+              let toolResultChain: Promise<void> = Promise.resolve();
+              return (payload: ReplyPayload) => {
+                const delivery = toolResultChain.then(async () => {
+                  turn.replyOperation?.recordActivity();
+                  const { text, skip } = params.presentation.normalizeStreamingText(payload);
+                  if (skip) {
+                    return;
+                  }
+                  if (text !== undefined) {
+                    await turn.typingSignals.signalTextDelta(text);
+                  }
+                  await turn.opts?.onToolResult?.({ ...payload, text });
+                });
+                // Keep later results best-effort while exposing this delivery to awaiting owners.
+                toolResultChain = delivery.catch((err: unknown) => {
+                  logVerbose(`tool result delivery failed: ${String(err)}`);
+                });
+                const task = toolResultChain.finally(() => {
+                  turn.pendingToolTasks.delete(task);
+                });
+                turn.pendingToolTasks.add(task);
+                return delivery;
+              };
+            })()
+          : undefined,
+      };
+      embeddedRunParams.onSuccessfulAuthProfile = (profileId) => {
+        maintenanceAuthProfile = {
+          authProfileId: profileId,
+          authProfileIdSource: profileId
+            ? profileId === runBaseParams.authProfileId
+              ? runBaseParams.authProfileIdSource
+              : "auto"
+            : undefined,
+        };
+      };
+      return runEmbeddedAgent(embeddedRunParams);
+    });
+    const resultCompactionCount = Math.max(0, result.meta?.agentMeta?.compactionCount ?? 0);
+    attemptCompactionCount = Math.max(attemptCompactionCount, resultCompactionCount);
+    return {
+      result,
+      maintenanceAuthProfile,
+      compactionRequestBudget,
+      bootstrapPromptWarningSignaturesSeen: resolveBootstrapWarningSignaturesSeen(
+        result.meta?.systemPromptReport,
+      ),
+    };
+  } finally {
+    // Runtime event/result counts are observable, but cannot prove a durable write target.
+    const accounting: CompactionAccountingFact | undefined =
+      compactionAccounting ??
+      (attemptCompactionCount > 0
+        ? {
+            kind: "presentation-only",
+            count: attemptCompactionCount,
+            currentContextSnapshot: { tokens: undefined },
+          }
+        : undefined);
+    params.onCompactionFacts({ accounting, postCompactionModelAttempted });
+  }
+}

src/auto-reply/reply/agent-runner-error-handler.ts

@@ -0,0 +1,294 @@
+import { sanitizeForLog } from "../../../packages/terminal-core/src/ansi.js";
+import {
+  classifyOAuthRefreshFailure,
+  classifyOAuthRefreshFailureError,
+} from "../../agents/auth-profiles/oauth-refresh-failure.js";
+import {
+  isCompactionFailureError,
+  isLikelyContextOverflowError,
+} from "../../agents/embedded-agent-helpers.js";
+import { findCliTimeoutError, isFailoverError } from "../../agents/failover-error.js";
+import {
+  GENERIC_EXTERNAL_RUN_FAILURE_TEXT,
+  HEARTBEAT_EXTERNAL_RUN_FAILURE_TEXT,
+  renderControlUiAgentFailureCopy,
+  renderFailoverCodeUserCopy,
+} from "../../agents/failover/user-copy.js";
+import { isAgentHarnessPreflightError } from "../../agents/harness/errors.js";
+import { LiveSessionModelSwitchError } from "../../agents/live-model-switch-error.js";
+import { formatErrorMessage } from "../../infra/errors.js";
+import { CommandLaneClearedError, GatewayDrainingError } from "../../process/command-queue.js";
+import { defaultRuntime } from "../../runtime.js";
+import type { ReplyPayload } from "../types.js";
+import { createAgentLifecycleTerminalBackstop } from "./agent-lifecycle-terminal.js";
+import { buildContextOverflowRecoveryText } from "./agent-runner-context-recovery.js";
+import type { AgentTurnInternalResult, AgentTurnParams } from "./agent-runner-execution.types.js";
+import {
+  buildAuthProfileFailoverFailureText,
+  buildExternalRunFailureReply,
+  isNonDirectConversationContext,
+  isVerboseFailureDetailEnabled,
+  markAgentRunFailureReplyPayload,
+  resolveExternalRunFailureTextForConversation,
+  resolveReplyFailureSummary,
+  resolveReplyFailoverFacts,
+} from "./agent-runner-failure-reply.js";
+import type { AgentFallbackCycleState } from "./agent-runner-fallback-cycle.js";
+import type { AgentTurnTimingTracker } from "./agent-runner-turn-timing.js";
+import {
+  buildRestartLifecycleReplyText,
+  resolveReplyOperationAbortReason,
+  resolveReplyOperationTerminationFields,
+  resolveRestartLifecycleError,
+} from "./reply-operation-abort.js";
+
+const MAX_LIVE_SWITCH_RETRIES = 2;
+
+type ErrorAction =
+  | { kind: "retry"; liveModelSwitchError?: LiveSessionModelSwitchError }
+  | Extract<AgentTurnInternalResult, { kind: "final" | "aborted" }>;
+
+export async function handleAgentExecutionError(params: {
+  turn: AgentTurnParams;
+  error: unknown;
+  runtimeConfig: AgentTurnParams["followupRun"]["run"]["config"];
+  runId: string;
+  state: AgentFallbackCycleState;
+  liveModelSwitchRetries: number;
+  shouldSurfaceToControlUi: boolean;
+  timing: AgentTurnTimingTracker;
+  modelPatch: { fail: (error: unknown) => Promise<void> };
+}): Promise<ErrorAction> {
+  const turn = params.turn;
+  const err = params.error;
+  // A failed candidate leaves its backstop pending; settlement takes it before later work.
+  // This keeps session-override failures from being mislabeled as model failures.
+  const postCompactionModelFailure =
+    params.state.postCompactionModelAttempted && params.state.pendingLifecycleTerminal
+      ? true
+      : undefined;
+  const takePendingLifecycleTerminal = () => {
+    const terminal =
+      params.state.pendingLifecycleTerminal?.backstop ??
+      createAgentLifecycleTerminalBackstop({
+        runId: params.runId,
+        sessionKey: turn.sessionKey,
+        startedAt: params.state.turnStartedAtMs,
+        getLifecycleGeneration: () => params.state.lifecycleGeneration,
+        resolveTerminationFields: (error) =>
+          resolveReplyOperationTerminationFields(
+            error,
+            turn.replyOperation?.abortSignal ?? turn.opts?.abortSignal,
+            turn.replyOperation,
+          ),
+      });
+    params.state.pendingLifecycleTerminal = undefined;
+    return terminal;
+  };
+  const settleFailure = async (
+    payload: ReplyPayload,
+  ): Promise<Extract<AgentTurnInternalResult, { kind: "final" }>> => {
+    takePendingLifecycleTerminal().emit("error", err);
+    turn.replyOperation?.fail("run_failed", err);
+    await params.modelPatch.fail(err);
+    return {
+      kind: "final",
+      payload: markAgentRunFailureReplyPayload(payload),
+      postCompactionModelFailure,
+    };
+  };
+  const resolveReplyOperationAbortAction = (abortError: unknown): ErrorAction | undefined => {
+    const reason = resolveReplyOperationAbortReason(turn.replyOperation, abortError);
+    if (!reason) {
+      return undefined;
+    }
+    // Preserve signal-owned timeout attribution; only normalized restart/supersession need metadata.
+    const terminalMetadata = reason === "user" ? undefined : { aborted: true, stopReason: reason };
+    takePendingLifecycleTerminal().emit(
+      reason === "restart" ? "end" : "error",
+      abortError,
+      terminalMetadata,
+    );
+    return { kind: "aborted", reason };
+  };
+  const replyOperationAbortAction = resolveReplyOperationAbortAction(err);
+  if (replyOperationAbortAction) {
+    return replyOperationAbortAction;
+  }
+  if (err instanceof LiveSessionModelSwitchError) {
+    if (params.liveModelSwitchRetries <= MAX_LIVE_SWITCH_RETRIES) {
+      params.state.pendingLifecycleTerminal = undefined;
+      return { kind: "retry", liveModelSwitchError: err };
+    }
+    const visibleReplyDelivered = await turn.resolveVisibleReplyDelivery?.();
+    defaultRuntime.error(
+      `Live model switch failed after ${MAX_LIVE_SWITCH_RETRIES} retries ` +
+        `(${sanitizeForLog(err.provider)}/${sanitizeForLog(err.model)}). The requested model may be unavailable.`,
+    );
+    takePendingLifecycleTerminal().emit("error", err);
+    const switchErrorText = params.shouldSurfaceToControlUi
+      ? renderControlUiAgentFailureCopy(
+          "model switch could not be completed. The requested model may be temporarily unavailable.",
+        )
+      : isVerboseFailureDetailEnabled(turn.resolvedVerboseLevel)
+        ? "⚠️ Agent failed before reply: model switch could not be completed. " +
+          "The requested model may be temporarily unavailable. Please try again shortly."
+        : "⚠️ Model switch could not be completed. The requested model may be temporarily unavailable. Please try again shortly.";
+    turn.replyOperation?.fail("run_failed", err);
+    await params.modelPatch.fail(err);
+    return {
+      kind: "final",
+      payload: markAgentRunFailureReplyPayload({
+        text: resolveExternalRunFailureTextForConversation({
+          text: switchErrorText,
+          visibleReplyDelivered,
+          sessionCtx: turn.sessionCtx,
+          isGenericRunnerFailure: !params.shouldSurfaceToControlUi,
+          cfg: turn.followupRun.run.config,
+        }),
+      }),
+    };
+  }
+  const message = formatErrorMessage(err);
+  params.timing.logIfSlow({
+    runId: params.runId,
+    sessionId: turn.followupRun.run.sessionId,
+    sessionKey: turn.sessionKey,
+    outcome: "error",
+    error: message,
+  });
+  // The exhausted preflight is deliberate, even if its diagnostic cause looks
+  // like HTTP/overload. Settle delivery and normal diagnostic policy without replay.
+  if (isAgentHarnessPreflightError(err)) {
+    const externalReply = buildExternalRunFailureReply(
+      { message, error: err },
+      {
+        includeDetails: isVerboseFailureDetailEnabled(turn.resolvedVerboseLevel),
+        isHeartbeat: turn.isHeartbeat,
+      },
+    );
+    const text = resolveExternalRunFailureTextForConversation({
+      text: params.shouldSurfaceToControlUi
+        ? renderControlUiAgentFailureCopy(message)
+        : externalReply.text,
+      visibleReplyDelivered: await turn.resolveVisibleReplyDelivery?.(),
+      sessionCtx: turn.sessionCtx,
+      isGenericRunnerFailure: externalReply.isGenericRunnerFailure,
+      cfg: turn.followupRun.run.config,
+    });
+    return await settleFailure({ text });
+  }
+  const failoverFacts = resolveReplyFailoverFacts(err, message);
+  const failureSummary = resolveReplyFailureSummary({
+    error: err,
+    message,
+    reason: failoverFacts.reason,
+    attempts: isFailoverError(err) ? err.attempts : undefined,
+  });
+  const failoverReason = failoverFacts.reason;
+  const isBilling = failureSummary?.kind === "billing";
+  const isContextOverflow =
+    !isBilling && (failoverReason === "context_overflow" || isLikelyContextOverflowError(message));
+  const isCompactionFailure = !isBilling && isCompactionFailureError(message);
+  const oauthRefreshFailure =
+    classifyOAuthRefreshFailureError(err) ?? classifyOAuthRefreshFailure(message);
+  const hasAuthProfileFailoverFailure = buildAuthProfileFailoverFailureText(err) !== null;
+  const providerRequestError =
+    !isBilling &&
+    !oauthRefreshFailure &&
+    !hasAuthProfileFailoverFailure &&
+    !params.shouldSurfaceToControlUi
+      ? failoverFacts.providerRequestError
+      : undefined;
+  const restartLifecycleError = resolveRestartLifecycleError(err);
+  if (
+    restartLifecycleError instanceof GatewayDrainingError ||
+    restartLifecycleError instanceof CommandLaneClearedError
+  ) {
+    takePendingLifecycleTerminal().emit("error", restartLifecycleError);
+    turn.replyOperation?.fail(
+      restartLifecycleError instanceof GatewayDrainingError
+        ? "gateway_draining"
+        : "command_lane_cleared",
+      restartLifecycleError,
+    );
+    return {
+      kind: "final",
+      payload: markAgentRunFailureReplyPayload({ text: buildRestartLifecycleReplyText() }),
+    };
+  }
+  if (isCompactionFailure) {
+    takePendingLifecycleTerminal().emit("error", err);
+    defaultRuntime.error(
+      `Auto-compaction failed (${message}). Preserving existing session mapping for ${turn.sessionKey ?? turn.followupRun.run.sessionId}.`,
+    );
+    turn.replyOperation?.fail("run_failed", err);
+    return {
+      kind: "final",
+      payload: markAgentRunFailureReplyPayload({
+        text: buildContextOverflowRecoveryText({
+          duringCompaction: true,
+          preserveSessionMapping: true,
+          cfg: params.runtimeConfig,
+          agentId: turn.followupRun.run.agentId,
+          primaryProvider: turn.followupRun.run.provider,
+          primaryModel: turn.followupRun.run.model,
+          runtimeProvider: params.state.attemptedRuntimeProvider,
+          runtimeModel: params.state.attemptedRuntimeModel,
+          activeSessionEntry: turn.getActiveSessionEntry(),
+        }),
+      }),
+    };
+  }
+  const replayPrevented = findCliTimeoutError(err)?.cliTimeout.observedActivity === true;
+  if (providerRequestError) {
+    return await settleFailure({
+      // Curated facet copy beats the generic classified summary; see
+      // buildExternalRunFailureReply for the same priority.
+      text: providerRequestError.userMessage,
+    });
+  }
+  defaultRuntime.error(`Embedded agent failed before reply: ${message}`);
+  const externalRunFailureCandidate =
+    !failureSummary && !isContextOverflow
+      ? buildExternalRunFailureReply(
+          { message, error: err },
+          {
+            includeAuthProfileId: !isNonDirectConversationContext(turn.sessionCtx),
+            includeDetails: isVerboseFailureDetailEnabled(turn.resolvedVerboseLevel),
+            isHeartbeat: turn.isHeartbeat,
+            replayPrevented,
+            failoverFacts,
+          },
+        )
+      : undefined;
+  const externalRunFailureReply =
+    !params.shouldSurfaceToControlUi ||
+    externalRunFailureCandidate?.presentation ||
+    renderFailoverCodeUserCopy(failoverFacts.code)
+      ? externalRunFailureCandidate
+      : undefined;
+  const fallbackText =
+    failureSummary?.text ??
+    (isContextOverflow
+      ? "⚠️ Context overflow — prompt too large for this model. Try a shorter message or a larger-context model."
+      : (externalRunFailureReply?.text ??
+        (params.shouldSurfaceToControlUi
+          ? renderControlUiAgentFailureCopy(message)
+          : turn.isHeartbeat
+            ? HEARTBEAT_EXTERNAL_RUN_FAILURE_TEXT
+            : GENERIC_EXTERNAL_RUN_FAILURE_TEXT)));
+  const userVisibleFallbackText = resolveExternalRunFailureTextForConversation({
+    text: fallbackText,
+    visibleReplyDelivered: await turn.resolveVisibleReplyDelivery?.(),
+    sessionCtx: turn.sessionCtx,
+    isGenericRunnerFailure: externalRunFailureReply?.isGenericRunnerFailure ?? false,
+    cfg: turn.followupRun.run.config,
+  });
+  return await settleFailure({
+    text: userVisibleFallbackText,
+    ...(externalRunFailureReply?.presentation
+      ? { presentation: externalRunFailureReply.presentation }
+      : {}),
+  });
+}

src/auto-reply/reply/agent-runner-event-handler.ts

@@ -0,0 +1,296 @@
+import { readStringValue } from "@openclaw/normalization-core/string-coerce";
+import { isMessagingToolSendAction } from "../../agents/embedded-agent-messaging.js";
+import type { RunEmbeddedAgentParams } from "../../agents/embedded-agent-runner/run/params.js";
+import { normalizeAgentPlanSteps } from "../../channels/streaming.js";
+import { logVerbose } from "../../globals.js";
+import { createSubsystemLogger } from "../../logging/subsystem.js";
+import type { ReplyPayload } from "../types.js";
+import type { AgentLifecycleTerminalBackstop } from "./agent-lifecycle-terminal.js";
+import { buildCommandOutputFromToolResultEvent } from "./agent-runner-command-output.js";
+import type { AgentTurnParams } from "./agent-runner-execution.types.js";
+import {
+  createCompactionHookNoticePayload,
+  createCompactionNoticePayload,
+  formatCompactionModelRef,
+  readCompactionHookMessages,
+} from "./compaction-notice.js";
+
+const agentCompactionLog = createSubsystemLogger("auto-reply/compaction");
+const CODEX_APP_SERVER_COMPACTION_BACKEND = "codex-app-server";
+
+export type MessageToolDeliveryState = {
+  toolCallIds: Set<string>;
+  completed: boolean;
+};
+
+function readApprovalScopeValue(value: unknown): "turn" | "session" | undefined {
+  return value === "turn" || value === "session" ? value : undefined;
+}
+
+/** Bridges embedded-agent events into channel progress and compaction notices. */
+export function createAgentRunEventHandler(params: {
+  turn: AgentTurnParams;
+  lifecycleBackstop: AgentLifecycleTerminalBackstop;
+  notifyAgentRunStart: () => void;
+  sourceRepliesAreToolOnly: boolean;
+  provider: string;
+  model: string;
+  runId: string;
+  effectiveSessionId?: string;
+  notifyUserAboutCompaction: boolean;
+  onCompactionCompleted: () => number;
+  messageToolDeliveryState: MessageToolDeliveryState;
+}): NonNullable<RunEmbeddedAgentParams["onAgentEvent"]> {
+  const shouldSuppressProgressAfterMessageToolDelivery = () =>
+    params.sourceRepliesAreToolOnly &&
+    params.messageToolDeliveryState.completed &&
+    params.turn.opts?.allowProgressCallbacksWhenSourceDeliverySuppressed !== true;
+
+  const currentMessageId =
+    params.turn.sessionCtx.MessageSidFull ?? params.turn.sessionCtx.MessageSid;
+  const deliverCompactionNoticePayload = async (noticePayload: ReplyPayload, label: string) => {
+    const deliver = params.turn.opts?.onBlockReply ?? params.turn.onCompactionNoticePayload;
+    if (!deliver) {
+      return;
+    }
+    try {
+      await deliver(noticePayload);
+    } catch (err) {
+      logVerbose(`compaction ${label} notice delivery failed (non-fatal): ${String(err)}`);
+    }
+  };
+  const sendCompactionNotice = async (phase: "start" | "end" | "incomplete") => {
+    await deliverCompactionNoticePayload(
+      createCompactionNoticePayload({
+        phase,
+        currentMessageId,
+        applyReplyToMode: params.turn.applyReplyToMode,
+      }),
+      phase,
+    );
+  };
+  const sendCompactionHookMessages = async (messages: string[]) => {
+    const noticePayload = createCompactionHookNoticePayload({
+      messages,
+      currentMessageId,
+      applyReplyToMode: params.turn.applyReplyToMode,
+    });
+    if (noticePayload) {
+      await deliverCompactionNoticePayload(noticePayload, "hook");
+    }
+  };
+
+  return async (evt) => {
+    params.turn.replyOperation?.recordActivity();
+    params.lifecycleBackstop.note(evt);
+    const hasLifecyclePhase = evt.stream === "lifecycle" && typeof evt.data.phase === "string";
+    if (evt.stream !== "lifecycle" || hasLifecyclePhase) {
+      params.notifyAgentRunStart();
+    }
+    if (evt.stream === "tool" && evt.data.hideFromChannelProgress !== true) {
+      const phase = readStringValue(evt.data.phase) ?? "";
+      const name = readStringValue(evt.data.name);
+      const toolCallId = readStringValue(evt.data.toolCallId) ?? "";
+      const args =
+        evt.data.args && typeof evt.data.args === "object"
+          ? (evt.data.args as Record<string, unknown>)
+          : undefined;
+      if (
+        params.sourceRepliesAreToolOnly &&
+        toolCallId &&
+        name &&
+        (phase === "start" || phase === "update") &&
+        args &&
+        isMessagingToolSendAction(name, args)
+      ) {
+        params.messageToolDeliveryState.toolCallIds.add(toolCallId);
+      }
+      if (shouldSuppressProgressAfterMessageToolDelivery()) {
+        return;
+      }
+      if (phase === "start" || phase === "update") {
+        const toolStartProgressPromise = params.turn.opts?.onToolStart?.({
+          itemId: readStringValue(evt.data.itemId),
+          toolCallId: readStringValue(evt.data.toolCallId),
+          name,
+          phase,
+          args,
+          detailMode: params.turn.toolProgressDetail,
+        });
+        await Promise.all([params.turn.typingSignals.signalToolStart(), toolStartProgressPromise]);
+      }
+      const commandOutput = buildCommandOutputFromToolResultEvent(evt);
+      if (commandOutput) {
+        await params.turn.opts?.onCommandOutput?.(commandOutput);
+      }
+    }
+
+    const suppressItemChannelProgress =
+      evt.stream === "item" &&
+      evt.data.suppressChannelProgress === true &&
+      Boolean(params.turn.opts?.onToolStart);
+    const hideItemFromChannelProgress =
+      evt.stream === "item" && evt.data.hideFromChannelProgress === true;
+    const itemPhase = evt.stream === "item" ? readStringValue(evt.data.phase) : "";
+    const itemName = evt.stream === "item" ? readStringValue(evt.data.name) : "";
+    const itemStatus = evt.stream === "item" ? readStringValue(evt.data.status) : "";
+    const itemToolCallId =
+      evt.stream === "item" ? (readStringValue(evt.data.toolCallId) ?? "") : "";
+    const completedMessageToolDelivery =
+      params.sourceRepliesAreToolOnly &&
+      itemPhase === "end" &&
+      itemStatus === "completed" &&
+      itemToolCallId.length > 0 &&
+      params.messageToolDeliveryState.toolCallIds.has(itemToolCallId);
+    const suppressProgressAfterMessageToolDelivery =
+      shouldSuppressProgressAfterMessageToolDelivery();
+    if (completedMessageToolDelivery) {
+      params.messageToolDeliveryState.toolCallIds.delete(itemToolCallId);
+      params.messageToolDeliveryState.completed = true;
+    }
+
+    if (
+      evt.stream === "item" &&
+      !hideItemFromChannelProgress &&
+      !suppressItemChannelProgress &&
+      (!suppressProgressAfterMessageToolDelivery || completedMessageToolDelivery)
+    ) {
+      const itemSummary = readStringValue(evt.data.summary);
+      const itemProgressText = readStringValue(evt.data.progressText);
+      const itemMeta = readStringValue(evt.data.meta);
+      const itemCommandBearing =
+        typeof evt.data.commandBearing === "boolean" ? evt.data.commandBearing : undefined;
+      const itemApprovalId = readStringValue(evt.data.approvalId);
+      const itemApprovalSlug = readStringValue(evt.data.approvalSlug);
+      await params.turn.opts?.onItemEvent?.({
+        itemId: readStringValue(evt.data.itemId),
+        kind: readStringValue(evt.data.kind),
+        title: readStringValue(evt.data.title),
+        phase: itemPhase,
+        status: itemStatus,
+        ...(itemToolCallId ? { toolCallId: itemToolCallId } : {}),
+        ...(itemName ? { name: itemName } : {}),
+        ...(itemSummary !== undefined ? { summary: itemSummary } : {}),
+        ...(itemProgressText !== undefined ? { progressText: itemProgressText } : {}),
+        ...(itemMeta !== undefined ? { meta: itemMeta } : {}),
+        ...(itemCommandBearing !== undefined ? { commandBearing: itemCommandBearing } : {}),
+        ...(itemApprovalId !== undefined ? { approvalId: itemApprovalId } : {}),
+        ...(itemApprovalSlug !== undefined ? { approvalSlug: itemApprovalSlug } : {}),
+      });
+    }
+    if (evt.stream === "plan" && !shouldSuppressProgressAfterMessageToolDelivery()) {
+      await params.turn.opts?.onPlanUpdate?.({
+        phase: readStringValue(evt.data.phase),
+        title: readStringValue(evt.data.title),
+        explanation: readStringValue(evt.data.explanation),
+        ...(evt.data.explanationFormat === "plain" ? { explanationFormat: "plain" as const } : {}),
+        steps: normalizeAgentPlanSteps(evt.data.steps),
+        source: readStringValue(evt.data.source),
+      });
+    }
+    if (evt.stream === "approval" && !shouldSuppressProgressAfterMessageToolDelivery()) {
+      await params.turn.opts?.onApprovalEvent?.({
+        phase: readStringValue(evt.data.phase),
+        kind: readStringValue(evt.data.kind),
+        status: readStringValue(evt.data.status),
+        title: readStringValue(evt.data.title),
+        itemId: readStringValue(evt.data.itemId),
+        toolCallId: readStringValue(evt.data.toolCallId),
+        approvalId: readStringValue(evt.data.approvalId),
+        approvalSlug: readStringValue(evt.data.approvalSlug),
+        command: readStringValue(evt.data.command),
+        host: readStringValue(evt.data.host),
+        reason: readStringValue(evt.data.reason),
+        scope: readApprovalScopeValue(evt.data.scope),
+        message: readStringValue(evt.data.message),
+      });
+    }
+    if (evt.stream === "command_output" && !shouldSuppressProgressAfterMessageToolDelivery()) {
+      await params.turn.opts?.onCommandOutput?.({
+        itemId: readStringValue(evt.data.itemId),
+        phase: readStringValue(evt.data.phase),
+        title: readStringValue(evt.data.title),
+        toolCallId: readStringValue(evt.data.toolCallId),
+        name: readStringValue(evt.data.name),
+        output: readStringValue(evt.data.output),
+        status: readStringValue(evt.data.status),
+        exitCode:
+          typeof evt.data.exitCode === "number" || evt.data.exitCode === null
+            ? evt.data.exitCode
+            : undefined,
+        durationMs: typeof evt.data.durationMs === "number" ? evt.data.durationMs : undefined,
+        cwd: readStringValue(evt.data.cwd),
+      });
+    }
+    if (evt.stream === "patch" && !shouldSuppressProgressAfterMessageToolDelivery()) {
+      await params.turn.opts?.onPatchSummary?.({
+        itemId: readStringValue(evt.data.itemId),
+        phase: readStringValue(evt.data.phase),
+        title: readStringValue(evt.data.title),
+        toolCallId: readStringValue(evt.data.toolCallId),
+        name: readStringValue(evt.data.name),
+        added: Array.isArray(evt.data.added)
+          ? evt.data.added.filter((entry): entry is string => typeof entry === "string")
+          : undefined,
+        modified: Array.isArray(evt.data.modified)
+          ? evt.data.modified.filter((entry): entry is string => typeof entry === "string")
+          : undefined,
+        deleted: Array.isArray(evt.data.deleted)
+          ? evt.data.deleted.filter((entry): entry is string => typeof entry === "string")
+          : undefined,
+        summary: readStringValue(evt.data.summary),
+      });
+    }
+    if (evt.stream !== "compaction") {
+      return;
+    }
+
+    const phase = readStringValue(evt.data.phase) ?? "";
+    const backend = readStringValue(evt.data.backend);
+    const hookMessages = readCompactionHookMessages(evt.data.messages);
+    const sendCompactionUserNotices = async (noticePhase: "start" | "end" | "incomplete") => {
+      if (hookMessages.length > 0) {
+        await sendCompactionHookMessages(hookMessages);
+      }
+      if (params.notifyUserAboutCompaction) {
+        await sendCompactionNotice(noticePhase);
+      }
+    };
+    if (phase === "start") {
+      await params.turn.opts?.onCompactionStart?.();
+      await sendCompactionUserNotices("start");
+      return;
+    }
+    if (phase !== "end") {
+      return;
+    }
+    if (evt.data.completed !== true) {
+      await params.turn.opts?.onCompactionEnd?.({ completed: false });
+      await sendCompactionUserNotices("incomplete");
+      return;
+    }
+
+    const compactionCount = params.onCompactionCompleted();
+    if (backend === CODEX_APP_SERVER_COMPACTION_BACKEND) {
+      const modelRef = formatCompactionModelRef(params.provider, params.model);
+      const consoleMessage =
+        `codex app-server auto-compaction succeeded for ${modelRef}; ` +
+        "refreshed session context";
+      agentCompactionLog.info("codex app-server auto-compaction succeeded", {
+        event: "codex_app_server_compaction_succeeded",
+        backend,
+        provider: params.provider,
+        model: params.model,
+        sessionKey: params.turn.sessionKey,
+        sessionId: params.effectiveSessionId,
+        threadId: readStringValue(evt.data.threadId),
+        turnId: readStringValue(evt.data.turnId),
+        itemId: readStringValue(evt.data.itemId),
+        compactionCount,
+        consoleMessage,
+      });
+    }
+    await params.turn.opts?.onCompactionEnd?.({ completed: true });
+    await sendCompactionUserNotices("end");
+  };
+}

src/auto-reply/reply/agent-runner-execute.ts

@@ -0,0 +1,559 @@
+import crypto from "node:crypto";
+import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
+import type { OpenClawConfig } from "../../config/config.js";
+import type { SessionEntry } from "../../config/sessions.js";
+import { withBeforeAgentReplyObserver } from "../../plugins/before-agent-reply.js";
+import { getGatewayContextResolver } from "../../plugins/runtime/gateway-request-scope.js";
+import { readPendingUserTurnTranscriptAdmission } from "../../sessions/user-turn-transcript-admission.js";
+import { setReplyPayloadMetadata } from "../reply-payload.js";
+import type { OriginatingChannelType } from "../templating.js";
+import { SILENT_REPLY_TOKEN } from "../tokens.js";
+import type { ReplyPayload } from "../types.js";
+import {
+  resolveReplyRunDeliveryContext,
+  resolveSourceReplyPolicy,
+  type RunReplyAgentParams,
+} from "./agent-runner-core.js";
+import { executeAgentTurn } from "./agent-runner-execution.js";
+import { markPostCompactionModelFailurePayload } from "./agent-runner-failure-reply.js";
+import { runMemoryFlushIfNeeded, runSessionCompactionIfNeeded } from "./agent-runner-memory.js";
+import { accountAgentTurnCompaction } from "./agent-runner-result-accounting.js";
+import { finalizeReplyAgentRun } from "./agent-runner-result.js";
+import { buildThreadingToolContext } from "./agent-runner-utils.js";
+import type { BlockReplyPipeline } from "./block-reply-pipeline.js";
+import type { CompactionNoticePhase } from "./compaction-notice.js";
+import { createFollowupRunner } from "./followup-runner.js";
+import {
+  buildRecoverablePendingFinalDeliveryText,
+  normalizePendingFinalDeliveryPayloads,
+} from "./pending-final-delivery.js";
+import type { FollowupRun } from "./queue.js";
+import type { ReplyMediaContext } from "./reply-media-paths.js";
+import { isReplyOperationSuperseded } from "./reply-operation-abort.js";
+import { recordReplyOperationAgentTurn } from "./reply-operation-run-state.js";
+import type { ReplyOperation } from "./reply-run-registry.js";
+import { replyRunRegistry } from "./reply-run-registry.js";
+import { resolveReplyToMode } from "./reply-threading.js";
+import { createReplyRestartRecoveryClaimController } from "./restart-recovery-claim.js";
+import { resolveRoutedDeliveryThreadId } from "./routed-delivery-thread.js";
+import type { TypingSignaler } from "./typing-mode.js";
+type ExecutePreparedReplyAgentRunInput = Pick<
+  RunReplyAgentParams,
+  | "blockReplyChunking"
+  | "blockStreamingEnabled"
+  | "commandBody"
+  | "defaultModel"
+  | "followupRun"
+  | "opts"
+  | "queueKey"
+  | "replyThreadingOverride"
+  | "resolvedBlockStreamingBreak"
+  | "resolvedQueue"
+  | "resolvedVerboseLevel"
+  | "runtimePolicySessionKey"
+  | "sessionCtx"
+  | "sessionKey"
+  | "shouldInjectGroupIntro"
+  | "storePath"
+  | "toolProgressDetail"
+  | "transcriptCommandBody"
+  | "typing"
+  | "typingMode"
+> & {
+  activeSessionStore: Record<string, SessionEntry> | undefined;
+  admitUserTurn: ReturnType<typeof createReplyRestartRecoveryClaimController>["admitUserTurn"];
+  applyReplyToMode: (payload: ReplyPayload) => ReplyPayload;
+  beginBeforeAgentReply: ReturnType<
+    typeof createReplyRestartRecoveryClaimController
+  >["beginBeforeAgentReply"];
+  blockReplyPipeline: BlockReplyPipeline | null;
+  cfg: OpenClawConfig;
+  checkpointBeforeAgentReply: ReturnType<
+    typeof createReplyRestartRecoveryClaimController
+  >["checkpointBeforeAgentReply"];
+  resolveVisibleReplyDelivery: () => Promise<boolean>;
+  getActiveIsNewSession: () => boolean;
+  getActiveSessionEntry: () => SessionEntry | undefined;
+  isHeartbeat: boolean;
+  isRestartRecoveryArmed: () => boolean;
+  pendingToolTasks: Set<Promise<void>>;
+  replyMediaContext: ReplyMediaContext;
+  replyOperation: ReplyOperation;
+  replyRouteThreadId: ReturnType<typeof resolveRoutedDeliveryThreadId>;
+  replyToChannel: OriginatingChannelType | undefined;
+  replyToMode: ReturnType<typeof resolveReplyToMode>;
+  resetSessionAfterRoleOrderingConflict: (reason: string) => Promise<boolean>;
+  returnWithQueuedFollowupDrain: <T>(value: T) => T;
+  runFollowupTurn: (queued: FollowupRun) => Promise<void>;
+  sendDirectCompactionNotice: ((phase: CompactionNoticePhase) => Promise<void>) | undefined;
+  setRunFollowupTurn: (runner: (queued: FollowupRun) => Promise<void>) => void;
+  setActiveSessionEntry: (entry: SessionEntry | undefined) => void;
+  shouldEmitToolOutput: () => boolean;
+  shouldEmitToolResult: () => boolean;
+  traceAgentPhase: <T>(name: string, run: () => Promise<T> | T) => Promise<T>;
+  turnAdoptionLifecycle: NonNullable<RunReplyAgentParams["opts"]>["turnAdoptionLifecycle"];
+  typingSignals: TypingSignaler;
+};
+
+function markPostCompactionFailureResult(
+  result: ReplyPayload | ReplyPayload[] | undefined,
+  postCompactionModelFailure: true | undefined,
+): ReplyPayload | ReplyPayload[] | undefined {
+  if (Array.isArray(result)) {
+    return result.map((payload) =>
+      markPostCompactionModelFailurePayload(postCompactionModelFailure, payload),
+    );
+  }
+  return result
+    ? markPostCompactionModelFailurePayload(postCompactionModelFailure, result)
+    : result;
+}
+
+export async function executePreparedReplyAgentRun(
+  context: ExecutePreparedReplyAgentRunInput,
+): Promise<ReplyPayload | ReplyPayload[] | undefined> {
+  const {
+    activeSessionStore,
+    admitUserTurn: admitUserTurnWithRecovery,
+    applyReplyToMode,
+    beginBeforeAgentReply: beginBeforeAgentReplyWithRecovery,
+    blockReplyChunking,
+    blockReplyPipeline,
+    blockStreamingEnabled,
+    cfg,
+    checkpointBeforeAgentReply: checkpointBeforeAgentReplyWithRecovery,
+    commandBody,
+    defaultModel,
+    followupRun,
+    getActiveIsNewSession,
+    getActiveSessionEntry,
+    isHeartbeat,
+    isRestartRecoveryArmed,
+    opts,
+    pendingToolTasks,
+    queueKey,
+    replyMediaContext,
+    replyOperation,
+    replyRouteThreadId,
+    replyThreadingOverride,
+    replyToChannel,
+    replyToMode,
+    resetSessionAfterRoleOrderingConflict,
+    resolvedBlockStreamingBreak,
+    resolvedQueue,
+    resolvedVerboseLevel,
+    returnWithQueuedFollowupDrain,
+    runtimePolicySessionKey,
+    sendDirectCompactionNotice,
+    sessionCtx,
+    sessionKey,
+    setActiveSessionEntry,
+    setRunFollowupTurn,
+    shouldEmitToolOutput,
+    shouldEmitToolResult,
+    shouldInjectGroupIntro,
+    storePath,
+    toolProgressDetail,
+    traceAgentPhase,
+    transcriptCommandBody,
+    turnAdoptionLifecycle,
+    typing,
+    typingMode,
+    typingSignals,
+  } = context;
+  let activeSessionEntry = getActiveSessionEntry();
+  const admitUserTurn = async (
+    ...args: Parameters<typeof admitUserTurnWithRecovery>
+  ): ReturnType<typeof admitUserTurnWithRecovery> => {
+    const result = await admitUserTurnWithRecovery(...args);
+    activeSessionEntry = getActiveSessionEntry();
+    return result;
+  };
+  const beginBeforeAgentReply = async (
+    ...args: Parameters<typeof beginBeforeAgentReplyWithRecovery>
+  ): ReturnType<typeof beginBeforeAgentReplyWithRecovery> => {
+    const result = await beginBeforeAgentReplyWithRecovery(...args);
+    activeSessionEntry = getActiveSessionEntry();
+    return result;
+  };
+  const checkpointBeforeAgentReply = async (
+    ...args: Parameters<typeof checkpointBeforeAgentReplyWithRecovery>
+  ): ReturnType<typeof checkpointBeforeAgentReplyWithRecovery> => {
+    const result = await checkpointBeforeAgentReplyWithRecovery(...args);
+    activeSessionEntry = getActiveSessionEntry();
+    return result;
+  };
+
+  await typingSignals.signalRunStart();
+
+  const preflightAdmission = readPendingUserTurnTranscriptAdmission(
+    followupRun.userTurnTranscriptRecorder,
+  );
+  const checkpointMemory = async (entry: SessionEntry) => {
+    const flushed = await traceAgentPhase("reply.memory_flush", () =>
+      runMemoryFlushIfNeeded({
+        preflightAdmission,
+        cfg,
+        followupRun,
+        promptForEstimate: followupRun.prompt,
+        opts,
+        defaultModel,
+        resolvedVerboseLevel,
+        sessionEntry: entry,
+        sessionStore: activeSessionStore,
+        sessionKey,
+        runtimePolicySessionKey,
+        storePath,
+        isHeartbeat,
+        replyOperation,
+      }),
+    );
+    setActiveSessionEntry(flushed.sessionEntry);
+    replyOperation.abortSignal.throwIfAborted();
+    if (flushed.outcome === "exhausted") {
+      await sendDirectCompactionNotice?.("memory_flush_degraded");
+    }
+    return flushed.sessionEntry;
+  };
+
+  const prePreflightCompactionCount = activeSessionEntry?.compactionCount ?? 0;
+  activeSessionEntry = await traceAgentPhase("reply.preflight_compaction", () =>
+    runSessionCompactionIfNeeded({
+      pendingUserEntryId: preflightAdmission?.entryId,
+      cfg,
+      followupRun,
+      promptForEstimate: followupRun.prompt,
+      defaultModel,
+      sessionEntry: activeSessionEntry,
+      sessionStore: activeSessionStore,
+      sessionKey,
+      runtimePolicySessionKey,
+      storePath,
+      isHeartbeat,
+      abortSignal: replyOperation.abortSignal,
+      beforeCompaction: checkpointMemory,
+      onCompactionStart: () => replyOperation.setPhase("preflight_compacting"),
+      onSessionIdChanged: (sessionId) => replyOperation.updateSessionId(sessionId),
+      onCompactionNotice: sendDirectCompactionNotice,
+    }),
+  );
+  setActiveSessionEntry(activeSessionEntry);
+  const preflightCompactionApplied =
+    (activeSessionEntry?.compactionCount ?? 0) > prePreflightCompactionCount;
+
+  const runFollowupTurn = createFollowupRunner({
+    resolveGatewayContext: getGatewayContextResolver(replyOperation),
+    opts,
+    typing,
+    typingMode,
+    sessionEntry: activeSessionEntry,
+    sessionStore: activeSessionStore,
+    sessionKey,
+    storePath,
+    defaultModel,
+    toolProgressDetail,
+  });
+  setRunFollowupTurn(runFollowupTurn);
+
+  replyOperation.setPhase("running");
+  const runStartedAt = Date.now();
+  const userTurnAdmission = await admitUserTurn(followupRun.userTurnTranscriptRecorder);
+  if (userTurnAdmission === "duplicate-source") {
+    return returnWithQueuedFollowupDrain(undefined);
+  }
+  // Adoption marks run start and must never be spool-replayed (would re-run tools).
+  // Suppressed delivery persists only the user transcript; crashed suppressed runs die
+  // silently. Deliverable turns atomically persist transcript plus recovery ownership.
+  await turnAdoptionLifecycle?.onAdopted();
+  const runOutcome = await withBeforeAgentReplyObserver(
+    {
+      beforeDispatch: async () => {
+        return await beginBeforeAgentReply();
+      },
+      afterDispatch: async (hookResult) => {
+        if (!hookResult?.handled) {
+          await checkpointBeforeAgentReply({ state: undefined });
+          return hookResult;
+        }
+        const hookReply = hookResult.reply ?? { text: SILENT_REPLY_TOKEN };
+        const hookFinalDeliveryText = buildRecoverablePendingFinalDeliveryText([hookReply]);
+        const normalizedHookReplies = normalizePendingFinalDeliveryPayloads([hookReply]);
+        let hookCheckpoint: Parameters<typeof checkpointBeforeAgentReply>[0] = {
+          state: normalizedHookReplies.length === 0 ? "handled-silent" : "pending",
+        };
+        if (sessionKey && storePath && normalizedHookReplies.length > 0) {
+          const sourceReplyPolicy = resolveSourceReplyPolicy({
+            cfg,
+            sessionCtx,
+            sessionEntry: activeSessionEntry,
+            sessionKey,
+            runtimePolicySessionKey,
+            opts,
+          });
+          if (!sourceReplyPolicy.suppressDelivery) {
+            const pendingFinalDeliveryIntentId = crypto.randomUUID();
+            const pendingFinalDeliveryDeliveryId = crypto.randomUUID();
+            setReplyPayloadMetadata(hookReply, {
+              pendingFinalDeliveryCompletion: {
+                deliveryId: pendingFinalDeliveryDeliveryId,
+                intentId: pendingFinalDeliveryIntentId,
+                ...(activeSessionEntry?.restartRecoveryDeliveryRunId
+                  ? { recoveryRunId: activeSessionEntry.restartRecoveryDeliveryRunId }
+                  : {}),
+                sessionId: replyOperation.sessionId,
+                sessionKey,
+                storePath,
+              },
+            });
+            hookCheckpoint = {
+              state: "handled-reply",
+              pendingFinalDelivery: {
+                text: hookFinalDeliveryText ?? "",
+                intentId: pendingFinalDeliveryIntentId,
+                deliveries: [{ id: pendingFinalDeliveryDeliveryId, state: "prepared" }],
+                context: resolveReplyRunDeliveryContext({
+                  cfg,
+                  sessionCtx,
+                  sessionEntry: activeSessionEntry,
+                  sessionKey,
+                  runtimePolicySessionKey,
+                  opts,
+                }),
+              },
+            };
+          } else {
+            // dispatch-from-config owns source visibility for every returned payload.
+            // This checkpoint records that recovery owes no delivery; the outer gate drops the reply.
+            hookCheckpoint = { state: "handled-silent" };
+          }
+        }
+        await checkpointBeforeAgentReply(hookCheckpoint);
+        return { ...hookResult, reply: hookReply };
+      },
+    },
+    () =>
+      traceAgentPhase("reply.run_agent_turn", () =>
+        executeAgentTurn({
+          commandBody,
+          transcriptCommandBody,
+          followupRun,
+          sessionCtx,
+          replyThreading: replyThreadingOverride ?? sessionCtx.ReplyThreading,
+          replyOperation,
+          opts,
+          resolveVisibleReplyDelivery: context.resolveVisibleReplyDelivery,
+          typingSignals,
+          blockReplyPipeline,
+          blockStreamingEnabled,
+          blockReplyChunking,
+          resolvedBlockStreamingBreak,
+          applyReplyToMode,
+          shouldEmitToolResult,
+          shouldEmitToolOutput,
+          pendingToolTasks,
+          resetSessionAfterRoleOrderingConflict,
+          isHeartbeat,
+          sessionKey,
+          runtimePolicySessionKey,
+          getActiveSessionEntry,
+          activeSessionStore,
+          storePath,
+          resolvedVerboseLevel,
+          toolProgressDetail,
+          replyMediaContext,
+          isRestartRecoveryArmed,
+        }),
+      ),
+  );
+  const operationSuperseded = isReplyOperationSuperseded(replyOperation);
+  recordReplyOperationAgentTurn(
+    followupRun.replyOperationRunStates,
+    replyOperation,
+    runOutcome.outcome,
+  );
+  activeSessionEntry = getActiveSessionEntry();
+  const activeIsNewSession = getActiveIsNewSession();
+
+  if (runOutcome.outcome.kind !== "settled") {
+    // Only captured facts cross cancellation; no successor adoption, hooks, or reply work.
+    await accountAgentTurnCompaction({
+      compaction: runOutcome.outcome.compaction,
+      sessionStore: activeSessionStore,
+      replyOperation,
+    });
+  }
+  if (operationSuperseded) {
+    return { text: SILENT_REPLY_TOKEN };
+  }
+  if (runOutcome.outcome.kind !== "settled") {
+    if (runOutcome.outcome.kind === "rejected" && !replyOperation.result) {
+      replyOperation.fail("run_failed", new Error("reply operation exited with final payload"));
+    }
+    return returnWithQueuedFollowupDrain(
+      runOutcome.outcome.kind === "rejected"
+        ? markPostCompactionModelFailurePayload(
+            runOutcome.outcome.postCompactionModelFailure,
+            runOutcome.outcome.payload,
+          )
+        : { text: SILENT_REPLY_TOKEN },
+    );
+  }
+
+  const result = await finalizeReplyAgentRun({
+    activeIsNewSession,
+    activeSessionEntry,
+    activeSessionStore,
+    blockReplyPipeline,
+    blockStreamingEnabled,
+    cfg,
+    commandBody,
+    defaultModel,
+    followupRun,
+    isHeartbeat,
+    opts,
+    pendingToolTasks,
+    preflightCompactionApplied,
+    queueKey,
+    replyMediaContext,
+    replyOperation,
+    replyRouteThreadId,
+    replyThreadingOverride,
+    replyToChannel,
+    replyToMode,
+    resolvedBlockStreamingBreak,
+    resolvedQueue,
+    resolvedVerboseLevel,
+    returnWithQueuedFollowupDrain,
+    runFollowupTurn,
+    execution: runOutcome.outcome,
+    runId: runOutcome.runId,
+    runStartedAt,
+    runtimePolicySessionKey,
+    sessionCtx,
+    sessionKey,
+    shouldInjectGroupIntro,
+    storePath,
+    typingSignals,
+  });
+  return markPostCompactionFailureResult(result, runOutcome.outcome.postCompactionModelFailure);
+}
+
+export function createReplyAgentRestartRecoveryController(
+  context: Pick<
+    RunReplyAgentParams,
+    "followupRun" | "opts" | "runtimePolicySessionKey" | "sessionCtx" | "sessionKey" | "storePath"
+  > & {
+    activeSessionStore: Record<string, SessionEntry> | undefined;
+    cfg: OpenClawConfig;
+    getActiveSessionEntry: () => SessionEntry | undefined;
+    replyOperation: ReplyOperation;
+    restartRecoverySourceTurnId: string | undefined;
+    setActiveSessionEntry: (entry: SessionEntry) => void;
+  },
+) {
+  const {
+    activeSessionStore,
+    cfg,
+    followupRun,
+    getActiveSessionEntry,
+    opts,
+    replyOperation,
+    restartRecoverySourceTurnId,
+    runtimePolicySessionKey,
+    sessionCtx,
+    sessionKey,
+    setActiveSessionEntry,
+    storePath,
+  } = context;
+
+  const restartRecoverySameChannelThreadRequired = restartRecoverySourceTurnId
+    ? buildThreadingToolContext({
+        sessionCtx,
+        config: cfg,
+        hasRepliedRef: undefined,
+      }).sameChannelThreadRequired
+    : undefined;
+  const {
+    admitUserTurn,
+    beginBeforeAgentReply,
+    checkpointBeforeAgentReply,
+    clear: clearRestartRecoveryDeliveryClaim,
+    isArmed: isRestartRecoveryArmed,
+  } = createReplyRestartRecoveryClaimController({
+    lifecycleGeneration: replyOperation.lifecycleGeneration,
+    admissionRunId:
+      normalizeOptionalString(sessionCtx.MessageSid) ??
+      normalizeOptionalString(sessionCtx.MessageSidFull),
+    getEntry: () =>
+      sessionKey
+        ? (activeSessionStore?.[sessionKey] ?? getActiveSessionEntry())
+        : getActiveSessionEntry(),
+    getSessionId: () => replyOperation.sessionId,
+    isRestartAbort: () =>
+      replyOperation.result?.kind === "aborted" &&
+      replyOperation.result.code === "aborted_for_restart",
+    resolveDeliveryContext: (entry) =>
+      sessionKey
+        ? resolveReplyRunDeliveryContext({
+            cfg,
+            sessionCtx,
+            sessionEntry: entry,
+            sessionKey,
+            runtimePolicySessionKey,
+            opts,
+          })
+        : undefined,
+    requesterAccountId:
+      followupRun.originatingAccountId ?? sessionCtx.AccountId ?? followupRun.run.agentAccountId,
+    requesterSenderId: sessionCtx.SenderId,
+    resolveUserTurnTarget: ({
+      entry,
+      sessionId,
+      sessionKey: targetSessionKey,
+      storePath: targetStorePath,
+    }) => ({
+      sessionId,
+      sessionKey: targetSessionKey,
+      sessionEntry: entry,
+      ...(activeSessionStore ? { sessionStore: activeSessionStore } : {}),
+      storePath: targetStorePath,
+      agentId: followupRun.run.agentId,
+      cwd: followupRun.run.workspaceDir,
+      config: cfg,
+    }),
+    ...(sessionKey ? { sessionKey } : {}),
+    setEntry: (entry) => {
+      setActiveSessionEntry(entry);
+      if (activeSessionStore && sessionKey) {
+        activeSessionStore[sessionKey] = entry;
+      }
+    },
+    sameChannelThreadRequired: restartRecoverySameChannelThreadRequired,
+    sourceTurnId: restartRecoverySourceTurnId,
+    sourceReplyDeliveryMode: sessionKey
+      ? resolveSourceReplyPolicy({
+          cfg,
+          sessionCtx,
+          sessionEntry: getActiveSessionEntry(),
+          sessionKey,
+          runtimePolicySessionKey,
+          opts,
+        }).sourceReplyDeliveryMode
+      : opts?.sourceReplyDeliveryMode,
+    ...(storePath ? { storePath } : {}),
+  });
+  const admitUserTurnWithSourceBinding: typeof admitUserTurn = async (...args) => {
+    const result = await admitUserTurn(...args);
+    if (result === "admitted" && restartRecoverySourceTurnId) {
+      replyRunRegistry.bindSourceTurnId(replyOperation, restartRecoverySourceTurnId);
+    }
+    return result;
+  };
+  return {
+    admitUserTurn: admitUserTurnWithSourceBinding,
+    beginBeforeAgentReply,
+    checkpointBeforeAgentReply,
+    clear: clearRestartRecoveryDeliveryClaim,
+    isArmed: isRestartRecoveryArmed,
+  };
+}

src/auto-reply/reply/agent-runner-execution-auth-failures.test.ts

@@ -0,0 +1,546 @@
+import { describe, expect, it } from "vitest";
+import { OAuthRefreshFailureError } from "../../agents/auth-profiles/oauth-refresh-failure.js";
+import { createCliOutputFailoverError } from "../../agents/cli-runner/output-error.js";
+import { FailoverError } from "../../agents/failover-error.js";
+import { MissingProviderAuthError, ProviderAuthError } from "../../agents/model-auth.js";
+import type { TemplateContext } from "../templating.js";
+import {
+  setupAgentRunnerExecutionTestState,
+  getExecuteAgentTurnForTest,
+  createRunAgentTurnParams,
+  createFollowupRun,
+  createMinimalRunAgentTurnParams,
+  createTestFallbackSummaryError,
+} from "./agent-runner-execution.test-support.js";
+
+const state = await setupAgentRunnerExecutionTestState();
+
+const providerLoginPresentation = (command: string) => ({
+  blocks: [
+    {
+      type: "buttons",
+      buttons: [
+        {
+          label: "Sign in",
+          action: { type: "command", command },
+        },
+      ],
+    },
+  ],
+});
+const PROVIDER_LOGIN_PRESENTATION = providerLoginPresentation("/login openai");
+
+describe("executeAgentTurn: authentication failures", () => {
+  it("surfaces gateway reauth guidance without a profile id", async () => {
+    state.runEmbeddedAgentMock.mockRejectedValueOnce(
+      new OAuthRefreshFailureError({ provider: "openai", message: "refresh_token_reused" }),
+    );
+
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const result = await executeAgentTurn(createRunAgentTurnParams(createFollowupRun()));
+
+    expect(result.kind).toBe("final");
+    if (result.kind === "final") {
+      expect(result.payload.text).toBe(
+        "⚠️ Your model provider needs a new login. Send `/login openai` from a private chat or Control UI session. Where shown, you can also select **Sign in**. You can also re-auth with `openclaw models auth login --provider openai` on the gateway.",
+      );
+      expect(result.payload.presentation).toEqual(PROVIDER_LOGIN_PRESENTATION);
+    }
+  });
+
+  it("adds provider login recovery to raw forwarded refresh failures", async () => {
+    const message = "OAuth token refresh failed for openai: refresh_token_invalidated";
+    state.runEmbeddedAgentMock.mockRejectedValueOnce(
+      new FailoverError(message, {
+        reason: "auth_permanent",
+        provider: "openai",
+        model: "gpt-5.6-sol",
+        status: 401,
+        rawError: message,
+      }),
+    );
+
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const result = await executeAgentTurn(createMinimalRunAgentTurnParams());
+
+    expect(result.kind).toBe("final");
+    if (result.kind === "final") {
+      expect(result.payload.presentation).toEqual(PROVIDER_LOGIN_PRESENTATION);
+    }
+  });
+
+  it("keeps provider login recovery actionable on Control UI turns", async () => {
+    state.isInternalMessageChannelMock.mockReturnValue(true);
+    state.runEmbeddedAgentMock.mockRejectedValueOnce(
+      new OAuthRefreshFailureError({ provider: "openai", message: "refresh_token_reused" }),
+    );
+    const followupRun = createFollowupRun();
+    followupRun.run.messageProvider = "webchat";
+
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const result = await executeAgentTurn(
+      createMinimalRunAgentTurnParams({
+        followupRun,
+        sessionCtx: { Provider: "webchat", MessageSid: "msg" } as unknown as TemplateContext,
+      }),
+    );
+
+    expect(result.kind).toBe("final");
+    if (result.kind === "final") {
+      expect(result.payload.text).toBe(
+        "⚠️ Your model provider needs a new login. Send `/login openai` from a private chat or Control UI session. Where shown, you can also select **Sign in**. You can also re-auth with `openclaw models auth login --provider openai` on the gateway.",
+      );
+      expect(result.payload.presentation).toEqual(PROVIDER_LOGIN_PRESENTATION);
+    }
+  });
+
+  it("surfaces gateway reauth guidance from typed OAuth refresh failures", async () => {
+    state.runEmbeddedAgentMock.mockRejectedValueOnce(
+      new OAuthRefreshFailureError({
+        provider: "openai",
+        profileId: "openai:user@example.com",
+        message: "invalid_grant",
+      }),
+    );
+
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const result = await executeAgentTurn(createMinimalRunAgentTurnParams());
+
+    expect(result.kind).toBe("final");
+    if (result.kind === "final") {
+      expect(result.payload.text).toBe(
+        "⚠️ Your model provider needs a new login. Send `/login openai` from a private chat or Control UI session. Where shown, you can also select **Sign in**. You can also re-auth with `openclaw models auth login --provider openai --profile-id 'openai:user@example.com'` on the gateway.",
+      );
+      expect(result.payload.presentation).toEqual(PROVIDER_LOGIN_PRESENTATION);
+    }
+  });
+
+  it("preserves OAuth profile guidance through failover wrappers", async () => {
+    const refreshError = new OAuthRefreshFailureError({
+      provider: "openai",
+      profileId: "openai:user@example.com",
+      message: "invalid_grant",
+    });
+    state.runEmbeddedAgentMock.mockRejectedValueOnce(
+      new FailoverError("OpenAI OAuth failed", {
+        reason: "auth",
+        provider: "openai",
+        model: "gpt-5.5",
+        profileId: "openai:user@example.com",
+        authProfileFailure: { allInCooldown: false },
+        status: 401,
+        cause: refreshError,
+      }),
+    );
+
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const result = await executeAgentTurn(createMinimalRunAgentTurnParams());
+
+    expect(result.kind).toBe("final");
+    if (result.kind === "final") {
+      expect(result.payload.text).toContain("--profile-id 'openai:user@example.com'");
+      expect(result.payload.presentation).toEqual(PROVIDER_LOGIN_PRESENTATION);
+    }
+  });
+
+  it("preserves OAuth profile guidance through fallback summaries", async () => {
+    const refreshError = new OAuthRefreshFailureError({
+      provider: "openai",
+      profileId: "openai:user@example.com",
+      message: "invalid_grant",
+    });
+    const failoverError = new FailoverError("OpenAI OAuth failed", {
+      reason: "auth",
+      provider: "openai",
+      model: "gpt-5.5",
+      profileId: "openai:user@example.com",
+      authProfileFailure: { allInCooldown: false },
+      status: 401,
+      cause: refreshError,
+    });
+    const summaryError = createTestFallbackSummaryError({
+      message: "All models failed",
+      attempts: [
+        {
+          provider: "openai",
+          model: "gpt-5.5",
+          error: "OpenAI OAuth failed",
+          reason: "auth",
+        },
+      ],
+      soonestCooldownExpiry: null,
+      cause: failoverError,
+    });
+    state.runEmbeddedAgentMock.mockRejectedValueOnce(summaryError);
+
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const result = await executeAgentTurn(createMinimalRunAgentTurnParams());
+
+    expect(result.kind).toBe("final");
+    if (result.kind === "final") {
+      expect(result.payload.text).toContain("--profile-id 'openai:user@example.com'");
+      expect(result.payload.presentation).toEqual(PROVIDER_LOGIN_PRESENTATION);
+    }
+  });
+
+  it("omits OAuth profile ids from group reauth guidance", async () => {
+    state.runEmbeddedAgentMock.mockRejectedValueOnce(
+      new OAuthRefreshFailureError({
+        provider: "openai",
+        profileId: "openai:user@example.com",
+        message: "invalid_grant",
+      }),
+    );
+
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const result = await executeAgentTurn(
+      createMinimalRunAgentTurnParams({
+        sessionCtx: {
+          Provider: "whatsapp",
+          MessageSid: "msg",
+          ChatType: "group",
+        } as unknown as TemplateContext,
+      }),
+    );
+
+    expect(result.kind).toBe("final");
+    if (result.kind === "final") {
+      expect(result.payload.text).toContain("openclaw models auth login --provider openai");
+      expect(result.payload.text).not.toContain("user@example.com");
+      expect(result.payload.presentation).toEqual(PROVIDER_LOGIN_PRESENTATION);
+    }
+  });
+
+  it.each([
+    ["openai", "/login openai"],
+    ["xai", "/login xai"],
+    ["minimax-portal", "/login minimax-portal"],
+  ])("keeps disabled %s OAuth profiles actionable on later turns", async (provider, command) => {
+    state.runEmbeddedAgentMock.mockRejectedValueOnce(
+      new FailoverError("All OpenAI auth profiles are unavailable", {
+        reason: "auth_permanent",
+        provider,
+        model: "fixture-model",
+        authMode: "oauth",
+        authProfileFailure: { allInCooldown: true },
+      }),
+    );
+
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const result = await executeAgentTurn(createMinimalRunAgentTurnParams());
+
+    expect(result.kind).toBe("final");
+    if (result.kind === "final") {
+      expect(result.payload.text).toContain(command);
+      expect(result.payload.presentation).toEqual(providerLoginPresentation(command));
+    }
+  });
+
+  it.each([
+    {
+      label: "provider names without OAuth evidence",
+      error: new FailoverError("Authentication unavailable", {
+        reason: "auth_permanent",
+        provider: "some-provider",
+        authProfileFailure: { allInCooldown: true },
+      }),
+    },
+    {
+      label: "OpenAI API-key failures",
+      error: new FailoverError("invalid API key", {
+        reason: "auth_permanent",
+        provider: "openai",
+        model: "gpt-5.5",
+        authMode: "api-key",
+        authProfileFailure: { allInCooldown: true },
+      }),
+    },
+    {
+      label: "transient OpenAI refresh failures",
+      error: new OAuthRefreshFailureError({
+        provider: "openai",
+        message: "temporary upstream issue",
+      }),
+    },
+  ])("does not offer provider login for $label", async ({ error }) => {
+    state.runEmbeddedAgentMock.mockRejectedValueOnce(error);
+
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const result = await executeAgentTurn(createMinimalRunAgentTurnParams());
+
+    expect(result.kind).toBe("final");
+    if (result.kind === "final") {
+      expect(result.payload.presentation).toBeUndefined();
+    }
+  });
+
+  it("adds provider login while retaining non-OpenAI terminal guidance", async () => {
+    state.runEmbeddedAgentMock.mockRejectedValueOnce(
+      new OAuthRefreshFailureError({
+        provider: "anthropic",
+        message: "invalid_grant",
+      }),
+    );
+
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const result = await executeAgentTurn(createMinimalRunAgentTurnParams());
+
+    expect(result.kind).toBe("final");
+    if (result.kind === "final") {
+      expect(result.payload.text).toBe(
+        "⚠️ Your model provider needs a new login. Send `/login anthropic` from a private chat or Control UI session. Where shown, you can also select **Sign in**. You can also re-auth with `openclaw models auth login --provider anthropic` on the gateway.",
+      );
+      expect(result.payload.presentation).toEqual(providerLoginPresentation("/login anthropic"));
+    }
+  });
+
+  it("surfaces Agent SDK OAuth session expiry in Discord channels", async () => {
+    const error = createCliOutputFailoverError({
+      output: {
+        text: "",
+        errorText: "Failed to authenticate: OAuth session expired and could not be refreshed",
+      },
+      provider: "claude-cli",
+      model: "claude-opus-5",
+    });
+    if (!error) {
+      throw new Error("expected CLI output failure");
+    }
+    state.runEmbeddedAgentMock.mockRejectedValueOnce(error);
+
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const result = await executeAgentTurn(
+      createMinimalRunAgentTurnParams({
+        sessionCtx: {
+          Provider: "discord",
+          Surface: "discord",
+          ChatType: "channel",
+          MessageSid: "msg",
+        } as unknown as TemplateContext,
+      }),
+    );
+
+    expect(result.kind).toBe("final");
+    if (result.kind === "final") {
+      expect(result.payload.text).toBe(
+        "⚠️ Your model provider needs a new login. Send `/login` from a private chat or Control UI session. Where shown, you can also select **Sign in**. You can also re-auth with `claude auth login && openclaw models auth login --provider anthropic --method cli` on the gateway.",
+      );
+      expect(result.payload.presentation).toEqual(providerLoginPresentation("/login"));
+    }
+  });
+
+  it("surfaces claude-cli re-auth hint from structured provider metadata when the message omits claude-cli", async () => {
+    state.runEmbeddedAgentMock.mockRejectedValueOnce(
+      new FailoverError(
+        "Failed to authenticate. API Error: 401 Invalid authentication credentials",
+        {
+          reason: "auth",
+          provider: "claude-cli",
+          model: "claude-sonnet-4-20250514",
+          status: 401,
+        },
+      ),
+    );
+
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const result = await executeAgentTurn(createMinimalRunAgentTurnParams());
+
+    expect(result.kind).toBe("final");
+    if (result.kind === "final") {
+      expect(result.payload.text).toBe(
+        "⚠️ Your model provider needs a new login. Send `/login` from a private chat or Control UI session. Where shown, you can also select **Sign in**. You can also re-auth with `claude auth login && openclaw models auth login --provider anthropic --method cli` on the gateway.",
+      );
+    }
+  });
+
+  it("surfaces the claude-cli re-auth hint when the CLI session is logged out", async () => {
+    state.runEmbeddedAgentMock.mockRejectedValueOnce(
+      new FailoverError("Not logged in · Please run /login", {
+        reason: "auth",
+        provider: "claude-cli",
+        model: "claude-sonnet-4-20250514",
+        status: 401,
+      }),
+    );
+
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const result = await executeAgentTurn(createMinimalRunAgentTurnParams());
+
+    expect(result.kind).toBe("final");
+    if (result.kind === "final") {
+      expect(result.payload.text).toBe(
+        "⚠️ Your model provider needs a new login. Send `/login` from a private chat or Control UI session. Where shown, you can also select **Sign in**. You can also re-auth with `claude auth login && openclaw models auth login --provider anthropic --method cli` on the gateway.",
+      );
+    }
+  });
+
+  it("surfaces direct provider auth guidance for missing API keys", async () => {
+    state.runEmbeddedAgentMock.mockRejectedValueOnce(
+      new ProviderAuthError(
+        "missing-provider-auth",
+        "openai",
+        'No API key found for provider "openai". You are authenticated with OpenAI Codex OAuth.',
+        { providerGuidance: true },
+      ),
+    );
+
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const result = await executeAgentTurn(createRunAgentTurnParams(createFollowupRun()));
+
+    expect(result.kind).toBe("final");
+    if (result.kind === "final") {
+      expect(result.payload.text).toBe(
+        "⚠️ Missing API key for OpenAI on the gateway. Use `openai/gpt-6-astra` with the OpenAI OAuth profile, or set `OPENAI_API_KEY` for direct OpenAI API-key runs.",
+      );
+    }
+  });
+
+  it("surfaces typed missing API-key auth guidance without parsing the message", async () => {
+    state.runEmbeddedAgentMock.mockRejectedValueOnce(
+      new MissingProviderAuthError("openai", {
+        mode: "api-key",
+        source: "env: OPENAI_API_KEY",
+      }),
+    );
+
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const result = await executeAgentTurn(createMinimalRunAgentTurnParams());
+
+    expect(result.kind).toBe("final");
+    if (result.kind === "final") {
+      expect(result.payload.text).toBe(
+        '⚠️ Missing API key for provider "openai". Run `openclaw doctor --fix` to repair stale OpenAI model/session routes, restart the gateway if doctor asks, then try again. If doctor has nothing to repair or the error persists, re-auth with `openclaw models auth login --provider openai` or run `openclaw configure`.',
+      );
+    }
+  });
+
+  it("formats auth-profile failover copy from typed FailoverError metadata", async () => {
+    state.runEmbeddedAgentMock.mockRejectedValueOnce(
+      new FailoverError("Auth profile failover exhausted for provider openai", {
+        reason: "auth",
+        provider: "openai",
+        status: 401,
+        authProfileFailure: { allInCooldown: true },
+        cause: new Error("invalid_grant"),
+      }),
+    );
+
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const result = await executeAgentTurn(createMinimalRunAgentTurnParams());
+
+    expect(result.kind).toBe("final");
+    if (result.kind === "final") {
+      expect(result.payload.text).toContain("Couldn't sign in to openai.");
+      expect(result.payload.text).toContain("openclaw configure");
+      expect(result.payload.text).toContain("(invalid_grant)");
+      expect(result.payload.text).not.toContain("Auth profile failover exhausted");
+    }
+  });
+
+  it("renders bounded recovery when the selected auth profile is unavailable", async () => {
+    state.isInternalMessageChannelMock.mockReturnValue(true);
+    state.runEmbeddedAgentMock.mockRejectedValueOnce(
+      new FailoverError('Codex app-server auth profile "openai:private" was not found', {
+        reason: "auth",
+        provider: "openai",
+        status: 401,
+        code: "selected_auth_profile_unavailable",
+        authProfileFailure: { allInCooldown: false },
+        cause: new Error("arbitrary plugin detail for openai:private"),
+      }),
+    );
+
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const result = await executeAgentTurn(createMinimalRunAgentTurnParams());
+
+    expect(result.kind).toBe("final");
+    if (result.kind === "final") {
+      expect(result.payload.text).toBe(
+        "The selected auth profile is unavailable in this agent's OpenClaw credential store. Import or migrate that credential into the agent, select another configured profile, or run `openclaw configure`, then retry.",
+      );
+      expect(result.payload.text).not.toContain("openai:private");
+      expect(result.payload.text).not.toContain("arbitrary plugin detail");
+      expect(result.payload.text).not.toContain("/login");
+      expect(result.payload.presentation).toBeUndefined();
+    }
+  });
+
+  it("does not suggest re-authentication for typed format failures", async () => {
+    state.runEmbeddedAgentMock.mockRejectedValueOnce(
+      new FailoverError("Format failover exhausted for provider openai", {
+        reason: "format",
+        provider: "openai",
+        authProfileFailure: { allInCooldown: true },
+        cause: new Error("messages must alternate roles"),
+      }),
+    );
+
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const result = await executeAgentTurn(createMinimalRunAgentTurnParams());
+
+    expect(result.kind).toBe("final");
+    if (result.kind === "final") {
+      expect(result.payload.text).toContain("Couldn't reach openai");
+      expect(result.payload.text).toContain("messages must alternate roles");
+      expect(result.payload.text).not.toContain("models auth login");
+      expect(result.payload.text).not.toContain("openclaw configure");
+    }
+  });
+
+  it("points stale openai missing-key failures at doctor repair with re-auth fallback", async () => {
+    state.runEmbeddedAgentMock.mockRejectedValueOnce(
+      new ProviderAuthError(
+        "missing-provider-auth",
+        "openai",
+        'No API key found for provider "openai".',
+      ),
+    );
+
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const result = await executeAgentTurn(createMinimalRunAgentTurnParams());
+
+    expect(result.kind).toBe("final");
+    if (result.kind === "final") {
+      expect(result.payload.text).toBe(
+        '⚠️ Missing API key for provider "openai". Run `openclaw doctor --fix` to repair stale OpenAI model/session routes, restart the gateway if doctor asks, then try again. If doctor has nothing to repair or the error persists, re-auth with `openclaw models auth login --provider openai` or run `openclaw configure`.',
+      );
+    }
+  });
+
+  it("falls back to a generic provider message for unsafe missing-key provider ids", async () => {
+    state.runEmbeddedAgentMock.mockRejectedValueOnce(
+      new ProviderAuthError(
+        "missing-provider-auth",
+        "openai`\nrm -rf /",
+        'No API key found for provider "openai`\nrm -rf /".',
+      ),
+    );
+
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const result = await executeAgentTurn(createRunAgentTurnParams(createFollowupRun()));
+
+    expect(result.kind).toBe("final");
+    if (result.kind === "final") {
+      expect(result.payload.text).toBe(
+        "⚠️ Missing API key for the selected provider on the gateway. Configure provider auth, then try again.",
+      );
+    }
+  });
+
+  it("falls back to a generic reauth command when the provider in the OAuth error is unsafe", async () => {
+    state.runEmbeddedAgentMock.mockRejectedValueOnce(
+      new OAuthRefreshFailureError({ provider: "openai`\nrm -rf /", message: "invalid_grant" }),
+    );
+
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const result = await executeAgentTurn(createRunAgentTurnParams(createFollowupRun()));
+
+    expect(result.kind).toBe("final");
+    if (result.kind === "final") {
+      expect(result.payload.text).toBe(
+        "⚠️ Your model provider needs a new login. Send `/login` from a private chat or Control UI session. Where shown, you can also select **Sign in**. You can also re-auth with `openclaw models auth login` on the gateway.",
+      );
+      expect(result.payload.presentation).toEqual(providerLoginPresentation("/login"));
+    }
+  });
+});

src/auto-reply/reply/agent-runner-execution-cli-admission.test.ts

@@ -0,0 +1,397 @@
+import { describe, expect, it, vi } from "vitest";
+import { withTestRunAdmission } from "../../agents/admitted-run-context.test-support.js";
+import { buildPreparedCliRunContext } from "../../agents/cli-runner.test-helpers.js";
+import { buildCliRunResult } from "../../agents/cli-runner/cli-run-settlement.js";
+import { executeDeps } from "../../agents/cli-runner/execute-deps.js";
+import { executePreparedCliRun } from "../../agents/cli-runner/execute.js";
+import { buildCliMcpGrantContext } from "../../agents/cli-runner/mcp-grant-context.js";
+import type { RunCliAgentParams } from "../../agents/cli-runner/types.js";
+import { GENERIC_EXTERNAL_RUN_FAILURE_TEXT } from "../../agents/failover/user-copy.js";
+import { installSessionPlacementAdmissionProvider } from "../../agents/session-placement-admission.js";
+import type { SessionEntry } from "../../config/sessions.js";
+import { loadSessionEntry, replaceSessionEntry } from "../../config/sessions/session-accessor.js";
+import {
+  setupAgentRunnerExecutionTestState,
+  getExecuteAgentTurnForTest,
+  createFollowupRun,
+  requireMockCall,
+  expectMockCallArgFields,
+  initialFallbackAttemptOptions,
+  fallbackAttemptOptions,
+  createMinimalRunAgentTurnParams,
+  makeTestSessionStorePath,
+} from "./agent-runner-execution.test-support.js";
+import type { FallbackRunnerParams } from "./agent-runner-execution.test-support.js";
+
+const state = await setupAgentRunnerExecutionTestState();
+
+function rejectUnexpectedCompactionSuccessor(): never {
+  throw new Error("Unexpected compaction successor during CLI admission test");
+}
+
+describe("executeAgentTurn: CLI admission", () => {
+  it.each([
+    "ordinary",
+    "heartbeat",
+    "preserved",
+    "revised",
+    "revision-established",
+    "rejected",
+    "rejected-clear",
+  ])("settles the %s reply's native binding before releasing placement", async (kind) => {
+    const sessionKey = "agent:main:cli-binding-settlement";
+    const storePath = makeTestSessionStorePath();
+    const entry: SessionEntry = {
+      sessionId: "session",
+      updatedAt: 1,
+      ...(kind === "revised" ? { lifecycleRevision: "original" } : {}),
+    };
+    const rejected = kind === "rejected" || kind === "rejected-clear";
+    const revisionChanged = kind === "revised" || kind === "revision-established";
+    const binding = { sessionId: "admitted-native-session", authProfileId: "anthropic:cli" };
+    const settledBinding = { ...binding, sessionId: "settled-native-session" };
+    await replaceSessionEntry(
+      { sessionKey, storePath },
+      {
+        ...entry,
+        cliSessionBindings: { "claude-cli": binding },
+      },
+    );
+    const followupRun = createFollowupRun();
+    followupRun.run.provider = "claude-cli";
+    followupRun.run.model = "claude-sonnet-4-6";
+    if (kind === "preserved") {
+      followupRun.run.inputProvenance = {
+        kind: "inter_session",
+        sourceTool: "exec_approval_followup",
+      };
+    }
+    state.isCliProviderMock.mockImplementation((provider) => provider === "claude-cli");
+    state.runWithModelFallbackMock.mockImplementationOnce(async (params: FallbackRunnerParams) => {
+      const first = await params.run(
+        "claude-cli",
+        "claude-sonnet-4-6",
+        initialFallbackAttemptOptions(params),
+      );
+      if (rejected) {
+        expect(first).toMatchObject({
+          classification: { code: "generic_external_run_failure" },
+        });
+        return {
+          result: await params.run("openai", "gpt-5.4", fallbackAttemptOptions(params, "format")),
+          provider: "openai",
+          model: "gpt-5.4",
+          attempts: [{ provider: "claude-cli", model: "claude-sonnet-4-6", reason: "format" }],
+        };
+      }
+      return {
+        result: first,
+        provider: "claude-cli",
+        model: "claude-sonnet-4-6",
+        attempts: [],
+      };
+    });
+    const candidateResult = {
+      payloads: [{ text: "done" }],
+      meta: {
+        agentMeta: { sessionId: settledBinding.sessionId, cliSessionBinding: settledBinding },
+      },
+    };
+    state.runCliAgentMock.mockResolvedValueOnce(
+      rejected
+        ? buildCliRunResult({
+            context: buildPreparedCliRunContext(),
+            output: { text: GENERIC_EXTERNAL_RUN_FAILURE_TEXT },
+            effectiveCliSessionId: settledBinding.sessionId,
+            bindingFlushOk: kind !== "rejected-clear",
+            usedHistoryPrompt: false,
+            userTurnHandled: true,
+            sessionBindingDisabled: false,
+            preparedContextAgentMeta: {},
+          })
+        : candidateResult,
+    );
+    state.runEmbeddedAgentMock.mockResolvedValueOnce({
+      payloads: [{ text: "fallback done" }],
+      meta: {},
+    });
+    let observedBinding: unknown;
+    const uninstall = installSessionPlacementAdmissionProvider({
+      assertCompactionSuccessorAllowed: rejectUnexpectedCompactionSuccessor,
+      executeLocalTurn: async (_claim, runLocal) => {
+        if (revisionChanged) {
+          // Mutating the prepared object must not change the captured admission revision.
+          entry.lifecycleRevision = "replacement";
+          await replaceSessionEntry(
+            { sessionKey, storePath },
+            {
+              ...entry,
+              cliSessionBindings: { "claude-cli": binding },
+            },
+          );
+        }
+        const result = await runLocal();
+        observedBinding = loadSessionEntry({ sessionKey, storePath })?.cliSessionBindings?.[
+          "claude-cli"
+        ];
+        return result;
+      },
+      executeTurn: async (_claim, _params, runLocal) => await runLocal(),
+    });
+    try {
+      const executeAgentTurn = await getExecuteAgentTurnForTest();
+      const result = await executeAgentTurn({
+        ...createMinimalRunAgentTurnParams({ followupRun }),
+        sessionKey,
+        storePath,
+        isHeartbeat: kind === "heartbeat",
+        activeSessionStore: { [sessionKey]: entry },
+        getActiveSessionEntry: () => entry,
+      });
+      if (revisionChanged) {
+        expect(result.kind).toBe("final");
+        expect(state.runCliAgentMock).not.toHaveBeenCalled();
+        expect(
+          loadSessionEntry({ sessionKey, storePath })?.cliSessionBindings?.["claude-cli"],
+        ).toEqual(binding);
+        return;
+      }
+      expect(result.kind).toBe("success");
+      expectMockCallArgFields(state.runCliAgentMock, 0, "CLI run params", {
+        cliSessionId: binding.sessionId,
+        cliSessionBinding: binding,
+      });
+      expect(observedBinding).toEqual(
+        kind === "rejected-clear"
+          ? undefined
+          : kind === "preserved" || rejected
+            ? binding
+            : settledBinding,
+      );
+    } finally {
+      uninstall();
+    }
+  });
+
+  it.each(["ordinary", "rejected-clear", "room-event"] as const)(
+    "retains the %s reply after its continuity write loses ownership",
+    async (kind) => {
+      const sessionKey = "agent:main:cli-owner-loss";
+      const storePath = makeTestSessionStorePath();
+      const binding = { sessionId: "previous-native-session" };
+      const entry: SessionEntry = {
+        sessionId: "session",
+        updatedAt: 1,
+        cliSessionBindings: { "claude-cli": binding },
+      };
+      await replaceSessionEntry({ sessionKey, storePath }, entry);
+      const followupRun = createFollowupRun();
+      followupRun.run.provider = "claude-cli";
+      followupRun.run.model = "claude-sonnet-4-6";
+      if (kind === "room-event") {
+        followupRun.currentInboundEventKind = "room_event";
+      }
+      state.isCliProviderMock.mockImplementation((provider) => provider === "claude-cli");
+      const candidate = buildCliRunResult({
+        context: buildPreparedCliRunContext(),
+        output: {
+          text: kind === "rejected-clear" ? GENERIC_EXTERNAL_RUN_FAILURE_TEXT : "Captured reply",
+        },
+        effectiveCliSessionId: "replacement-native-session",
+        bindingFlushOk: kind !== "rejected-clear",
+        usedHistoryPrompt: false,
+        userTurnHandled: true,
+        sessionBindingDisabled: false,
+        preparedContextAgentMeta: {},
+      });
+      const provider: Parameters<typeof installSessionPlacementAdmissionProvider>[0] = {
+        assertCompactionSuccessorAllowed: rejectUnexpectedCompactionSuccessor,
+        executeLocalTurn: async (_claim, runLocal) => await runLocal(),
+        executeTurn: async (_claim, _params, runLocal) => await runLocal(),
+      };
+      const uninstall = installSessionPlacementAdmissionProvider(provider);
+      let uninstallReplacement: (() => void) | undefined;
+      state.runCliAgentMock.mockImplementationOnce(async () => {
+        uninstallReplacement = installSessionPlacementAdmissionProvider({ ...provider });
+        return candidate;
+      });
+      state.runWithModelFallbackMock.mockImplementationOnce(
+        async (params: FallbackRunnerParams) => {
+          const result = await params.run(
+            "claude-cli",
+            "claude-sonnet-4-6",
+            initialFallbackAttemptOptions(params),
+          );
+          expect(result).toMatchObject({
+            classification: null,
+            result: {
+              payloads: expect.arrayContaining(candidate.payloads ?? []),
+              meta: {
+                replayInvalid: true,
+                error: {
+                  message: expect.stringContaining("CLI session continuity could not be saved"),
+                  fallbackSafe: false,
+                },
+              },
+            },
+          });
+          return { result, provider: "claude-cli", model: "claude-sonnet-4-6", attempts: [] };
+        },
+      );
+      try {
+        const executeAgentTurn = await getExecuteAgentTurnForTest();
+        await executeAgentTurn({
+          ...createMinimalRunAgentTurnParams({ followupRun }),
+          sessionKey,
+          storePath,
+          activeSessionStore: { [sessionKey]: entry },
+          getActiveSessionEntry: () => entry,
+        });
+        expect(state.runCliAgentMock).toHaveBeenCalledOnce();
+        expect(state.runEmbeddedAgentMock).not.toHaveBeenCalled();
+        expect(
+          loadSessionEntry({ sessionKey, storePath })?.cliSessionBindings?.["claude-cli"],
+        ).toEqual(binding);
+      } finally {
+        uninstallReplacement?.();
+        uninstall();
+      }
+    },
+  );
+
+  it("carries the admitted session permission and placement into the CLI grant", async () => {
+    state.isCliProviderMock.mockReturnValue(true);
+    state.runWithModelFallbackMock.mockImplementationOnce(async (params: FallbackRunnerParams) => ({
+      result: await params.run(
+        "claude-cli",
+        "claude-sonnet-4-6",
+        initialFallbackAttemptOptions(params),
+      ),
+      provider: "claude-cli",
+      model: "claude-sonnet-4-6",
+      attempts: [],
+    }));
+    let sessionEntry: SessionEntry = {
+      sessionId: "session",
+      updatedAt: 1,
+      permissionMode: "guarded",
+      sessionRoot: "/workspace/old",
+      execHost: "gateway",
+      cliSessionBindings: {
+        "claude-cli": { sessionId: "old-native-session", forceReuse: true },
+      },
+    };
+    const admittedSessionEntry: SessionEntry = {
+      sessionId: "session",
+      updatedAt: 2,
+      permissionMode: "read-only",
+      sessionRoot: "/workspace/project",
+      execHost: "node",
+      execNode: "node-a",
+      execCwd: "/workspace/project/task",
+      cliSessionBindings: {
+        "claude-cli": { sessionId: "new-native-session", forceReuse: true },
+      },
+    };
+    state.runCliAgentMock.mockResolvedValueOnce({ payloads: [{ text: "done" }], meta: {} });
+    const followupRun = createFollowupRun();
+    followupRun.run.provider = "claude-cli";
+    followupRun.run.model = "claude-sonnet-4-6";
+    const restoreAdmission = installSessionPlacementAdmissionProvider({
+      assertCompactionSuccessorAllowed: rejectUnexpectedCompactionSuccessor,
+      executeLocalTurn: async (_claim, runLocal) => {
+        sessionEntry = admittedSessionEntry;
+        return await runLocal();
+      },
+      executeTurn: async (_claim, _params, runLocal) => await runLocal(),
+    });
+
+    try {
+      const executeAgentTurn = await getExecuteAgentTurnForTest();
+      const result = await executeAgentTurn({
+        ...createMinimalRunAgentTurnParams({ followupRun }),
+        getActiveSessionEntry: () => sessionEntry,
+      });
+
+      expect(result.kind).toBe("success");
+      const run = requireMockCall(
+        state.runCliAgentMock,
+        0,
+        "CLI run params",
+      )[0] as RunCliAgentParams;
+      expect(run.sessionEntry).toBe(admittedSessionEntry);
+      expect(run.sessionEntry?.sessionRoot).toBe("/workspace/project");
+      expect(run.cliSessionId).toBe("new-native-session");
+      expect(run.cliSessionBinding).toMatchObject({
+        sessionId: "new-native-session",
+        forceReuse: true,
+      });
+      const observedCliSessionId = run.cliSessionBinding?.sessionId ?? run.cliSessionId;
+      expect(observedCliSessionId).toBe("new-native-session");
+      if (!observedCliSessionId) {
+        throw new Error("expected admitted CLI session binding");
+      }
+      expect(
+        buildCliMcpGrantContext({
+          run,
+          config: run.config ?? {},
+          requireExplicitMessageTarget: false,
+          agentId: "main",
+          modelProvider: "anthropic",
+          modelId: "claude-sonnet-4-6",
+        }).execSession,
+      ).toMatchObject({
+        permissionMode: "read-only",
+        execHost: "node",
+        execNode: "node-a",
+      });
+
+      const nodeInvoke = vi.fn<typeof executeDeps.invokeNodeClaudeCliRun>(async (request) => {
+        expect(request.nodeId).toBe("node-a");
+        expect(request.argv).toContain("new-native-session");
+        expect(request.argv).not.toContain("old-native-session");
+        return {
+          ok: true,
+          payloadJSON: JSON.stringify({ exitCode: 0, stderrTail: "", truncated: false }),
+        };
+      });
+      const restoreNodeInvoke = executeDeps.invokeNodeClaudeCliRun;
+      const backend = {
+        command: "claude",
+        args: ["-p"],
+        resumeArgs: ["--resume", "{sessionId}"],
+        output: "text" as const,
+        input: "stdin" as const,
+        serialize: true,
+      };
+      const prepared = buildPreparedCliRunContext({
+        provider: "claude-cli",
+        model: run.model,
+        runId: run.runId,
+        workspaceDir: run.workspaceDir,
+        config: run.config,
+        sessionEntry: run.sessionEntry,
+        backend,
+      });
+      prepared.params = {
+        ...run,
+        admittedRunContext: prepared.params.admittedRunContext,
+        skillsSnapshot: undefined,
+      };
+      prepared.cwd = run.cwd;
+      prepared.reusableCliSession = { mode: "reuse", sessionId: observedCliSessionId };
+      executeDeps.invokeNodeClaudeCliRun = nodeInvoke;
+      try {
+        await withTestRunAdmission(prepared.params, async (admittedRunContext) => {
+          prepared.params.admittedRunContext = admittedRunContext;
+          await executePreparedCliRun(prepared, observedCliSessionId);
+        });
+      } finally {
+        executeDeps.invokeNodeClaudeCliRun = restoreNodeInvoke;
+      }
+      expect(nodeInvoke).toHaveBeenCalledOnce();
+    } finally {
+      restoreAdmission();
+    }
+  });
+});

src/auto-reply/reply/agent-runner-execution-cli-auth.test.ts

@@ -0,0 +1,172 @@
+import path from "node:path";
+import { describe, expect, it, onTestFinished } from "vitest";
+import { saveAuthProfileStore } from "../../agents/auth-profiles/store-runtime.js";
+import type { AuthProfileCredential } from "../../agents/auth-profiles/types.js";
+import { testing as cliBackendsTesting } from "../../agents/cli-backends.test-support.js";
+import { closeOpenClawAgentDatabaseByPath } from "../../state/openclaw-agent-db.js";
+import {
+  createFollowupRun,
+  createMinimalRunAgentTurnParams,
+  expectMockCallArgFields,
+  fallbackAttemptOptions,
+  getExecuteAgentTurnForTest,
+  setupAgentRunnerExecutionTestState,
+  type FallbackRunnerParams,
+} from "./agent-runner-execution.test-support.js";
+
+const state = await setupAgentRunnerExecutionTestState();
+const managedProfile = "claude-cli:managed";
+const canonicalProfile = "anthropic:managed";
+const primaryProfile = "openai:primary";
+const googleProfile = "google:managed";
+const nativeProfile = "anthropic:claude-cli";
+const customProfile = "custom-cli:managed";
+const credentials = {
+  [managedProfile]: { type: "token", provider: "claude-cli", token: "synthetic-managed-token" },
+  [canonicalProfile]: { type: "token", provider: "anthropic", token: "synthetic-canonical-token" },
+  [primaryProfile]: { type: "api_key", provider: "openai", key: "synthetic-primary-key" },
+  [googleProfile]: { type: "api_key", provider: "google", key: "synthetic-google-key" },
+  [nativeProfile]: { type: "token", provider: "claude-cli", token: "synthetic-native-token" },
+  [customProfile]: { type: "token", provider: "custom-cli", token: "synthetic-custom-token" },
+} satisfies Record<string, AuthProfileCredential>;
+
+describe("executeAgentTurn: CLI credential selection", () => {
+  it.each([
+    {
+      name: "selects ordered CLI credentials after an automatic cross-provider fallback",
+      selected: primaryProfile,
+      source: "auto",
+      primary: "openai",
+      provider: "claude-cli",
+      backend: "claude-cli",
+      profiles: [primaryProfile, managedProfile],
+      expected: managedProfile,
+    },
+    {
+      name: "rejects an incompatible explicit account before CLI execution",
+      selected: primaryProfile,
+      source: "user",
+      primary: "openai",
+      provider: "claude-cli",
+      backend: "claude-cli",
+      profiles: [primaryProfile, managedProfile],
+      error: 'cannot use auth profile "openai:primary"',
+    },
+    {
+      name: "forwards explicitly selected canonical credentials",
+      selected: canonicalProfile,
+      source: "user",
+      primary: "anthropic",
+      provider: "claude-cli",
+      backend: "claude-cli",
+      profiles: [canonicalProfile, managedProfile],
+      expected: canonicalProfile,
+    },
+    {
+      name: "preserves a selected native login even when a managed account exists",
+      selected: nativeProfile,
+      source: "user",
+      primary: "claude-cli",
+      provider: "claude-cli",
+      backend: "claude-cli",
+      profiles: [nativeProfile, managedProfile],
+      expected: undefined,
+    },
+    {
+      name: "uses the executing Google candidate for canonical API-key fallback",
+      selected: primaryProfile,
+      source: "auto",
+      primary: "openai",
+      provider: "google",
+      backend: "google-gemini-cli",
+      profiles: [primaryProfile, googleProfile],
+      expected: googleProfile,
+    },
+    {
+      name: "retains existing scoped forwarding for a custom CLI backend",
+      selected: customProfile,
+      source: "user",
+      primary: "custom-cli",
+      provider: "custom-cli",
+      backend: "custom-cli",
+      profiles: [customProfile],
+      expected: customProfile,
+    },
+  ] as const)("$name", async (testCase) => {
+    const followupRun = createFollowupRun();
+    onTestFinished(() => {
+      closeOpenClawAgentDatabaseByPath(
+        path.join(followupRun.run.agentDir, "openclaw-agent.sqlite"),
+      );
+    });
+    const model = "test-model";
+    followupRun.run.provider = testCase.primary;
+    followupRun.run.model = model;
+    followupRun.run.authProfileId = testCase.selected;
+    followupRun.run.authProfileIdSource = testCase.source;
+    followupRun.run.thinkingCatalog = [{ provider: testCase.provider, id: model, input: ["text"] }];
+    const profiles = Object.fromEntries(testCase.profiles.map((id) => [id, credentials[id]]));
+    followupRun.run.config = {
+      auth: {
+        order: Object.fromEntries(testCase.profiles.map((id) => [credentials[id].provider, [id]])),
+      },
+      agents: {
+        defaults: {
+          models: { [`${testCase.provider}/${model}`]: { agentRuntime: { id: testCase.backend } } },
+        },
+      },
+    };
+    saveAuthProfileStore({ version: 1, profiles }, followupRun.run.agentDir, {
+      filterExternalAuthProfiles: false,
+      syncExternalCli: false,
+    });
+    cliBackendsTesting.setDepsForTest({
+      resolveRuntimeCliBackends: () => [
+        {
+          id: "claude-cli",
+          modelProvider: "anthropic",
+          pluginId: "anthropic",
+          config: { command: "claude" },
+        },
+        {
+          id: "google-gemini-cli",
+          modelProvider: "google",
+          pluginId: "google",
+          config: { command: "gemini" },
+        },
+        {
+          id: "custom-cli",
+          modelProvider: "custom-cli",
+          pluginId: "custom",
+          config: { command: "custom" },
+        },
+      ],
+      resolvePluginSetupCliBackend: () => undefined,
+    });
+    state.isCliProviderMock.mockImplementation((provider) => provider === testCase.backend);
+    state.runWithModelFallbackMock.mockImplementationOnce(async (params: FallbackRunnerParams) => ({
+      result: await params.run(
+        testCase.provider,
+        model,
+        fallbackAttemptOptions(params, "rate_limit"),
+      ),
+      provider: testCase.provider,
+      model,
+      attempts: [],
+    }));
+    state.runCliAgentMock.mockResolvedValueOnce({ payloads: [{ text: "done" }], meta: {} });
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const result = executeAgentTurn(createMinimalRunAgentTurnParams({ followupRun }));
+    if ("error" in testCase) {
+      expect(await result).toMatchObject({ kind: "final", payload: { isError: true } });
+      expect(state.runCliAgentMock).not.toHaveBeenCalled();
+      return;
+    }
+    expect((await result).kind).toBe("success");
+    expect(state.runCliAgentMock).toHaveBeenCalledOnce();
+    expectMockCallArgFields(state.runCliAgentMock, 0, "CLI credential handoff", {
+      provider: testCase.backend,
+      authProfileId: testCase.expected,
+    });
+  });
+});

src/auto-reply/reply/agent-runner-execution-cli-commentary.test.ts

@@ -0,0 +1,304 @@
+import { describe, expect, it, vi } from "vitest";
+import { testing as cliBackendsTesting } from "../../agents/cli-backends.test-support.js";
+import type { RunCliAgentParams } from "../../agents/cli-runner/types.js";
+import type { TemplateContext } from "../templating.js";
+import type { GetReplyOptions } from "../types.js";
+import {
+  createFollowupRun,
+  initialFallbackAttemptOptions,
+  createMockTypingSignaler,
+  getExecuteAgentTurnForTest,
+  loadActualRunCliAgentForTest,
+  setupAgentRunnerExecutionTestState,
+} from "./agent-runner-execution.test-support.js";
+import type { FallbackRunnerParams } from "./agent-runner-execution.test-support.js";
+
+const state = await setupAgentRunnerExecutionTestState();
+
+const scriptedCliProgram = String.raw`
+let input = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => { input += chunk; });
+process.stdin.on("end", () => {
+  if (!input.trim()) process.exit(2);
+  const events = [
+    { type: "init", session_id: "scripted-commentary" },
+    {
+      type: "stream_event",
+      event: {
+        type: "content_block_delta",
+        delta: { type: "text_delta", text: "The subprocess findings are durable." },
+      },
+    },
+    {
+      type: "stream_event",
+      event: {
+        type: "content_block_start",
+        index: 1,
+        content_block: { type: "tool_use", id: "tool-scripted", name: "Read", input: {} },
+      },
+    },
+    {
+      type: "stream_event",
+      event: {
+        type: "content_block_delta",
+        delta: { type: "text_delta", text: "Subprocess final answer." },
+      },
+    },
+    { type: "stream_event", event: { type: "message_stop" } },
+    { type: "result", session_id: "scripted-commentary", result: "Subprocess final answer." },
+  ];
+  process.stdout.write(events.map((event) => JSON.stringify(event)).join("\n") + "\n");
+});
+`;
+
+function useClaudeCliFallback() {
+  state.isCliProviderMock.mockReturnValue(true);
+  state.runWithModelFallbackMock.mockImplementationOnce(async (params: FallbackRunnerParams) => ({
+    result: await params.run(
+      "claude-cli",
+      "claude-opus-4-6",
+      initialFallbackAttemptOptions(params),
+    ),
+    provider: "claude-cli",
+    model: "claude-opus-4-6",
+    attempts: [],
+  }));
+}
+
+function useScriptedClaudeCliBackend() {
+  const backend = {
+    id: "claude-cli",
+    modelProvider: "anthropic",
+    pluginId: "anthropic",
+    bundleMcp: false,
+    contextEngineHostCapabilities: ["thread-bootstrap-projection"] as const,
+    config: {
+      command: process.execPath,
+      args: ["-e", scriptedCliProgram],
+      input: "stdin" as const,
+      output: "jsonl" as const,
+      jsonlDialect: "claude-stream-json" as const,
+      sessionMode: "none" as const,
+      systemPromptWhen: "never" as const,
+    },
+  };
+  cliBackendsTesting.setDepsForTest({
+    resolvePluginSetupCliBackend: ({ backend: id }) =>
+      id === backend.id ? { pluginId: backend.pluginId, backend } : undefined,
+    resolveRuntimeCliBackends: () => [backend],
+  });
+  state.runCliAgentMock.mockImplementationOnce(async (params: RunCliAgentParams) => {
+    return await (
+      await loadActualRunCliAgentForTest()
+    )(params);
+  });
+}
+
+function createClaudeCliFollowupRun() {
+  const followupRun = createFollowupRun();
+  followupRun.run.agentId = "agent";
+  followupRun.run.provider = "claude-cli";
+  followupRun.run.model = "claude-opus-4-6";
+  followupRun.run.skillsSnapshot = { prompt: "", skills: [], version: 0 };
+  followupRun.run.timeoutMs = 10_000;
+  return followupRun;
+}
+
+function createTurnParams(opts: GetReplyOptions, blockStreamingEnabled: boolean) {
+  return {
+    commandBody: "hi",
+    followupRun: createClaudeCliFollowupRun(),
+    sessionCtx: { Provider: "telegram", MessageSid: "msg" } as unknown as TemplateContext,
+    opts,
+    typingSignals: createMockTypingSignaler(),
+    blockReplyPipeline: null,
+    blockStreamingEnabled,
+    resolvedBlockStreamingBreak: "message_end" as const,
+    applyReplyToMode: <T>(payload: T) => payload,
+    shouldEmitToolResult: () => true,
+    shouldEmitToolOutput: () => false,
+    pendingToolTasks: new Set<Promise<void>>(),
+    resetSessionAfterRoleOrderingConflict: async () => false,
+    isHeartbeat: false,
+    sessionKey: "main",
+    getActiveSessionEntry: () => undefined,
+    resolvedVerboseLevel: "off" as const,
+  };
+}
+
+describe("executeAgentTurn: CLI durable commentary", () => {
+  it("delivers commentary from a real JSONL CLI subprocess", async () => {
+    useClaudeCliFallback();
+    useScriptedClaudeCliBackend();
+    state.createBlockReplyDeliveryHandlerMock.mockImplementationOnce(
+      (params: { onBlockReply: NonNullable<GetReplyOptions["onBlockReply"]> }) =>
+        params.onBlockReply,
+    );
+    const onBlockReply = vi.fn<NonNullable<GetReplyOptions["onBlockReply"]>>(async () => undefined);
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const result = await executeAgentTurn(createTurnParams({ onBlockReply }, true));
+
+    expect(state.runCliAgentMock.mock.calls[0]?.[0]).toMatchObject({ emitCommentaryText: true });
+    const resolveContextEngineHost = state.runEmbeddedAgentEntryMock.mock.calls[0]?.[0]?.harness
+      ?.resolveContextEngineHost as
+      | ((
+          provider: string,
+          model: string,
+        ) => {
+          id: string;
+          label: string;
+          capabilities: readonly string[];
+        })
+      | undefined;
+    expect(resolveContextEngineHost?.("claude-cli", "claude-opus-4-6")).toEqual({
+      id: "cli:claude-cli",
+      label: 'CLI backend "claude-cli"',
+      capabilities: ["thread-bootstrap-projection"],
+    });
+    expect(result.kind).toBe("success");
+    if (result.kind === "success") {
+      expect(result.runResult.payloads).toEqual([{ text: "Subprocess final answer." }]);
+    }
+    expect(onBlockReply).toHaveBeenCalledExactlyOnceWith({
+      text: "The subprocess findings are durable.",
+    });
+  });
+
+  it("delivers completed CLI commentary through block streaming", async () => {
+    useClaudeCliFallback();
+    state.createBlockReplyDeliveryHandlerMock.mockImplementationOnce(
+      (params: { onBlockReply: NonNullable<GetReplyOptions["onBlockReply"]> }) =>
+        params.onBlockReply,
+    );
+    state.runCliAgentMock.mockImplementationOnce(
+      async (params: { runId: string; emitCommentaryText?: boolean }) => {
+        expect(params.emitCommentaryText).toBe(true);
+        const agentEvents = await import("../../infra/agent-events.js");
+        agentEvents.emitAgentEvent({
+          runId: params.runId,
+          stream: "item",
+          data: {
+            kind: "preamble",
+            itemId: "commentary-durable-1",
+            progressText: "The durable findings live here.",
+          },
+        });
+        return { payloads: [{ text: "Short final wrap-up." }], meta: {} };
+      },
+    );
+
+    const onBlockReply = vi.fn<NonNullable<GetReplyOptions["onBlockReply"]>>(async () => undefined);
+    const onItemEvent = vi.fn<NonNullable<GetReplyOptions["onItemEvent"]>>(async () => undefined);
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const result = await executeAgentTurn(
+      createTurnParams(
+        {
+          onBlockReply,
+          onItemEvent,
+          commentaryProgressEnabled: false,
+          progressPreambleEnabled: true,
+        },
+        true,
+      ),
+    );
+
+    await vi.waitFor(() => {
+      expect(onBlockReply).toHaveBeenCalledExactlyOnceWith({
+        text: "The durable findings live here.",
+      });
+      expect(onItemEvent).toHaveBeenCalledExactlyOnceWith({
+        itemId: "commentary-durable-1",
+        kind: "preamble",
+        progressText: "The durable findings live here.",
+        suppressDurableProgress: true,
+      });
+    });
+    expect(result.kind).toBe("success");
+    if (result.kind === "success") {
+      expect(result.runResult.payloads).toEqual([{ text: "Short final wrap-up." }]);
+    }
+  });
+
+  it("forwards channel presentation callbacks to native CLI input", async () => {
+    useClaudeCliFallback();
+    state.createBlockReplyDeliveryHandlerMock.mockImplementationOnce(
+      (params: { onBlockReply: NonNullable<GetReplyOptions["onBlockReply"]> }) =>
+        params.onBlockReply,
+    );
+    state.runCliAgentMock.mockImplementationOnce(async (params: RunCliAgentParams) => {
+      await params.onBlockReply?.({
+        text: "Which color?",
+        presentation: {
+          blocks: [
+            {
+              type: "buttons",
+              buttons: [
+                {
+                  label: "Blue",
+                  action: { type: "question", questionId: "question-1", optionValue: "Blue" },
+                },
+              ],
+            },
+          ],
+        },
+      });
+      await params.onPartialReply?.({ text: "Fallback question" });
+      return { payloads: [{ text: "Answered." }], meta: {} };
+    });
+
+    const onBlockReply = vi.fn<NonNullable<GetReplyOptions["onBlockReply"]>>(async () => undefined);
+    const onPartialReply = vi.fn<NonNullable<GetReplyOptions["onPartialReply"]>>(
+      async () => undefined,
+    );
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+
+    await executeAgentTurn(createTurnParams({ onBlockReply, onPartialReply }, false));
+
+    expect(onBlockReply).toHaveBeenCalledWith(
+      expect.objectContaining({ text: "Which color?", presentation: expect.any(Object) }),
+    );
+    expect(onPartialReply).toHaveBeenCalledWith({ text: "Fallback question" });
+  });
+
+  it("delivers commentary payloads without block streaming", async () => {
+    useClaudeCliFallback();
+    state.createBlockReplyDeliveryHandlerMock.mockImplementationOnce(
+      (params: { onBlockReply: NonNullable<GetReplyOptions["onBlockReply"]> }) =>
+        params.onBlockReply,
+    );
+    state.runCliAgentMock.mockImplementationOnce(
+      async (params: { runId: string; emitCommentaryText?: boolean }) => {
+        expect(params.emitCommentaryText).toBe(true);
+        const agentEvents = await import("../../infra/agent-events.js");
+        agentEvents.emitAgentEvent({
+          runId: params.runId,
+          stream: "item",
+          data: {
+            kind: "preamble",
+            itemId: "commentary-payload-1",
+            progressText: "A durable commentary update.",
+          },
+        });
+        return { payloads: [{ text: "Final answer." }], meta: {} };
+      },
+    );
+
+    const onBlockReply = vi.fn<NonNullable<GetReplyOptions["onBlockReply"]>>(async () => undefined);
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const result = await executeAgentTurn(
+      createTurnParams({ onBlockReply, commentaryPayloadsEnabled: true }, false),
+    );
+
+    await vi.waitFor(() => {
+      expect(onBlockReply).toHaveBeenCalledExactlyOnceWith({
+        text: "A durable commentary update.",
+        isCommentary: true,
+      });
+    });
+    expect(result.kind).toBe("success");
+    if (result.kind === "success") {
+      expect(result.runResult.payloads).toEqual([{ text: "Final answer." }]);
+    }
+  });
+});

src/auto-reply/reply/agent-runner-execution-cli-delegation.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest";
+import { buildCliMcpGrantContext } from "../../agents/cli-runner/mcp-grant-context.js";
+import type { RunCliAgentParams } from "../../agents/cli-runner/types.js";
+import {
+  createFollowupRun,
+  createMinimalRunAgentTurnParams,
+  fallbackAttemptOptions,
+  getExecuteAgentTurnForTest,
+  initialFallbackAttemptOptions,
+  requireMockCall,
+  setupAgentRunnerExecutionTestState,
+} from "./agent-runner-execution.test-support.js";
+import type { FallbackRunnerParams } from "./agent-runner-execution.test-support.js";
+
+const state = await setupAgentRunnerExecutionTestState();
+
+function resolveMockedCliGrantCapability() {
+  const run = requireMockCall(state.runCliAgentMock, 0, "CLI run params")[0] as RunCliAgentParams;
+  return buildCliMcpGrantContext({
+    run,
+    config: run.config ?? {},
+    requireExplicitMessageTarget: false,
+    agentId: "main",
+    modelProvider: "openai",
+    modelId: "gpt-5.4",
+  }).delegationCapability;
+}
+
+describe("executeAgentTurn: CLI delegation grants", () => {
+  it("keeps primary CLI completion grants unrestricted", async () => {
+    state.isCliProviderMock.mockReturnValue(true);
+    state.runWithModelFallbackMock.mockImplementationOnce(async (params: FallbackRunnerParams) => ({
+      result: await params.run("codex-cli", "gpt-5.4", initialFallbackAttemptOptions(params)),
+      provider: "codex-cli",
+      model: "gpt-5.4",
+      attempts: [],
+    }));
+    state.runCliAgentMock.mockResolvedValue({ payloads: [{ text: "done" }], meta: {} });
+    const followupRun = createFollowupRun();
+    followupRun.run.provider = "codex-cli";
+    followupRun.run.model = "gpt-5.4";
+    followupRun.run.inputProvenance = {
+      kind: "inter_session",
+      sourceTool: "subagent_announce",
+    };
+
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const result = await executeAgentTurn(createMinimalRunAgentTurnParams({ followupRun }));
+
+    expect(result.kind).toBe("success");
+    expect(resolveMockedCliGrantCapability()).toBeUndefined();
+  });
+
+  it("restricts fallback CLI completion grants", async () => {
+    state.isCliProviderMock.mockImplementation((provider) => provider === "codex-cli");
+    state.runWithModelFallbackMock.mockImplementationOnce(async (params: FallbackRunnerParams) => {
+      await params.run("anthropic", "claude", initialFallbackAttemptOptions(params));
+      return {
+        result: await params.run("codex-cli", "gpt-5.4", fallbackAttemptOptions(params, "unknown")),
+        provider: "codex-cli",
+        model: "gpt-5.4",
+        attempts: [{ provider: "anthropic", model: "claude", error: "rate limit" }],
+      };
+    });
+    state.runEmbeddedAgentMock.mockResolvedValue({ payloads: [], meta: {} });
+    state.runCliAgentMock.mockResolvedValue({ payloads: [{ text: "done" }], meta: {} });
+    const followupRun = createFollowupRun();
+    followupRun.run.inputProvenance = {
+      kind: "inter_session",
+      sourceTool: "subagent_announce",
+    };
+
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const result = await executeAgentTurn(createMinimalRunAgentTurnParams({ followupRun }));
+
+    expect(result.kind).toBe("success");
+    expect(resolveMockedCliGrantCapability()).toBe("report_only");
+  });
+});

src/auto-reply/reply/agent-runner-execution-cli-progress.test.ts

@@ -0,0 +1,897 @@
+import { describe, expect, it, onTestFinished, vi } from "vitest";
+import { createDeferred } from "../../../test/helpers/promise.js";
+import { createCliJsonlStreamingParser } from "../../agents/cli-output-stream.js";
+import type { TemplateContext } from "../templating.js";
+import type { GetReplyOptions } from "../types.js";
+import {
+  createAgentTurnExecutionDefaults,
+  setupAgentRunnerExecutionTestState,
+  getExecuteAgentTurnForTest,
+  createMockTypingSignaler,
+  createFollowupRun,
+  initialFallbackAttemptOptions,
+  runInitialFallbackAttempt,
+  createMinimalRunAgentTurnParams,
+} from "./agent-runner-execution.test-support.js";
+import type {
+  FallbackRunnerParams,
+  EmbeddedAgentParams,
+} from "./agent-runner-execution.test-support.js";
+
+const state = await setupAgentRunnerExecutionTestState();
+
+describe("executeAgentTurn: CLI progress bridging", () => {
+  it("bridges CLI assistant agent events into onPartialReply for live preview (#76869)", async () => {
+    state.isCliProviderMock.mockReturnValue(true);
+    state.runWithModelFallbackMock.mockImplementationOnce(async (params: FallbackRunnerParams) => ({
+      result: await runInitialFallbackAttempt(params, "claude-cli", "claude-opus-4-6"),
+      provider: "claude-cli",
+      model: "claude-opus-4-6",
+      attempts: [],
+    }));
+    state.runCliAgentMock.mockImplementationOnce(
+      async (params: { runId: string; emitCommentaryText?: boolean }) => {
+        expect(params.emitCommentaryText).toBe(false);
+        const realAgentEvents = await vi.importActual<typeof import("../../infra/agent-events.js")>(
+          "../../infra/agent-events.js",
+        );
+        realAgentEvents.emitAgentEvent({
+          runId: params.runId,
+          stream: "assistant",
+          data: { text: "Hello", delta: "Hello" },
+        });
+        realAgentEvents.emitAgentEvent({
+          runId: params.runId,
+          stream: "assistant",
+          data: { text: "Hello world", delta: " world" },
+        });
+        return { payloads: [{ text: "Hello world" }], meta: {} };
+      },
+    );
+
+    const onPartialReply = vi.fn<NonNullable<GetReplyOptions["onPartialReply"]>>(
+      async (_payload) => undefined,
+    );
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const followupRun = createFollowupRun();
+    followupRun.run.provider = "claude-cli";
+    followupRun.run.model = "claude-opus-4-6";
+
+    await executeAgentTurn({
+      commandBody: "hi",
+      followupRun,
+      sessionCtx: {
+        Provider: "telegram",
+        MessageSid: "msg",
+      } as unknown as TemplateContext,
+      opts: { onPartialReply },
+      typingSignals: createMockTypingSignaler(),
+      ...createAgentTurnExecutionDefaults(),
+    });
+
+    const partialTexts = onPartialReply.mock.calls.map((call) => call[0].text);
+    expect(partialTexts).toEqual(["Hello", "Hello world"]);
+  });
+
+  it("serializes and drains bridged CLI assistant previews before completing (#76869)", async () => {
+    state.isCliProviderMock.mockReturnValue(true);
+    state.runWithModelFallbackMock.mockImplementationOnce(async (params: FallbackRunnerParams) => ({
+      result: await runInitialFallbackAttempt(params, "claude-cli", "claude-opus-4-6"),
+      provider: "claude-cli",
+      model: "claude-opus-4-6",
+      attempts: [],
+    }));
+    state.runCliAgentMock.mockImplementationOnce(
+      async (params: { runId: string; emitCommentaryText?: boolean }) => {
+        expect(params.emitCommentaryText).toBe(false);
+        const realAgentEvents = await vi.importActual<typeof import("../../infra/agent-events.js")>(
+          "../../infra/agent-events.js",
+        );
+        realAgentEvents.emitAgentEvent({
+          runId: params.runId,
+          stream: "assistant",
+          data: { text: "Hello", delta: "Hello" },
+        });
+        realAgentEvents.emitAgentEvent({
+          runId: params.runId,
+          stream: "assistant",
+          data: { text: "Hello world", delta: " world" },
+        });
+        return { payloads: [{ text: "Hello world" }], meta: {} };
+      },
+    );
+
+    let firstPreviewStarted: (() => void) | undefined;
+    let releaseFirstPreview: (() => void) | undefined;
+    const firstPreviewPromise = new Promise<void>((resolve) => {
+      firstPreviewStarted = resolve;
+    });
+    const previewOrder: string[] = [];
+    const onPartialReply = vi.fn<NonNullable<GetReplyOptions["onPartialReply"]>>(
+      async (payload) => {
+        previewOrder.push(payload.text ?? "");
+        if (payload.text === "Hello") {
+          firstPreviewStarted?.();
+          await new Promise<void>((resolve) => {
+            releaseFirstPreview = resolve;
+          });
+          previewOrder.push("Hello released");
+        }
+      },
+    );
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const followupRun = createFollowupRun();
+    followupRun.run.provider = "claude-cli";
+    followupRun.run.model = "claude-opus-4-6";
+
+    const runPromise = executeAgentTurn({
+      commandBody: "hi",
+      followupRun,
+      sessionCtx: {
+        Provider: "telegram",
+        MessageSid: "msg",
+      } as unknown as TemplateContext,
+      opts: { onPartialReply },
+      typingSignals: createMockTypingSignaler(),
+      ...createAgentTurnExecutionDefaults(),
+    });
+
+    await firstPreviewPromise;
+    await new Promise((resolve) => {
+      setImmediate(resolve);
+    });
+    expect(previewOrder).toEqual(["Hello"]);
+
+    releaseFirstPreview?.();
+    await runPromise;
+
+    expect(previewOrder).toEqual(["Hello", "Hello released", "Hello world"]);
+  });
+
+  it("bridges CLI tool agent events into onToolStart for live preview", async () => {
+    state.isCliProviderMock.mockReturnValue(true);
+    state.runWithModelFallbackMock.mockImplementationOnce(async (params: FallbackRunnerParams) => ({
+      result: await runInitialFallbackAttempt(params, "claude-cli", "claude-opus-4-6"),
+      provider: "claude-cli",
+      model: "claude-opus-4-6",
+      attempts: [],
+    }));
+    state.runCliAgentMock.mockImplementationOnce(
+      async (params: { runId: string; emitCommentaryText?: boolean }) => {
+        expect(params.emitCommentaryText).toBe(false);
+        const realAgentEvents = await vi.importActual<typeof import("../../infra/agent-events.js")>(
+          "../../infra/agent-events.js",
+        );
+        realAgentEvents.emitAgentEvent({
+          runId: params.runId,
+          stream: "tool",
+          data: {
+            phase: "start",
+            name: "Bash",
+            toolCallId: "toolu_01ABCD",
+            args: { command: "ls -la" },
+          },
+        });
+        realAgentEvents.emitAgentEvent({
+          runId: params.runId,
+          stream: "tool",
+          data: {
+            phase: "result",
+            name: "Bash",
+            toolCallId: "toolu_01ABCD",
+            isError: false,
+          },
+        });
+        return { payloads: [{ text: "done" }], meta: {} };
+      },
+    );
+
+    const onToolStart = vi.fn<NonNullable<GetReplyOptions["onToolStart"]>>(async () => undefined);
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const followupRun = createFollowupRun();
+    followupRun.run.provider = "claude-cli";
+    followupRun.run.model = "claude-opus-4-6";
+
+    await executeAgentTurn({
+      commandBody: "hi",
+      followupRun,
+      sessionCtx: { Provider: "telegram", MessageSid: "msg" } as unknown as TemplateContext,
+      opts: { onToolStart },
+      typingSignals: createMockTypingSignaler(),
+      ...createAgentTurnExecutionDefaults(),
+    });
+    await new Promise((resolve) => {
+      setImmediate(resolve);
+    });
+
+    expect(onToolStart).toHaveBeenCalledTimes(1);
+    const call = onToolStart.mock.calls[0]?.[0];
+    expect(call?.name).toBe("Bash");
+    expect(call?.phase).toBe("start");
+    expect(call?.args).toEqual({ command: "ls -la" });
+  });
+
+  it("starts CLI assistant progress before a later tool while typing is slow", async () => {
+    state.isCliProviderMock.mockReturnValue(true);
+    state.runWithModelFallbackMock.mockImplementationOnce(async (params: FallbackRunnerParams) => ({
+      result: await runInitialFallbackAttempt(params, "claude-cli", "claude-opus-4-6"),
+      provider: "claude-cli",
+      model: "claude-opus-4-6",
+      attempts: [],
+    }));
+    state.runCliAgentMock.mockImplementationOnce(async (params: { runId: string }) => {
+      const agentEvents = await import("../../infra/agent-events.js");
+      agentEvents.emitAgentEvent({
+        runId: params.runId,
+        stream: "assistant",
+        data: { text: "answer before tool", delta: "answer before tool" },
+      });
+      agentEvents.emitAgentEvent({
+        runId: params.runId,
+        stream: "assistant",
+        data: { text: "answer before tool 2", delta: " 2" },
+      });
+      agentEvents.emitAgentEvent({
+        runId: params.runId,
+        stream: "tool",
+        data: {
+          phase: "start",
+          name: "Bash",
+          toolCallId: "toolu_order",
+          args: { command: "echo hi" },
+        },
+      });
+      return { payloads: [{ text: "final" }], meta: {} };
+    });
+
+    let releaseTyping: (() => void) | undefined;
+    const typingPending = new Promise<void>((resolve) => {
+      releaseTyping = resolve;
+    });
+    const typingSignals = createMockTypingSignaler();
+    vi.mocked(typingSignals.signalTextDelta).mockReturnValue(typingPending);
+    const callbackOrder: string[] = [];
+    const toolStarted = createDeferred();
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const followupRun = createFollowupRun();
+    followupRun.run.provider = "claude-cli";
+    followupRun.run.model = "claude-opus-4-6";
+    const runPromise = executeAgentTurn({
+      commandBody: "hi",
+      followupRun,
+      sessionCtx: { Provider: "telegram", MessageSid: "msg" } as unknown as TemplateContext,
+      opts: {
+        preserveProgressCallbackStartOrder: true,
+        onPartialReply: (payload) => {
+          callbackOrder.push(`partial:${payload.text}`);
+        },
+        onToolStart: () => {
+          callbackOrder.push("tool");
+          toolStarted.resolve();
+        },
+      },
+      typingSignals,
+      ...createAgentTurnExecutionDefaults(),
+    });
+    onTestFinished(async () => {
+      releaseTyping?.();
+      await runPromise;
+    });
+
+    try {
+      await Promise.race([toolStarted.promise, runPromise]);
+      expect(callbackOrder).toEqual([
+        "partial:answer before tool",
+        "partial:answer before tool 2",
+        "tool",
+      ]);
+    } finally {
+      releaseTyping?.();
+      await runPromise;
+    }
+  });
+
+  it("starts CLI tool progress before later assistant text while typing is slow", async () => {
+    state.isCliProviderMock.mockReturnValue(true);
+    state.runWithModelFallbackMock.mockImplementationOnce(async (params: FallbackRunnerParams) => ({
+      result: await runInitialFallbackAttempt(params, "claude-cli", "claude-opus-4-6"),
+      provider: "claude-cli",
+      model: "claude-opus-4-6",
+      attempts: [],
+    }));
+    state.runCliAgentMock.mockImplementationOnce(async (params: { runId: string }) => {
+      const agentEvents = await import("../../infra/agent-events.js");
+      agentEvents.emitAgentEvent({
+        runId: params.runId,
+        stream: "tool",
+        data: {
+          phase: "start",
+          name: "Bash",
+          toolCallId: "toolu_inverse_order",
+          args: { command: "echo hi" },
+        },
+      });
+      agentEvents.emitAgentEvent({
+        runId: params.runId,
+        stream: "tool",
+        data: {
+          phase: "update",
+          name: "Bash",
+          toolCallId: "toolu_inverse_order",
+          args: { command: "echo hi" },
+        },
+      });
+      agentEvents.emitAgentEvent({
+        runId: params.runId,
+        stream: "assistant",
+        data: { text: "answer after tool", delta: "answer after tool" },
+      });
+      return { payloads: [{ text: "final" }], meta: {} };
+    });
+
+    let releaseTyping: (() => void) | undefined;
+    const typingPending = new Promise<void>((resolve) => {
+      releaseTyping = resolve;
+    });
+    const typingSignals = createMockTypingSignaler();
+    vi.mocked(typingSignals.signalToolStart).mockReturnValue(typingPending);
+    const callbackOrder: string[] = [];
+    const partialReplyStarted = createDeferred();
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const followupRun = createFollowupRun();
+    followupRun.run.provider = "claude-cli";
+    followupRun.run.model = "claude-opus-4-6";
+    const runPromise = executeAgentTurn({
+      commandBody: "hi",
+      followupRun,
+      sessionCtx: { Provider: "telegram", MessageSid: "msg" } as unknown as TemplateContext,
+      opts: {
+        preserveProgressCallbackStartOrder: true,
+        onPartialReply: (payload) => {
+          callbackOrder.push(`partial:${payload.text}`);
+          partialReplyStarted.resolve();
+        },
+        onToolStart: (payload) => {
+          callbackOrder.push(`tool:${payload.phase}`);
+        },
+      },
+      typingSignals,
+      ...createAgentTurnExecutionDefaults(),
+    });
+    onTestFinished(async () => {
+      releaseTyping?.();
+      await runPromise;
+    });
+
+    try {
+      await Promise.race([partialReplyStarted.promise, runPromise]);
+      expect(callbackOrder).toEqual(["tool:start", "tool:update", "partial:answer after tool"]);
+    } finally {
+      releaseTyping?.();
+      await runPromise;
+    }
+  });
+
+  it("bridges CLI preambles for progress headlines when commentary is disabled", async () => {
+    state.isCliProviderMock.mockReturnValue(true);
+    state.runWithModelFallbackMock.mockImplementationOnce(async (params: FallbackRunnerParams) => ({
+      result: await runInitialFallbackAttempt(params, "claude-cli", "claude-opus-4-6"),
+      provider: "claude-cli",
+      model: "claude-opus-4-6",
+      attempts: [],
+    }));
+    state.runCliAgentMock.mockImplementationOnce(
+      async (params: { runId: string; emitCommentaryText?: boolean }) => {
+        expect(params.emitCommentaryText).toBe(true);
+        const agentEvents = await import("../../infra/agent-events.js");
+        // Inter-tool commentary surfaces as a stream:"item", kind:"preamble" agent event.
+        agentEvents.emitAgentEvent({
+          runId: params.runId,
+          stream: "item",
+          data: {
+            kind: "preamble",
+            itemId: "commentary-1",
+            progressText: "Let me check the files.",
+          },
+        });
+        return { payloads: [{ text: "done" }], meta: {} };
+      },
+    );
+
+    const onItemEvent = vi.fn<NonNullable<GetReplyOptions["onItemEvent"]>>(async () => undefined);
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const followupRun = createFollowupRun();
+    followupRun.run.provider = "claude-cli";
+    followupRun.run.model = "claude-opus-4-6";
+
+    await executeAgentTurn({
+      commandBody: "hi",
+      followupRun,
+      sessionCtx: { Provider: "telegram", MessageSid: "msg" } as unknown as TemplateContext,
+      opts: {
+        onItemEvent,
+        commentaryProgressEnabled: false,
+        progressPreambleEnabled: true,
+      },
+      typingSignals: createMockTypingSignaler(),
+      ...createAgentTurnExecutionDefaults(),
+    });
+    await new Promise((resolve) => {
+      setImmediate(resolve);
+    });
+
+    expect(onItemEvent).toHaveBeenCalledTimes(1);
+    const call = onItemEvent.mock.calls[0]?.[0];
+    expect(call?.kind).toBe("preamble");
+    expect(call?.progressText).toBe("Let me check the files.");
+    expect(call?.itemId).toBe("commentary-1");
+  });
+
+  it("does not emit CLI preambles when both progress lanes are disabled", async () => {
+    state.isCliProviderMock.mockReturnValue(true);
+    state.runWithModelFallbackMock.mockImplementationOnce(async (params: FallbackRunnerParams) => ({
+      result: await runInitialFallbackAttempt(params, "claude-cli", "claude-opus-4-6"),
+      provider: "claude-cli",
+      model: "claude-opus-4-6",
+      attempts: [],
+    }));
+    state.runCliAgentMock.mockImplementationOnce(
+      async (params: { runId: string; emitCommentaryText?: boolean }) => {
+        // With no commentary lane or headline consumer, pre-tool text stays in
+        // the assistant stream instead of being split into progress events.
+        expect(params.emitCommentaryText).toBe(false);
+        return { payloads: [{ text: "done" }], meta: {} };
+      },
+    );
+
+    const onItemEvent = vi.fn<NonNullable<GetReplyOptions["onItemEvent"]>>();
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const followupRun = createFollowupRun();
+    followupRun.run.provider = "claude-cli";
+    followupRun.run.model = "claude-opus-4-6";
+
+    await executeAgentTurn({
+      commandBody: "hi",
+      followupRun,
+      sessionCtx: { Provider: "telegram", MessageSid: "msg" } as unknown as TemplateContext,
+      opts: {
+        onItemEvent,
+        commentaryProgressEnabled: false,
+        progressPreambleEnabled: false,
+      },
+      typingSignals: createMockTypingSignaler(),
+      ...createAgentTurnExecutionDefaults(),
+    });
+
+    expect(state.runCliAgentMock).toHaveBeenCalledTimes(1);
+    expect(onItemEvent).not.toHaveBeenCalled();
+  });
+
+  it("does not bridge CLI tool deltas when silentExpected is set", async () => {
+    state.isCliProviderMock.mockReturnValue(true);
+    state.runWithModelFallbackMock.mockImplementationOnce(async (params: FallbackRunnerParams) => ({
+      result: await runInitialFallbackAttempt(params, "claude-cli", "claude-opus-4-6"),
+      provider: "claude-cli",
+      model: "claude-opus-4-6",
+      attempts: [],
+    }));
+    state.runCliAgentMock.mockImplementationOnce(async (params: { runId: string }) => {
+      const realAgentEvents = await vi.importActual<typeof import("../../infra/agent-events.js")>(
+        "../../infra/agent-events.js",
+      );
+      realAgentEvents.emitAgentEvent({
+        runId: params.runId,
+        stream: "tool",
+        data: {
+          phase: "start",
+          name: "Bash",
+          toolCallId: "toolu_silent",
+          args: { command: "echo silent" },
+        },
+      });
+      return { payloads: [{ text: "final" }], meta: {} };
+    });
+
+    const onToolStart = vi.fn<NonNullable<GetReplyOptions["onToolStart"]>>(async () => undefined);
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const followupRun = createFollowupRun();
+    followupRun.run.provider = "claude-cli";
+    followupRun.run.model = "claude-opus-4-6";
+    followupRun.run.silentExpected = true;
+
+    await executeAgentTurn({
+      commandBody: "hi",
+      followupRun,
+      sessionCtx: { Provider: "telegram", MessageSid: "msg" } as unknown as TemplateContext,
+      opts: { onToolStart },
+      typingSignals: createMockTypingSignaler(),
+      ...createAgentTurnExecutionDefaults(),
+    });
+    await new Promise((resolve) => {
+      setImmediate(resolve);
+    });
+
+    expect(onToolStart).not.toHaveBeenCalled();
+  });
+
+  it("does not bridge CLI assistant deltas when silentExpected is set (#76869)", async () => {
+    state.isCliProviderMock.mockReturnValue(true);
+    state.runWithModelFallbackMock.mockImplementationOnce(async (params: FallbackRunnerParams) => ({
+      result: await runInitialFallbackAttempt(params, "claude-cli", "claude-opus-4-6"),
+      provider: "claude-cli",
+      model: "claude-opus-4-6",
+      attempts: [],
+    }));
+    state.runCliAgentMock.mockImplementationOnce(async (params: { runId: string }) => {
+      const realAgentEvents = await vi.importActual<typeof import("../../infra/agent-events.js")>(
+        "../../infra/agent-events.js",
+      );
+      realAgentEvents.emitAgentEvent({
+        runId: params.runId,
+        stream: "assistant",
+        data: { text: "secret heartbeat output", delta: "secret heartbeat output" },
+      });
+      realAgentEvents.emitAgentEvent({
+        runId: params.runId,
+        stream: "assistant",
+        data: { text: "NO_REPLY do not preview", delta: " do not preview" },
+      });
+      return { payloads: [{ text: "final" }], meta: {} };
+    });
+
+    const onPartialReply = vi.fn<NonNullable<GetReplyOptions["onPartialReply"]>>(
+      async (_payload) => undefined,
+    );
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const followupRun = createFollowupRun();
+    followupRun.run.provider = "claude-cli";
+    followupRun.run.model = "claude-opus-4-6";
+    followupRun.run.silentExpected = true;
+
+    await executeAgentTurn({
+      commandBody: "hi",
+      followupRun,
+      sessionCtx: { Provider: "telegram", MessageSid: "msg" } as unknown as TemplateContext,
+      opts: { onPartialReply },
+      typingSignals: createMockTypingSignaler(),
+      ...createAgentTurnExecutionDefaults(),
+    });
+    await new Promise((resolve) => {
+      setImmediate(resolve);
+    });
+
+    expect(onPartialReply).not.toHaveBeenCalled();
+  });
+
+  it("bridges CLI thinking agent events into onReasoningStream with the reasoning opt-in gate", async () => {
+    state.isCliProviderMock.mockReturnValue(true);
+    state.runWithModelFallbackMock.mockImplementationOnce(async (params: FallbackRunnerParams) => ({
+      result: await params.run(
+        "claude-cli",
+        "claude-opus-4-7",
+        initialFallbackAttemptOptions(params),
+      ),
+      provider: "claude-cli",
+      model: "claude-opus-4-7",
+      attempts: [],
+    }));
+    state.runCliAgentMock.mockImplementationOnce(async (params: { runId: string }) => {
+      const realAgentEvents = await vi.importActual<typeof import("../../infra/agent-events.js")>(
+        "../../infra/agent-events.js",
+      );
+      realAgentEvents.emitAgentEvent({
+        runId: params.runId,
+        stream: "thinking",
+        data: { text: "Thinking", delta: "Thinking", isReasoningSnapshot: true },
+      });
+      realAgentEvents.emitAgentEvent({
+        runId: params.runId,
+        stream: "thinking",
+        data: { text: "Thinking", delta: "", isReasoningSnapshot: true },
+      });
+      realAgentEvents.emitAgentEvent({
+        runId: params.runId,
+        stream: "thinking",
+        data: { text: "Thinking about it", delta: " about it", isReasoningSnapshot: true },
+      });
+      return { payloads: [{ text: "Thinking about it" }], meta: {} };
+    });
+
+    const onReasoningStream = vi.fn<NonNullable<GetReplyOptions["onReasoningStream"]>>(
+      async (_payload) => undefined,
+    );
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const followupRun = createFollowupRun();
+    followupRun.run.provider = "claude-cli";
+    followupRun.run.model = "claude-opus-4-7";
+
+    await executeAgentTurn({
+      commandBody: "hi",
+      followupRun,
+      sessionCtx: {
+        Provider: "telegram",
+        MessageSid: "msg",
+      } as unknown as TemplateContext,
+      opts: { onReasoningStream },
+      typingSignals: createMockTypingSignaler(),
+      ...createAgentTurnExecutionDefaults(),
+    });
+
+    expect(onReasoningStream.mock.calls.map((call) => call[0])).toEqual([
+      {
+        text: "Thinking",
+        isReasoningSnapshot: true,
+        requiresReasoningProgressOptIn: true,
+      },
+      {
+        text: "Thinking about it",
+        isReasoningSnapshot: true,
+        requiresReasoningProgressOptIn: true,
+      },
+    ]);
+  });
+
+  it("bridges tagged Claude CLI reasoning separately from its visible answer", async () => {
+    state.isCliProviderMock.mockReturnValue(true);
+    state.runWithModelFallbackMock.mockImplementationOnce(async (params: FallbackRunnerParams) => ({
+      result: await params.run(
+        "claude-cli",
+        "claude-opus-4-7",
+        initialFallbackAttemptOptions(params),
+      ),
+      provider: "claude-cli",
+      model: "claude-opus-4-7",
+      attempts: [],
+    }));
+    state.runCliAgentMock.mockImplementationOnce(async (params: { runId: string }) => {
+      const realAgentEvents = await vi.importActual<typeof import("../../infra/agent-events.js")>(
+        "../../infra/agent-events.js",
+      );
+      const parser = createCliJsonlStreamingParser({
+        backend: {
+          command: "local-cli",
+          output: "jsonl",
+          jsonlDialect: "claude-stream-json",
+        },
+        providerId: "claude-cli",
+        onAssistantDelta: (delta) =>
+          realAgentEvents.emitAgentEvent({
+            runId: params.runId,
+            stream: "assistant",
+            data: delta,
+          }),
+        onThinkingDelta: (delta) =>
+          realAgentEvents.emitAgentEvent({
+            runId: params.runId,
+            stream: "thinking",
+            data: delta,
+          }),
+      });
+      parser.push(
+        [
+          JSON.stringify({
+            type: "stream_event",
+            event: {
+              type: "content_block_delta",
+              delta: {
+                type: "text_delta",
+                text: "<thinking>Private analysis.</thinking>Visible answer.",
+              },
+            },
+          }),
+          JSON.stringify({
+            type: "result",
+            result: "<thinking>Private analysis.</thinking>Visible answer.",
+          }),
+          "",
+        ].join("\n"),
+      );
+      parser.finish();
+      return { payloads: [{ text: parser.getOutput()?.text ?? "" }], meta: {} };
+    });
+
+    const onPartialReply = vi.fn<NonNullable<GetReplyOptions["onPartialReply"]>>(
+      async () => undefined,
+    );
+    const onReasoningStream = vi.fn<NonNullable<GetReplyOptions["onReasoningStream"]>>(
+      async () => undefined,
+    );
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const followupRun = createFollowupRun();
+    followupRun.run.provider = "claude-cli";
+    followupRun.run.model = "claude-opus-4-7";
+
+    await executeAgentTurn({
+      commandBody: "hi",
+      followupRun,
+      sessionCtx: { Provider: "telegram", MessageSid: "msg" } as unknown as TemplateContext,
+      opts: { onPartialReply, onReasoningStream },
+      typingSignals: createMockTypingSignaler(),
+      ...createAgentTurnExecutionDefaults(),
+    });
+
+    expect(onReasoningStream.mock.calls.map(([payload]) => payload.text)).toEqual([
+      "Private analysis.",
+    ]);
+    expect(onPartialReply.mock.calls.map(([payload]) => payload.text)).toEqual(["Visible answer."]);
+  });
+
+  it("does not bridge CLI thinking events to onReasoningStream when silentExpected is set", async () => {
+    state.isCliProviderMock.mockReturnValue(true);
+    state.runWithModelFallbackMock.mockImplementationOnce(async (params: FallbackRunnerParams) => ({
+      result: await params.run(
+        "claude-cli",
+        "claude-opus-4-7",
+        initialFallbackAttemptOptions(params),
+      ),
+      provider: "claude-cli",
+      model: "claude-opus-4-7",
+      attempts: [],
+    }));
+    state.runCliAgentMock.mockImplementationOnce(async (params: { runId: string }) => {
+      const realAgentEvents = await vi.importActual<typeof import("../../infra/agent-events.js")>(
+        "../../infra/agent-events.js",
+      );
+      realAgentEvents.emitAgentEvent({
+        runId: params.runId,
+        stream: "thinking",
+        data: { text: "heartbeat scratch text", delta: "heartbeat scratch text" },
+      });
+      realAgentEvents.emitAgentEvent({
+        runId: params.runId,
+        stream: "thinking",
+        data: { text: "NO_REPLY do not preview reasoning", delta: " do not preview reasoning" },
+      });
+      return { payloads: [{ text: "final" }], meta: {} };
+    });
+
+    const onReasoningStream = vi.fn<NonNullable<GetReplyOptions["onReasoningStream"]>>(
+      async (_payload) => undefined,
+    );
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const followupRun = createFollowupRun();
+    followupRun.run.provider = "claude-cli";
+    followupRun.run.model = "claude-opus-4-7";
+    followupRun.run.silentExpected = true;
+
+    await executeAgentTurn({
+      commandBody: "hi",
+      followupRun,
+      sessionCtx: { Provider: "telegram", MessageSid: "msg" } as unknown as TemplateContext,
+      opts: { onReasoningStream },
+      typingSignals: createMockTypingSignaler(),
+      ...createAgentTurnExecutionDefaults(),
+    });
+    await new Promise((resolve) => {
+      setImmediate(resolve);
+    });
+
+    expect(onReasoningStream).not.toHaveBeenCalled();
+  });
+
+  it("does not bridge non-Claude CLI assistant events to onReasoningStream", async () => {
+    state.isCliProviderMock.mockReturnValue(true);
+    state.runWithModelFallbackMock.mockImplementationOnce(async (params: FallbackRunnerParams) => ({
+      result: await params.run("codex-cli", "gpt-5.5", initialFallbackAttemptOptions(params)),
+      provider: "codex-cli",
+      model: "gpt-5.5",
+      attempts: [],
+    }));
+    state.runCliAgentMock.mockImplementationOnce(async (params: { runId: string }) => {
+      const realAgentEvents = await vi.importActual<typeof import("../../infra/agent-events.js")>(
+        "../../infra/agent-events.js",
+      );
+      realAgentEvents.emitAgentEvent({
+        runId: params.runId,
+        stream: "assistant",
+        data: { text: "final answer", delta: "final answer" },
+      });
+      return { payloads: [{ text: "final answer" }], meta: {} };
+    });
+
+    const onReasoningStream = vi.fn<NonNullable<GetReplyOptions["onReasoningStream"]>>(
+      async (_payload) => undefined,
+    );
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const followupRun = createFollowupRun();
+    followupRun.run.provider = "codex-cli";
+    followupRun.run.model = "gpt-5.5";
+
+    await executeAgentTurn({
+      commandBody: "hi",
+      followupRun,
+      sessionCtx: { Provider: "telegram", MessageSid: "msg" } as unknown as TemplateContext,
+      opts: { onReasoningStream },
+      typingSignals: createMockTypingSignaler(),
+      ...createAgentTurnExecutionDefaults(),
+    });
+    await new Promise((resolve) => {
+      setImmediate(resolve);
+    });
+
+    expect(onReasoningStream).not.toHaveBeenCalled();
+  });
+
+  it("does not double-fire onReasoningStream from the bridge when the API/native runtime path is active", async () => {
+    state.isCliProviderMock.mockReturnValue(false);
+    state.runWithModelFallbackMock.mockImplementationOnce(async (params: FallbackRunnerParams) => ({
+      result: await params.run(
+        "anthropic",
+        "claude-sonnet-4-7",
+        initialFallbackAttemptOptions(params),
+      ),
+      provider: "anthropic",
+      model: "claude-sonnet-4-7",
+      attempts: [],
+    }));
+    state.runEmbeddedAgentMock.mockImplementationOnce(async (params: EmbeddedAgentParams) => {
+      const realAgentEvents = await vi.importActual<typeof import("../../infra/agent-events.js")>(
+        "../../infra/agent-events.js",
+      );
+      realAgentEvents.emitAgentEvent({
+        runId: "api-run",
+        stream: "assistant",
+        data: { text: "assistant text from API run", delta: "assistant text from API run" },
+      });
+      await params.onAgentEvent?.({
+        stream: "assistant",
+        data: { text: "assistant text from API run", delta: "assistant text from API run" },
+      });
+      return { payloads: [{ text: "final" }], meta: {} };
+    });
+
+    const onReasoningStream = vi.fn<NonNullable<GetReplyOptions["onReasoningStream"]>>(
+      async (_payload) => undefined,
+    );
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const followupRun = createFollowupRun();
+    followupRun.run.provider = "anthropic";
+    followupRun.run.model = "claude-sonnet-4-7";
+
+    await executeAgentTurn({
+      commandBody: "hi",
+      followupRun,
+      sessionCtx: { Provider: "telegram", MessageSid: "msg" } as unknown as TemplateContext,
+      opts: { onReasoningStream, runId: "api-run" },
+      typingSignals: createMockTypingSignaler(),
+      ...createAgentTurnExecutionDefaults(),
+    });
+    await new Promise((resolve) => {
+      setImmediate(resolve);
+    });
+
+    expect(onReasoningStream).not.toHaveBeenCalled();
+  });
+
+  it("preserves embedded reasoning stream opt-in markers", async () => {
+    state.runEmbeddedAgentMock.mockImplementationOnce(async (params: EmbeddedAgentParams) => {
+      await params.onReasoningStream?.({ text: "stream thought" });
+      await params.onReasoningStream?.({
+        text: "ambient thought",
+        requiresReasoningProgressOptIn: true,
+      });
+      return { payloads: [{ text: "final" }], meta: {} };
+    });
+
+    const onReasoningStream = vi.fn<NonNullable<GetReplyOptions["onReasoningStream"]>>(
+      async (_payload) => undefined,
+    );
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+
+    await executeAgentTurn(
+      createMinimalRunAgentTurnParams({
+        opts: { onReasoningStream },
+      }),
+    );
+
+    expect(
+      onReasoningStream.mock.calls.map(([payload]) => ({
+        text: payload.text,
+        requiresReasoningProgressOptIn: payload.requiresReasoningProgressOptIn,
+      })),
+    ).toEqual([
+      { text: "stream thought", requiresReasoningProgressOptIn: undefined },
+      { text: "ambient thought", requiresReasoningProgressOptIn: true },
+    ]);
+  });
+});

src/auto-reply/reply/agent-runner-execution-cli-sessions.test.ts

@@ -0,0 +1,947 @@
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { prepareCliPromptImagePayload } from "../../agents/cli-runner/helpers.js";
+import type { RunCliAgentParams } from "../../agents/cli-runner/types.js";
+import { detectAndLoadPromptImages } from "../../agents/embedded-agent-runner/run/images.js";
+import { FailoverError } from "../../agents/failover-error.js";
+import { installSessionPlacementAdmissionProvider } from "../../agents/session-placement-admission.js";
+import type { SessionEntry } from "../../config/sessions.js";
+import { replaceSessionEntry } from "../../config/sessions/session-accessor.js";
+import { registerGeneratedMediaTaskActivity } from "../../tasks/generated-media-task-activity.js";
+import { resetGeneratedMediaTaskActivityForTests } from "../../tasks/task-runtime.test-helpers.js";
+import type { TemplateContext } from "../templating.js";
+import { SILENT_REPLY_TOKEN } from "../tokens.js";
+import {
+  setupAgentRunnerExecutionTestState,
+  getExecuteAgentTurnForTest,
+  createFollowupRun,
+  createTestUserTurnRecorder,
+  requireRecord,
+  requireMockCall,
+  expectMockCallArgFields,
+  initialFallbackAttemptOptions,
+  createMinimalRunAgentTurnParams,
+  createRunAgentTurnParams,
+  makeTestSessionStorePath,
+} from "./agent-runner-execution.test-support.js";
+import type { FallbackRunnerParams } from "./agent-runner-execution.test-support.js";
+
+const state = await setupAgentRunnerExecutionTestState();
+afterEach(resetGeneratedMediaTaskActivityForTests);
+
+function rejectUnexpectedCompactionSuccessor(): never {
+  throw new Error("Unexpected compaction successor during CLI session routing test");
+}
+
+describe("executeAgentTurn: CLI session routing", () => {
+  it("carries prepared model and thread context facts into CLI execution", async () => {
+    state.isCliProviderMock.mockReturnValue(true);
+    state.runWithModelFallbackMock.mockImplementationOnce(async (params: FallbackRunnerParams) => ({
+      result: await params.run(
+        "claude-cli",
+        "claude-sonnet-4-6",
+        initialFallbackAttemptOptions(params),
+      ),
+      provider: "claude-cli",
+      model: "claude-sonnet-4-6",
+      attempts: [],
+    }));
+    state.runCliAgentMock.mockResolvedValueOnce({
+      payloads: [{ text: "done" }],
+      meta: {},
+    });
+    const followupRun = createFollowupRun();
+    followupRun.originatingThreadId = 42;
+    followupRun.run.provider = "claude-cli";
+    followupRun.run.model = "claude-sonnet-4-6";
+    followupRun.run.thinkingCatalog = [
+      {
+        provider: "claude-cli",
+        id: "claude-sonnet-4-6",
+        contextWindow: 400_000,
+        contextTokens: 321_000,
+        input: ["text", "image"],
+      },
+    ];
+
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const result = await executeAgentTurn(
+      createMinimalRunAgentTurnParams({
+        followupRun,
+        sessionCtx: {
+          Provider: "telegram",
+          MessageSid: "msg",
+          MessageThreadId: "stale-topic",
+        } as unknown as TemplateContext,
+      }),
+    );
+
+    expect(result.kind).toBe("success");
+    expectMockCallArgFields(state.runCliAgentMock, 0, "CLI run params", {
+      modelContextWindow: 400_000,
+      modelContextTokens: 321_000,
+      currentThreadTs: "42",
+    });
+  });
+
+  it("preserves queued image fields from runs created before the prepared marker", async () => {
+    state.isCliProviderMock.mockReturnValue(true);
+    state.runWithModelFallbackMock.mockImplementationOnce(async (params: FallbackRunnerParams) => ({
+      result: await params.run(
+        "claude-cli",
+        "claude-opus-5",
+        initialFallbackAttemptOptions(params),
+      ),
+      provider: "claude-cli",
+      model: "claude-opus-5",
+      attempts: [],
+    }));
+    state.runCliAgentMock.mockResolvedValueOnce({
+      payloads: [{ text: "described" }],
+      meta: {},
+    });
+    const images = [
+      {
+        type: "image" as const,
+        data: "iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAYAAABytg0kAAAAFElEQVR4nGP4z8Dwn4GBgYGJAQoAHxcCAr7cGDwAAAAASUVORK5CYII=",
+        mimeType: "image/png",
+      },
+    ];
+    const imageOrder = ["inline" as const];
+    const followupRun = createFollowupRun();
+    followupRun.run.provider = "claude-cli";
+    followupRun.run.model = "claude-opus-5";
+    followupRun.images = images;
+    followupRun.imageOrder = imageOrder;
+
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const result = await executeAgentTurn(
+      createMinimalRunAgentTurnParams({
+        followupRun,
+        sessionCtx: {
+          Provider: "telegram",
+          MessageSid: "msg",
+        } as unknown as TemplateContext,
+      }),
+    );
+
+    expect(result.kind).toBe("success");
+    expectMockCallArgFields(state.runCliAgentMock, 0, "CLI run params", {
+      images,
+      imageOrder,
+    });
+  });
+
+  it("keeps prepared current-turn images aligned with CLI media facts", async () => {
+    state.isCliProviderMock.mockReturnValue(true);
+    state.runWithModelFallbackMock.mockImplementationOnce(async (params: FallbackRunnerParams) => ({
+      result: await params.run(
+        "claude-cli",
+        "claude-opus-5",
+        initialFallbackAttemptOptions(params),
+      ),
+      provider: "claude-cli",
+      model: "claude-opus-5",
+      attempts: [],
+    }));
+    const images = [
+      {
+        type: "image" as const,
+        data: "iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAYAAABytg0kAAAAFElEQVR4nGP4z8Dwn4GBgYGJAQoAHxcCAr7cGDwAAAAASUVORK5CYII=",
+        mimeType: "image/png",
+      },
+    ];
+    const imageOrder = ["inline" as const];
+    const media = [{ path: "/openclaw-test-missing/current.png", contentType: "image/png" }];
+    const mediaImageLayout = {
+      slots: [{ kind: "inline" as const, factIndex: 0 }],
+      suppressedFactIndexes: [],
+    };
+    state.runCliAgentMock.mockImplementationOnce(async (params: RunCliAgentParams) => {
+      expect(params.modelHasVision).toBe(true);
+      const internalParams = params as RunCliAgentParams & {
+        mediaImageLayout?: typeof mediaImageLayout;
+      };
+      await expect(
+        prepareCliPromptImagePayload({
+          backend: { command: "claude" },
+          prompt: params.prompt,
+          imagePrompt: params.prompt,
+          workspaceDir: params.workspaceDir,
+          images: [...images, ...images],
+          imageOrder: [...imageOrder, ...imageOrder],
+          media,
+        }),
+      ).rejects.toThrow("failed to hydrate 1 structured image attachment");
+
+      const reconciled = await detectAndLoadPromptImages({
+        prompt: params.prompt,
+        media: params.media,
+        workspaceDir: params.workspaceDir,
+        model: { input: ["text", "image"] },
+        existingImages: params.images,
+        imageOrder: params.imageOrder,
+        mediaImageLayout: internalParams.mediaImageLayout,
+      });
+      expect(reconciled).toMatchObject({
+        failedMediaCount: 0,
+        images,
+      });
+      return {
+        payloads: [{ text: "described" }],
+        meta: {},
+      };
+    });
+    const followupRun = createFollowupRun();
+    followupRun.run.provider = "claude-cli";
+    followupRun.run.model = "claude-opus-5";
+    followupRun.run.thinkingCatalog = [
+      {
+        provider: "claude-cli",
+        id: "claude-opus-5",
+        input: ["text", "image"],
+      },
+    ];
+    const preparedFollowupRun = followupRun as typeof followupRun & {
+      currentTurnImagesPrepared?: true;
+      mediaImageLayout?: typeof mediaImageLayout;
+    };
+    preparedFollowupRun.currentTurnImagesPrepared = true;
+    preparedFollowupRun.mediaImageLayout = mediaImageLayout;
+    followupRun.images = images;
+    followupRun.imageOrder = imageOrder;
+    followupRun.media = media;
+
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const result = await executeAgentTurn(
+      createMinimalRunAgentTurnParams({
+        followupRun,
+        sessionCtx: {
+          Provider: "telegram",
+          MessageSid: "msg",
+          media,
+        } as unknown as TemplateContext,
+      }),
+    );
+
+    expect(result.kind).toBe("success");
+    expectMockCallArgFields(state.runCliAgentMock, 0, "CLI run params", {
+      images,
+      imageOrder,
+      mediaImageLayout,
+      media,
+    });
+  });
+
+  it("forwards the static extra system prompt to CLI backends", async () => {
+    state.isCliProviderMock.mockReturnValue(true);
+    state.runWithModelFallbackMock.mockImplementationOnce(async (params: FallbackRunnerParams) => ({
+      result: await params.run("codex-cli", "gpt-5.4", initialFallbackAttemptOptions(params)),
+      provider: "codex-cli",
+      model: "gpt-5.4",
+      attempts: [],
+    }));
+    state.runCliAgentMock.mockResolvedValueOnce({
+      payloads: [{ text: "final" }],
+      meta: {},
+    });
+
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const followupRun = createFollowupRun();
+    followupRun.run.agentId = "main";
+    followupRun.run.provider = "codex-cli";
+    followupRun.run.model = "gpt-5.4";
+    followupRun.run.extraSystemPrompt = "dynamic inbound metadata\n\nstable group prompt";
+    followupRun.run.extraSystemPromptStatic = "stable group prompt";
+    followupRun.run.senderId = "sender-static";
+    followupRun.run.senderName = "Sender Static";
+    followupRun.run.senderUsername = "sender-static-user";
+    followupRun.run.senderE164 = "+15550002222";
+    followupRun.run.execOverrides = { host: "node", node: "mac-a" };
+    followupRun.run.bashElevated = {
+      enabled: true,
+      allowed: true,
+      defaultLevel: "full",
+    };
+    followupRun.run.groupId = "group-static";
+    followupRun.run.groupChannel = "ops";
+    followupRun.run.groupSpace = "workspace-static";
+    followupRun.run.spawnedBy = "agent:main:telegram:group:parent";
+    followupRun.run.runtimePolicySessionKey = "agent:main:telegram:default:direct:sender-static";
+    followupRun.originatingChannel = "telegram";
+
+    const result = await executeAgentTurn(createRunAgentTurnParams(followupRun));
+
+    expect(result.kind).toBe("success");
+    expectMockCallArgFields(state.runCliAgentMock, 0, "CLI run params", {
+      modelProvider: "codex-cli",
+      extraSystemPrompt: "dynamic inbound metadata\n\nstable group prompt",
+      extraSystemPromptStatic: "stable group prompt",
+      trigger: "user",
+      messageChannel: "telegram",
+      messageProvider: "telegram",
+      senderId: "sender-static",
+      senderName: "Sender Static",
+      senderUsername: "sender-static-user",
+      senderE164: "+15550002222",
+      execOverrides: { host: "node", node: "mac-a" },
+      bashElevated: { enabled: true, allowed: true, defaultLevel: "full" },
+      groupId: "group-static",
+      groupChannel: "ops",
+      groupSpace: "workspace-static",
+      spawnedBy: "agent:main:telegram:group:parent",
+      runtimePolicySessionKey: "agent:main:telegram:default:direct:sender-static",
+    });
+  });
+
+  it("passes silent empty-reply policy to CLI backends for message-tool-only turns", async () => {
+    state.isCliProviderMock.mockReturnValue(true);
+    state.runWithModelFallbackMock.mockImplementationOnce(async (params: FallbackRunnerParams) => ({
+      result: await params.run(
+        "claude-cli",
+        "claude-sonnet-4-6",
+        initialFallbackAttemptOptions(params),
+      ),
+      provider: "claude-cli",
+      model: "claude-sonnet-4-6",
+      attempts: [],
+    }));
+    state.runCliAgentMock.mockResolvedValueOnce({
+      payloads: [{ text: SILENT_REPLY_TOKEN }],
+      meta: { executionTrace: { fallbackUsed: false } },
+    });
+
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const followupRun = createFollowupRun();
+    followupRun.run.provider = "claude-cli";
+    followupRun.run.model = "claude-sonnet-4-6";
+    followupRun.run.sourceReplyDeliveryMode = "message_tool_only";
+    followupRun.run.allowEmptyAssistantReplyAsSilent = true;
+    followupRun.originatingChannel = "telegram";
+
+    const result = await executeAgentTurn(
+      createMinimalRunAgentTurnParams({
+        followupRun,
+        sessionCtx: {
+          Provider: "telegram",
+          MessageSid: "msg",
+          ChatType: "group",
+        } as unknown as TemplateContext,
+      }),
+    );
+
+    expect(result.kind).toBe("success");
+    expectMockCallArgFields(state.runCliAgentMock, 0, "CLI run params", {
+      provider: "claude-cli",
+      model: "claude-sonnet-4-6",
+      sourceReplyDeliveryMode: "message_tool_only",
+      allowEmptyAssistantReplyAsSilent: true,
+      messageChannel: "telegram",
+      messageProvider: "telegram",
+    });
+  });
+
+  it("passes prepared CLI user turns to the runtime persistence boundary", async () => {
+    state.isCliProviderMock.mockReturnValue(true);
+    state.runWithModelFallbackMock.mockImplementationOnce(async (params: FallbackRunnerParams) => ({
+      result: await params.run("codex-cli", "gpt-5.4", initialFallbackAttemptOptions(params)),
+      provider: "codex-cli",
+      model: "gpt-5.4",
+      attempts: [],
+    }));
+    state.runCliAgentMock.mockResolvedValueOnce({
+      payloads: [{ text: "final" }],
+      meta: {},
+    });
+
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const followupRun = createFollowupRun();
+    followupRun.run.provider = "codex-cli";
+    followupRun.run.model = "gpt-5.4";
+    const preparedUserTurnMessage = {
+      role: "user",
+      content: "describe this",
+      MediaPath: "/tmp/image.png",
+      MediaPaths: ["/tmp/image.png"],
+      MediaType: "image/png",
+      MediaTypes: ["image/png"],
+    } as never;
+    followupRun.userTurnTranscriptRecorder = createTestUserTurnRecorder(preparedUserTurnMessage);
+    const storePath = makeTestSessionStorePath();
+    const sessionEntry: SessionEntry = {
+      sessionId: "session",
+      sessionFile: path.join(path.dirname(storePath), "session.jsonl"),
+      updatedAt: 1,
+    };
+    await replaceSessionEntry({ sessionKey: "agent:main:main", storePath }, sessionEntry);
+    const activeSessionStore = { main: sessionEntry };
+
+    await replaceSessionEntry({ sessionKey: "main", storePath }, sessionEntry);
+    const result = await executeAgentTurn({
+      ...createMinimalRunAgentTurnParams({ followupRun }),
+      commandBody: "runtime prompt",
+      transcriptCommandBody: "display prompt",
+      activeSessionStore,
+      storePath,
+      getActiveSessionEntry: () => activeSessionStore.main,
+    });
+
+    expect(result.kind).toBe("success");
+    expect(state.runCliAgentMock).toHaveBeenCalledOnce();
+    expectMockCallArgFields(state.runCliAgentMock, 0, "CLI runtime", {
+      sessionKey: "main",
+      agentId: "main",
+      sessionId: "session",
+      suppressNextUserMessagePersistence: false,
+      persistAssistantTranscript: true,
+      storePath,
+      sessionTarget: {
+        agentId: "main",
+        sessionId: "session",
+        sessionKey: "main",
+        storePath,
+      },
+    });
+    const call = requireMockCall(state.runCliAgentMock, 0, "CLI runtime");
+    const callParams = requireRecord(call[0], "CLI runtime");
+    expect(callParams.userTurnTranscriptRecorder).toEqual(expect.any(Object));
+    expect(requireRecord(callParams.userTurnTranscriptRecorder, "user turn recorder").message).toBe(
+      preparedUserTurnMessage,
+    );
+    expect(callParams.onUserMessagePersisted).toEqual(expect.any(Function));
+  });
+
+  it("reuses CLI sessions for room-event turns", async () => {
+    state.isCliProviderMock.mockReturnValue(true);
+    state.runWithModelFallbackMock.mockImplementationOnce(async (params: FallbackRunnerParams) => ({
+      result: await params.run("codex-cli", "gpt-5.4", initialFallbackAttemptOptions(params)),
+      provider: "codex-cli",
+      model: "gpt-5.4",
+      attempts: [],
+    }));
+    state.runCliAgentMock.mockResolvedValueOnce({
+      payloads: [{ text: "ambient" }],
+      meta: {
+        agentMeta: {
+          sessionId: "existing-cli-session",
+          cliSessionBinding: {
+            sessionId: "existing-cli-session",
+            authProfileId: "profile",
+          },
+        },
+      },
+    });
+
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const followupRun = createFollowupRun();
+    followupRun.currentInboundEventKind = "room_event";
+    followupRun.run.provider = "codex-cli";
+    followupRun.run.model = "gpt-5.4";
+    const sessionEntry = {
+      cliSessionBindings: {
+        "codex-cli": { sessionId: "existing-cli-session" },
+      },
+    } as unknown as SessionEntry;
+    const activeSessionStore = { main: sessionEntry };
+
+    const result = await executeAgentTurn({
+      ...createMinimalRunAgentTurnParams({ followupRun }),
+      activeSessionStore,
+      getActiveSessionEntry: () => sessionEntry,
+    });
+
+    expect(result.kind).toBe("success");
+    expectMockCallArgFields(state.runCliAgentMock, 0, "CLI run params", {
+      currentInboundEventKind: "room_event",
+      persistAssistantTranscript: false,
+      cliSessionId: "existing-cli-session",
+      cliSessionBinding: {
+        sessionId: "existing-cli-session",
+      },
+    });
+    if (result.kind !== "success") {
+      throw new Error("expected success");
+    }
+    expect(result.runResult.meta?.agentMeta?.sessionId).toBe("existing-cli-session");
+    expect(result.runResult.meta?.agentMeta?.cliSessionBinding).toEqual({
+      sessionId: "existing-cli-session",
+      authProfileId: "profile",
+    });
+  });
+
+  it("keeps the first CLI session created by a room-event turn", async () => {
+    state.isCliProviderMock.mockReturnValue(true);
+    state.runWithModelFallbackMock.mockImplementationOnce(async (params: FallbackRunnerParams) => ({
+      result: await params.run("codex-cli", "gpt-5.4", initialFallbackAttemptOptions(params)),
+      provider: "codex-cli",
+      model: "gpt-5.4",
+      attempts: [],
+    }));
+    state.runCliAgentMock.mockResolvedValueOnce({
+      payloads: [{ text: "ambient" }],
+      meta: {
+        agentMeta: {
+          sessionId: "new-cli-session",
+          cliSessionBinding: {
+            sessionId: "new-cli-session",
+            authProfileId: "profile",
+          },
+        },
+      },
+    });
+
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const followupRun = createFollowupRun();
+    followupRun.currentInboundEventKind = "room_event";
+    followupRun.run.provider = "codex-cli";
+    followupRun.run.model = "gpt-5.4";
+    const sessionEntry = {} as unknown as SessionEntry;
+
+    const result = await executeAgentTurn({
+      ...createMinimalRunAgentTurnParams({ followupRun }),
+      getActiveSessionEntry: () => sessionEntry,
+    });
+
+    expect(result.kind).toBe("success");
+    expectMockCallArgFields(state.runCliAgentMock, 0, "CLI run params", {
+      currentInboundEventKind: "room_event",
+      cliSessionId: undefined,
+      cliSessionBinding: undefined,
+    });
+    if (result.kind !== "success") {
+      throw new Error("expected success");
+    }
+    expect(result.runResult.meta?.agentMeta?.sessionId).toBe("new-cli-session");
+    expect(result.runResult.meta?.agentMeta?.cliSessionBinding).toEqual({
+      sessionId: "new-cli-session",
+      authProfileId: "profile",
+    });
+  });
+
+  it("drops replacement room-event CLI sessions when reuse fails", async () => {
+    state.isCliProviderMock.mockReturnValue(true);
+    state.runWithModelFallbackMock.mockImplementationOnce(async (params: FallbackRunnerParams) => ({
+      result: await params.run("codex-cli", "gpt-5.4", initialFallbackAttemptOptions(params)),
+      provider: "codex-cli",
+      model: "gpt-5.4",
+      attempts: [],
+    }));
+    state.runCliAgentMock.mockResolvedValueOnce({
+      payloads: [{ text: "ambient" }],
+      meta: {
+        agentMeta: {
+          sessionId: "transient-cli-session",
+          cliSessionBinding: {
+            sessionId: "transient-cli-session",
+            authProfileId: "profile",
+          },
+          clearCliSessionBinding: true,
+        },
+      },
+    });
+
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const followupRun = createFollowupRun();
+    followupRun.currentInboundEventKind = "room_event";
+    followupRun.run.provider = "codex-cli";
+    followupRun.run.model = "gpt-5.4";
+    const sessionEntry = {
+      cliSessionBindings: {
+        "codex-cli": { sessionId: "existing-cli-session" },
+      },
+    } as unknown as SessionEntry;
+    const activeSessionStore = { main: sessionEntry };
+    let cleanupObservedBeforePlacementRelease = false;
+    const restoreAdmission = installSessionPlacementAdmissionProvider({
+      assertCompactionSuccessorAllowed: rejectUnexpectedCompactionSuccessor,
+      executeLocalTurn: async (_claim, runLocal) => {
+        const resultLocal = await runLocal();
+        expect(activeSessionStore.main.cliSessionBindings?.["codex-cli"]).toBeUndefined();
+        cleanupObservedBeforePlacementRelease = true;
+        return resultLocal;
+      },
+      executeTurn: async (_claim, _params, runLocal) => await runLocal(),
+    });
+
+    let result: Awaited<ReturnType<typeof executeAgentTurn>>;
+    try {
+      result = await executeAgentTurn({
+        ...createMinimalRunAgentTurnParams({ followupRun }),
+        activeSessionStore,
+        getActiveSessionEntry: () => sessionEntry,
+      });
+    } finally {
+      restoreAdmission();
+    }
+
+    expect(result.kind).toBe("success");
+    expect(cleanupObservedBeforePlacementRelease).toBe(true);
+    expectMockCallArgFields(state.runCliAgentMock, 0, "CLI run params", {
+      currentInboundEventKind: "room_event",
+      cliSessionId: "existing-cli-session",
+      cliSessionBinding: {
+        sessionId: "existing-cli-session",
+      },
+    });
+    if (result.kind !== "success") {
+      throw new Error("expected success");
+    }
+    expect(result.runResult.meta?.agentMeta?.sessionId).toBe("");
+    expect(result.runResult.meta?.agentMeta?.cliSessionBinding).toBeUndefined();
+    expect(result.runResult.meta?.agentMeta?.clearCliSessionBinding).toBeUndefined();
+    expect(activeSessionStore.main.cliSessionBindings?.["codex-cli"]).toBeUndefined();
+  });
+
+  it("keeps room-event CLI bindings when synthetic hooks return no CLI binding", async () => {
+    state.isCliProviderMock.mockReturnValue(true);
+    state.runWithModelFallbackMock.mockImplementationOnce(async (params: FallbackRunnerParams) => ({
+      result: await params.run("codex-cli", "gpt-5.4", initialFallbackAttemptOptions(params)),
+      provider: "codex-cli",
+      model: "gpt-5.4",
+      attempts: [],
+    }));
+    state.runCliAgentMock.mockResolvedValueOnce({
+      payloads: [{ text: "handled" }],
+      meta: {
+        agentMeta: {
+          sessionId: "openclaw-session",
+          provider: "codex-cli",
+          model: "gpt-5.4",
+        },
+      },
+    });
+
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const followupRun = createFollowupRun();
+    followupRun.currentInboundEventKind = "room_event";
+    followupRun.run.provider = "codex-cli";
+    followupRun.run.model = "gpt-5.4";
+    const sessionEntry = {
+      cliSessionBindings: {
+        "codex-cli": { sessionId: "existing-cli-session" },
+      },
+    } as unknown as SessionEntry;
+    const activeSessionStore = { main: sessionEntry };
+
+    const result = await executeAgentTurn({
+      ...createMinimalRunAgentTurnParams({ followupRun }),
+      activeSessionStore,
+      getActiveSessionEntry: () => sessionEntry,
+    });
+
+    expect(result.kind).toBe("success");
+    if (result.kind !== "success") {
+      throw new Error("expected success");
+    }
+    expect(result.runResult.meta?.agentMeta?.sessionId).toBe("");
+    expect(result.runResult.meta?.agentMeta?.cliSessionBinding).toBeUndefined();
+    expect(activeSessionStore.main.cliSessionBindings?.["codex-cli"]).toEqual({
+      sessionId: "existing-cli-session",
+    });
+  });
+
+  it("clears room-event CLI bindings when an unflushed replacement is dropped", async () => {
+    state.isCliProviderMock.mockReturnValue(true);
+    state.runWithModelFallbackMock.mockImplementationOnce(async (params: FallbackRunnerParams) => ({
+      result: await params.run("codex-cli", "gpt-5.4", initialFallbackAttemptOptions(params)),
+      provider: "codex-cli",
+      model: "gpt-5.4",
+      attempts: [],
+    }));
+    state.runCliAgentMock.mockResolvedValueOnce({
+      payloads: [{ text: "handled" }],
+      meta: {
+        agentMeta: {
+          sessionId: "",
+          provider: "codex-cli",
+          model: "gpt-5.4",
+          clearCliSessionBinding: true,
+        },
+      },
+    });
+
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+    const followupRun = createFollowupRun();
+    followupRun.currentInboundEventKind = "room_event";
+    followupRun.run.provider = "codex-cli";
+    followupRun.run.model = "gpt-5.4";
+    const sessionEntry = {
+      cliSessionBindings: {
+        "codex-cli": { sessionId: "existing-cli-session" },
+      },
+    } as unknown as SessionEntry;
+    const activeSessionStore = { main: sessionEntry };
+
+    const result = await executeAgentTurn({
+      ...createMinimalRunAgentTurnParams({ followupRun }),
+      activeSessionStore,
+      getActiveSessionEntry: () => sessionEntry,
+    });
+
+    expect(result.kind).toBe("success");
+    if (result.kind !== "success") {
+      throw new Error("expected success");
+    }
+    expect(result.runResult.meta?.agentMeta?.sessionId).toBe("");
+    expect(result.runResult.meta?.agentMeta?.cliSessionBinding).toBeUndefined();
+    expect(result.runResult.meta?.agentMeta?.clearCliSessionBinding).toBeUndefined();
+    expect(activeSessionStore.main.cliSessionBindings?.["codex-cli"]).toBeUndefined();
+  });
+
+  it("clears a fork-marked Claude CLI binding when the channel turn fails", async () => {
+    state.isCliProviderMock.mockReturnValue(true);
+    state.runWithModelFallbackMock.mockImplementationOnce(async (params: FallbackRunnerParams) => ({
+      result: await params.run(
+        "claude-cli",
+        "claude-opus-4-8",
+        initialFallbackAttemptOptions(params),
+      ),
+      provider: "claude-cli",
+      model: "claude-opus-4-8",
+      attempts: [],
+    }));
+    state.runCliAgentMock.mockRejectedValueOnce(
+      new FailoverError("No conversation found", {
+        reason: "session_expired",
+        provider: "claude-cli",
+        model: "claude-opus-4-8",
+      }),
+    );
+
+    const followupRun = createFollowupRun();
+    followupRun.run.provider = "claude-cli";
+    followupRun.run.model = "claude-opus-4-8";
+    const sessionEntry = {
+      sessionId: "openclaw-session",
+      updatedAt: 1,
+      cliSessionBindings: {
+        "claude-cli": { sessionId: "stale-cli-session", forkNextResume: true },
+      },
+      cliSessionIds: { "claude-cli": "stale-cli-session" },
+      claudeCliSessionId: "stale-cli-session",
+    } as SessionEntry;
+    const activeSessionStore = { main: sessionEntry };
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+
+    const result = await executeAgentTurn({
+      ...createMinimalRunAgentTurnParams({ followupRun }),
+      activeSessionStore,
+      getActiveSessionEntry: () => sessionEntry,
+    });
+
+    expect(result.kind).toBe("final");
+    expect(sessionEntry.cliSessionBindings?.["claude-cli"]).toBeUndefined();
+    expect(sessionEntry.cliSessionIds?.["claude-cli"]).toBeUndefined();
+    expect(sessionEntry.claudeCliSessionId).toBeUndefined();
+  });
+
+  it("preserves a reused binding after a channel turn starts detached media", async () => {
+    const sessionKey = "agent:main:cron:media-job:run:run-1";
+    state.isCliProviderMock.mockReturnValue(true);
+    state.runWithModelFallbackMock.mockImplementationOnce(async (params: FallbackRunnerParams) => ({
+      result: await params.run(
+        "claude-cli",
+        "claude-opus-4-8",
+        initialFallbackAttemptOptions(params),
+      ),
+      provider: "claude-cli",
+      model: "claude-opus-4-8",
+      attempts: [],
+    }));
+    const abort = Object.assign(new Error("detached media continues"), { name: "AbortError" });
+    state.runCliAgentMock.mockImplementationOnce(async () => {
+      registerGeneratedMediaTaskActivity("tool:image_generate:run-1", sessionKey);
+      throw abort;
+    });
+
+    const followupRun = createFollowupRun();
+    followupRun.run.provider = "claude-cli";
+    followupRun.run.model = "claude-opus-4-8";
+    const sessionEntry = {
+      sessionId: "openclaw-session",
+      updatedAt: 1,
+      cliSessionBindings: { "claude-cli": { sessionId: "media-session" } },
+      cliSessionIds: { "claude-cli": "media-session" },
+      claudeCliSessionId: "media-session",
+    } as SessionEntry;
+    const activeSessionStore = { [sessionKey]: sessionEntry };
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+
+    await executeAgentTurn({
+      ...createMinimalRunAgentTurnParams({ followupRun }),
+      sessionKey,
+      activeSessionStore,
+      getActiveSessionEntry: () => sessionEntry,
+    });
+
+    expect(sessionEntry.cliSessionBindings?.["claude-cli"]?.sessionId).toBe("media-session");
+    expect(sessionEntry.cliSessionIds?.["claude-cli"]).toBe("media-session");
+    expect(sessionEntry.claudeCliSessionId).toBe("media-session");
+  });
+
+  it("preserves a reused binding after an operator aborts a channel turn", async () => {
+    const sessionKey = "agent:main:direct:aborted-run";
+    state.isCliProviderMock.mockReturnValue(true);
+    state.runWithModelFallbackMock.mockImplementationOnce(async (params: FallbackRunnerParams) => ({
+      result: await params.run(
+        "claude-cli",
+        "claude-opus-4-8",
+        initialFallbackAttemptOptions(params),
+      ),
+      provider: "claude-cli",
+      model: "claude-opus-4-8",
+      attempts: [],
+    }));
+    state.runCliAgentMock.mockRejectedValueOnce(
+      Object.assign(new Error("CLI run aborted"), { name: "AbortError" }),
+    );
+
+    const followupRun = createFollowupRun();
+    followupRun.run.provider = "claude-cli";
+    followupRun.run.model = "claude-opus-4-8";
+    const sessionEntry = {
+      sessionId: "openclaw-session",
+      updatedAt: 1,
+      cliSessionBindings: { "claude-cli": { sessionId: "aborted-session" } },
+      cliSessionIds: { "claude-cli": "aborted-session" },
+      claudeCliSessionId: "aborted-session",
+    } as SessionEntry;
+    const activeSessionStore = { [sessionKey]: sessionEntry };
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+
+    await executeAgentTurn({
+      ...createMinimalRunAgentTurnParams({ followupRun }),
+      sessionKey,
+      activeSessionStore,
+      getActiveSessionEntry: () => sessionEntry,
+    });
+
+    expect(sessionEntry.cliSessionBindings?.["claude-cli"]?.sessionId).toBe("aborted-session");
+    expect(sessionEntry.cliSessionIds?.["claude-cli"]).toBe("aborted-session");
+    expect(sessionEntry.claudeCliSessionId).toBe("aborted-session");
+  });
+
+  it("does not attribute media from an earlier admitted turn to a queued failure", async () => {
+    const sessionKey = "agent:main:cron:media-job:run:run-queued";
+    state.isCliProviderMock.mockReturnValue(true);
+    state.runWithModelFallbackMock.mockImplementationOnce(async (params: FallbackRunnerParams) => ({
+      result: await params.run(
+        "claude-cli",
+        "claude-opus-4-8",
+        initialFallbackAttemptOptions(params),
+      ),
+      provider: "claude-cli",
+      model: "claude-opus-4-8",
+      attempts: [],
+    }));
+    state.runCliAgentMock.mockRejectedValueOnce(
+      new FailoverError("queued session expired", {
+        reason: "session_expired",
+        provider: "claude-cli",
+        model: "claude-opus-4-8",
+      }),
+    );
+
+    let releaseAdmission!: () => void;
+    const admissionGate = new Promise<void>((resolve) => {
+      releaseAdmission = resolve;
+    });
+    let notifyAdmissionWait!: () => void;
+    const admissionWait = new Promise<void>((resolve) => {
+      notifyAdmissionWait = resolve;
+    });
+    const restoreAdmission = installSessionPlacementAdmissionProvider({
+      assertCompactionSuccessorAllowed: rejectUnexpectedCompactionSuccessor,
+      executeLocalTurn: async (_claim, runLocal) => {
+        notifyAdmissionWait();
+        await admissionGate;
+        return await runLocal();
+      },
+      executeTurn: async (_claim, _params, runLocal) => await runLocal(),
+    });
+
+    const followupRun = createFollowupRun();
+    followupRun.run.provider = "claude-cli";
+    followupRun.run.model = "claude-opus-4-8";
+    const sessionEntry = {
+      sessionId: "openclaw-session",
+      updatedAt: 1,
+      cliSessionBindings: { "claude-cli": { sessionId: "queued-stale-session" } },
+      cliSessionIds: { "claude-cli": "queued-stale-session" },
+      claudeCliSessionId: "queued-stale-session",
+    } as SessionEntry;
+    const activeSessionStore = { [sessionKey]: sessionEntry };
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+
+    try {
+      const runPromise = executeAgentTurn({
+        ...createMinimalRunAgentTurnParams({ followupRun }),
+        sessionKey,
+        activeSessionStore,
+        getActiveSessionEntry: () => sessionEntry,
+      });
+      await admissionWait;
+      registerGeneratedMediaTaskActivity("tool:image_generate:earlier-turn", sessionKey);
+      releaseAdmission();
+      const result = await runPromise;
+
+      expect(result.kind).toBe("final");
+      expect(sessionEntry.cliSessionBindings?.["claude-cli"]).toBeUndefined();
+      expect(sessionEntry.cliSessionIds?.["claude-cli"]).toBeUndefined();
+      expect(sessionEntry.claudeCliSessionId).toBeUndefined();
+    } finally {
+      releaseAdmission();
+      restoreAdmission();
+    }
+  });
+
+  it("clears a reused binding after the CLI reports an expired session", async () => {
+    state.isCliProviderMock.mockReturnValue(true);
+    state.runWithModelFallbackMock.mockImplementationOnce(async (params: FallbackRunnerParams) => ({
+      result: await params.run(
+        "claude-cli",
+        "claude-opus-4-8",
+        initialFallbackAttemptOptions(params),
+      ),
+      provider: "claude-cli",
+      model: "claude-opus-4-8",
+      attempts: [],
+    }));
+    state.runCliAgentMock.mockRejectedValueOnce(
+      new FailoverError("No conversation found with session ID stale-cli-session", {
+        reason: "session_expired",
+        provider: "claude-cli",
+        model: "claude-opus-4-8",
+      }),
+    );
+
+    const followupRun = createFollowupRun();
+    followupRun.run.provider = "claude-cli";
+    followupRun.run.model = "claude-opus-4-8";
+    followupRun.run.skillsSnapshot = { prompt: "", skills: [], version: 0 };
+    followupRun.run.timeoutMs = 10_000;
+    const sessionEntry = {
+      sessionId: "openclaw-session",
+      updatedAt: 1,
+      cliSessionBindings: { "claude-cli": { sessionId: "stale-cli-session" } },
+      cliSessionIds: { "claude-cli": "stale-cli-session" },
+      claudeCliSessionId: "stale-cli-session",
+    } as SessionEntry;
+    const activeSessionStore = { main: sessionEntry };
+    const executeAgentTurn = await getExecuteAgentTurnForTest();
+
+    const result = await executeAgentTurn({
+      ...createMinimalRunAgentTurnParams({ followupRun }),
+      activeSessionStore,
+      getActiveSessionEntry: () => sessionEntry,
+    });
+
+    expect(result.kind).toBe("final");
+    expect(state.runCliAgentMock.mock.calls[0]?.[0]).toMatchObject({
+      cliSessionId: "stale-cli-session",
+    });
+    expect(sessionEntry.cliSessionBindings?.["claude-cli"]).toBeUndefined();
+    expect(sessionEntry.cliSessionIds?.["claude-cli"]).toBeUndefined();
+    expect(sessionEntry.claudeCliSessionId).toBeUndefined();
+  }, 15_000);
+});