@rynx-ai/runtime 0.1.11-beta.4 → 0.1.11-beta.41

package/dist/codex-session-store.d.ts

@@ -8,6 +8,23 @@ export interface CodexSessionRecord {
      * metadata remains self-contained; this only tells a runner where the
      * Provider persisted its rollout/state. */
     runtimeHomeOwnerSessionId?: string;
+    /** Claude hook/forwarder rendezvous ownership. A rotated target keeps the
+     * physical pane's bridge while the retired logical source is re-keyed to an
+     * isolated bridge; both may still share one Provider runtime home. */
+    bridgeOwnerSessionId?: string;
+    /** Durable recovery edge for a Claude-native `/clear`·`/fork`. The target
+     * binding is written before IPC publication; `published` is flipped only
+     * after the parent durably creates the logical target. */
+    nativeRotationSourceSessionId?: string;
+    /** Authoritative latest published target when this record is the source.
+     * Avoids choosing an arbitrary historical edge after repeated rotations. */
+    nativeRotationTargetSessionId?: string;
+    nativeRotationKind?: "clear" | "fork";
+    nativeRotationPublished?: boolean;
+    /** Stable transcript boundary captured by the rotating forwarder at the
+     * target SessionStart. Clear starts at zero; fork starts after the copied
+     * source prefix. Recovery must not replace this with a later file EOF. */
+    nativeRotationInitialTranscriptOffset?: number;
     updatedAt: string;
 }
 export interface ClaudeForkIntent {
@@ -15,6 +32,12 @@ export interface ClaudeForkIntent {
     sourceSessionId: string;
     sourceClaudeSessionId: string;
     targetClaudeSessionId: string;
+    /** Target transcript atomically cloned before the target runner starts. Its
+     * presence means recovery must resume this exact file, never re-clone a
+     * source that may have advanced since the fork boundary. */
+    forkTranscriptPath?: string;
+    /** Exact byte length of the cloned prefix, measured before Claude starts. */
+    forkTranscriptPrefixBytes?: number;
     updatedAt: string;
 }
 export interface CodexSessionStore {

package/dist/codex-session-store.js

@@ -107,6 +107,27 @@ export class FileCodexSessionStore {
                         ...(record.runtimeHomeOwnerSessionId
                             ? { runtimeHomeOwnerSessionId: record.runtimeHomeOwnerSessionId }
                             : {}),
+                        ...(record.bridgeOwnerSessionId
+                            ? { bridgeOwnerSessionId: record.bridgeOwnerSessionId }
+                            : {}),
+                        ...(record.nativeRotationSourceSessionId
+                            ? { nativeRotationSourceSessionId: record.nativeRotationSourceSessionId }
+                            : {}),
+                        ...(record.nativeRotationTargetSessionId
+                            ? { nativeRotationTargetSessionId: record.nativeRotationTargetSessionId }
+                            : {}),
+                        ...(record.nativeRotationKind
+                            ? { nativeRotationKind: record.nativeRotationKind }
+                            : {}),
+                        ...(record.nativeRotationPublished
+                            ? { nativeRotationPublished: true }
+                            : {}),
+                        ...(Number.isSafeInteger(record.nativeRotationInitialTranscriptOffset) &&
+                            record.nativeRotationInitialTranscriptOffset >= 0
+                            ? {
+                                nativeRotationInitialTranscriptOffset: record.nativeRotationInitialTranscriptOffset,
+                            }
+                            : {}),
                         updatedAt: record.updatedAt,
                     };
                 }

package/dist/host.d.ts

@@ -1,14 +1,35 @@
-import { type ResolvedExecutionSnapshot, type ResolvedExecutionBudget, type RuntimeUserInput, type SessionWorkspaceSnapshot, type SessionInteractionResolution, type SessionEvent } from "@rynx-ai/core";
+import { type ResolvedExecutionSnapshot, type RuntimeTurnOptions, type RuntimeUserInput, type SessionCollaborationMode, type LiveSessionFailure, type SessionWorkspaceSnapshot, type SessionInteractionResolution, type SessionEvent } from "@rynx-ai/core";
 import { type AgentRuntimeId } from "@rynx-ai/core";
 import { type AppConfig } from "@rynx-ai/core";
 import { createCodexChildEnv } from "./codex-child-env.js";
-import type { InjectOutcome } from "./runner/protocol.js";
+import type { InjectResult } from "./runner/protocol.js";
 import type { ResolveInteractionResult } from "./interactions.js";
 import { CodexAppServerClient } from "./codex-app-server/client.js";
 import type { ModelListResponse, ThreadGoal } from "./codex-app-server/protocol.js";
 import { type TerminalInjector } from "./claude/native-integration.js";
 import { FileCodexSessionStore, resolveCodexSessionStorePath, type ClaudeForkIntent, type CodexSessionRecord, type CodexSessionStore } from "./codex-session-store.js";
 import { AgentRuntimeError as CodexRuntimeError } from "@rynx-ai/core";
+/** Delivery policy carried only inside the runner process. It is not part of
+ * the public SessionEvent protocol: the same canonical event has different
+ * retry semantics depending on whether it came from a transcript item, a
+ * terminal hook, or a best-effort live snapshot. */
+export type MirrorDeliveryPolicy = "ordinary" | "terminal-status" | "best-effort" | "compaction" | "compaction-hook";
+export type MirrorDeliveryOutcome = "confirmed" | "ambiguous" | "dropped" | "superseded";
+export interface MirrorDeliveryOptions {
+    policy: MirrorDeliveryPolicy;
+    /** Stable local source key used by the Claude forwarder to checkpoint one
+     * item only after this delivery is handled. It is not sent to SQLite. */
+    sourceId?: string;
+    /** Independent retry lane. Claude native sub-agents use one lane each so a
+     * blocked child cannot stop its siblings or the parent transcript. */
+    lane?: string;
+    /** Claude-local write-only dead letter for an exhausted permanent ordinary
+     * item. No startup path replays this file automatically. */
+    deadLetterPath?: string;
+    /** Internal completion detail for state machines (not part of the wire). */
+    onOutcome?: (outcome: MirrorDeliveryOutcome) => void;
+}
+export type MirrorEmitter = (event: SessionEvent, delivery?: MirrorDeliveryOptions) => void | Promise<void>;
 export { FileCodexSessionStore, resolveCodexSessionStorePath, type CodexSessionRecord, type CodexSessionStore, type ClaudeForkIntent, };
 export interface CodexRuntimeStatus {
     codex_available: boolean;
@@ -99,7 +120,10 @@ export type RetargetMirror = (newSessionId: string, meta: {
     workspace: SessionWorkspaceSnapshot;
     execution: ResolvedExecutionSnapshot;
     parentSessionId?: string;
-}) => void;
+    /** Runs after parent target persistence + child resource transfer, but
+     * before the child proves `rotate.applied` to the parent. */
+    beforeApplied?: () => void | Promise<void>;
+}) => void | Promise<void>;
 export interface LiveSessionOpts {
     /** Immutable Session-owned snapshots. Provider launch/resume never re-opens a
      * Project or Agent template. */
@@ -107,14 +131,6 @@ export interface LiveSessionOpts {
     execution: ResolvedExecutionSnapshot;
     retargetMirror?: RetargetMirror;
 }
-/**
- * The `OPENAI_*` retry env for a codex-lineage app-server spawn, or `undefined`
- * when the budget declares no retry or the runtime is claude. claude applies
- * its retry budget per-run in `buildOptions` (see the claude executor), so it
- * never needs a dedicated app-server.
- */
-export declare function codexRetryEnv(runtime: AgentRuntimeId, budget?: ResolvedExecutionBudget): Record<string, string> | undefined;
-export declare function codexBackendKey(runtime: AgentRuntimeId, budget?: ResolvedExecutionBudget): string;
 export declare class LocalAgentHost implements CodexCapabilities {
     private readonly config;
     private readonly sessionStore;
@@ -122,9 +138,10 @@ export declare class LocalAgentHost implements CodexCapabilities {
     private readonly defaultRuntime;
     private readonly injectedCommandRunner?;
     private readonly injectedAppServerClient?;
-    private readonly clock;
-    private readonly backendIdleTtlMs;
     private readonly forwarderClientFactory;
+    private readonly preloadClientFactory;
+    /** Builds one short-lived message/interrupt client. */
+    private readonly injectionClientFactory;
     private readonly backends;
     private readonly sessionId;
     private readonly runtimeHomeSessionId;
@@ -133,26 +150,31 @@ export declare class LocalAgentHost implements CodexCapabilities {
     private readonly runtimeHomes;
     private readonly liveSessions;
     private readonly liveClaudeSessions;
+    /** Exact pre-live startup failure, retained after the partial handle has been
+     * cleaned up so Core/plugin callers receive the failed phase, not a generic
+     * `live session unavailable` wrapper. */
+    private readonly liveStartupErrors;
     /** Claude forwarders stopped before their terminal is killed. Runner shutdown
      * finalizes these synchronously afterwards to scrub raw interaction answers. */
     private readonly pendingClaudeFinalizers;
+    private readonly pendingCleanupTasks;
     private readonly liveEnsuring;
     private readonly forkingTargets;
     /** Short-lived dedupe for managed fork notifications delivered after the
      * `thread/fork` response. Values are expected source Provider thread ids. */
     private readonly managedForkThreadStarts;
-    constructor({ config, commandRunner, sessionStore, allowedRoots, appServerClient, now, backendIdleTtlMs, forwarderClientFactory, sessionId, runtimeHomeSessionId, }: {
+    constructor({ config, commandRunner, sessionStore, allowedRoots, appServerClient, forwarderClientFactory, preloadClientFactory, injectionClientFactory, sessionId, runtimeHomeSessionId, }: {
         config: AppConfig;
         commandRunner?: CodexCommandRunner;
         sessionStore?: CodexSessionStore;
         allowedRoots?: string[];
         appServerClient?: CodexAppServerClient | null;
-        /** Monotonic-ish clock for idle reaping (tests inject a controllable one). */
-        now?: () => number;
-        /** Idle TTL after which a per-budget composite backend is reaped (ms). */
-        backendIdleTtlMs?: number;
         /** Override the live-session forwarder connection factory (tests inject a fake). */
         forwarderClientFactory?: (appServerUrl: string) => CodexAppServerClient;
+        /** Override the short-lived known-thread preload connection factory. */
+        preloadClientFactory?: (appServerUrl: string) => CodexAppServerClient;
+        /** Override the short-lived message/interrupt connection factory. */
+        injectionClientFactory?: (appServerUrl: string) => CodexAppServerClient;
         /** The rynx session (localThreadId) this host serves — a per-session runner
          *  child sets it from `RYNX_RUNNER_SESSION` so the private CODEX_HOME is
          *  session-scoped. The shared `__cap__` child / tests fall back to a sentinel
@@ -164,20 +186,22 @@ export declare class LocalAgentHost implements CodexCapabilities {
         runtimeHomeSessionId?: string;
     });
     private getBackend;
-    /**
-     * Stop + drop per-budget composite backends that have been idle longer than
-     * the TTL and have no in-flight run. Base per-runtime backends (key === the
-     * bare runtime id) are never reaped — they live for the process lifetime, as
-     * before. There are no per-conversation close hooks, so this lazy sweep (run
-     * on every `getBackend`) is how dedicated app-servers get reclaimed.
-     */
-    private reapIdleBackends;
     private createBackend;
     /** This session's private native home, shared by its app-server + TUI. */
     private runtimeHome;
     private createAppServerClient;
     /** Resolve a pending native question/approval without opening a new Turn. */
     resolveInteraction(localThreadId: string, interactionId: string, resolution: SessionInteractionResolution): Promise<ResolveInteractionResult>;
+    /** Apply collaboration mode to an already-loaded Codex-lineage thread. The
+     * caller persists only after this native RPC succeeds. */
+    updateCollaborationMode(localThreadId: string, mode: SessionCollaborationMode): Promise<void>;
+    /** Apply one explicit collaboration mode to the current native thread and
+     * remember only a successful RPC. A supplied client is already initialized
+     * and remains owned by its caller (used by cold-resume preload). */
+    private applyLiveCollaborationMode;
+    /** Apply pending explicit model/effort settings and, when requested, one
+     * collaboration mode in a single native update. */
+    private applyLiveThreadSettings;
     /**
      * The command to run in a session's live terminal so it co-drives the codex
      * app-server thread (Phase D). Returns `null` when live-terminal is off, the
@@ -187,11 +211,16 @@ export declare class LocalAgentHost implements CodexCapabilities {
      * SAME thread the structured data channel drives.
      */
     codexTerminalSpec(localThreadId: string): Promise<{
+        lifecycle: "required" | "auxiliary";
         command: string;
         args: string[];
         cwd: string;
         env?: Record<string, string>;
         skipTraexStartupPrompts?: boolean;
+        scrollback?: number;
+        tmuxAllowPassthrough?: boolean;
+        tmuxStartOnAttach?: boolean;
+        keepAliveAfterExit?: boolean;
     } | null>;
     /**
      * Bring up (idempotently) a session's persistent codex forwarder and emit its
@@ -207,31 +236,48 @@ export declare class LocalAgentHost implements CodexCapabilities {
      * existing session, the app-server resumes the persisted id. Rynx never writes
      * or repairs Codex's private rollout files.
      */
-    ensureLiveCodexSession(localThreadId: string, emit: (event: SessionEvent) => void, opts: LiveSessionOpts): Promise<boolean>;
+    ensureLiveCodexSession(localThreadId: string, emit: MirrorEmitter, opts: LiveSessionOpts): Promise<boolean>;
     private startLiveCodexSession;
     /** Bind a session's codex thread id once known (TUI broadcast or store): persist
      *  it, unblock injection, and kick off the resume-subscribe loop (once). */
     private onLiveThreadStarted;
+    /** Start the known-thread observer after the replacement TUI has launched.
+     * Fresh sessions already connected their discovery listener before launch;
+     * this is therefore an idempotent no-op for them and for a healthy observer. */
+    startLiveCodexObserver(localThreadId: string): void;
+    /** reference implementation treats the forwarder as a required component of one native
+     * lifecycle: if its transport dies, it closes the app-server instead of
+     * accepting turns that can no longer reach the canonical mirror. */
+    private failObserverLifecycle;
     private shouldIgnoreManagedForkThreadStarted;
     private rememberManagedForkThreadStart;
     /**
      * Subscribe the forwarder connection to a thread (reference implementation's
      * `_subscribe_until_ready`). A fresh TUI thread has no rollout until its first
      * turn, so `thread/resume` is retried: park until the forwarder observes the
-     * thread active, then retry WITHOUT `excludeTurns` so the response backfills the
-     * first turn's items (replayed, deduped against the live stream). Once resume
-     * succeeds, subsequent turns arrive as live notifications on this connection.
+     * thread active, then retry. Like reference implementation, the first attempt always uses
+     * `excludeTurns`: a known-session cold resume therefore never reconstructs
+     * historical running/completed state. Only a fresh thread whose first attempt
+     * failed as not-ready retries without `excludeTurns`, backfilling the newly
+     * materialized first turn and de-duplicating it against live notifications.
      */
     private subscribeUntilReady;
-    /** Await a live session's thread binding (bounded). Returns false on timeout /
+    /** Await a live session's thread binding. `null` leaves the deadline to the
+     *  caller; a number keeps the Provider-local bound. Returns false on timeout /
      *  no live session. Injection and the runner's `live.ready` gate on this. */
-    waitLiveReady(localThreadId: string, timeoutMs?: number): Promise<boolean>;
-    /** Await the stronger Terminal gate: another app-server connection has
-     * successfully resumed the thread, so the detached TUI cannot race rollout
-     * discovery or indexing. */
-    waitTerminalReady(localThreadId: string, timeoutMs?: number): Promise<boolean>;
+    waitLiveReady(localThreadId: string, timeoutMs?: number | null): Promise<boolean>;
+    /** Await the observer subscription diagnostic. Codex/Traex Terminal startup
+     * deliberately does not gate on this promise: the dedicated preload owns resume,
+     * while the independent observer attaches in the background. */
+    waitTerminalReady(localThreadId: string, timeoutMs?: number | null): Promise<boolean>;
     /** Diagnostic from the provider adapter when native discovery/resume failed. */
     liveSessionError(localThreadId: string): string | undefined;
+    /** Structured phase + concrete cause used by the runner wire protocol. */
+    liveSessionFailure(localThreadId: string): LiveSessionFailure | undefined;
+    /** Publish the background TUI/thread discovery failure so an executor
+     * already waiting in the 60s bridge window exits immediately with the exact
+     * 30s discovery cause. */
+    failLiveStartup(localThreadId: string, error: Error): boolean;
     /**
      * Inject a user turn into a session's live codex thread — reference implementation's
      * single-writer web send. `turn/steer` when a turn is open (mid-turn
@@ -239,13 +285,13 @@ export declare class LocalAgentHost implements CodexCapabilities {
      * resumed from the persisted native id. Serialized per session so two
      * injects can't double-open a turn.
      *
-     * Returns an {@link InjectOutcome}: `notLive` when this session has no live
+     * Returns an {@link InjectResult}: `notLive` when this session has no live
      * forwarder (caller may use the run path); `notReady`/`failed` are hard errors
      * the caller reports WITHOUT re-running (re-running double-writes alongside the
      * forwarder). Park-until-ready (~60s), aligning reference implementation's executor waiting for
      * the bridge instead of a short race that falls back to a second output path.
      */
-    injectMessage(localThreadId: string, input: RuntimeUserInput | string): Promise<InjectOutcome>;
+    injectMessage(localThreadId: string, input: RuntimeUserInput | string, options?: RuntimeTurnOptions): Promise<InjectResult>;
     /**
      * Interrupt the session's active turn — the web Stop button. codex: the
      * app-server `turn/interrupt` on the active `{threadId, turnId}` (exactly what
@@ -259,9 +305,16 @@ export declare class LocalAgentHost implements CodexCapabilities {
     stopLiveCodexSession(localThreadId: string, opts?: {
         deferClaudeInteractionCleanup?: boolean;
     }): void;
+    /** Tear down one codex-lineage native runtime without deleting its durable
+     * session-store binding. reference implementation couples its auxiliary Terminal, observer,
+     * forwarder and per-session app-server as one disposable runtime envelope;
+     * the next message recreates that envelope and cold-resumes the native id. */
+    teardownLiveCodexSession(localThreadId: string, error?: Error): boolean;
+    teardownAuxiliaryTerminalRuntime(localThreadId: string): Promise<void>;
     /** Complete the second shutdown phase after the runner has killed all native
      * terminals and hook subprocesses. Must run before the runner process exits. */
-    finalizeStoppedLiveSessions(): void;
+    finalizeStoppedLiveSessions(): Promise<void>;
+    private trackCleanup;
     /** The interactive `claude` TUI spec for a claude-native live session: the real
      *  `claude` binary with rynx's hooks (`--settings`), resuming the bound session.
      *  Trust is pre-seeded so the daemon-spawned TUI never blocks on a first-run
@@ -272,6 +325,11 @@ export declare class LocalAgentHost implements CodexCapabilities {
      * Provider startup never re-opens an Agent template or process-level plugin
      * snapshot. */
     private prepareExecutionSkills;
+    /** Repair the only cross-process crash window in native rotation. A target
+     * started through the Session registry proves that logical publication is
+     * durable; a published target in turn proves its source must no longer own
+     * the shared live bridge. */
+    private reconcileClaudeNativeRotation;
     private startLiveClaudeSession;
     /** Persist claude's discovered session id (reusing the `codexSessionId` store
      *  field, as the claude executor already does) and release the readiness gate. */
@@ -280,7 +338,7 @@ export declare class LocalAgentHost implements CodexCapabilities {
      *  serialized per session. Parks until the thread is ready AND the tmux injector
      *  is (re)attached, then pastes; `injectViaTerminal` RAISES if the prompt never
      *  appears (reference implementation RAISE), so a not-ready pane is a hard error — NOT a
-     *  fall-through-to-run signal. Returns {@link InjectOutcome}. */
+     *  fall-through-to-run signal. Returns {@link InjectResult}. */
     private injectClaude;
     /** Park until the claude session's tmux injector is (re)attached by the
      *  runner-child, or the deadline passes. Pane relaunch re-attaches it via
@@ -288,9 +346,12 @@ export declare class LocalAgentHost implements CodexCapabilities {
      *  would fail and (pre-reference implementation) fall through to a second output path. */
     private waitInjector;
     /** Attach a session's tmux pane injector (from the runner-child, which owns the
-     *  terminal registry — the host does not hold tmux). Ignored for codex sessions
-     *  (they inject via the app-server). Idempotent. */
+     *  terminal registry — the host does not hold tmux). Claude uses it for normal
+     *  message injection; Codex uses it only to dismiss the exact TUI-local Plan
+     *  picker after its synthetic Web form is submitted. Idempotent. */
     attachTerminalInjector(localThreadId: string, injector: TerminalInjector): void;
+    /** Close an active native response when its terminal or runner disappears. */
+    failLiveSession(localThreadId: string, error: Error): boolean;
     /** List the models a runtime exposes (App Server for codex/traex; static for claude). */
     listModels(runtime?: AgentRuntimeId): Promise<ModelListResponse | null>;
     /**
@@ -319,7 +380,3 @@ export declare function isUnsupportedMethodError(error: unknown): boolean;
  *  — a fresh TUI thread before its first turn. Retryable (park until active).
  *  Mirrors reference implementation's `_is_thread_not_ready_error`. */
 export declare function isThreadNotReadyError(error: unknown): boolean;
-/** A persisted thread id that a freshly started app-server cannot load yet.
- * During startup, both errors can be transient while the rollout index catches
- * up. Retry the same id; never use either error as permission to replace it. */
-export declare function isRetryableThreadResumeError(error: unknown): boolean;