@linzumi/cli 0.0.1-beta → 0.0.2-beta

package/src/channelSession.ts

@@ -0,0 +1,3248 @@
+/*
+- Date: 2026-04-24
+  Spec: plans/2026-04-24-local-codex-channel-session-module-spec.md
+  Relationship: Owns one channel-bound local Codex session: Kandan thread
+  binding, sender queueing, Codex turn lifecycle, typing heartbeat, queued
+  interrupt handling, and Codex output forwarding.
+
+- Date: 2026-04-24
+  Spec: plans/2026-04-24-local-codex-runner-deep-quality-spec.md
+  Relationship: Keeps channel event dedupe bounded and represents Codex turn
+  lifecycle as an explicit state machine so queued-message interrupts cannot
+  race in-flight turn starts, malformed stored Codex thread ids can rebound,
+  and non-recoverable delivery failures become terminal failed input states.
+
+- Date: 2026-04-25
+  Spec: plans/2026-04-24-local-codex-runner-deep-quality-spec.md
+  Relationship: Makes bare `processing` impossible to publish from the runner
+  by requiring each processing message state to carry the specific active
+  Codex work reason at the channel-session boundary.
+
+- Date: 2026-04-25
+  Spec: plans/2026-04-24-local-codex-runner-deep-quality-spec.md
+  Relationship: Reduces raw Codex notifications and thread snapshots into
+  logical transcript units before Kandan projection, so TUI input projection
+  failures and ambiguous assistant-output reconciliation fail as state-machine
+  errors instead of creating source-less or duplicate-looking transcript rows,
+  and so live reasoning, command-output, terminal-interaction, search, abort,
+  live file-change, and completed tool-call observations update Kandan using
+  existing Codex output kinds.
+
+- Date: 2026-04-25
+  Spec: plans/2026-04-24-local-codex-runner-deep-quality-spec.md
+  Relationship: Surfaces non-auto-accepted Codex app-server approval requests
+  as Kandan message state, then resolves the blocked app-server request only
+  after a scoped Kandan approval control arrives.
+*/
+import {
+  availabilityMessage,
+  detectCodexVersion,
+  identityFromAccessToken,
+  isCodexAuthoredEvent,
+  localRunnerPayload,
+  parseKandanChatEvent,
+  senderAllowed,
+  type KandanChatEvent,
+  type RunnerIdentity,
+  type RunnerPayloadContext,
+} from "./channelSessionSupport";
+import { createHash, randomUUID } from "node:crypto";
+import { type CodexAppServerClient } from "./codexAppServer";
+import {
+  codexAssistantDeltaFromNotification,
+  codexAssistantStructuredMessage,
+  codexCommandExecutionStructuredMessage,
+  codexCommandOutputDeltaFromNotification,
+  codexFileChangeDeltaFromNotification,
+  codexFileChangeStructuredMessage,
+  codexOutputMessagesForTurn,
+  codexReasoningDeltaFromNotification,
+  codexReasoningStructuredMessage,
+  codexTerminalInputFromNotification,
+  codexWebSearchProgressFromNotification,
+  codexWebSearchStructuredMessage,
+  webSearchProgressBody,
+  codexUserInputMessageFromNotification,
+  codexUserInputMessagesForTurn,
+  type CodexUserInputMessage,
+} from "./codexOutput";
+import { arrayValue, integerValue, objectValue, stringValue } from "./json";
+import {
+  codexInputForQueuedKandanMessage,
+  interruptQueuedMessages,
+  type QueuedKandanMessage,
+} from "./kandanQueue";
+import { type PhoenixClient } from "./phoenix";
+import {
+  type JsonObject,
+  type JsonRpcRequest,
+  type JsonRpcResponse,
+  type KandanChannelSessionOptions,
+  type KandanControl,
+  isJsonObject,
+} from "./protocol";
+import { type RunnerLogger } from "./runnerLogger";
+
+export type ChannelSessionRuntime = {
+  readonly handleCodexNotification: (
+    method: string,
+    params: JsonObject,
+  ) => void;
+  readonly handleControl: (control: KandanControl) => Promise<JsonObject | undefined>;
+  readonly handleKandanReconnect: () => Promise<void>;
+  readonly currentCodexThreadId: () => string | undefined;
+  readonly currentKandanThreadId: () => string | undefined;
+  readonly close: () => Promise<void>;
+};
+
+export type ChannelSessionRunnerOptions = {
+  readonly token: string;
+  readonly runnerId: string;
+  readonly cwd: string;
+  readonly codexBin: string;
+  readonly fast?: boolean | undefined;
+  readonly launchTui?: boolean | undefined;
+  readonly channelSession: KandanChannelSessionOptions;
+};
+
+type ChannelSessionContext = {
+  readonly kandan: PhoenixClient;
+  readonly codex: CodexAppServerClient;
+  readonly topic: string;
+  readonly instanceId: string;
+  readonly options: ChannelSessionRunnerOptions;
+  readonly log: RunnerLogger;
+};
+
+type ChannelSessionState = {
+  rootSeq: number | undefined;
+  kandanThreadId: string | undefined;
+  codexThreadId: string | undefined;
+  turn: TurnState;
+  closed: boolean;
+  minSeq: number;
+  queue: QueuedKandanMessage[];
+  forwardedTurnIds: string[];
+  forwardingTurnIds: string[];
+  retryableTurnIds: string[];
+  localTuiTurnIds: string[];
+  mirroredTuiInputProjections: MirroredTuiInputProjection[];
+  pendingTuiInputMirrors: PendingTuiInputMirror[];
+  turnReplyTargets: TurnReplyTarget[];
+  streamingAssistantOutputs: StreamingAssistantOutput[];
+  streamingReasoningOutputs: StreamingReasoningOutput[];
+  streamingCommandOutputs: StreamingCommandOutput[];
+  streamingFileChangeOutputs: StreamingFileChangeOutput[];
+  forwardedTerminalInputKeys: string[];
+  webSearchProgressOutputs: WebSearchProgressOutput[];
+  pendingApprovalRequests: PendingCodexApprovalRequest[];
+  activeProcessingState: ActiveProcessingState | undefined;
+  assistantDeltaForwardChain: Promise<void>;
+  reasoningDeltaForwardChain: Promise<void>;
+  commandOutputForwardChain: Promise<void>;
+  fileChangeForwardChain: Promise<void>;
+  terminalInputForwardChain: Promise<void>;
+  webSearchProgressForwardChain: Promise<void>;
+  typingHeartbeat: ReturnType<typeof setInterval> | undefined;
+  typingHeartbeatInFlight: boolean;
+};
+
+type TurnState =
+  | { readonly status: "idle" }
+  | { readonly status: "starting"; readonly queuedSeq: number; readonly interruptAfterStart: boolean }
+  | { readonly status: "active"; readonly turnId: string; readonly queuedSeq: number }
+  | { readonly status: "completing"; readonly turnId: string; readonly queuedSeq: number };
+
+const codexTypingHeartbeatMs = 5_000;
+const maxForwardedTurnIds = 64;
+
+type StreamingAssistantOutput = {
+  readonly itemKey: string;
+  readonly turnId: string | undefined;
+  readonly seq: number;
+  readonly content: string;
+};
+
+type StreamingReasoningOutput = {
+  readonly itemKey: string;
+  readonly turnId: string | undefined;
+  readonly seq: number;
+  readonly content: string;
+};
+
+type StreamingCommandOutput = {
+  readonly itemKey: string;
+  readonly turnId: string | undefined;
+  readonly seq: number;
+  readonly output: string;
+  readonly processId: string | undefined;
+  readonly stream: string;
+};
+
+type StreamingFileChangeOutput = {
+  readonly itemKey: string;
+  readonly turnId: string | undefined;
+  readonly seq: number;
+  readonly patchText: string;
+};
+
+type WebSearchProgressOutput = {
+  readonly turnId: string;
+  readonly itemKey: string;
+  readonly seq: number;
+  readonly queries: string[];
+};
+
+type MirroredTuiInputProjection = {
+  readonly logicalKey: string;
+  readonly turnId: string;
+  readonly seq: number;
+  readonly itemKeys: string[];
+};
+
+type PendingTuiInputMirror = {
+  readonly turnId: string;
+  readonly promise: Promise<void>;
+};
+
+type TurnReplyTarget = {
+  readonly turnId: string;
+  readonly replyToSeq: number;
+};
+
+type ActiveProcessingState =
+  | {
+      readonly seq: number;
+      readonly reason: Exclude<LocalCodexProcessingReason, "awaiting approval">;
+    }
+  | {
+      readonly seq: number;
+      readonly reason: "awaiting approval";
+      readonly approval: CodexApprovalMessageState;
+    };
+
+type PendingCodexApprovalRequest = {
+  readonly requestId: string;
+  readonly sourceSeq: number;
+  readonly turnId: string;
+  readonly resolve: (response: JsonObject) => void;
+  readonly reject: (error: Error) => void;
+};
+
+type CodexApprovalMessageState = {
+  readonly requestId: string;
+  readonly kind: string;
+  readonly summary: string;
+};
+
+export async function attachChannelSession(
+  args: ChannelSessionContext,
+): Promise<ChannelSessionRuntime> {
+  const session = args.options.channelSession;
+  const chatTopic = `chat:${session.workspaceSlug}:${session.channelSlug}`;
+  const state = initialChannelSessionState(0, session.kandanThreadId);
+  const joined = await args.kandan.join(chatTopic, { last_seq: 0 }, {
+    rejoinPayload: () => ({ last_seq: state.minSeq }),
+  });
+  const cursor = integerValue(joined.cursor) ?? 0;
+  const runnerIdentity = identityFromAccessToken(args.options.token);
+  const codexVersion = detectCodexVersion(args.options.codexBin, args.options.cwd);
+  state.minSeq = cursor;
+  const payloadContext = {
+    runnerIdentity,
+    codexVersion,
+  };
+  const eventBuffer = {
+    ready: false,
+    pending: [] as KandanChatEvent[],
+  };
+
+  args.codex.onRequest?.(request =>
+    handleCodexServerRequest(args, state, payloadContext, request)
+  );
+
+  args.kandan.onEvent((topic, event, payload) => {
+    if (topic !== chatTopic || event !== "event") {
+      return;
+    }
+
+    const parsed = parseKandanChatEvent(payload);
+
+    if (parsed === undefined) {
+      return;
+    }
+
+    if (!eventBuffer.ready) {
+      eventBuffer.pending.push(parsed);
+      return;
+    }
+
+    void processKandanChatEvent(args, state, runnerIdentity, parsed, payloadContext);
+  });
+
+  await bindChannelSession(args, state, payloadContext);
+  await processBufferedKandanEvents(args, state, runnerIdentity, payloadContext, eventBuffer.pending);
+  eventBuffer.ready = true;
+  await drainKandanMessageQueue(args, state, payloadContext);
+
+  return {
+    handleCodexNotification: (method, params) => {
+      const turnId = codexNotificationTurnId(params);
+      const threadId = codexNotificationThreadId(params);
+
+      if (
+        threadId !== undefined &&
+        state.codexThreadId === threadId
+      ) {
+        const processingReason = processingReasonForCodexNotification(method, params);
+        if (turnId !== undefined && processingReason !== undefined) {
+          void refreshActiveProcessingState(args, state, turnId, processingReason).catch(error => {
+            args.log("kandan.message_state_refresh_failed", {
+              turn_id: turnId,
+              reason: processingReason,
+              message: error instanceof Error ? error.message : String(error),
+            });
+          });
+        }
+
+        switch (method) {
+          case "turn/started":
+            if (turnId !== undefined) {
+              rememberLocalTuiTurnIfNeeded(args, state, threadId, turnId);
+            }
+            break;
+          case "turn/aborted":
+          case "turn/canceled":
+          case "turn/cancelled":
+          case "turn/failed":
+            if (turnId !== undefined) {
+              void failActiveCodexTurn(args, state, turnId, abortReason(params), payloadContext)
+                .catch(error => {
+                  args.log("codex.turn_abort_handling_failed", {
+                    turn_id: turnId,
+                    message: error instanceof Error ? error.message : String(error),
+                  });
+                });
+            }
+            break;
+          case "turn/completed":
+            if (turnId !== undefined) {
+              enqueueWebSearchProgressCompletion(args, state, turnId);
+              enqueueFileChangeCompletion(args, state, turnId);
+              void forwardCompletedCodexTurn(args, state, turnId, payloadContext).catch(error => {
+                args.log("codex.turn_forward_failed", {
+                  turn_id: turnId,
+                  message: error instanceof Error ? error.message : String(error),
+                });
+              });
+            }
+            break;
+          case "item/agentMessage/delta":
+            enqueueAssistantDelta(args, state, params, payloadContext);
+            break;
+          case "item/reasoning/textDelta":
+            enqueueReasoningDelta(args, state, params, payloadContext);
+            break;
+          case "item/commandExecution/outputDelta":
+          case "command/exec/outputDelta":
+            enqueueCommandOutputDelta(args, state, params, payloadContext);
+            break;
+          case "item/fileChange/outputDelta":
+            enqueueFileChangeDelta(args, state, params, payloadContext);
+            break;
+          case "item/commandExecution/terminalInteraction":
+            enqueueTerminalInput(args, state, params, payloadContext);
+            break;
+          case "item/started":
+            enqueueWebSearchProgress(args, state, params, payloadContext);
+            break;
+          case "item/completed":
+            enqueueWebSearchProgress(args, state, params, payloadContext);
+            if (turnId !== undefined) {
+              const promise = mirrorLocalTuiInputFromNotification(
+                args,
+                state,
+                turnId,
+                params,
+                payloadContext,
+              );
+              rememberPendingTuiInputMirror(state, turnId, promise);
+              void promise
+                .catch(error => {
+                  args.log("codex.tui_input_mirror_failed", {
+                    turn_id: turnId,
+                    message: error instanceof Error ? error.message : String(error),
+                  });
+                })
+                .finally(() => forgetPendingTuiInputMirror(state, turnId));
+            }
+            break;
+        }
+      }
+    },
+    handleControl: control => handleChannelSessionControl(args, state, payloadContext, control),
+    currentCodexThreadId: () => state.codexThreadId,
+    currentKandanThreadId: () => state.kandanThreadId,
+    handleKandanReconnect: async () => {
+      if (state.closed) {
+        return;
+      }
+
+      args.log("kandan.reconnected", {
+        kandan_thread_id: state.kandanThreadId ?? null,
+        codex_thread_id: state.codexThreadId ?? null,
+        min_seq: state.minSeq,
+      });
+      await bindCurrentCodexThread(args, state);
+      if (state.kandanThreadId !== undefined && state.turn.status !== "idle") {
+        startCodexTypingHeartbeat(args, state, state.kandanThreadId);
+      }
+      await drainKandanMessageQueue(args, state, payloadContext);
+    },
+    close: async () => {
+      state.closed = true;
+      rejectPendingApprovalRequests(state, new Error("runner closed"));
+      await stopCodexTyping(args, state);
+    },
+  };
+}
+
+async function bindCurrentCodexThread(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+): Promise<void> {
+  if (state.codexThreadId === undefined) {
+    return;
+  }
+
+  const session = args.options.channelSession;
+  await pushOk(args.kandan, args.topic, "session:bind", {
+    workspace: session.workspaceSlug,
+    channel: session.channelSlug,
+    thread_id: state.kandanThreadId ?? null,
+    codex_thread_id: state.codexThreadId,
+    instance_id: args.instanceId,
+  });
+}
+
+function initialChannelSessionState(
+  cursor: number,
+  kandanThreadId: string | undefined,
+): ChannelSessionState {
+  return {
+    rootSeq: undefined,
+    kandanThreadId,
+    codexThreadId: undefined,
+    turn: { status: "idle" },
+    closed: false,
+    minSeq: cursor,
+    queue: [],
+    forwardedTurnIds: [],
+    forwardingTurnIds: [],
+    retryableTurnIds: [],
+    localTuiTurnIds: [],
+    mirroredTuiInputProjections: [],
+    pendingTuiInputMirrors: [],
+    turnReplyTargets: [],
+    streamingAssistantOutputs: [],
+    streamingReasoningOutputs: [],
+    streamingCommandOutputs: [],
+    streamingFileChangeOutputs: [],
+    forwardedTerminalInputKeys: [],
+    webSearchProgressOutputs: [],
+    pendingApprovalRequests: [],
+    activeProcessingState: undefined,
+    assistantDeltaForwardChain: Promise.resolve(),
+    reasoningDeltaForwardChain: Promise.resolve(),
+    commandOutputForwardChain: Promise.resolve(),
+    fileChangeForwardChain: Promise.resolve(),
+    terminalInputForwardChain: Promise.resolve(),
+    webSearchProgressForwardChain: Promise.resolve(),
+    typingHeartbeat: undefined,
+    typingHeartbeatInFlight: false,
+  };
+}
+
+async function bindChannelSession(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  payloadContext: RunnerPayloadContext,
+): Promise<void> {
+  const session = args.options.channelSession;
+  const codexVersion = payloadContext.codexVersion;
+
+  if (state.kandanThreadId === undefined) {
+    state.codexThreadId = await startCodexThread(args.codex, args.options);
+    const reply = await pushOk(args.kandan, args.topic, "session:announce", {
+      workspace: session.workspaceSlug,
+      channel: session.channelSlug,
+      body: availabilityMessage(args.options, codexVersion, state.codexThreadId),
+      payload: localRunnerPayload(
+        args.options,
+        args.instanceId,
+        "availability",
+        state.codexThreadId,
+        payloadContext,
+      ),
+      client_message_id: `local-codex-root-${args.instanceId}`,
+    });
+    state.rootSeq = integerValue(reply.seq);
+    if (state.rootSeq !== undefined) {
+      state.minSeq = Math.max(state.minSeq, state.rootSeq);
+    }
+  } else {
+    const resolved = await pushOk(args.kandan, args.topic, "session:resolve_thread_session", {
+      workspace: session.workspaceSlug,
+      channel: session.channelSlug,
+      thread_id: state.kandanThreadId,
+    });
+    state.rootSeq = integerValue(resolved.seq);
+    state.codexThreadId = stringValue(resolved.codex_thread_id);
+
+    if (state.codexThreadId === undefined) {
+      throw new Error(
+        "Kandan thread root metadata did not include a Codex thread id",
+      );
+    }
+
+    await pushOk(args.kandan, args.topic, "session:post_thread_message", {
+      workspace: session.workspaceSlug,
+      channel: session.channelSlug,
+      thread_id: state.kandanThreadId,
+      body: availabilityMessage(args.options, codexVersion, state.codexThreadId),
+      payload: localRunnerPayload(
+        args.options,
+        args.instanceId,
+        "availability",
+        state.codexThreadId,
+        payloadContext,
+      ),
+    });
+  }
+}
+
+async function handleChannelSessionControl(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  payloadContext: RunnerPayloadContext,
+  control: KandanControl,
+): Promise<JsonObject | undefined> {
+  if (control.type === "resolve_codex_approval_request") {
+    return resolvePendingCodexApprovalRequest(args, state, control);
+  }
+
+  if (control.type !== "interrupt_queued_messages") {
+    return undefined;
+  }
+
+  if (
+    state.codexThreadId === undefined ||
+    state.kandanThreadId === undefined ||
+    control.threadId !== state.codexThreadId
+  ) {
+    return { instanceId: args.instanceId, ok: false, error: "thread_not_bound" };
+  }
+
+  const interrupted = interruptQueuedMessages(state.queue, control.throughSeq);
+  const activeQueuedSeq =
+    state.turn.status === "active" || state.turn.status === "starting"
+      ? state.turn.queuedSeq
+      : undefined;
+  const targetsActiveTurn =
+    control.throughSeq !== undefined && activeQueuedSeq === control.throughSeq;
+
+  if (!interrupted.ok && !targetsActiveTurn) {
+    return { instanceId: args.instanceId, ok: false, error: "queue_empty" };
+  }
+
+  switch (state.turn.status) {
+    case "active":
+      const interruptedActiveSeq = state.turn.queuedSeq;
+      await args.codex.request("turn/interrupt", {
+        threadId: state.codexThreadId,
+        turnId: state.turn.turnId,
+      });
+
+      state.queue = interrupted.ok ? interrupted.queue : state.queue;
+      state.turn = { status: "idle" };
+      clearActiveProcessingState(state, interruptedActiveSeq);
+      await publishMessageState(args, state.kandanThreadId, interruptedActiveSeq, {
+        status: "processed",
+      });
+      break;
+    case "starting":
+      state.queue = interrupted.ok ? interrupted.queue : state.queue;
+      state.turn = {
+        status: "starting",
+        queuedSeq: state.turn.queuedSeq,
+        interruptAfterStart: true,
+      };
+      break;
+    case "idle":
+    case "completing":
+      state.queue = interrupted.ok ? interrupted.queue : state.queue;
+      break;
+  }
+
+  args.log("codex.queued_messages_interrupted", {
+    through_seq: control.throughSeq ?? null,
+    selected_count: interrupted.ok ? interrupted.selectedCount : 0,
+    remaining_count: interrupted.ok ? interrupted.remainingCount : state.queue.length,
+  });
+  if (interrupted.ok) {
+    for (const seq of interrupted.selectedSeqs) {
+      await publishMessageState(args, state.kandanThreadId, seq, {
+        status: "processing",
+        reason: "interrupt requested",
+      });
+    }
+  }
+  await drainKandanMessageQueue(args, state, payloadContext);
+  return {
+    instanceId: args.instanceId,
+    ok: true,
+    interruptedQueuedMessages: interrupted.ok ? interrupted.selectedCount : 0,
+  };
+}
+
+async function resolvePendingCodexApprovalRequest(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  control: Extract<KandanControl, { readonly type: "resolve_codex_approval_request" }>,
+): Promise<JsonObject> {
+  if (
+    state.codexThreadId === undefined ||
+    state.kandanThreadId === undefined ||
+    control.threadId !== state.codexThreadId
+  ) {
+    return { instanceId: args.instanceId, ok: false, error: "thread_not_bound" };
+  }
+
+  const approval = state.pendingApprovalRequests.find(
+    pending =>
+      pending.requestId === control.requestId &&
+      pending.sourceSeq === control.sourceSeq,
+  );
+
+  if (approval === undefined) {
+    return { instanceId: args.instanceId, ok: false, error: "approval_request_not_found" };
+  }
+
+  state.pendingApprovalRequests = state.pendingApprovalRequests.filter(
+    pending => pending !== approval,
+  );
+
+  const codexDecision = control.decision === "approve" ? "accept" : "decline";
+  approval.resolve({ decision: codexDecision });
+  state.activeProcessingState = { seq: approval.sourceSeq, reason: "streaming response" };
+
+  await publishMessageState(args, state.kandanThreadId, approval.sourceSeq, {
+    status: "processing",
+    reason: "streaming response",
+  });
+
+  args.log("codex.approval_request_resolved", {
+    request_id: control.requestId,
+    source_seq: control.sourceSeq,
+    decision: control.decision,
+    codex_decision: codexDecision,
+  });
+
+  return { instanceId: args.instanceId, ok: true };
+}
+
+async function handleKandanChatEvent(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  runnerIdentity: RunnerIdentity,
+  payloadContext: RunnerPayloadContext,
+  event: KandanChatEvent,
+): Promise<void> {
+  const session = args.options.channelSession;
+
+  if (
+    event.type !== "thread.message" ||
+    event.threadId === undefined ||
+    event.body.trim() === ""
+  ) {
+    args.log("kandan.message_ignored", {
+      seq: event.seq,
+      actor_slug: event.actorSlug ?? null,
+      actor_user_id: event.actorUserId ?? null,
+      reason: "not_thread_message_or_empty",
+    });
+    return;
+  }
+
+  if (isCodexAuthoredEvent(event)) {
+    args.log("kandan.message_ignored", {
+      seq: event.seq,
+      actor_slug: event.actorSlug ?? null,
+      actor_user_id: event.actorUserId ?? null,
+      reason: "codex_authored",
+    });
+    return;
+  }
+
+  if (!senderAllowed(session.listenUser, event, runnerIdentity)) {
+    args.log("kandan.message_ignored", {
+      seq: event.seq,
+      actor_slug: event.actorSlug ?? null,
+      actor_user_id: event.actorUserId ?? null,
+      reason: "sender_not_allowed",
+    });
+    await publishKandanMessageState(args, event, {
+      status: "ignored",
+      reason: "sender_not_allowed",
+    });
+    return;
+  }
+
+  if (state.kandanThreadId === undefined) {
+    if (state.rootSeq === undefined || event.replyToSeq !== state.rootSeq) {
+      const bound = await bindUnboundHistoricalThread(args, state, event);
+
+      if (!bound) {
+        args.log("kandan.message_ignored", {
+          seq: event.seq,
+          actor_slug: event.actorSlug ?? null,
+          actor_user_id: event.actorUserId ?? null,
+          reason: "not_root_reply",
+        });
+        await publishKandanMessageState(args, event, {
+          status: "ignored",
+          reason: "not_root_reply",
+        });
+        return;
+      }
+    } else {
+      state.kandanThreadId = event.threadId;
+    }
+  }
+
+  if (event.threadId !== state.kandanThreadId) {
+    args.log("kandan.message_ignored", {
+      seq: event.seq,
+      actor_slug: event.actorSlug ?? null,
+      actor_user_id: event.actorUserId ?? null,
+      reason: "different_thread",
+    });
+    await publishKandanMessageState(args, event, {
+      status: "ignored",
+      reason: "different_thread",
+    });
+    return;
+  }
+
+  state.queue.push({
+    seq: event.seq,
+    actorSlug: event.actorSlug,
+    actorUserId: event.actorUserId,
+    body: event.body,
+  });
+  args.log("kandan.message_queued", {
+    seq: event.seq,
+    actor_slug: event.actorSlug ?? null,
+    actor_user_id: event.actorUserId ?? null,
+    queue_depth: state.queue.length,
+  });
+  await publishKandanMessageState(args, event, { status: "queued" });
+  await drainKandanMessageQueue(args, state, payloadContext);
+}
+
+async function bindUnboundHistoricalThread(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  event: KandanChatEvent,
+): Promise<boolean> {
+  if (event.threadId === undefined || event.replyToSeq === undefined) {
+    return false;
+  }
+
+  const session = args.options.channelSession;
+
+  try {
+    const resolved = await pushOk(args.kandan, args.topic, "session:resolve_thread_session", {
+      workspace: session.workspaceSlug,
+      channel: session.channelSlug,
+      thread_id: event.threadId,
+    });
+    const rootSeq = integerValue(resolved.seq);
+    const codexThreadId = stringValue(resolved.codex_thread_id);
+
+    if (rootSeq !== event.replyToSeq || codexThreadId === undefined) {
+      return false;
+    }
+
+    state.rootSeq = rootSeq;
+    state.kandanThreadId = event.threadId;
+    state.codexThreadId = codexThreadId;
+    await bindCurrentCodexThread(args, state);
+    args.log("kandan.thread_bound_from_historical_reply", {
+      seq: event.seq,
+      kandan_thread_id: event.threadId,
+      root_seq: rootSeq,
+      codex_thread_id: codexThreadId,
+    });
+    return true;
+  } catch (error) {
+    args.log("kandan.thread_bind_from_historical_reply_failed", {
+      seq: event.seq,
+      kandan_thread_id: event.threadId,
+      message: error instanceof Error ? error.message : String(error),
+    });
+    return false;
+  }
+}
+
+async function processBufferedKandanEvents(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  runnerIdentity: RunnerIdentity,
+  payloadContext: RunnerPayloadContext,
+  pendingEvents: readonly KandanChatEvent[],
+): Promise<void> {
+  const events = [...pendingEvents].sort(
+    (left, right) => left.seq - right.seq,
+  );
+
+  for (const event of events) {
+    await processKandanChatEvent(args, state, runnerIdentity, event, payloadContext);
+  }
+}
+
+async function processKandanChatEvent(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  runnerIdentity: RunnerIdentity,
+  event: KandanChatEvent,
+  payloadContext: RunnerPayloadContext,
+): Promise<void> {
+  if (event.seq <= state.minSeq) {
+    return;
+  }
+
+  state.minSeq = event.seq;
+  args.log("kandan.chat_event", {
+    seq: event.seq,
+    type: event.type,
+    actor_slug: event.actorSlug ?? null,
+    actor_user_id: event.actorUserId ?? null,
+    thread_id: event.threadId ?? null,
+    reply_to_seq: event.replyToSeq ?? null,
+    local_runner_event_type: event.localRunnerEventType ?? null,
+  });
+
+  try {
+    await handleKandanChatEvent(args, state, runnerIdentity, payloadContext, event);
+  } catch (error) {
+    args.log("kandan.chat_event_failed", {
+      seq: event.seq,
+      message: error instanceof Error ? error.message : String(error),
+    });
+  }
+}
+
+async function drainKandanMessageQueue(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  payloadContext: RunnerPayloadContext,
+): Promise<void> {
+  if (state.closed || state.turn.status !== "idle") {
+    return;
+  }
+
+  const next = state.queue.shift();
+
+  if (next === undefined) {
+    return;
+  }
+
+  state.turn = { status: "starting", queuedSeq: next.seq, interruptAfterStart: false };
+  state.activeProcessingState = { seq: next.seq, reason: "starting turn" };
+  args.log("codex.turn_starting", {
+    queued_seq: next.seq,
+    actor_slug: next.actorSlug ?? null,
+    actor_user_id: next.actorUserId ?? null,
+    codex_thread_id: state.codexThreadId ?? null,
+    queue_depth: state.queue.length,
+  });
+  await publishQueuedMessageState(args, state, next, {
+    status: "processing",
+    reason: "starting turn",
+  });
+
+  try {
+    const codexThreadId = state.codexThreadId;
+
+    if (codexThreadId === undefined) {
+      throw new Error("Codex thread is not bound");
+    }
+
+    if (state.kandanThreadId !== undefined) {
+      startCodexTypingHeartbeat(args, state, state.kandanThreadId);
+    }
+
+    const started = await args.codex.request("turn/start", {
+      threadId: codexThreadId,
+      input: [{ type: "text", text: codexInputForQueuedKandanMessage(next) }],
+      ...codexTurnRuntimeOverrides(args.options),
+    });
+    const turnId = extractTurnIdFromResponse(started);
+    const interruptAfterStart =
+      state.turn.status === "starting" && state.turn.interruptAfterStart;
+    state.turn = { status: "active", turnId, queuedSeq: next.seq };
+    rememberTurnReplyTarget(state, turnId, next.seq);
+    args.log("codex.turn_started", { turn_id: turnId });
+
+    if (interruptAfterStart) {
+      await args.codex.request("turn/interrupt", {
+        threadId: codexThreadId,
+        turnId,
+      });
+      state.turn = { status: "idle" };
+      clearActiveProcessingState(state, next.seq);
+      if (state.kandanThreadId !== undefined) {
+        await publishMessageState(args, state.kandanThreadId, next.seq, {
+          status: "processed",
+        });
+      }
+      await drainKandanMessageQueue(args, state, payloadContext);
+    }
+  } catch (error) {
+    if (isRecoverableCodexThreadError(error) && state.kandanThreadId !== undefined) {
+      const oldCodexThreadId = state.codexThreadId;
+      try {
+        await stopCodexTyping(args, state);
+        const newCodexThreadId = await startCodexThread(args.codex, args.options);
+        state.codexThreadId = newCodexThreadId;
+        args.log("codex.thread_rebound", {
+          kandan_thread_id: state.kandanThreadId,
+          old_codex_thread_id: oldCodexThreadId ?? null,
+          new_codex_thread_id: newCodexThreadId,
+        });
+        await postCodexThreadReboundMessage(
+          args,
+          state,
+          payloadContext,
+          oldCodexThreadId,
+          newCodexThreadId,
+        );
+        state.queue = [next, ...state.queue];
+        state.turn = { status: "idle" };
+        await drainKandanMessageQueue(args, state, payloadContext);
+        return;
+      } catch (recoveryError) {
+        args.log("codex.thread_rebind_failed", {
+          kandan_thread_id: state.kandanThreadId,
+          old_codex_thread_id: oldCodexThreadId ?? null,
+          message: recoveryError instanceof Error ? recoveryError.message : String(recoveryError),
+        });
+      }
+    }
+
+    state.turn = { status: "idle" };
+    clearActiveProcessingState(state, next.seq);
+    await stopCodexTyping(args, state);
+    await publishQueuedMessageState(
+      args,
+      state,
+      next,
+      {
+        status: "failed",
+        reason: error instanceof Error ? error.message : String(error),
+      },
+    );
+    args.log("codex.turn_start_failed", {
+      queued_seq: next.seq,
+      message: error instanceof Error ? error.message : String(error),
+    });
+  }
+}
+
+async function handleCodexServerRequest(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  payloadContext: RunnerPayloadContext,
+  request: JsonRpcRequest,
+): Promise<JsonObject> {
+  const params = objectValue(request.params) ?? {};
+  const turnId = stringValue(params.turnId);
+
+  if (codexApprovalRequestCanAutoAccept(args.options, request.method)) {
+    args.log("codex.server_request_auto_accepted", {
+      method: request.method,
+      turn_id: turnId ?? null,
+    });
+    return { decision: "accept" };
+  }
+
+  if (codexApprovalRequestCanSurface(request.method)) {
+    if (turnId === undefined) {
+      throw new Error(`Codex approval request missing turn id: ${request.method}`);
+    }
+
+    return requestKandanApproval(args, state, request, turnId, payloadContext);
+  }
+
+  const message = `unhandled Codex app-server request: ${request.method}`;
+
+  args.log("codex.server_request_unhandled", {
+    method: request.method,
+    turn_id: turnId ?? null,
+  });
+
+  if (turnId !== undefined) {
+    await failActiveCodexTurn(args, state, turnId, message, payloadContext);
+  }
+
+  throw new Error(message);
+}
+
+function codexApprovalRequestCanAutoAccept(
+  options: ChannelSessionRunnerOptions,
+  method: string,
+): boolean {
+  return (
+    options.channelSession.approvalPolicy === "never" &&
+    (
+      method === "item/commandExecution/requestApproval" ||
+      method === "item/fileChange/requestApproval"
+    )
+  );
+}
+
+function codexApprovalRequestCanSurface(method: string): boolean {
+  return (
+    method === "item/commandExecution/requestApproval" ||
+    method === "item/fileChange/requestApproval"
+  );
+}
+
+async function requestKandanApproval(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  request: JsonRpcRequest,
+  turnId: string,
+  payloadContext: RunnerPayloadContext,
+): Promise<JsonObject> {
+  const sourceSeq = activeQueuedSeqForTurn(state, turnId);
+
+  if (sourceSeq === undefined || state.kandanThreadId === undefined) {
+    const message = `Codex approval request has no active Kandan source message: ${request.method}`;
+    await failActiveCodexTurn(args, state, turnId, message, payloadContext);
+    throw new Error(message);
+  }
+
+  const approval = codexApprovalMessageState(request);
+  state.activeProcessingState = { seq: sourceSeq, reason: "awaiting approval", approval };
+  await publishMessageState(args, state.kandanThreadId, sourceSeq, {
+    status: "processing",
+    reason: "awaiting approval",
+    approval,
+  });
+
+  args.log("codex.approval_request_pending", {
+    request_id: approval.requestId,
+    source_seq: sourceSeq,
+    turn_id: turnId,
+    method: request.method,
+  });
+
+  return new Promise<JsonObject>((resolve, reject) => {
+    state.pendingApprovalRequests = [
+      ...state.pendingApprovalRequests,
+      {
+        requestId: approval.requestId,
+        sourceSeq,
+        turnId,
+        resolve,
+        reject,
+      },
+    ];
+  });
+}
+
+function codexApprovalMessageState(request: JsonRpcRequest): CodexApprovalMessageState {
+  const params = objectValue(request.params) ?? {};
+  const command = stringValue(params.command) ?? stringValue(params.cmd);
+  const filePath =
+    stringValue(params.path) ??
+    stringValue(params.filePath) ??
+    stringValue(params.file);
+  const summary =
+    command ??
+    filePath ??
+    stringValue(params.reason) ??
+    stringValue(params.summary) ??
+    request.method;
+
+  return {
+    requestId: String(request.id),
+    kind: request.method,
+    summary,
+  };
+}
+
+function rejectPendingApprovalRequests(state: ChannelSessionState, error: Error): void {
+  const pendingApprovals = state.pendingApprovalRequests;
+  state.pendingApprovalRequests = [];
+  pendingApprovals.forEach(approval => approval.reject(error));
+}
+
+function rejectPendingApprovalRequestsForTurn(
+  state: ChannelSessionState,
+  turnId: string,
+  error: Error,
+): void {
+  const pendingApprovals = state.pendingApprovalRequests;
+  state.pendingApprovalRequests = pendingApprovals.filter(approval => approval.turnId !== turnId);
+  pendingApprovals
+    .filter(approval => approval.turnId === turnId)
+    .forEach(approval => approval.reject(error));
+}
+
+async function forwardCompletedCodexTurn(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  turnId: string,
+  payloadContext: RunnerPayloadContext,
+): Promise<void> {
+  if (isLocalTuiTurn(state, turnId)) {
+    ensureKandanThreadForLocalTuiTurn(state);
+  }
+
+  if (
+    state.kandanThreadId === undefined ||
+    state.codexThreadId === undefined ||
+    state.forwardedTurnIds.includes(turnId) ||
+    state.forwardingTurnIds.includes(turnId) ||
+    !turnCanForward(state, turnId)
+  ) {
+    return;
+  }
+
+  const completingQueuedSeq =
+    state.turn.status === "active" && state.turn.turnId === turnId
+      ? state.turn.queuedSeq
+      : undefined;
+  const completingActiveTurn = completingQueuedSeq !== undefined;
+  const completingLocalTuiTurn = isLocalTuiTurn(state, turnId);
+  if (completingQueuedSeq !== undefined) {
+    state.turn = { status: "completing", turnId, queuedSeq: completingQueuedSeq };
+  }
+  await waitForPendingTuiInputMirror(state, turnId);
+  await waitForStreamingForwardChains(state);
+  rememberForwardingTurnId(state, turnId);
+  forgetRetryableTurnId(state, turnId);
+
+  try {
+    const session = args.options.channelSession;
+    const read = await args.codex.request("thread/read", {
+      threadId: state.codexThreadId,
+      includeTurns: true,
+    });
+    const tuiInputMessages =
+      isLocalTuiTurn(state, turnId)
+        ? codexUserInputMessagesForTurn(read, turnId)
+        : [];
+    const messages = codexOutputMessagesForTurn(read, turnId);
+    args.log("codex.turn_completed", {
+      turn_id: turnId,
+      tui_input_count: tuiInputMessages.length,
+      output_count: messages.length,
+    });
+
+    if (isLocalTuiTurn(state, turnId)) {
+      ensureKandanThreadForLocalTuiTurn(state);
+    }
+
+    for (const message of tuiInputMessages) {
+      await mirrorLocalTuiInputMessage(args, state, turnId, message, payloadContext);
+    }
+
+    if (
+      completingLocalTuiTurn &&
+      sourceMessageSeqForTurn(state, turnId) === undefined
+    ) {
+      throw new LogicalProjectionError(
+        `Cannot forward Codex output for local TUI turn ${turnId} before mirroring its human input`,
+      );
+    }
+
+    for (const message of messages) {
+      const sourceMessageSeq = sourceMessageSeqForTurn(state, turnId);
+      const rootSeq = state.rootSeq;
+      const streamedStructured = resolveStreamingStructuredOutputForCompletedMessage(
+        state,
+        message.itemKey,
+        message.structured,
+      );
+
+      if (streamedStructured !== undefined) {
+        await editCodexStructuredOutput(
+          args,
+          state,
+          streamedStructured.seq,
+          message.body,
+          message.structured,
+        );
+        forgetStreamingStructuredOutput(state, message.itemKey, message.structured);
+        args.log("kandan.codex_output_forwarded", {
+          turn_id: turnId,
+          item_key: message.itemKey,
+          structured_kind: stringValue(message.structured.kind) ?? null,
+          command: stringValue(message.structured.command) ?? null,
+          file_paths: fileChangePaths(message.structured),
+        });
+        continue;
+      }
+
+      if (
+        stringValue(message.structured.kind) === "codex_terminal_input" &&
+        state.forwardedTerminalInputKeys.includes(message.itemKey)
+      ) {
+        continue;
+      }
+
+      const streamed = resolveStreamingAssistantOutputForCompletedMessage(
+        state,
+        turnId,
+        message.itemKey,
+        message.body,
+        message.structured,
+      );
+
+      switch (streamed.status) {
+        case "none":
+          await pushOk(args.kandan, args.topic, "session:post_thread_message", {
+            workspace: session.workspaceSlug,
+            channel: session.channelSlug,
+            thread_id: state.kandanThreadId,
+            body: message.body,
+            payload: {
+              ...localRunnerPayload(
+                args.options,
+                args.instanceId,
+                "codex_output",
+                state.codexThreadId,
+                payloadContext,
+                sourceMessageSeq,
+              ),
+              ...(rootSeq === undefined ? {} : { reply_to_seq: rootSeq }),
+              structured: message.structured,
+            },
+            client_message_id: `local-codex-${args.instanceId}-${turnId}-${message.itemKey}`,
+          });
+          break;
+        case "matched":
+          await editStreamedCodexOutput(
+            args,
+            state,
+            streamed.output.seq,
+            message.itemKey,
+            message.body,
+            "completed",
+          );
+          forgetStreamingAssistantOutput(state, streamed.output.itemKey);
+          break;
+        case "ambiguous":
+          throw new LogicalProjectionError(
+            `Cannot reconcile completed assistant item ${message.itemKey} for turn ${turnId}; ${streamed.candidateCount} active streamed assistant outputs exist`,
+          );
+      }
+      args.log("kandan.codex_output_forwarded", {
+        turn_id: turnId,
+        item_key: message.itemKey,
+        structured_kind: stringValue(message.structured.kind) ?? null,
+        command: stringValue(message.structured.command) ?? null,
+        file_paths: fileChangePaths(message.structured),
+      });
+    }
+
+    rememberForwardedTurnId(state, turnId);
+    forgetLocalTuiTurnId(state, turnId);
+    if (completingQueuedSeq !== undefined) {
+      await publishMessageState(args, state.kandanThreadId, completingQueuedSeq, {
+        status: "processed",
+      });
+      clearActiveProcessingState(state, completingQueuedSeq);
+    }
+  } catch (error) {
+    if (error instanceof LogicalProjectionError) {
+      if (completingQueuedSeq !== undefined && state.kandanThreadId !== undefined) {
+        await publishMessageState(args, state.kandanThreadId, completingQueuedSeq, {
+          status: "failed",
+          reason: error.message,
+        });
+        clearActiveProcessingState(state, completingQueuedSeq);
+      }
+      forgetLocalTuiTurnId(state, turnId);
+      rememberForwardedTurnId(state, turnId);
+      args.log("codex.logical_projection_failed", {
+        turn_id: turnId,
+        message: error.message,
+      });
+      return;
+    }
+
+    rememberRetryableTurnId(state, turnId);
+    throw error;
+  } finally {
+    forgetForwardingTurnId(state, turnId);
+    if (
+      completingActiveTurn &&
+      state.turn.status === "completing" &&
+      state.turn.turnId === turnId
+    ) {
+      state.turn = { status: "idle" };
+      await stopCodexTyping(args, state);
+      await drainKandanMessageQueue(args, state, payloadContext);
+    }
+    if (completingLocalTuiTurn && !completingActiveTurn) {
+      await stopCodexTyping(args, state);
+    }
+  }
+}
+
+async function forwardAssistantDelta(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  params: JsonObject,
+  payloadContext: RunnerPayloadContext,
+): Promise<void> {
+  if (state.kandanThreadId === undefined || state.codexThreadId === undefined) {
+    return;
+  }
+
+  const delta = codexAssistantDeltaFromNotification(params);
+
+  if (delta === undefined) {
+    return;
+  }
+
+  if (
+    delta.turnId !== undefined &&
+    turnIsFinalizingOrForwarded(state, delta.turnId)
+  ) {
+    return;
+  }
+
+  if (delta.turnId !== undefined) {
+    await waitForPendingTuiInputMirror(state, delta.turnId);
+  }
+
+  if (
+    delta.turnId !== undefined &&
+    isLocalTuiTurn(state, delta.turnId) &&
+    sourceMessageSeqForTurn(state, delta.turnId) === undefined
+  ) {
+    args.log("codex.delta_waiting_for_tui_input_projection", {
+      turn_id: delta.turnId,
+      item_key: delta.itemKey,
+    });
+    return;
+  }
+
+  const existing = findStreamingAssistantOutput(state, delta.itemKey);
+  const nextContent = `${existing?.content ?? ""}${delta.delta}`;
+  const sourceMessageSeq =
+    delta.turnId === undefined ? undefined : sourceMessageSeqForTurn(state, delta.turnId);
+  const rootSeq = state.rootSeq;
+
+  if (delta.turnId !== undefined && sourceMessageSeq === undefined) {
+    args.log("codex.delta_without_source_message", {
+      turn_id: delta.turnId,
+      item_key: delta.itemKey,
+    });
+    return;
+  }
+
+  if (existing === undefined && nextContent.trim() === "") {
+    return;
+  }
+
+  if (existing === undefined) {
+    const session = args.options.channelSession;
+    const reply = await pushOk(args.kandan, args.topic, "session:post_thread_message", {
+      workspace: session.workspaceSlug,
+      channel: session.channelSlug,
+      thread_id: state.kandanThreadId,
+      body: nextContent,
+      payload: {
+        ...localRunnerPayload(
+          args.options,
+          args.instanceId,
+          "codex_output",
+          state.codexThreadId,
+          payloadContext,
+          sourceMessageSeq,
+        ),
+        ...(rootSeq === undefined ? {} : { reply_to_seq: rootSeq }),
+        structured: codexAssistantStructuredMessage(delta.itemKey, nextContent, "streaming"),
+      },
+      client_message_id: streamingClientMessageId(args.instanceId, delta),
+    });
+    const seq = integerValue(reply.seq);
+
+    if (seq !== undefined) {
+      rememberStreamingAssistantOutput(state, {
+        itemKey: delta.itemKey,
+        turnId: delta.turnId,
+        seq,
+        content: nextContent,
+      });
+    }
+  } else {
+    await editStreamedCodexOutput(
+      args,
+      state,
+      existing.seq,
+      delta.itemKey,
+      nextContent,
+      "streaming",
+    );
+    rememberStreamingAssistantOutput(state, {
+      ...existing,
+      content: nextContent,
+    });
+  }
+
+  args.log("kandan.codex_delta_forwarded", {
+    item_key: delta.itemKey,
+    turn_id: delta.turnId ?? null,
+    content_length: nextContent.length,
+  });
+}
+
+function enqueueAssistantDelta(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  params: JsonObject,
+  payloadContext: RunnerPayloadContext,
+): void {
+  const previous = state.assistantDeltaForwardChain;
+  const next = previous
+    .catch(() => undefined)
+    .then(() => forwardAssistantDelta(args, state, params, payloadContext));
+
+  state.assistantDeltaForwardChain = next.catch(error => {
+    args.log("codex.delta_forward_failed", {
+      turn_id: codexNotificationTurnId(params) ?? null,
+      message: error instanceof Error ? error.message : String(error),
+    });
+  });
+}
+
+function enqueueReasoningDelta(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  params: JsonObject,
+  payloadContext: RunnerPayloadContext,
+): void {
+  const previous = state.reasoningDeltaForwardChain;
+  const next = previous
+    .catch(() => undefined)
+    .then(() => forwardReasoningDelta(args, state, params, payloadContext));
+
+  state.reasoningDeltaForwardChain = next.catch(error => {
+    args.log("codex.reasoning_delta_forward_failed", {
+      turn_id: codexNotificationTurnId(params) ?? null,
+      message: error instanceof Error ? error.message : String(error),
+    });
+  });
+}
+
+function enqueueCommandOutputDelta(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  params: JsonObject,
+  payloadContext: RunnerPayloadContext,
+): void {
+  const previous = state.commandOutputForwardChain;
+  const next = previous
+    .catch(() => undefined)
+    .then(() => forwardCommandOutputDelta(args, state, params, payloadContext));
+
+  state.commandOutputForwardChain = next.catch(error => {
+    args.log("codex.command_output_forward_failed", {
+      turn_id: codexNotificationTurnId(params) ?? null,
+      message: error instanceof Error ? error.message : String(error),
+    });
+  });
+}
+
+function enqueueFileChangeDelta(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  params: JsonObject,
+  payloadContext: RunnerPayloadContext,
+): void {
+  const previous = state.fileChangeForwardChain;
+  const next = previous
+    .catch(() => undefined)
+    .then(() => forwardFileChangeDelta(args, state, params, payloadContext));
+
+  state.fileChangeForwardChain = next.catch(error => {
+    args.log("codex.file_change_forward_failed", {
+      turn_id: codexNotificationTurnId(params) ?? null,
+      message: error instanceof Error ? error.message : String(error),
+    });
+  });
+}
+
+function enqueueTerminalInput(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  params: JsonObject,
+  payloadContext: RunnerPayloadContext,
+): void {
+  const previous = state.terminalInputForwardChain;
+  const next = previous
+    .catch(() => undefined)
+    .then(() => forwardTerminalInput(args, state, params, payloadContext));
+
+  state.terminalInputForwardChain = next.catch(error => {
+    args.log("codex.terminal_input_forward_failed", {
+      turn_id: codexNotificationTurnId(params) ?? null,
+      message: error instanceof Error ? error.message : String(error),
+    });
+  });
+}
+
+function enqueueWebSearchProgress(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  params: JsonObject,
+  payloadContext: RunnerPayloadContext,
+): void {
+  const previous = state.webSearchProgressForwardChain;
+  const next = previous
+    .catch(() => undefined)
+    .then(() => forwardWebSearchProgress(args, state, params, payloadContext));
+
+  state.webSearchProgressForwardChain = next.catch(error => {
+    args.log("codex.web_search_progress_forward_failed", {
+      turn_id: codexNotificationTurnId(params) ?? null,
+      message: error instanceof Error ? error.message : String(error),
+    });
+  });
+}
+
+function enqueueWebSearchProgressCompletion(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  turnId: string,
+): void {
+  const previous = state.webSearchProgressForwardChain;
+  const next = previous
+    .catch(() => undefined)
+    .then(() => completeWebSearchProgress(args, state, turnId));
+
+  state.webSearchProgressForwardChain = next.catch(error => {
+    args.log("codex.web_search_progress_completion_failed", {
+      turn_id: turnId,
+      message: error instanceof Error ? error.message : String(error),
+    });
+  });
+}
+
+function enqueueFileChangeCompletion(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  turnId: string,
+): void {
+  const previous = state.fileChangeForwardChain;
+  const next = previous
+    .catch(() => undefined)
+    .then(() => completeFileChangeOutputs(args, state, turnId));
+
+  state.fileChangeForwardChain = next.catch(error => {
+    args.log("codex.file_change_completion_failed", {
+      turn_id: turnId,
+      message: error instanceof Error ? error.message : String(error),
+    });
+  });
+}
+
+async function forwardReasoningDelta(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  params: JsonObject,
+  payloadContext: RunnerPayloadContext,
+): Promise<void> {
+  if (state.kandanThreadId === undefined || state.codexThreadId === undefined) {
+    return;
+  }
+
+  const delta = codexReasoningDeltaFromNotification(params);
+
+  if (delta === undefined) {
+    return;
+  }
+
+  const turnId = delta.turnId ?? activeTurnId(state);
+
+  if (turnId === undefined || turnIsFinalizingOrForwarded(state, turnId)) {
+    return;
+  }
+
+  const sourceMessageSeq = sourceMessageSeqForTurn(state, turnId);
+
+  if (sourceMessageSeq === undefined) {
+    args.log("codex.reasoning_without_source_message", {
+      turn_id: turnId,
+      item_key: delta.itemKey,
+    });
+    return;
+  }
+
+  const existing = findStreamingReasoningOutput(state, delta.itemKey);
+  const nextContent = `${existing?.content ?? ""}${delta.delta}`;
+
+  if (existing === undefined && nextContent.trim() === "") {
+    return;
+  }
+
+  if (existing === undefined) {
+    const session = args.options.channelSession;
+    const reply = await pushOk(args.kandan, args.topic, "session:post_thread_message", {
+      workspace: session.workspaceSlug,
+      channel: session.channelSlug,
+      thread_id: state.kandanThreadId,
+      body: nextContent,
+      payload: {
+        ...localRunnerPayload(
+          args.options,
+          args.instanceId,
+          "codex_output",
+          state.codexThreadId,
+          payloadContext,
+          sourceMessageSeq,
+        ),
+        ...(state.rootSeq === undefined ? {} : { reply_to_seq: state.rootSeq }),
+        structured: codexReasoningStructuredMessage(delta.itemKey, nextContent, "streaming"),
+      },
+      client_message_id: streamingClientMessageId(args.instanceId, {
+        itemKey: `reasoning:${delta.itemKey}`,
+        turnId,
+      }),
+    });
+    const seq = integerValue(reply.seq);
+
+    if (seq !== undefined) {
+      rememberStreamingReasoningOutput(state, {
+        itemKey: delta.itemKey,
+        turnId,
+        seq,
+        content: nextContent,
+      });
+    }
+  } else {
+    await editCodexStructuredOutput(
+      args,
+      state,
+      existing.seq,
+      nextContent,
+      codexReasoningStructuredMessage(delta.itemKey, nextContent, "streaming"),
+    );
+    rememberStreamingReasoningOutput(state, { ...existing, content: nextContent });
+  }
+
+  args.log("kandan.codex_reasoning_delta_forwarded", {
+    item_key: delta.itemKey,
+    turn_id: turnId,
+    content_length: nextContent.length,
+  });
+}
+
+async function forwardCommandOutputDelta(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  params: JsonObject,
+  payloadContext: RunnerPayloadContext,
+): Promise<void> {
+  if (state.kandanThreadId === undefined || state.codexThreadId === undefined) {
+    return;
+  }
+
+  const delta = codexCommandOutputDeltaFromNotification(params);
+
+  if (delta === undefined) {
+    return;
+  }
+
+  const turnId = delta.turnId ?? activeTurnId(state);
+
+  if (turnId === undefined || turnIsFinalizingOrForwarded(state, turnId)) {
+    return;
+  }
+
+  const sourceMessageSeq = sourceMessageSeqForTurn(state, turnId);
+
+  if (sourceMessageSeq === undefined) {
+    args.log("codex.command_output_without_source_message", {
+      turn_id: turnId,
+      item_key: delta.itemKey,
+    });
+    return;
+  }
+
+  const existing = findStreamingCommandOutput(state, delta.itemKey);
+  const output = `${existing?.output ?? ""}${delta.delta}`;
+  const body = commandOutputBody("command output", output);
+  const structured = codexCommandExecutionStructuredMessage(
+    delta.itemKey,
+    {
+      command: "command output",
+      output,
+      processId: delta.processId,
+      stream: delta.stream,
+    },
+    "streaming",
+  );
+
+  if (existing === undefined) {
+    const session = args.options.channelSession;
+    const reply = await pushOk(args.kandan, args.topic, "session:post_thread_message", {
+      workspace: session.workspaceSlug,
+      channel: session.channelSlug,
+      thread_id: state.kandanThreadId,
+      body,
+      payload: {
+        ...localRunnerPayload(
+          args.options,
+          args.instanceId,
+          "codex_output",
+          state.codexThreadId,
+          payloadContext,
+          sourceMessageSeq,
+        ),
+        ...(state.rootSeq === undefined ? {} : { reply_to_seq: state.rootSeq }),
+        structured,
+      },
+      client_message_id: streamingClientMessageId(args.instanceId, {
+        itemKey: `command:${delta.itemKey}`,
+        turnId,
+      }),
+    });
+    const seq = integerValue(reply.seq);
+
+    if (seq !== undefined) {
+      rememberStreamingCommandOutput(state, {
+        itemKey: delta.itemKey,
+        turnId,
+        seq,
+        output,
+        processId: delta.processId,
+        stream: delta.stream,
+      });
+    }
+  } else {
+    await editCodexStructuredOutput(args, state, existing.seq, body, structured);
+    rememberStreamingCommandOutput(state, {
+      ...existing,
+      output,
+      processId: delta.processId ?? existing.processId,
+      stream: delta.stream,
+    });
+  }
+
+  args.log("kandan.codex_command_output_forwarded", {
+    item_key: delta.itemKey,
+    turn_id: turnId,
+    process_id: delta.processId ?? null,
+    stream: delta.stream,
+    output_length: output.length,
+  });
+}
+
+async function forwardFileChangeDelta(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  params: JsonObject,
+  payloadContext: RunnerPayloadContext,
+): Promise<void> {
+  if (state.kandanThreadId === undefined || state.codexThreadId === undefined) {
+    return;
+  }
+
+  const delta = codexFileChangeDeltaFromNotification(params);
+
+  if (delta === undefined) {
+    return;
+  }
+
+  const turnId = delta.turnId ?? activeTurnId(state);
+
+  if (turnId === undefined || turnIsFinalizingOrForwarded(state, turnId)) {
+    return;
+  }
+
+  const sourceMessageSeq = sourceMessageSeqForTurn(state, turnId);
+
+  if (sourceMessageSeq === undefined) {
+    args.log("codex.file_change_without_source_message", {
+      turn_id: turnId,
+      item_key: delta.itemKey,
+    });
+    return;
+  }
+
+  const existing = findStreamingFileChangeOutput(state, delta.itemKey);
+  const patchText = `${existing?.patchText ?? ""}${delta.patchText}`;
+  const structured = codexFileChangeStructuredMessage(
+    delta.itemKey,
+    patchText,
+    "streaming",
+    "started",
+  );
+
+  if (existing === undefined) {
+    const session = args.options.channelSession;
+    const reply = await pushOk(args.kandan, args.topic, "session:post_thread_message", {
+      workspace: session.workspaceSlug,
+      channel: session.channelSlug,
+      thread_id: state.kandanThreadId,
+      body: patchText,
+      payload: {
+        ...localRunnerPayload(
+          args.options,
+          args.instanceId,
+          "codex_output",
+          state.codexThreadId,
+          payloadContext,
+          sourceMessageSeq,
+        ),
+        ...(state.rootSeq === undefined ? {} : { reply_to_seq: state.rootSeq }),
+        structured,
+      },
+      client_message_id: streamingClientMessageId(args.instanceId, {
+        itemKey: `file-change:${delta.itemKey}`,
+        turnId,
+      }),
+    });
+    const seq = integerValue(reply.seq);
+
+    if (seq !== undefined) {
+      rememberStreamingFileChangeOutput(state, {
+        itemKey: delta.itemKey,
+        turnId,
+        seq,
+        patchText,
+      });
+    }
+  } else {
+    await editCodexStructuredOutput(args, state, existing.seq, patchText, structured);
+    rememberStreamingFileChangeOutput(state, {
+      ...existing,
+      patchText,
+    });
+  }
+
+  args.log("kandan.codex_file_change_forwarded", {
+    item_key: delta.itemKey,
+    turn_id: turnId,
+    patch_length: patchText.length,
+  });
+}
+
+async function forwardTerminalInput(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  params: JsonObject,
+  payloadContext: RunnerPayloadContext,
+): Promise<void> {
+  if (state.kandanThreadId === undefined || state.codexThreadId === undefined) {
+    return;
+  }
+
+  const terminal = codexTerminalInputFromNotification(params);
+
+  if (terminal === undefined || state.forwardedTerminalInputKeys.includes(terminal.itemKey)) {
+    return;
+  }
+
+  const turnId = terminal.turnId ?? activeTurnId(state);
+
+  if (turnId === undefined || turnIsFinalizingOrForwarded(state, turnId)) {
+    return;
+  }
+
+  const sourceMessageSeq = sourceMessageSeqForTurn(state, turnId);
+
+  if (sourceMessageSeq === undefined) {
+    args.log("codex.terminal_input_without_source_message", {
+      turn_id: turnId,
+      item_key: terminal.itemKey,
+    });
+    return;
+  }
+
+  const session = args.options.channelSession;
+  await pushOk(args.kandan, args.topic, "session:post_thread_message", {
+    workspace: session.workspaceSlug,
+    channel: session.channelSlug,
+    thread_id: state.kandanThreadId,
+    body: terminal.inputText,
+    payload: {
+      ...localRunnerPayload(
+        args.options,
+        args.instanceId,
+        "codex_output",
+        state.codexThreadId,
+        payloadContext,
+        sourceMessageSeq,
+      ),
+      ...(state.rootSeq === undefined ? {} : { reply_to_seq: state.rootSeq }),
+      structured: {
+        kind: "codex_terminal_input",
+        item_id: terminal.itemKey,
+        transcript_unit_id: `codex_terminal_input:${terminal.itemKey}`,
+        stream_state: "completed",
+        process_id: terminal.processId ?? "",
+        input_text: terminal.inputText,
+      },
+    },
+    client_message_id: streamingClientMessageId(args.instanceId, {
+      itemKey: `terminal:${terminal.itemKey}`,
+      turnId,
+    }),
+  });
+  rememberForwardedTerminalInputKey(state, terminal.itemKey);
+  args.log("kandan.codex_output_forwarded", {
+    turn_id: turnId,
+    item_key: terminal.itemKey,
+    structured_kind: "codex_terminal_input",
+    command: null,
+    file_paths: [],
+  });
+}
+
+async function forwardWebSearchProgress(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  params: JsonObject,
+  payloadContext: RunnerPayloadContext,
+): Promise<void> {
+  if (state.kandanThreadId === undefined || state.codexThreadId === undefined) {
+    return;
+  }
+
+  const progress = codexWebSearchProgressFromNotification(params);
+
+  if (progress === undefined || progress.turnId === undefined) {
+    return;
+  }
+
+  const sourceMessageSeq = sourceMessageSeqForTurn(state, progress.turnId);
+
+  if (sourceMessageSeq === undefined) {
+    args.log("codex.web_search_without_source_message", {
+      turn_id: progress.turnId,
+      item_key: progress.itemKey,
+    });
+    return;
+  }
+
+  const itemKey = webSearchProgressItemKey(progress.turnId);
+  const existing = findWebSearchProgressOutput(state, progress.turnId);
+  const queries = mergeWebSearchQueries(existing?.queries ?? [], progress.queries);
+  const body = webSearchProgressBody(queries);
+  const structured = codexWebSearchStructuredMessage(itemKey, queries, "streaming");
+
+  if (existing === undefined) {
+    const session = args.options.channelSession;
+    const reply = await pushOk(args.kandan, args.topic, "session:post_thread_message", {
+      workspace: session.workspaceSlug,
+      channel: session.channelSlug,
+      thread_id: state.kandanThreadId,
+      body,
+      payload: {
+        ...localRunnerPayload(
+          args.options,
+          args.instanceId,
+          "codex_output",
+          state.codexThreadId,
+          payloadContext,
+          sourceMessageSeq,
+        ),
+        ...(state.rootSeq === undefined ? {} : { reply_to_seq: state.rootSeq }),
+        structured,
+      },
+      client_message_id: webSearchProgressClientMessageId(args.instanceId, progress.turnId),
+    });
+    const seq = integerValue(reply.seq);
+
+    if (seq !== undefined) {
+      rememberWebSearchProgressOutput(state, {
+        turnId: progress.turnId,
+        itemKey,
+        seq,
+        queries,
+      });
+    }
+  } else if (queries.length !== existing.queries.length) {
+    await editCodexStructuredOutput(args, state, existing.seq, body, structured);
+    rememberWebSearchProgressOutput(state, {
+      ...existing,
+      queries,
+    });
+  }
+
+  args.log("kandan.codex_web_search_progress_forwarded", {
+    turn_id: progress.turnId,
+    item_key: progress.itemKey,
+    query_count: queries.length,
+  });
+}
+
+async function completeWebSearchProgress(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  turnId: string,
+): Promise<void> {
+  const existing = findWebSearchProgressOutput(state, turnId);
+
+  if (existing === undefined) {
+    return;
+  }
+
+  await editCodexStructuredOutput(
+    args,
+    state,
+    existing.seq,
+    webSearchProgressBody(existing.queries),
+    codexWebSearchStructuredMessage(existing.itemKey, existing.queries, "completed"),
+  );
+  forgetWebSearchProgressOutput(state, turnId);
+}
+
+async function completeFileChangeOutputs(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  turnId: string,
+): Promise<void> {
+  const outputs = state.streamingFileChangeOutputs.filter(
+    output => output.turnId === turnId,
+  );
+
+  for (const output of outputs) {
+    await editCodexStructuredOutput(
+      args,
+      state,
+      output.seq,
+      output.patchText,
+      codexFileChangeStructuredMessage(
+        output.itemKey,
+        output.patchText,
+        "completed",
+        "completed",
+      ),
+    );
+  }
+}
+
+function streamingClientMessageId(
+  instanceId: string,
+  delta: { readonly itemKey: string; readonly turnId: string | undefined },
+): string {
+  const digest = createHash("sha256")
+    .update(`${instanceId}:${delta.turnId ?? "turn"}:${delta.itemKey}`)
+    .digest("hex")
+    .slice(0, 32);
+
+  return `local-codex-stream-${digest}`;
+}
+
+function webSearchProgressClientMessageId(instanceId: string, turnId: string): string {
+  const digest = createHash("sha256")
+    .update(`${instanceId}:${turnId}:web-search`)
+    .digest("hex")
+    .slice(0, 32);
+
+  return `local-codex-search-${digest}`;
+}
+
+function webSearchProgressItemKey(turnId: string): string {
+  return `web-search:${turnId}`;
+}
+
+function commandOutputBody(command: string, output: string): string {
+  return [`$ ${command}`, output].filter(part => part.trim() !== "").join("\n\n");
+}
+
+async function editStreamedCodexOutput(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  targetSeq: number,
+  itemKey: string,
+  content: string,
+  streamState: "streaming" | "completed",
+): Promise<void> {
+  await editCodexStructuredOutput(
+    args,
+    state,
+    targetSeq,
+    content,
+    codexAssistantStructuredMessage(itemKey, content, streamState),
+  );
+}
+
+async function editCodexStructuredOutput(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  targetSeq: number,
+  content: string,
+  structured: JsonObject,
+): Promise<void> {
+  if (state.kandanThreadId === undefined) {
+    return;
+  }
+
+  const session = args.options.channelSession;
+  await pushOk(args.kandan, args.topic, "session:edit_thread_message", {
+    workspace: session.workspaceSlug,
+    channel: session.channelSlug,
+    thread_id: state.kandanThreadId,
+    target_seq: targetSeq,
+    body: content,
+    structured,
+  });
+}
+
+async function mirrorLocalTuiInputFromNotification(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  turnId: string,
+  params: JsonObject,
+  payloadContext: RunnerPayloadContext,
+): Promise<void> {
+  if (!isLocalTuiTurn(state, turnId)) {
+    return;
+  }
+
+  const message = codexUserInputMessageFromNotification(params);
+
+  if (message === undefined) {
+    return;
+  }
+
+  await mirrorLocalTuiInputMessage(args, state, turnId, message, payloadContext);
+}
+
+async function mirrorLocalTuiInputMessage(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  turnId: string,
+  message: CodexUserInputMessage,
+  payloadContext: RunnerPayloadContext,
+): Promise<void> {
+  const logicalKey = tuiInputLogicalKey(turnId, message.body);
+
+  if (findMirroredTuiInputProjection(state, logicalKey) !== undefined) {
+    rememberMirroredTuiInputItemKey(state, logicalKey, message.itemKey);
+    return;
+  }
+
+  ensureKandanThreadForLocalTuiTurn(state);
+  const threadId = state.kandanThreadId;
+  const codexThreadId = state.codexThreadId;
+
+  if (threadId === undefined || codexThreadId === undefined) {
+    return;
+  }
+
+  const session = args.options.channelSession;
+  const reply = await pushOk(args.kandan, args.topic, "session:post_thread_user_message", {
+    workspace: session.workspaceSlug,
+    channel: session.channelSlug,
+    thread_id: threadId,
+    body: message.body,
+    payload: {
+      ...localRunnerPayload(
+        args.options,
+        args.instanceId,
+        "tui_input",
+        codexThreadId,
+        payloadContext,
+      ),
+      ...(state.rootSeq === undefined ? {} : { reply_to_seq: state.rootSeq }),
+    },
+    client_message_id: tuiInputClientMessageId(args.instanceId, turnId, message.itemKey),
+  });
+  const seq = integerValue(reply.seq);
+  if (seq !== undefined) {
+    rememberTurnReplyTarget(state, turnId, seq);
+    rememberMirroredTuiInputProjection(state, {
+      logicalKey,
+      turnId,
+      seq,
+      itemKeys: [message.itemKey],
+    });
+  }
+  args.log("kandan.tui_input_mirrored", {
+    turn_id: turnId,
+    item_key: message.itemKey,
+    actor_user_id: payloadContext.runnerIdentity.actorUserId ?? null,
+    actor_slug: payloadContext.runnerIdentity.actorUsername ?? null,
+  });
+}
+
+function tuiInputClientMessageId(
+  instanceId: string,
+  turnId: string,
+  itemKey: string,
+): string {
+  const digest = createHash("sha256")
+    .update(`${instanceId}:${turnId}:${itemKey}`)
+    .digest("hex")
+    .slice(0, 32);
+
+  return `local-codex-tui-${digest}`;
+}
+
+function tuiInputLogicalKey(turnId: string, body: string): string {
+  const digest = createHash("sha256")
+    .update(`${turnId}:${body.trim()}`)
+    .digest("hex")
+    .slice(0, 32);
+
+  return `local-codex-tui-input:${digest}`;
+}
+
+function findMirroredTuiInputProjection(
+  state: ChannelSessionState,
+  logicalKey: string,
+): MirroredTuiInputProjection | undefined {
+  return state.mirroredTuiInputProjections.find(
+    projection => projection.logicalKey === logicalKey,
+  );
+}
+
+function rememberMirroredTuiInputProjection(
+  state: ChannelSessionState,
+  projection: MirroredTuiInputProjection,
+): void {
+  state.mirroredTuiInputProjections = [
+    ...state.mirroredTuiInputProjections.filter(
+      existing => existing.logicalKey !== projection.logicalKey,
+    ),
+    projection,
+  ].slice(-maxForwardedTurnIds);
+}
+
+function rememberMirroredTuiInputItemKey(
+  state: ChannelSessionState,
+  logicalKey: string,
+  itemKey: string,
+): void {
+  const existing = findMirroredTuiInputProjection(state, logicalKey);
+
+  if (existing === undefined || existing.itemKeys.includes(itemKey)) {
+    return;
+  }
+
+  rememberMirroredTuiInputProjection(state, {
+    ...existing,
+    itemKeys: [...existing.itemKeys, itemKey],
+  });
+}
+
+function findStreamingAssistantOutput(
+  state: ChannelSessionState,
+  itemKey: string,
+): StreamingAssistantOutput | undefined {
+  return state.streamingAssistantOutputs.find(output => output.itemKey === itemKey);
+}
+
+function findStreamingReasoningOutput(
+  state: ChannelSessionState,
+  itemKey: string,
+): StreamingReasoningOutput | undefined {
+  return state.streamingReasoningOutputs.find(output => output.itemKey === itemKey);
+}
+
+function findStreamingCommandOutput(
+  state: ChannelSessionState,
+  itemKey: string,
+): StreamingCommandOutput | undefined {
+  return state.streamingCommandOutputs.find(output => output.itemKey === itemKey);
+}
+
+function findStreamingFileChangeOutput(
+  state: ChannelSessionState,
+  itemKey: string,
+): StreamingFileChangeOutput | undefined {
+  return state.streamingFileChangeOutputs.find(output => output.itemKey === itemKey);
+}
+
+type StreamedStructuredOutput = {
+  readonly itemKey: string;
+  readonly seq: number;
+};
+
+function resolveStreamingStructuredOutputForCompletedMessage(
+  state: ChannelSessionState,
+  itemKey: string,
+  structured: JsonObject,
+): StreamedStructuredOutput | undefined {
+  switch (stringValue(structured.kind)) {
+    case "codex_reasoning": {
+      const output = findStreamingReasoningOutput(state, itemKey);
+      return output === undefined ? undefined : { itemKey: output.itemKey, seq: output.seq };
+    }
+    case "codex_command_execution": {
+      const output = findStreamingCommandOutput(state, itemKey);
+      return output === undefined ? undefined : { itemKey: output.itemKey, seq: output.seq };
+    }
+    case "codex_file_change": {
+      const output = findStreamingFileChangeOutput(state, itemKey);
+      return output === undefined ? undefined : { itemKey: output.itemKey, seq: output.seq };
+    }
+    default:
+      return undefined;
+  }
+}
+
+function forgetStreamingStructuredOutput(
+  state: ChannelSessionState,
+  itemKey: string,
+  structured: JsonObject,
+): void {
+  switch (stringValue(structured.kind)) {
+    case "codex_reasoning":
+      forgetStreamingReasoningOutput(state, itemKey);
+      break;
+    case "codex_command_execution":
+      forgetStreamingCommandOutput(state, itemKey);
+      break;
+    case "codex_file_change":
+      forgetStreamingFileChangeOutput(state, itemKey);
+      break;
+  }
+}
+
+type StreamingAssistantOutputResolution =
+  | { readonly status: "matched"; readonly output: StreamingAssistantOutput }
+  | { readonly status: "none" }
+  | { readonly status: "ambiguous"; readonly candidateCount: number };
+
+class LogicalProjectionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "LogicalProjectionError";
+  }
+}
+
+function resolveStreamingAssistantOutputForCompletedMessage(
+  state: ChannelSessionState,
+  turnId: string,
+  itemKey: string,
+  body: string,
+  structured: JsonObject,
+): StreamingAssistantOutputResolution {
+  const exact = findStreamingAssistantOutput(state, itemKey);
+
+  if (exact !== undefined) {
+    return { status: "matched", output: exact };
+  }
+
+  if (stringValue(structured.kind) !== "codex_assistant_message") {
+    return { status: "none" };
+  }
+
+  const candidates = state.streamingAssistantOutputs.filter(
+    output => output.turnId === turnId,
+  );
+
+  switch (candidates.length) {
+    case 0:
+      return { status: "none" };
+    case 1: {
+      const [output] = candidates;
+      return output === undefined
+        ? { status: "none" }
+        : { status: "matched", output };
+    }
+    default: {
+      const contentMatched = candidates.filter(
+        output => normalizedTranscriptText(output.content) === normalizedTranscriptText(body),
+      );
+
+      if (contentMatched.length === 1) {
+        const [output] = contentMatched;
+        return output === undefined
+          ? { status: "ambiguous", candidateCount: candidates.length }
+          : { status: "matched", output };
+      }
+
+      return { status: "ambiguous", candidateCount: candidates.length };
+    }
+  }
+}
+
+function normalizedTranscriptText(value: string): string {
+  return value.trim().replace(/\s+/g, " ");
+}
+
+function turnIsFinalizingOrForwarded(
+  state: ChannelSessionState,
+  turnId: string,
+): boolean {
+  return (
+    state.forwardingTurnIds.includes(turnId) ||
+    state.forwardedTurnIds.includes(turnId)
+  );
+}
+
+function rememberStreamingAssistantOutput(
+  state: ChannelSessionState,
+  output: StreamingAssistantOutput,
+): void {
+  state.streamingAssistantOutputs = [
+    ...state.streamingAssistantOutputs.filter(existing => existing.itemKey !== output.itemKey),
+    output,
+  ].slice(-maxForwardedTurnIds);
+}
+
+function forgetStreamingAssistantOutput(
+  state: ChannelSessionState,
+  itemKey: string,
+): void {
+  state.streamingAssistantOutputs = state.streamingAssistantOutputs.filter(
+    output => output.itemKey !== itemKey,
+  );
+}
+
+function rememberStreamingReasoningOutput(
+  state: ChannelSessionState,
+  output: StreamingReasoningOutput,
+): void {
+  state.streamingReasoningOutputs = [
+    ...state.streamingReasoningOutputs.filter(existing => existing.itemKey !== output.itemKey),
+    output,
+  ].slice(-maxForwardedTurnIds);
+}
+
+function forgetStreamingReasoningOutput(
+  state: ChannelSessionState,
+  itemKey: string,
+): void {
+  state.streamingReasoningOutputs = state.streamingReasoningOutputs.filter(
+    output => output.itemKey !== itemKey,
+  );
+}
+
+function rememberStreamingCommandOutput(
+  state: ChannelSessionState,
+  output: StreamingCommandOutput,
+): void {
+  state.streamingCommandOutputs = [
+    ...state.streamingCommandOutputs.filter(existing => existing.itemKey !== output.itemKey),
+    output,
+  ].slice(-maxForwardedTurnIds);
+}
+
+function forgetStreamingCommandOutput(
+  state: ChannelSessionState,
+  itemKey: string,
+): void {
+  state.streamingCommandOutputs = state.streamingCommandOutputs.filter(
+    output => output.itemKey !== itemKey,
+  );
+}
+
+function rememberStreamingFileChangeOutput(
+  state: ChannelSessionState,
+  output: StreamingFileChangeOutput,
+): void {
+  state.streamingFileChangeOutputs = [
+    ...state.streamingFileChangeOutputs.filter(existing => existing.itemKey !== output.itemKey),
+    output,
+  ].slice(-maxForwardedTurnIds);
+}
+
+function forgetStreamingFileChangeOutput(
+  state: ChannelSessionState,
+  itemKey: string,
+): void {
+  state.streamingFileChangeOutputs = state.streamingFileChangeOutputs.filter(
+    output => output.itemKey !== itemKey,
+  );
+}
+
+function rememberForwardedTerminalInputKey(
+  state: ChannelSessionState,
+  itemKey: string,
+): void {
+  if (state.forwardedTerminalInputKeys.includes(itemKey)) {
+    return;
+  }
+
+  state.forwardedTerminalInputKeys = [...state.forwardedTerminalInputKeys, itemKey]
+    .slice(-maxForwardedTurnIds);
+}
+
+function findWebSearchProgressOutput(
+  state: ChannelSessionState,
+  turnId: string,
+): WebSearchProgressOutput | undefined {
+  return state.webSearchProgressOutputs.find(output => output.turnId === turnId);
+}
+
+function rememberWebSearchProgressOutput(
+  state: ChannelSessionState,
+  output: WebSearchProgressOutput,
+): void {
+  state.webSearchProgressOutputs = [
+    ...state.webSearchProgressOutputs.filter(existing => existing.turnId !== output.turnId),
+    output,
+  ].slice(-maxForwardedTurnIds);
+}
+
+function forgetWebSearchProgressOutput(
+  state: ChannelSessionState,
+  turnId: string,
+): void {
+  state.webSearchProgressOutputs = state.webSearchProgressOutputs.filter(
+    output => output.turnId !== turnId,
+  );
+}
+
+function mergeWebSearchQueries(
+  existing: readonly string[],
+  incoming: readonly string[],
+): string[] {
+  return [...existing, ...incoming].reduce<string[]>((acc, query) => {
+    if (acc.includes(query)) {
+      return acc;
+    }
+
+    return [...acc, query];
+  }, []);
+}
+
+function codexNotificationTurnId(params: JsonObject): string | undefined {
+  const turn = objectValue(params.turn);
+
+  return (
+    stringValue(turn?.id) ??
+    stringValue(params.turnId) ??
+    stringValue(params.turn_id)
+  );
+}
+
+function codexNotificationThreadId(params: JsonObject): string | undefined {
+  const thread = objectValue(params.thread);
+  const turn = objectValue(params.turn);
+
+  return (
+    stringValue(params.threadId) ??
+    stringValue(params.thread_id) ??
+    stringValue(thread?.id) ??
+    stringValue(turn?.threadId) ??
+    stringValue(turn?.thread_id)
+  );
+}
+
+function rememberLocalTuiTurnIfNeeded(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  threadId: string,
+  turnId: string,
+): void {
+  if (
+    args.options.launchTui !== true ||
+    state.codexThreadId !== threadId ||
+    state.turn.status !== "idle"
+  ) {
+    return;
+  }
+
+  state.localTuiTurnIds = rememberTurnId(state.localTuiTurnIds, turnId);
+  if (state.kandanThreadId !== undefined) {
+    startCodexTypingHeartbeat(args, state, state.kandanThreadId);
+  }
+  args.log("codex.tui_turn_started", { turn_id: turnId, codex_thread_id: threadId });
+}
+
+function isLocalTuiTurn(state: ChannelSessionState, turnId: string): boolean {
+  return state.localTuiTurnIds.includes(turnId);
+}
+
+function ensureKandanThreadForLocalTuiTurn(
+  state: ChannelSessionState,
+): void {
+  if (state.kandanThreadId !== undefined || state.rootSeq === undefined) {
+    return;
+  }
+
+  state.kandanThreadId = randomUUID();
+}
+
+function forgetLocalTuiTurnId(
+  state: ChannelSessionState,
+  turnId: string,
+): void {
+  state.localTuiTurnIds = state.localTuiTurnIds.filter(id => id !== turnId);
+}
+
+function rememberPendingTuiInputMirror(
+  state: ChannelSessionState,
+  turnId: string,
+  promise: Promise<void>,
+): void {
+  state.pendingTuiInputMirrors = [
+    ...state.pendingTuiInputMirrors.filter(pending => pending.turnId !== turnId),
+    { turnId, promise },
+  ].slice(-maxForwardedTurnIds);
+}
+
+function forgetPendingTuiInputMirror(
+  state: ChannelSessionState,
+  turnId: string,
+): void {
+  state.pendingTuiInputMirrors = state.pendingTuiInputMirrors.filter(
+    pending => pending.turnId !== turnId,
+  );
+}
+
+async function waitForPendingTuiInputMirror(
+  state: ChannelSessionState,
+  turnId: string,
+): Promise<void> {
+  const pending = state.pendingTuiInputMirrors.find(
+    mirror => mirror.turnId === turnId,
+  );
+
+  if (pending !== undefined) {
+    await pending.promise;
+  }
+}
+
+async function waitForStreamingForwardChains(
+  state: ChannelSessionState,
+): Promise<void> {
+  await Promise.all([
+    state.assistantDeltaForwardChain.catch(() => undefined),
+    state.reasoningDeltaForwardChain.catch(() => undefined),
+    state.commandOutputForwardChain.catch(() => undefined),
+    state.fileChangeForwardChain.catch(() => undefined),
+    state.terminalInputForwardChain.catch(() => undefined),
+    state.webSearchProgressForwardChain.catch(() => undefined),
+  ]);
+}
+
+function rememberTurnReplyTarget(
+  state: ChannelSessionState,
+  turnId: string,
+  replyToSeq: number,
+): void {
+  state.turnReplyTargets = [
+    ...state.turnReplyTargets.filter(target => target.turnId !== turnId),
+    { turnId, replyToSeq },
+  ].slice(-maxForwardedTurnIds);
+}
+
+function sourceMessageSeqForTurn(
+  state: ChannelSessionState,
+  turnId: string,
+): number | undefined {
+  return state.turnReplyTargets.find(target => target.turnId === turnId)?.replyToSeq;
+}
+
+function fileChangePaths(structured: JsonObject): string[] {
+  const changes = arrayValue(structured.changes) ?? [];
+
+  return changes
+    .filter(isJsonObject)
+    .map(change => stringValue(change.path) ?? "")
+    .filter(path => path.trim() !== "");
+}
+
+async function postCodexThreadReboundMessage(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  payloadContext: RunnerPayloadContext,
+  oldCodexThreadId: string | undefined,
+  newCodexThreadId: string,
+): Promise<void> {
+  if (state.kandanThreadId === undefined) {
+    return;
+  }
+
+  const session = args.options.channelSession;
+  const body = [
+    "Codex reconnected.",
+    "",
+    "The previous local Codex app-server thread was not available in this process, so this runner started a new local Codex thread for this Kandan thread.",
+    "",
+    `Previous Codex thread: ${oldCodexThreadId ?? "unknown"}`,
+    `New Codex thread: ${newCodexThreadId}`,
+  ].join("\n");
+
+  await pushOk(args.kandan, args.topic, "session:post_thread_message", {
+    workspace: session.workspaceSlug,
+    channel: session.channelSlug,
+    thread_id: state.kandanThreadId,
+    body,
+    payload: localRunnerPayload(
+      args.options,
+      args.instanceId,
+      "availability",
+      newCodexThreadId,
+      payloadContext,
+    ),
+    client_message_id: `local-codex-rebound-${args.instanceId}-${newCodexThreadId}`,
+  });
+}
+
+function isRecoverableCodexThreadError(error: unknown): boolean {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+
+  return (
+    error.message.includes("turn/start failed: thread not found") ||
+    error.message.includes("turn/start failed: invalid thread id")
+  );
+}
+
+function turnCanForward(state: ChannelSessionState, turnId: string): boolean {
+  if (state.retryableTurnIds.includes(turnId)) {
+    return true;
+  }
+
+  if (isLocalTuiTurn(state, turnId)) {
+    return true;
+  }
+
+  switch (state.turn.status) {
+    case "active":
+      return state.turn.turnId === turnId;
+    case "completing":
+      return state.turn.turnId === turnId;
+    case "idle":
+    case "starting":
+      return false;
+  }
+}
+
+function rememberForwardedTurnId(
+  state: ChannelSessionState,
+  turnId: string,
+): void {
+  if (state.forwardedTurnIds.includes(turnId)) {
+    return;
+  }
+
+  state.forwardedTurnIds = rememberTurnId(state.forwardedTurnIds, turnId);
+  forgetRetryableTurnId(state, turnId);
+}
+
+function rememberForwardingTurnId(
+  state: ChannelSessionState,
+  turnId: string,
+): void {
+  state.forwardingTurnIds = rememberTurnId(state.forwardingTurnIds, turnId);
+}
+
+function forgetForwardingTurnId(
+  state: ChannelSessionState,
+  turnId: string,
+): void {
+  state.forwardingTurnIds = state.forwardingTurnIds.filter(id => id !== turnId);
+}
+
+function rememberRetryableTurnId(
+  state: ChannelSessionState,
+  turnId: string,
+): void {
+  state.retryableTurnIds = rememberTurnId(state.retryableTurnIds, turnId);
+}
+
+function forgetRetryableTurnId(
+  state: ChannelSessionState,
+  turnId: string,
+): void {
+  state.retryableTurnIds = state.retryableTurnIds.filter(id => id !== turnId);
+}
+
+function rememberTurnId(
+  values: readonly string[],
+  turnId: string,
+): string[] {
+  if (values.includes(turnId)) {
+    return [...values];
+  }
+
+  return [...values, turnId].slice(-maxForwardedTurnIds);
+}
+
+async function stopCodexTyping(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+): Promise<void> {
+  stopCodexTypingHeartbeat(state);
+
+  if (state.kandanThreadId === undefined) {
+    return;
+  }
+
+  const session = args.options.channelSession;
+  await pushOptional(
+    args.kandan,
+    args.topic,
+    "session:typing_stop",
+    {
+      workspace: session.workspaceSlug,
+      channel: session.channelSlug,
+      thread_id: state.kandanThreadId,
+    },
+    args.log,
+  );
+}
+
+function startCodexTypingHeartbeat(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  threadId: string,
+): void {
+  const send = () => {
+    if (state.typingHeartbeatInFlight) {
+      return;
+    }
+
+    const session = args.options.channelSession;
+    state.typingHeartbeatInFlight = true;
+    void pushOptional(
+      args.kandan,
+      args.topic,
+      "session:typing_start",
+      {
+        workspace: session.workspaceSlug,
+        channel: session.channelSlug,
+        thread_id: threadId,
+      },
+      args.log,
+    )
+      .then(() => refreshActiveProcessingHeartbeat(args, state))
+      .catch(error => {
+        args.log("kandan.typing_heartbeat_failed", {
+          message: error instanceof Error ? error.message : String(error),
+        });
+      })
+      .finally(() => {
+      state.typingHeartbeatInFlight = false;
+    });
+  };
+
+  send();
+
+  if (state.typingHeartbeat === undefined) {
+    state.typingHeartbeat = setInterval(send, codexTypingHeartbeatMs);
+  }
+}
+
+function stopCodexTypingHeartbeat(state: ChannelSessionState): void {
+  if (state.typingHeartbeat !== undefined) {
+    clearInterval(state.typingHeartbeat);
+    state.typingHeartbeat = undefined;
+  }
+}
+
+type LocalCodexProcessingReason =
+  | "starting turn"
+  | "streaming response"
+  | "running terminal command"
+  | "interrupt requested"
+  | "awaiting approval";
+
+type LocalCodexMessageState =
+  | { readonly status: "queued" }
+  | { readonly status: "processed" }
+  | {
+      readonly status: "processing";
+      readonly reason: LocalCodexProcessingReason;
+      readonly approval?: CodexApprovalMessageState | undefined;
+    }
+  | { readonly status: "ignored"; readonly reason: string }
+  | { readonly status: "failed"; readonly reason: string };
+
+async function publishKandanMessageState(
+  args: ChannelSessionContext,
+  event: KandanChatEvent,
+  state: LocalCodexMessageState,
+): Promise<void> {
+  if (event.threadId === undefined) {
+    return;
+  }
+
+  await publishMessageState(
+    args,
+    event.threadId,
+    event.seq,
+    state,
+    event.actorSlug,
+    event.actorUserId,
+  );
+}
+
+async function publishQueuedMessageState(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  message: QueuedKandanMessage,
+  messageState: LocalCodexMessageState,
+): Promise<void> {
+  if (state.kandanThreadId === undefined) {
+    return;
+  }
+
+  await publishMessageState(
+    args,
+    state.kandanThreadId,
+    message.seq,
+    messageState,
+    message.actorSlug,
+    message.actorUserId,
+  );
+}
+
+async function publishMessageState(
+  args: ChannelSessionContext,
+  threadId: string,
+  seq: number,
+  state: LocalCodexMessageState,
+  actorSlug?: string,
+  actorUserId?: number,
+): Promise<void> {
+  const session = args.options.channelSession;
+  const payload = {
+    workspace: session.workspaceSlug,
+    channel: session.channelSlug,
+    thread_id: threadId,
+    seq,
+    status: state.status,
+    ...("reason" in state ? { reason: state.reason } : {}),
+    ...(state.status === "processing" && state.approval !== undefined
+      ? {
+          approval_request_id: state.approval.requestId,
+          approval_kind: state.approval.kind,
+          approval_summary: state.approval.summary,
+        }
+      : {}),
+    ...(actorSlug === undefined ? {} : { actor_slug: actorSlug }),
+    ...(actorUserId === undefined ? {} : { actor_user_id: actorUserId }),
+  };
+
+  await pushOptional(args.kandan, args.topic, "message_state", payload, args.log);
+}
+
+function processingReasonForCodexNotification(
+  method: string,
+  params: JsonObject,
+): Exclude<LocalCodexProcessingReason, "awaiting approval"> | undefined {
+  if (method === "item/agentMessage/delta" || method === "item/reasoning/textDelta") {
+    return "streaming response";
+  }
+
+  if (
+    method.startsWith("item/commandExecution/") ||
+    method === "command/exec/outputDelta"
+  ) {
+    return "running terminal command";
+  }
+
+  const item = objectValue(params.item) ?? params;
+  const itemType = stringValue(item.type);
+
+  switch (itemType) {
+    case "commandExecution":
+    case "terminalInput":
+      return "running terminal command";
+    case "agentMessage":
+    case "reasoning":
+    case "fileChange":
+    case "web_search_call":
+    case "webSearchCall":
+    case "webSearch":
+      return "streaming response";
+    default:
+      return undefined;
+  }
+}
+
+function activeTurnId(state: ChannelSessionState): string | undefined {
+  switch (state.turn.status) {
+    case "active":
+    case "completing":
+      return state.turn.turnId;
+    case "idle":
+    case "starting":
+      return undefined;
+  }
+}
+
+function abortReason(params: JsonObject): string {
+  return (
+    stringValue(params.reason) ??
+    stringValue(params.message) ??
+    stringValue(params.error) ??
+    "codex_turn_aborted"
+  );
+}
+
+async function failActiveCodexTurn(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  turnId: string,
+  reason: string,
+  payloadContext: RunnerPayloadContext,
+): Promise<void> {
+  rejectPendingApprovalRequestsForTurn(state, turnId, new Error(reason));
+  const seq = activeQueuedSeqForTurn(state, turnId);
+
+  if (seq !== undefined && state.kandanThreadId !== undefined) {
+    await publishMessageState(args, state.kandanThreadId, seq, {
+      status: "failed",
+      reason,
+    });
+    clearActiveProcessingState(state, seq);
+  }
+
+  forgetLocalTuiTurnId(state, turnId);
+  rememberForwardedTurnId(state, turnId);
+
+  if (
+    state.turn.status !== "idle" &&
+    (state.turn.status === "starting" || state.turn.turnId === turnId)
+  ) {
+    state.turn = { status: "idle" };
+  }
+
+  await stopCodexTyping(args, state);
+  await drainKandanMessageQueue(args, state, payloadContext);
+}
+
+function activeQueuedSeqForTurn(
+  state: ChannelSessionState,
+  turnId: string,
+): number | undefined {
+  switch (state.turn.status) {
+    case "active":
+    case "completing":
+      return state.turn.turnId === turnId ? state.turn.queuedSeq : undefined;
+    case "idle":
+    case "starting":
+      return undefined;
+  }
+}
+
+async function refreshActiveProcessingState(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+  turnId: string,
+  reason: Exclude<LocalCodexProcessingReason, "awaiting approval">,
+): Promise<void> {
+  const seq = activeQueuedSeqForTurn(state, turnId);
+
+  if (seq === undefined || state.kandanThreadId === undefined) {
+    return;
+  }
+
+  if (
+    state.activeProcessingState?.seq === seq &&
+    state.activeProcessingState.reason === reason
+  ) {
+    return;
+  }
+
+  state.activeProcessingState = { seq, reason };
+  await publishMessageState(args, state.kandanThreadId, seq, {
+    status: "processing",
+    reason,
+  });
+}
+
+async function refreshActiveProcessingHeartbeat(
+  args: ChannelSessionContext,
+  state: ChannelSessionState,
+): Promise<void> {
+  const activeProcessingState = state.activeProcessingState;
+
+  if (
+    activeProcessingState === undefined ||
+    state.kandanThreadId === undefined
+  ) {
+    return;
+  }
+
+  await publishMessageState(
+    args,
+    state.kandanThreadId,
+    activeProcessingState.seq,
+    processingMessageStateFromActive(activeProcessingState),
+  );
+}
+
+function clearActiveProcessingState(state: ChannelSessionState, seq: number): void {
+  if (state.activeProcessingState?.seq === seq) {
+    state.activeProcessingState = undefined;
+  }
+}
+
+function processingMessageStateFromActive(
+  state: ActiveProcessingState,
+): Extract<LocalCodexMessageState, { readonly status: "processing" }> {
+  switch (state.reason) {
+    case "awaiting approval":
+      return { status: "processing", reason: state.reason, approval: state.approval };
+    case "starting turn":
+    case "streaming response":
+    case "running terminal command":
+    case "interrupt requested":
+      return { status: "processing", reason: state.reason };
+  }
+}
+
+function extractThreadIdFromResponse(response: JsonRpcResponse): string {
+  if ("error" in response) {
+    throw new Error(`thread/start failed: ${response.error.message}`);
+  }
+
+  const threadId = stringValue(
+    objectValue(objectValue(response.result)?.thread)?.id,
+  );
+
+  if (threadId === undefined) {
+    throw new Error("thread/start response did not include thread.id");
+  }
+
+  return threadId;
+}
+
+function extractTurnIdFromResponse(response: JsonRpcResponse): string {
+  if ("error" in response) {
+    throw new Error(`turn/start failed: ${response.error.message}`);
+  }
+
+  const turnId = stringValue(
+    objectValue(objectValue(response.result)?.turn)?.id,
+  );
+
+  if (turnId === undefined) {
+    throw new Error("turn/start response did not include turn.id");
+  }
+
+  return turnId;
+}
+
+async function startCodexThread(
+  codex: CodexAppServerClient,
+  options: ChannelSessionRunnerOptions,
+): Promise<string> {
+  const start = await codex.request("thread/start", {
+    cwd: options.cwd,
+    serviceName: "kandan-local-runner",
+    personality: "pragmatic",
+    ...codexThreadRuntimeOverrides(options),
+  });
+
+  return extractThreadIdFromResponse(start);
+}
+
+function codexThreadRuntimeOverrides(options: ChannelSessionRunnerOptions): JsonObject {
+  const session = options.channelSession;
+
+  return {
+    ...(session.model === undefined ? {} : { model: session.model }),
+    ...(session.reasoningEffort === undefined
+      ? {}
+      : { reasoningEffort: session.reasoningEffort }),
+    ...(options.fast === true ? { serviceTier: "fast" } : {}),
+    ...(session.approvalPolicy === undefined
+      ? {}
+      : { approvalPolicy: session.approvalPolicy }),
+    ...(session.sandbox === undefined ? {} : { sandbox: session.sandbox }),
+  };
+}
+
+function codexTurnRuntimeOverrides(options: ChannelSessionRunnerOptions): JsonObject {
+  const session = options.channelSession;
+
+  return {
+    cwd: options.cwd,
+    ...(session.model === undefined ? {} : { model: session.model }),
+    ...(session.reasoningEffort === undefined ? {} : { effort: session.reasoningEffort }),
+    ...(options.fast === true ? { serviceTier: "fast" } : {}),
+    ...(session.approvalPolicy === undefined
+      ? {}
+      : { approvalPolicy: session.approvalPolicy }),
+    ...(session.sandbox === undefined
+      ? {}
+      : { sandboxPolicy: codexSandboxPolicy(session.sandbox, options.cwd) }),
+  };
+}
+
+function codexSandboxPolicy(sandbox: string, cwd: string): JsonObject {
+  switch (sandbox) {
+    case "danger-full-access":
+      return { type: "dangerFullAccess" };
+    case "read-only":
+      return {
+        type: "readOnly",
+        access: { type: "fullAccess" },
+        networkAccess: false,
+      };
+    case "workspace-write":
+      return {
+        type: "workspaceWrite",
+        writableRoots: [cwd],
+        readOnlyAccess: { type: "fullAccess" },
+        networkAccess: false,
+        excludeTmpdirEnvVar: false,
+        excludeSlashTmp: false,
+      };
+    default:
+      throw new Error(`unsupported Codex sandbox mode: ${sandbox}`);
+  }
+}
+
+async function pushOk(
+  kandan: PhoenixClient,
+  topic: string,
+  event: string,
+  payload: JsonObject,
+): Promise<JsonObject> {
+  const reply = await kandan.push(topic, event, payload);
+
+  if (
+    isJsonObject(reply) &&
+    reply.status === "ok" &&
+    isJsonObject(reply.response)
+  ) {
+    return reply.response;
+  }
+
+  throw new Error(
+    `kandan push failed: ${event}: ${JSON.stringify(reply).slice(0, 500)}`,
+  );
+}
+
+async function pushOptional(
+  kandan: PhoenixClient,
+  topic: string,
+  event: string,
+  payload: JsonObject,
+  log: RunnerLogger,
+): Promise<void> {
+  try {
+    await pushOk(kandan, topic, event, payload);
+  } catch (error) {
+    log("kandan.optional_push_failed", {
+      event,
+      message: error instanceof Error ? error.message : String(error),
+    });
+  }
+}