@rynx-ai/runtime 0.1.10 → 0.1.11-beta.2

package/dist/codex-session-store.js

@@ -1,8 +1,14 @@
+import { execFile } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { constants as fsConstants } from "node:fs";
-import { access, mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import { access, mkdir, readFile, rename, rm, stat, utimes, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { normalizeRuntimeId } from "@rynx-ai/core";
+import { promisify } from "node:util";
+import { rynxHome, } from "@rynx-ai/core";
+const FILE_LOCK_LEASE_MS = 5_000;
+const FILE_LOCK_HEARTBEAT_MS = 1_000;
+const execFileAsync = promisify(execFile);
+let ownProcessIdentity;
 export class FileCodexSessionStore {
     filePath;
     tail = Promise.resolve();
@@ -44,6 +50,27 @@ export class FileCodexSessionStore {
         }
         return null;
     }
+    async getClaudeForkIntent(targetSessionId) {
+        const data = await this.readAll();
+        return data.claudeForkIntents?.[targetSessionId] ?? null;
+    }
+    async setClaudeForkIntent(intent) {
+        await this.runExclusive(async () => {
+            const data = await this.readAll();
+            data.claudeForkIntents ??= {};
+            data.claudeForkIntents[intent.targetSessionId] = intent;
+            await this.writeAll(data);
+        });
+    }
+    async deleteClaudeForkIntent(targetSessionId) {
+        await this.runExclusive(async () => {
+            const data = await this.readAll();
+            if (!data.claudeForkIntents?.[targetSessionId])
+                return;
+            delete data.claudeForkIntents[targetSessionId];
+            await this.writeAll(data);
+        });
+    }
     async isWritable() {
         try {
             await mkdir(path.dirname(this.filePath), { recursive: true });
@@ -66,14 +93,22 @@ export class FileCodexSessionStore {
             if (!parsed || typeof parsed !== "object") {
                 return {};
             }
-            // Backfill the runtime on legacy records written before multi-runtime
-            // support (default to codex), and normalize the renamed `traecli` runtime
-            // to `traex` so routing and thread-binding checks stay consistent.
+            // The provider binding no longer owns workspace/execution state. Keep
+            // accepting legacy JSON fields, but strip them from the in-memory record
+            // so callers cannot accidentally treat them as a second snapshot.
             if (parsed.sessions) {
-                for (const record of Object.values(parsed.sessions)) {
-                    if (record) {
-                        record.runtime = normalizeRuntimeId(record.runtime) ?? "codex";
-                    }
+                for (const [id, record] of Object.entries(parsed.sessions)) {
+                    if (!record)
+                        continue;
+                    parsed.sessions[id] = {
+                        localThreadId: record.localThreadId,
+                        codexSessionId: record.codexSessionId,
+                        ...(record.parentSessionId ? { parentSessionId: record.parentSessionId } : {}),
+                        ...(record.runtimeHomeOwnerSessionId
+                            ? { runtimeHomeOwnerSessionId: record.runtimeHomeOwnerSessionId }
+                            : {}),
+                        updatedAt: record.updatedAt,
+                    };
                 }
             }
             return parsed;
@@ -98,16 +133,113 @@ export class FileCodexSessionStore {
             release = resolve;
         });
         await previous.catch(() => undefined);
+        let releaseFileLock;
         try {
+            releaseFileLock = await this.acquireFileLock();
             return await task();
         }
         finally {
-            release();
+            try {
+                await releaseFileLock?.();
+            }
+            finally {
+                release();
+            }
+        }
+    }
+    async acquireFileLock() {
+        await mkdir(path.dirname(this.filePath), { recursive: true });
+        const lockPath = `${this.filePath}.lock`;
+        const recoveryPath = `${lockPath}.recovery`;
+        const token = randomUUID();
+        const ownerPath = path.join(lockPath, "owner");
+        ownProcessIdentity ??= processIdentity(process.pid);
+        const processIdentityValue = await ownProcessIdentity;
+        if (!processIdentityValue) {
+            throw new Error("could not resolve Session binding lock process identity");
         }
+        for (let attempt = 0; attempt < 1_000; attempt += 1) {
+            if (await pathExists(recoveryPath)) {
+                await recoverExpiredLockDirectory(recoveryPath);
+                await lockRetryDelay();
+                continue;
+            }
+            if (await publishOwnedLockDirectory(lockPath, token, processIdentityValue)) {
+                const heartbeat = startLockHeartbeat(lockPath);
+                let recoveryWaits = 0;
+                while (await pathExists(recoveryPath)) {
+                    await recoverExpiredLockDirectory(recoveryPath);
+                    recoveryWaits += 1;
+                    if (recoveryWaits >= 1_000) {
+                        clearInterval(heartbeat);
+                        await releaseOwnedLockDirectory(lockPath, token, "release");
+                        throw new Error(`timed out waiting for Session binding store recovery: ${this.filePath}`);
+                    }
+                    await lockRetryDelay();
+                }
+                if (await lockOwnerToken(ownerPath) !== token) {
+                    clearInterval(heartbeat);
+                    continue;
+                }
+                return async () => {
+                    clearInterval(heartbeat);
+                    await releaseOwnedLockDirectory(lockPath, token, "release");
+                };
+            }
+            try {
+                const lockStat = await stat(lockPath);
+                if (Date.now() - lockStat.mtimeMs > FILE_LOCK_LEASE_MS) {
+                    const recoveryToken = randomUUID();
+                    const recoveryOwnerPath = path.join(recoveryPath, "owner");
+                    if (!await publishOwnedLockDirectory(recoveryPath, recoveryToken, processIdentityValue)) {
+                        await lockRetryDelay();
+                        continue;
+                    }
+                    const recoveryHeartbeat = startLockHeartbeat(recoveryPath);
+                    try {
+                        const currentStat = await stat(lockPath);
+                        if (Date.now() - currentStat.mtimeMs <= FILE_LOCK_LEASE_MS) {
+                            continue;
+                        }
+                        const owner = await readLockOwner(ownerPath);
+                        if (owner && await lockOwnerProcessIsCurrent(owner)) {
+                            continue;
+                        }
+                        if (await lockOwnerToken(recoveryOwnerPath) !== recoveryToken) {
+                            continue;
+                        }
+                        const stalePath = `${lockPath}.stale-${randomUUID()}`;
+                        try {
+                            await rename(lockPath, stalePath);
+                            await rm(stalePath, { recursive: true, force: true });
+                        }
+                        catch (error) {
+                            if (!isMissingFileError(error))
+                                throw error;
+                        }
+                    }
+                    finally {
+                        clearInterval(recoveryHeartbeat);
+                        await releaseOwnedLockDirectory(recoveryPath, recoveryToken, "recovery-release");
+                    }
+                    continue;
+                }
+            }
+            catch (error) {
+                if (!isMissingFileError(error))
+                    throw error;
+            }
+            await lockRetryDelay();
+        }
+        throw new Error(`timed out acquiring Session binding store lock: ${this.filePath}`);
     }
 }
-export function resolveCodexSessionStorePath(config) {
-    return path.resolve(config.AGENT_SESSION_STORE_PATH ?? path.join(process.cwd(), ".codex-proxy", "sessions.json"));
+export function resolveCodexSessionStorePath(config, env = process.env) {
+    const home = rynxHome(env);
+    const configured = config.AGENT_SESSION_STORE_PATH;
+    return configured
+        ? path.resolve(home, configured)
+        : path.join(home, ".codex-proxy", "sessions.json");
 }
 async function pathExists(targetPath) {
     try {
@@ -124,3 +256,136 @@ async function pathExists(targetPath) {
 function isMissingFileError(error) {
     return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT");
 }
+async function readLockOwner(ownerPath) {
+    try {
+        const owner = JSON.parse(await readFile(ownerPath, "utf8"));
+        if (!Number.isInteger(owner.pid)
+            || owner.pid <= 0
+            || typeof owner.token !== "string"
+            || (owner.processIdentity !== null && typeof owner.processIdentity !== "string")) {
+            return null;
+        }
+        return owner;
+    }
+    catch {
+        return null;
+    }
+}
+async function lockOwnerToken(ownerPath) {
+    return (await readLockOwner(ownerPath))?.token ?? null;
+}
+async function lockOwnerProcessIsCurrent(owner) {
+    if (!owner.processIdentity)
+        return false;
+    return await processIdentity(owner.pid) === owner.processIdentity;
+}
+async function processIdentity(pid) {
+    try {
+        if (process.platform === "linux") {
+            const [statLine, bootId] = await Promise.all([
+                readFile(`/proc/${pid}/stat`, "utf8"),
+                readFile("/proc/sys/kernel/random/boot_id", "utf8"),
+            ]);
+            const closeParen = statLine.lastIndexOf(")");
+            const fields = statLine.slice(closeParen + 2).trim().split(/\s+/);
+            const startTicks = fields[19];
+            return startTicks ? `linux:${bootId.trim()}:${startTicks}` : null;
+        }
+        if (process.platform === "darwin") {
+            const { stdout } = await execFileAsync("/bin/ps", ["-p", String(pid), "-o", "lstart=", "-o", "command="], {
+                encoding: "utf8",
+                env: { ...process.env, LANG: "C", LC_ALL: "C" },
+            });
+            const startedAt = stdout.trim();
+            return startedAt ? `darwin:${startedAt}` : null;
+        }
+        if (process.platform === "win32") {
+            const { stdout } = await execFileAsync("powershell.exe", [
+                "-NoProfile",
+                "-Command",
+                `(Get-Process -Id ${pid} -ErrorAction Stop).StartTime.ToUniversalTime().Ticks`,
+            ], { encoding: "utf8" });
+            const startedAt = stdout.trim();
+            return startedAt ? `win32:${startedAt}` : null;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+function lockRetryDelay() {
+    return new Promise((resolve) => setTimeout(resolve, 10));
+}
+function startLockHeartbeat(lockPath) {
+    const heartbeat = setInterval(() => {
+        const now = new Date();
+        void utimes(lockPath, now, now).catch(() => undefined);
+    }, FILE_LOCK_HEARTBEAT_MS);
+    heartbeat.unref?.();
+    return heartbeat;
+}
+async function publishOwnedLockDirectory(lockPath, token, processIdentityValue) {
+    const candidatePath = `${lockPath}.claim-${process.pid}-${token}`;
+    await mkdir(candidatePath);
+    try {
+        await writeFile(path.join(candidatePath, "owner"), JSON.stringify({
+            pid: process.pid,
+            processIdentity: processIdentityValue,
+            token,
+        }), "utf8");
+        try {
+            await rename(candidatePath, lockPath);
+            return true;
+        }
+        catch (error) {
+            if (isLockContentionError(error))
+                return false;
+            throw error;
+        }
+    }
+    finally {
+        await rm(candidatePath, { recursive: true, force: true });
+    }
+}
+async function recoverExpiredLockDirectory(lockPath) {
+    try {
+        const lockStat = await stat(lockPath);
+        if (Date.now() - lockStat.mtimeMs <= FILE_LOCK_LEASE_MS)
+            return false;
+        const owner = await readLockOwner(path.join(lockPath, "owner"));
+        if (owner && await lockOwnerProcessIsCurrent(owner))
+            return false;
+        const stalePath = `${lockPath}.stale-${randomUUID()}`;
+        await rename(lockPath, stalePath);
+        await rm(stalePath, { recursive: true, force: true });
+        return true;
+    }
+    catch (error) {
+        if (isMissingFileError(error))
+            return false;
+        throw error;
+    }
+}
+async function releaseOwnedLockDirectory(lockPath, token, suffix) {
+    try {
+        if (await lockOwnerToken(path.join(lockPath, "owner")) !== token)
+            return;
+        const releasePath = `${lockPath}.${suffix}-${token}`;
+        await rename(lockPath, releasePath);
+        await rm(releasePath, { recursive: true, force: true });
+    }
+    catch (error) {
+        if (!isMissingFileError(error))
+            throw error;
+    }
+}
+function isLockContentionError(error) {
+    return Boolean(error
+        && typeof error === "object"
+        && "code" in error
+        && (error.code === "EEXIST"
+            || error.code === "ENOTEMPTY"
+            || error.code === "EACCES"
+            || error.code === "EPERM"));
+}

package/dist/host.d.ts

@@ -1,4 +1,4 @@
-import { type AgentSpec, type ReasoningEffort, type ResolvedExecutionBudget, type RuntimeUserInput, type SessionInteractionResolution, type SessionEvent } from "@rynx-ai/core";
+import { type ResolvedExecutionSnapshot, type ResolvedExecutionBudget, type RuntimeUserInput, 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";
@@ -7,9 +7,9 @@ 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 CodexSessionRecord, type CodexSessionStore } from "./codex-session-store.js";
+import { FileCodexSessionStore, resolveCodexSessionStorePath, type ClaudeForkIntent, type CodexSessionRecord, type CodexSessionStore } from "./codex-session-store.js";
 import { AgentRuntimeError as CodexRuntimeError } from "@rynx-ai/core";
-export { FileCodexSessionStore, resolveCodexSessionStorePath, type CodexSessionRecord, type CodexSessionStore, };
+export { FileCodexSessionStore, resolveCodexSessionStorePath, type CodexSessionRecord, type CodexSessionStore, type ClaudeForkIntent, };
 export interface CodexRuntimeStatus {
     codex_available: boolean;
     logged_in: boolean;
@@ -84,12 +84,6 @@ export interface CodexCapabilities {
     getGoal(localThreadId: string): Promise<CapabilityResult<ThreadGoal | null>>;
     setGoal(localThreadId: string, objective: string): Promise<CapabilityResult>;
     clearGoal(localThreadId: string): Promise<CapabilityResult>;
-    /**
-     * Fork the Codex thread bound to `currentLocalThreadId` and bind the forked
-     * thread (carrying full context) to `newLocalThreadId`, so a new Lark
-     * conversation resumes from it. Used by `/fork`.
-     */
-    forkSession(currentLocalThreadId: string, newLocalThreadId: string): Promise<CapabilityResult>;
 }
 /**
  * Per-session claude-native live handle. claude has no app-server, so the
@@ -102,20 +96,15 @@ export interface CodexCapabilities {
  *  The runner-child owns the mirror emitter + transport, so it supplies this. */
 export type RetargetMirror = (newSessionId: string, meta: {
     kind: "clear" | "fork";
-    agent?: string;
-    model?: string;
-    cwd?: string;
+    workspace: SessionWorkspaceSnapshot;
+    execution: ResolvedExecutionSnapshot;
     parentSessionId?: string;
 }) => void;
 export interface LiveSessionOpts {
-    cwd?: string;
-    runtime?: AgentRuntimeId;
-    reasoningEffort?: ReasoningEffort;
-    /** Preset agent id (or inline {@link LiveSessionOpts.agentSpec}), so the live
-     *  launch applies the agent's model / skills / instructions — not just the
-     *  runtime. Absent ⇒ falls back to the config defaults (prior behavior). */
-    agentName?: string;
-    agentSpec?: AgentSpec;
+    /** Immutable Session-owned snapshots. Provider launch/resume never re-opens a
+     * Project or Agent template. */
+    workspace: SessionWorkspaceSnapshot;
+    execution: ResolvedExecutionSnapshot;
     retargetMirror?: RetargetMirror;
 }
 /**
@@ -138,6 +127,7 @@ export declare class LocalAgentHost implements CodexCapabilities {
     private readonly forwarderClientFactory;
     private readonly backends;
     private readonly sessionId;
+    private readonly runtimeHomeSessionId;
     private sessionSandbox?;
     private sessionApprovalPolicy?;
     private readonly runtimeHomes;
@@ -147,7 +137,11 @@ export declare class LocalAgentHost implements CodexCapabilities {
      * finalizes these synchronously afterwards to scrub raw interaction answers. */
     private readonly pendingClaudeFinalizers;
     private readonly liveEnsuring;
-    constructor({ config, commandRunner, sessionStore, allowedRoots, appServerClient, now, backendIdleTtlMs, forwarderClientFactory, sessionId, }: {
+    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, }: {
         config: AppConfig;
         commandRunner?: CodexCommandRunner;
         sessionStore?: CodexSessionStore;
@@ -164,6 +158,10 @@ export declare class LocalAgentHost implements CodexCapabilities {
          *  session-scoped. The shared `__cap__` child / tests fall back to a sentinel
          *  (its home only backs home-agnostic caps like listModels). */
         sessionId?: string;
+        /** Provider-internal home owner loaded from the durable native binding.
+         * Forked Sessions keep independent runners/contexts while sharing the
+         * Provider store in which thread/fork atomically persisted their rollout. */
+        runtimeHomeSessionId?: string;
     });
     private getBackend;
     /**
@@ -203,19 +201,18 @@ export declare class LocalAgentHost implements CodexCapabilities {
      * DETERMINISTIC (`resp_codex_<turnId>`) so items converge across snapshot/live.
      *
      * Returns false for claude / no app-server (the caller falls back to the
-     * streaming run path). This client CREATES the codex thread (`threadStart`) so
-     * it owns the thread's item/turn notification stream — the app-server delivers
-     * items to the thread-creating connection, for turns started by ANY client (web
-     * inject AND the co-driving `codex --remote` TUI). The TUI pane (launched by the
-     * runner child, which owns the terminal registry) merely `resume`s this thread
-     * to display it. The thread id is persisted so `codexTerminalSpec` resumes it.
+     * streaming run path). For a fresh session the native remote TUI creates the
+     * Codex thread and its `thread/started` notification supplies the id. For an
+     * 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: (event: SessionEvent) => void, opts: LiveSessionOpts): Promise<boolean>;
     private startLiveCodexSession;
-    private refreshLiveCodexSession;
     /** 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;
+    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
@@ -228,11 +225,17 @@ export declare class LocalAgentHost implements CodexCapabilities {
     /** Await a live session's thread binding (bounded). 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>;
+    /** Diagnostic from the provider adapter when native discovery/resume failed. */
+    liveSessionError(localThreadId: string): string | undefined;
     /**
      * 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
-     * supplement), else `turn/start`. NEVER creates a thread (the TUI owns creation;
-     * this targets the id the forwarder captured). Serialized per session so two
+     * supplement), else `turn/start`. The thread was created by the native TUI or
+     * 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
@@ -264,21 +267,10 @@ export declare class LocalAgentHost implements CodexCapabilities {
      *  prompt. Questions and PermissionRequest approvals use the runtime-local
      *  generic interaction bridge and remain inside the active Turn. */
     private claudeTerminalSpec;
-    /** Bring up a claude-native live forwarder: prepare the bridge dir (the TUI's
-     *  hooks write into it), then tail bridge + transcript and drive a per-turn
-     *  {@link SessionNormalizer} → `emit` (the SAME sink shape the codex path uses). */
-    /** Resolve an agent spec's launch config — model, instructions, and the session skill env —
-     *  for a LIVE native session, reusing the same core resolvers the non-live
-     *  run path uses ({@link resolveAgentExecution} for the model,
-     *  {@link resolveAgent} for instructions and skills).
-     *
-     *  Skills are spec-rooted: each declared ref is replayed into a
-     *  SESSION-scoped temp dir (cache-accelerated); the owner's catalog plays no
-     *  role, and no spec / no `skills` means ZERO skills. Every declared skill
-     *  must resolve at its declared content hash; missing, failed, or drifted
-     *  materialization aborts launch before a native session starts.
-     *  `skillsCleanup` removes the session dir (call on session stop). */
-    private resolveLiveAgentConfig;
+    /** Materialize only the immutable skill declarations stored on the Session.
+     * Provider startup never re-opens an Agent template or process-level plugin
+     * snapshot. */
+    private prepareExecutionSkills;
     private startLiveClaudeSession;
     /** Persist claude's discovered session id (reusing the `codexSessionId` store
      *  field, as the claude executor already does) and release the readiness gate. */
@@ -309,7 +301,11 @@ export declare class LocalAgentHost implements CodexCapabilities {
     getGoal(localThreadId: string): Promise<CapabilityResult<ThreadGoal | null>>;
     setGoal(localThreadId: string, objective: string): Promise<CapabilityResult>;
     clearGoal(localThreadId: string): Promise<CapabilityResult>;
-    forkSession(currentLocalThreadId: string, newLocalThreadId: string): Promise<CapabilityResult>;
+    forkSession(currentLocalThreadId: string, newLocalThreadId: string, options?: {
+        workspace: SessionWorkspaceSnapshot;
+        execution: ResolvedExecutionSnapshot;
+    }): Promise<CapabilityResult>;
+    private performForkSession;
 }
 export declare function parseCodexLoginStatus(exitCode: number, output: string): {
     loggedIn: boolean;
@@ -322,3 +318,7 @@ 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;