@rynx-ai/runtime 0.1.11-beta.3 → 0.1.11-beta.30

package/dist/claude/session-status.js

@@ -0,0 +1,163 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const STATUS_TO_RUNNER = {
+    busy: "running",
+    waiting: "running",
+    idle: "idle",
+    shell: "idle",
+    running: "running",
+    completed: "idle",
+    failed: "idle",
+    error: "idle",
+    done: "idle",
+};
+const SCAN_FRESHNESS_MS = 120_000;
+const DEFAULT_MAX_RESOLVE_ATTEMPTS = 40;
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function readJsonRecord(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return isRecord(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function matchesSession(record, expectedSessionId) {
+    if (record.kind !== "interactive")
+        return false;
+    return expectedSessionId === undefined || record.sessionId === expectedSessionId;
+}
+export function claudeSessionsDir(configDir = process.env.CLAUDE_CONFIG_DIR?.trim() || join(homedir(), ".claude")) {
+    return join(configDir, "sessions");
+}
+export function resolveClaudeSessionStatusFile({ panePid, expectedSessionId, configDir, now = Date.now(), }) {
+    const directory = claudeSessionsDir(configDir);
+    if (panePid !== undefined) {
+        const candidate = join(directory, `${panePid}.json`);
+        const record = readJsonRecord(candidate);
+        if (record && matchesSession(record, expectedSessionId))
+            return candidate;
+    }
+    if (!expectedSessionId)
+        return undefined;
+    try {
+        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+            if (!entry.isFile() || !entry.name.endsWith(".json"))
+                continue;
+            const candidate = join(directory, entry.name);
+            let modifiedAt;
+            try {
+                modifiedAt = statSync(candidate).mtimeMs;
+            }
+            catch {
+                continue;
+            }
+            if (now - modifiedAt > SCAN_FRESHNESS_MS)
+                continue;
+            const record = readJsonRecord(candidate);
+            if (record && matchesSession(record, expectedSessionId))
+                return candidate;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+export function readClaudeSessionStatus(path) {
+    const record = readJsonRecord(path);
+    if (!record || typeof record.status !== "string")
+        return undefined;
+    const runnerStatus = STATUS_TO_RUNNER[record.status];
+    if (!runnerStatus)
+        return undefined;
+    const updatedAt = record.statusUpdatedAt;
+    const waitingFor = record.status === "waiting" ? record.waitingFor : undefined;
+    return {
+        runnerStatus,
+        rawStatus: record.status,
+        ...(Number.isSafeInteger(updatedAt) ? { statusUpdatedAt: updatedAt } : {}),
+        ...(typeof waitingFor === "string" && waitingFor ? { blockedOn: waitingFor } : {}),
+    };
+}
+export class ClaudeSessionStatusPoller {
+    options;
+    path;
+    attempts = 0;
+    exhausted = false;
+    lastMtime;
+    lastEdge;
+    lastStatus;
+    constructor(options) {
+        this.options = options;
+    }
+    get active() {
+        return this.path !== undefined && !this.exhausted;
+    }
+    get status() {
+        return this.lastStatus;
+    }
+    tick() {
+        if (this.exhausted)
+            return;
+        if (!this.path) {
+            this.tryResolve();
+            if (!this.path)
+                return;
+        }
+        this.readAndPublish();
+    }
+    retire() {
+        this.exhausted = true;
+    }
+    resync() {
+        if (!this.active)
+            return;
+        this.lastMtime = undefined;
+        this.lastEdge = undefined;
+    }
+    tryResolve() {
+        this.attempts += 1;
+        this.path = resolveClaudeSessionStatusFile({
+            panePid: this.options.panePid(),
+            expectedSessionId: this.options.sessionId(),
+            ...(this.options.configDir ? { configDir: this.options.configDir } : {}),
+            now: this.options.now?.() ?? Date.now(),
+        });
+        if (!this.path &&
+            this.attempts >= (this.options.maxResolveAttempts ?? DEFAULT_MAX_RESOLVE_ATTEMPTS)) {
+            this.exhausted = true;
+        }
+    }
+    readAndPublish() {
+        if (!this.path)
+            return;
+        let mtime;
+        try {
+            mtime = statSync(this.path).mtimeMs;
+        }
+        catch {
+            this.exhausted = true;
+            return;
+        }
+        if (this.lastMtime === mtime)
+            return;
+        this.lastMtime = mtime;
+        const status = readClaudeSessionStatus(this.path);
+        if (!status) {
+            this.lastStatus = undefined;
+            this.lastEdge = undefined;
+            return;
+        }
+        this.lastStatus = status;
+        const edge = `${status.runnerStatus}\0${status.blockedOn ?? ""}`;
+        if (edge === this.lastEdge)
+            return;
+        this.lastEdge = edge;
+        this.options.onStatus(status);
+    }
+}

package/dist/claude/transcript.js

@@ -22,11 +22,32 @@ export function subagentTranscriptPath(parentTranscriptPath, agentId) {
     const dir = parentTranscriptPath.replace(/\.jsonl$/, "");
     return join(dir, "subagents", `agent-${agentId}.jsonl`);
 }
+function strippedImagePlaceholder(source) {
+    const mediaType = source.media_type;
+    const label = typeof mediaType === "string" && mediaType ? `${mediaType} image` : "image";
+    return `[${label} omitted from history to save context — re-run the tool call above (e.g. Read the same path) to view it again]`;
+}
+/** Remove Claude's inline image bytes before tool output reaches canonical
+ *  history. A Read image result can contain a full-resolution base64 payload;
+ *  replaying it as text only bloats the transcript, while the model cannot use
+ *  those encoded bytes as text. Keep a small, human-readable marker instead. */
+function stripInlineImageData(value) {
+    if (Array.isArray(value))
+        return value.map(stripInlineImageData);
+    if (!isObject(value))
+        return value;
+    const source = isObject(value.source) ? value.source : undefined;
+    if (value.type === "image" && source) {
+        return { type: "text", text: strippedImagePlaceholder(source) };
+    }
+    return Object.fromEntries(Object.entries(value).map(([key, nested]) => [key, stripInlineImageData(nested)]));
+}
 function stringifyToolContent(content) {
-    if (typeof content === "string")
-        return content;
-    if (Array.isArray(content)) {
-        return content
+    const stripped = stripInlineImageData(content);
+    if (typeof stripped === "string")
+        return stripped;
+    if (Array.isArray(stripped)) {
+        return stripped
             .map((part) => part && typeof part === "object" && "text" in part
             ? String(part.text ?? "")
             : typeof part === "string"
@@ -34,18 +55,7 @@ function stringifyToolContent(content) {
                 : JSON.stringify(part))
             .join("");
     }
-    return content == null ? "" : JSON.stringify(content);
-}
-function toolLabel(name, input) {
-    if (input && typeof input === "object") {
-        const rec = input;
-        for (const key of ["command", "cmd", "path", "file_path", "pattern", "query"]) {
-            const v = rec[key];
-            if (typeof v === "string" && v)
-                return v;
-        }
-    }
-    return name ?? "tool";
+    return stripped == null ? "" : JSON.stringify(stripped);
 }
 const BASH_INPUT_RE = /<bash-input>([\s\S]*?)<\/bash-input>/;
 const BASH_STDOUT_RE = /<bash-stdout>([\s\S]*?)<\/bash-stdout>/;
@@ -132,7 +142,7 @@ export function parseTranscriptRecord(record, opts) {
                     type: "tool",
                     event: "on_tool_start",
                     name: block.name,
-                    input: { ...(isObject(block.input) ? block.input : {}), id: block.id, command: toolLabel(block.name, block.input) },
+                    input: { ...(isObject(block.input) ? block.input : {}), id: block.id },
                     data: { id: block.id },
                     ...parentTag,
                 });

package/dist/codex-app-server/client.d.ts

@@ -1,5 +1,5 @@
 import type { RuntimeUserInput, SessionInteractionResolution } from "@rynx-ai/core";
-import type { AskForApproval, ClientInfo, CollaborationModeListResponse, GetAuthStatusParams, GetAuthStatusResponse, InitializeResponse, ModelListParams, ModelListResponse, ReviewStartParams, ReviewStartResponse, SandboxMode, ThreadForkParams, ThreadGoalClearParams, ThreadGoalGetParams, ThreadGoalGetResponse, ThreadGoalSetParams, ThreadListParams, ThreadListResponse, ResumedThread, ThreadResumeParams, ThreadSettingsUpdateParams, ThreadStartParams, TurnInterruptParams, TurnStartParams, TurnSteerParams, UserInput } from "./protocol.js";
+import type { AskForApproval, ClientInfo, CollaborationModeListResponse, ConfigReadParams, ConfigReadResponse, GetAuthStatusParams, GetAuthStatusResponse, InitializeResponse, ModelListParams, ModelListResponse, ReviewStartParams, ReviewStartResponse, SandboxMode, ThreadForkParams, ThreadGoalClearParams, ThreadGoalGetParams, ThreadGoalGetResponse, ThreadGoalSetParams, ThreadListParams, ThreadListResponse, ResumedThread, ThreadResumeParams, ThreadRuntimeSettings, ThreadSettingsUpdateParams, ThreadStartParams, TurnInterruptParams, TurnStartParams, TurnSteerParams, UserInput } from "./protocol.js";
 import { CodexAppServerTransport, type CodexAppServerProcessSpawner, type RpcChannel, type TransportLogger } from "./transport.js";
 import type { ResolveInteractionResult, RuntimeInteractionListener } from "../interactions.js";
 export type ApprovalDecisionPolicy = "auto-approve-session" | "auto-decline" | "auto-cancel";
@@ -29,9 +29,11 @@ export declare class CodexAppServerClient {
     private interactionListener;
     private connectionListener;
     private connectionState;
+    private connectionEstablished;
     private readonly pendingInteractions;
     private readonly settledInteractions;
     private initializeResponse;
+    private initializePromise;
     constructor({ spawner, channel, logger, clientInfo, approvalDecisionPolicy, }: CodexAppServerClientOptions);
     /**
      * The multi-client endpoint a `codex --remote` TUI can attach to, when this
@@ -42,13 +44,16 @@ export declare class CodexAppServerClient {
     terminalRemoteUrl(): string | undefined;
     ensureInitialized(): Promise<InitializeResponse>;
     getAuthStatus(params?: GetAuthStatusParams): Promise<GetAuthStatusResponse>;
+    /** Read the runtime's merged effective config. This is the stable seam for
+     * discovering a fresh thread's model across Traex YAML/TOML generations. */
+    configRead(params: ConfigReadParams): Promise<ConfigReadResponse>;
     threadStart(params: ThreadStartParams): Promise<{
         threadId: string;
-    }>;
+    } & ThreadRuntimeSettings>;
     threadResume(params: ThreadResumeParams): Promise<{
         threadId: string;
         thread: ResumedThread;
-    }>;
+    } & ThreadRuntimeSettings>;
     turnStart(params: TurnStartParams): Promise<{
         turnId: string;
     }>;
@@ -94,9 +99,8 @@ export declare class CodexAppServerClient {
      * resolver still wins correctly.
      */
     setInteractionListener(listener: RuntimeInteractionListener | null): void;
-    /** Observe the underlying app-server connection independently from any one
-     * interaction. A disconnected client that never received the duplicate
-     * native request still has to count as unavailable during host failover. */
+    /** Observe the initialized connection lifecycle. Registration never reports
+     * disconnected for a client that has not connected yet. */
     setConnectionListener(listener: ((state: "connected" | "disconnected") => void) | null): void;
     private setConnectionState;
     resolveInteraction(interactionId: string, resolution: SessionInteractionResolution): ResolveInteractionResult;

package/dist/codex-app-server/client.js

@@ -953,9 +953,11 @@ export class CodexAppServerClient {
     interactionListener = null;
     connectionListener = null;
     connectionState = "disconnected";
+    connectionEstablished = false;
     pendingInteractions = new Map();
     settledInteractions = new Set();
     initializeResponse = null;
+    initializePromise = null;
     constructor({ spawner, channel, logger = defaultLogger, clientInfo = DEFAULT_CLIENT_INFO, approvalDecisionPolicy = "auto-approve-session", }) {
         this.logger = logger;
         this.clientInfo = clientInfo;
@@ -988,30 +990,66 @@ export class CodexAppServerClient {
         if (this.initializeResponse) {
             return this.initializeResponse;
         }
-        await this.transport.ensureStarted();
-        const response = await this.transport.sendRequest("initialize", {
-            clientInfo: this.clientInfo,
-            capabilities: { experimentalApi: true },
-        });
-        this.initializeResponse = response;
-        this.setConnectionState("connected");
-        return response;
+        if (this.initializePromise)
+            return this.initializePromise;
+        const initializing = (async () => {
+            await this.transport.ensureStarted();
+            const response = await this.transport.sendRequest("initialize", {
+                clientInfo: this.clientInfo,
+                capabilities: { experimentalApi: true },
+            });
+            // Codex app-server uses the full initialize handshake: it does not accept
+            // capability requests after merely replying to `initialize`. The client
+            // must acknowledge that response with the `initialized` notification
+            // before `thread/resume`, `turn/start`, and the other APIs are legal.
+            await this.transport.sendNotification("initialized");
+            this.initializeResponse = response;
+            this.setConnectionState("connected");
+            return response;
+        })();
+        this.initializePromise = initializing;
+        try {
+            return await initializing;
+        }
+        finally {
+            if (this.initializePromise === initializing)
+                this.initializePromise = null;
+        }
     }
     async getAuthStatus(params = {}) {
         await this.ensureInitialized();
         return this.transport.sendRequest("getAuthStatus", params);
     }
+    /** Read the runtime's merged effective config. This is the stable seam for
+     * discovering a fresh thread's model across Traex YAML/TOML generations. */
+    async configRead(params) {
+        await this.ensureInitialized();
+        return this.transport.sendRequest("config/read", params);
+    }
     async threadStart(params) {
         await this.ensureInitialized();
         const response = await this.transport.sendRequest("thread/start", params);
-        return { threadId: response.thread.id };
+        return {
+            threadId: response.thread.id,
+            ...(response.model ? { model: response.model } : {}),
+            ...(response.reasoningEffort === undefined
+                ? {}
+                : { reasoningEffort: response.reasoningEffort }),
+        };
     }
     async threadResume(params) {
         await this.ensureInitialized();
         const response = await this.transport.sendRequest("thread/resume", params);
         // Expose the whole `thread` (not just its id): its `turns[].items[]` are the
         // backfill the forwarder replays for a fresh thread's first turn.
-        return { threadId: response.thread.id, thread: response.thread };
+        return {
+            threadId: response.thread.id,
+            thread: response.thread,
+            ...(response.model ? { model: response.model } : {}),
+            ...(response.reasoningEffort === undefined
+                ? {}
+                : { reasoningEffort: response.reasoningEffort }),
+        };
     }
     async turnStart(params) {
         await this.ensureInitialized();
@@ -1146,14 +1184,18 @@ export class CodexAppServerClient {
     setInteractionListener(listener) {
         this.interactionListener = listener;
     }
-    /** Observe the underlying app-server connection independently from any one
-     * interaction. A disconnected client that never received the duplicate
-     * native request still has to count as unavailable during host failover. */
+    /** Observe the initialized connection lifecycle. Registration never reports
+     * disconnected for a client that has not connected yet. */
     setConnectionListener(listener) {
         this.connectionListener = listener;
-        listener?.(this.connectionState);
+        if (listener && this.connectionEstablished)
+            listener(this.connectionState);
     }
     setConnectionState(state) {
+        if (state === "connected")
+            this.connectionEstablished = true;
+        if (state === "disconnected" && !this.connectionEstablished)
+            return;
         if (this.connectionState === state)
             return;
         this.connectionState = state;
@@ -1363,7 +1405,17 @@ export function buildTextUserInput(message) {
 export function buildRuntimeUserInput(input) {
     return input.content.map((part) => part.type === "text"
         ? { type: "text", text: part.text, text_elements: [] }
-        : { type: "localImage", path: part.path });
+        : part.type === "local_image"
+            ? { type: "localImage", path: part.path }
+            : {
+                type: "text",
+                text: `[[RYNX_FILE_RESOURCE ${JSON.stringify({
+                    path: part.path,
+                    ...(part.resource.filename ? { filename: part.resource.filename } : {}),
+                    mediaType: part.resource.mediaType,
+                })}]]\nInspect this absolute file path with the available file-reading tools before answering.`,
+                text_elements: [],
+            });
 }
 const defaultLogger = {
     log(entry) {

package/dist/codex-app-server/forwarder.d.ts

@@ -23,20 +23,37 @@
  */
 import type { AgentEvent, UserContentPart } from "@rynx-ai/core";
 import type { CodexAppServerClient } from "./client.js";
-import type { ResumedTurn } from "./protocol.js";
+import type { McpStartupPlan } from "./mcp-startup.js";
+import type { CollaborationModeKind, ReasoningEffort, ResumedTurn } from "./protocol.js";
 export interface CodexForwarderSink {
     /** A turn began. `turnId` is codex's turn id, used to derive a stable
      *  `responseId`. Start a fresh normalizer/response. */
     onTurnStart(turnId?: string): void;
+    /** The observer received the provider's authoritative `turn/started` edge.
+     * Unlike `onTurnStart`, this is not fired early by turn/start acceptance. */
+    onTurnObserved?(turnId?: string): void;
     /** One mapped event within the current turn. */
     onEvent(event: AgentEvent): void;
+    /** Turn-scoped content arrived while no Provider Turn is active. Attach it
+     * to that response without opening a Turn or changing Session status. */
+    onTurnContentEvent?(turnId: string | undefined, event: AgentEvent): void;
+    /** Provider startup is session status, not a model item. Hosts that already
+     * published the response can forward it without synthesizing another start. */
+    onStatus?(note: string | undefined, statusKind?: "startup"): void;
     /** The current turn finished; `usage` is the runtime's raw snapshot if any. */
-    onTurnEnd(usage?: Record<string, unknown>): void;
+    onTurnEnd(usage?: Record<string, unknown>, reason?: "superseded"): void;
+    /** The provider confirmed that the active turn was explicitly interrupted. */
+    onTurnInterrupted?(usage?: Record<string, unknown>): void;
+    /** Resume proved that the newest turn is terminal even though its live edge
+     * was missed. This updates session state without replaying historical items. */
+    onRecoveredTurnStatus?(status: "idle" | "failed", turnId: string | undefined, error?: Error): void;
     /** A turn failed on the runtime. */
     onTurnError(error: Error): void;
     /** The user's turn text (sourced from codex's `userMessage` item), so a
      *  co-driving TUI's prompt is recorded even though this process never injected it. */
     onUserMessage?(content: string | UserContentPart[]): void;
+    /** Out-of-lifecycle counterpart of `onUserMessage`, scoped when possible. */
+    onTurnContentUserMessage?(turnId: string | undefined, content: string | UserContentPart[]): void;
     /** A managed Core fork also broadcasts `thread/started`, but does not switch
      * the source TUI. Discard that notification before changing the bound thread. */
     shouldIgnoreThreadStarted?(threadId: string, forkedFromId?: string): boolean;
@@ -46,6 +63,22 @@ export interface CodexForwarderSink {
     /** The thread showed activity (a turn/item began, so its rollout now exists).
      *  Fired once; lets a parked `thread/resume` retry (reference implementation's ready signal). */
     onThreadActive?(): void;
+    /** The native TUI or another app-server client changed collaboration mode. */
+    onCollaborationModeChanged?(mode: CollaborationModeKind): void;
+    /** Full mutable settings reported by the native thread. In particular, a
+     * TUI `/model` switch must become the model used by the next mode snapshot. */
+    onThreadSettingsChanged?(settings: {
+        model?: string;
+        reasoningEffort?: ReasoningEffort | null;
+    }): void;
+    /** Codex's terminal-local Plan picker is not emitted by app-server today.
+     * Synthesize it only after a live Plan item and its Turn both complete. */
+    onPlanImplementationPrompt?(prompt: CodexPlanImplementationPrompt): void;
+}
+export interface CodexPlanImplementationPrompt {
+    threadId: string;
+    turnId: string;
+    text: string;
 }
 export interface CodexSessionForwarderOptions {
     /** Some Codex-lineage runtimes publish the final item one frame after
@@ -58,6 +91,9 @@ export interface CodexSessionForwarderOptions {
     assistantMessageGraceMs?: number;
     /** Surface Traex's provider-capacity queue as a canonical running status. */
     surfaceQueueStatus?: boolean;
+    /** Provider-configured MCP servers. Their startup round is synthesized because
+     * Codex currently sends per-server edges only to the thread-owning TUI. */
+    mcpStartup?: McpStartupPlan | null;
 }
 export declare class CodexSessionForwarder {
     private readonly client;
@@ -69,9 +105,16 @@ export declare class CodexSessionForwarder {
     private currentThreadIdValue;
     private activeSignaled;
     private completionTimer;
+    /** Turn id retained only for late-item dedup while a terminal response waits
+     * for its bounded output-ordering grace. It is not an active provider turn. */
+    private pendingCompletionTurnId;
     private assistantMessageTimer;
     private deferredAssistantMessage;
     private pendingCompletion;
+    private readonly pendingMcpServers;
+    private readonly failedMcpServers;
+    private mcpStartupTimer;
+    private lastMcpStatusNote;
     /** Completed-item dedup keys already mirrored (live vs resume backfill). Key =
      *  `threadId:turnId:item.id`; anonymous items use a per-(thread,turn) position
      *  counter. Mirrors reference implementation `_completed_item_key` + `synced_item_keys`. */
@@ -79,16 +122,38 @@ export declare class CodexSessionForwarder {
     /** Per-(thread,turn) position counter for items lacking a stable codex id
      *  (peek-then-advance; advanced only on a successful claim). reference implementation anon path. */
     private readonly anonCounters;
+    private pendingPlanImplementation;
+    /** Latest aggregate diff per Turn. Codex republishes the complete diff after
+     * every edit; only the terminal snapshot belongs in transcript history. */
+    private readonly turnDiffByTurn;
+    private replayingBackfill;
     constructor(client: CodexAppServerClient, sink: CodexForwarderSink, options?: CodexSessionForwarderOptions);
     /** Begin mirroring. Idempotent. */
     start(): void;
     stop(): void;
-    /** True while a turn is open — injection uses `turn/steer` then, else `turn/start`. */
+    /** True while the provider owns an active turn, including the short interval
+     * between injection acceptance and observer confirmation. */
     isTurnOpen(): boolean;
     /** The current turn's codex id (only meaningful while {@link isTurnOpen}). */
     currentTurnId(): string | null;
+    /**
+     * Record a turn accepted by the injection connection before the independent
+     * observer receives `turn/started`. This closes the read-decide-RPC-write race:
+     * another web message arriving in that window must steer this turn, not start
+     * a second one.
+     */
+    noteTurnAccepted(turnId: string): void;
+    hasPendingMcpStartup(): boolean;
+    /** Mark and return the startup servers cancelled by a web Stop. */
+    cancelMcpStartup(): string[];
+    /** Diagnostic suffix for an injection failure during Provider startup. */
+    mcpStartupDetail(): string | null;
     /** The bound codex thread id captured from `thread/started` (null until then). */
     threadId(): string | null;
+    /** Seed an already-persisted/resumed thread binding. The bridge retains this
+     * state even when app-server does not rebroadcast `thread/started`, so
+     * terminal-boundary recovery must know it too. */
+    noteThreadBound(threadId: string): void;
     /**
      * Replay the backlog turns from a `thread/resume` response as if they were live
      * `item/completed` notifications — the fresh-thread first-turn backfill. Each
@@ -97,11 +162,21 @@ export declare class CodexSessionForwarder {
      * not doubled.
      */
     replayBackfill(turns: ResumedTurn[]): void;
+    /** Suppress our synthesized picker when a future app-server emits the native
+     * `plan_implementation` request itself. */
+    noteNativePlanImplementationPrompt(turnId?: string): void;
+    /** Fail an open response exactly once when its observer or terminal exits. */
+    failOpenTurn(error: Error): boolean;
     private handle;
     private scheduleCompletion;
     private refreshCompletionGrace;
     private flushPendingCompletion;
     private settle;
+    private handleMcpStartupStatus;
+    private settleMcpStartup;
+    private clearMcpStartupTimer;
+    private emitMcpStartupStatus;
+    private emitMcpStatus;
     /** Map + emit one completed codex item, deduped by a TOTAL key and routing the
      *  user echo to {@link CodexForwarderSink.onUserMessage}. Shared by live + backfill. */
     private processCompletedItem;
@@ -118,4 +193,18 @@ export declare class CodexSessionForwarder {
     private completedItemKey;
     private advanceAnonCounter;
     private ensureTurn;
+    private consumeTurnDiff;
+    /** Start (or confirm) the app-server's authoritative active turn. A newer
+     * start supersedes an older response whose terminal edge arrived late; a
+     * pending Traex completion is flushed first so its final item grace remains
+     * intact. */
+    private beginTurn;
+    /** Active-turn clearing contract:
+     *
+     * - an identified active turn is closed only by the same id;
+     * - an id-less boundary cannot close an identified active turn;
+     * - with no observed active turn, an identified boundary may recover a
+     *   missed start only when it carries the currently-bound thread id. */
+    private terminalBoundaryMatchesActiveTurn;
+    private notificationMatchesCurrentThread;
 }