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

package/dist/claude/native-bridge.js

@@ -13,8 +13,8 @@
  */
 import { appendFileSync, closeSync, mkdirSync, openSync, readFileSync, readSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { createHash } from "node:crypto";
-import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { adoptLegacyRuntimeDirectory, legacyRuntimeStateRoot, runtimeSessionDigest, runtimeSessionStateDir, } from "../runtime-state-paths.js";
 export const HOOKS_FILE = "hooks.jsonl";
 export const STATE_FILE = "state.json";
 export const DELTAS_FILE = "message_deltas.jsonl";
@@ -26,15 +26,9 @@ export const INTERACTION_RESULTS_DIR = "interaction-results";
 export const INTERACTION_CLAIMS_DIR = "interaction-claims";
 export const INTERACTION_LEASES_DIR = "interaction-leases";
 export const MANAGED_SETTINGS_FILE = "managed-settings.json";
-/** Uid-scoped root so other users on a shared host cannot read interaction data. */
-function bridgeRoot() {
-    const uid = typeof process.getuid === "function" ? process.getuid() : "nouid";
-    return join(tmpdir(), `rynx-${uid}`, "claude-native");
-}
 /** The deterministic bridge directory for a rynx session id. */
 export function claudeBridgeDir(sessionId) {
-    const digest = createHash("sha256").update(sessionId).digest("hex").slice(0, 32);
-    return join(bridgeRoot(), digest);
+    return join(runtimeSessionStateDir(sessionId), "claude-bridge");
 }
 /**
  * Create/refresh the bridge dir and clear stale files. Native interactions use
@@ -43,6 +37,7 @@ export function claudeBridgeDir(sessionId) {
  */
 export function prepareClaudeBridgeDir(sessionId) {
     const dir = claudeBridgeDir(sessionId);
+    adoptLegacyRuntimeDirectory(join(legacyRuntimeStateRoot(), "claude-native", runtimeSessionDigest(sessionId)), dir);
     mkdirSync(dir, { recursive: true, mode: 0o700 });
     for (const file of [
         HOOKS_FILE,

package/dist/claude/native-integration.d.ts

@@ -32,6 +32,9 @@ export interface ClaudeForwarderSink {
     /** Fired once SessionStart reveals claude's session id + transcript path, so
      *  the host can persist the id and release its readiness gate. */
     onSessionDiscovered?(claudeSessionId: string, transcriptPath: string): void;
+    /** A resumed TUI announced a different native session id than the persisted
+     *  binding. The host keeps the original binding and fails readiness. */
+    onSessionResumeError?(error: Error): void;
     /** The claude session rotated (`/clear` → fresh, `/fork` → derived): a new
      *  SessionStart reported a new session id + transcript. The forwarder has
      *  already re-pointed to the new transcript and reset its per-session state; the
@@ -45,8 +48,13 @@ export interface ClaudeLiveSessionOptions {
     /** Resume: a known transcript path to tail immediately (else await SessionStart). */
     transcriptPath?: string;
     /** Resume: the claude session id for that transcript — used to match the
-     *  persisted tail cursor so a re-launch resumes instead of re-mirroring. */
+     *  persisted binding. It may be supplied without `transcriptPath`; Claude's
+     *  SessionStart hook remains the source of truth for the actual file path. */
     claudeSessionId?: string;
+    /** Rynx already owns the persisted history for a resumed Session. When no
+     *  matching forwarder cursor exists, follow only records appended after the
+     *  SessionStart discovery instead of mirroring native history a second time. */
+    resumeAtEndOnDiscovery?: boolean;
     /** Poll interval (ms). The files are append-only, so polling is simplest. */
     pollMs?: number;
     /** Inactivity (ms) FALLBACK close for a turn whose Stop hook never fired. */
@@ -83,6 +91,9 @@ export declare class ClaudeLiveSession {
     private discovered;
     /** claude's current session uuid (changes on `/clear`·`/fork`·resume). */
     private currentClaudeSessionId?;
+    /** Persisted native id requested through `claude --resume`. */
+    private readonly expectedClaudeSessionId?;
+    private readonly resumeAtEndOnDiscovery;
     /** Every claude session uuid seen — a resume into an UNSEEN id + a forkedFrom
      *  marker signals a `/fork` (vs. resuming a known branch). */
     private readonly seenClaudeSessionIds;

package/dist/claude/native-integration.js

@@ -155,6 +155,9 @@ export class ClaudeLiveSession {
     discovered = false;
     /** claude's current session uuid (changes on `/clear`·`/fork`·resume). */
     currentClaudeSessionId;
+    /** Persisted native id requested through `claude --resume`. */
+    expectedClaudeSessionId;
+    resumeAtEndOnDiscovery;
     /** Every claude session uuid seen — a resume into an UNSEEN id + a forkedFrom
      *  marker signals a `/fork` (vs. resuming a known branch). */
     seenClaudeSessionIds = new Set();
@@ -223,6 +226,8 @@ export class ClaudeLiveSession {
         this.isProcessAlive = opts.isProcessAlive ?? processIsAlive;
         this.leaseUpdatedAt = opts.interactionLeaseUpdatedAt ??
             ((interactionId) => interactionLeaseUpdatedAt(this.bridgeDir, interactionId));
+        this.expectedClaudeSessionId = opts.claudeSessionId;
+        this.resumeAtEndOnDiscovery = opts.resumeAtEndOnDiscovery ?? false;
         this.transcriptPath = opts.transcriptPath;
         // Resume path: bind the session id + restore the persisted forwarder cursor so
         // we continue from where a prior forwarder left off (no re-mirror on relaunch).
@@ -245,7 +250,7 @@ export class ClaudeLiveSession {
     restoreForwardState(transcriptPath) {
         const state = readForwardState(this.bridgeDir);
         if (!state || state.transcriptPath !== transcriptPath)
-            return;
+            return false;
         for (const id of state.seenSourceIds)
             this.seenSourceIds.add(id);
         const fingerprint = jsonlCursorFingerprint(transcriptPath, state.byteOffset);
@@ -253,6 +258,7 @@ export class ClaudeLiveSession {
             fingerprint !== undefined && fingerprint === state.cursorFingerprint
                 ? state.byteOffset // cursor valid → resume here
                 : fileSize(transcriptPath); // truncated/replaced → skip to EOF
+        return true;
     }
     /** Persist the durable forwarder cursor (byte offset + seen ids + fingerprint). */
     persistForwardState() {
@@ -437,6 +443,11 @@ export class ClaudeLiveSession {
             return;
         // First discovery: bind the transcript + reveal the session id.
         if (!this.transcriptPath) {
+            if (this.expectedClaudeSessionId &&
+                ev.sessionId !== this.expectedClaudeSessionId) {
+                this.sink.onSessionResumeError?.(new Error(`Claude resumed ${ev.sessionId ?? "an unknown session"} instead of ${this.expectedClaudeSessionId}`));
+                return;
+            }
             this.transcriptPath = ev.transcriptPath;
             this.transcriptOffset = 0;
             this.currentClaudeSessionId = ev.sessionId;
@@ -444,7 +455,10 @@ export class ClaudeLiveSession {
                 this.seenClaudeSessionIds.add(ev.sessionId);
             // Resume from the persisted cursor so a relaunched forwarder doesn't re-mirror
             // already-logged turns.
-            this.restoreForwardState(ev.transcriptPath);
+            const restored = this.restoreForwardState(ev.transcriptPath);
+            if (!restored && this.resumeAtEndOnDiscovery) {
+                this.transcriptOffset = fileSize(ev.transcriptPath);
+            }
             if (!this.discovered && ev.sessionId) {
                 this.discovered = true;
                 this.sink.onSessionDiscovered?.(ev.sessionId, ev.transcriptPath);

package/dist/claude/transcript.d.ts

@@ -1,11 +1,4 @@
 import type { AgentEvent, TerminalCommandData } from "@rynx-ai/core";
-/** Claude Code encodes a cwd into a project-dir name by replacing `/` and `.`
- *  with `-` (e.g. `/Users/x/Workspace/rynx` → `-Users-x-Workspace-rynx`). */
-export declare function encodeClaudeProjectDir(cwd: string): string;
-/** The directory Claude Code writes this cwd's session transcripts into. */
-export declare function claudeProjectDir(cwd: string, home?: string): string;
-/** The transcript file for a specific claude session id. */
-export declare function claudeTranscriptPath(cwd: string, sessionId: string, home?: string): string;
 /** A sub-agent (Task) writes its own transcript to
  *  `<project>/<sessionId>/subagents/agent-<agentId>.jsonl`, alongside the parent
  *  `<sessionId>.jsonl`. Derive that path from the parent transcript path. */

package/dist/claude/transcript.js

@@ -1,11 +1,11 @@
 /**
  * Claude Code transcript reader (Phase E, claude-native). Claude Code appends a
- * JSONL transcript per session at
- * `~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl`; the interactive TUI's
- * stdout is a full-screen UI, so — like reference implementation's claude-native — we take the
- * structured story from this file, not the PTY. Each `user`/`assistant` record
- * wraps an Anthropic message (`{ role, content: [blocks] }`), so we map its
- * blocks to the same typed {@link AgentEvent}s the headless executor emits.
+ * JSONL transcript per session. Its `SessionStart` hook supplies the actual
+ * transcript path; Rynx never derives that path from Claude's private directory
+ * layout. The interactive TUI's stdout is a full-screen UI, so we read this
+ * hook-provided file for the UI mirror only. Each `user`/`assistant` record wraps
+ * an Anthropic message (`{ role, content: [blocks] }`), which we map to the same
+ * typed {@link AgentEvent}s the headless executor emits.
  *
  * Records are full messages (not deltas), so text → a completed message,
  * thinking → completed reasoning, tool_use → tool start, tool_result → tool end.
@@ -14,21 +14,7 @@
  */
 import { readFileSync } from "node:fs";
 import { open, stat } from "node:fs/promises";
-import { homedir } from "node:os";
 import { join } from "node:path";
-/** Claude Code encodes a cwd into a project-dir name by replacing `/` and `.`
- *  with `-` (e.g. `/Users/x/Workspace/rynx` → `-Users-x-Workspace-rynx`). */
-export function encodeClaudeProjectDir(cwd) {
-    return cwd.replace(/[/.]/g, "-");
-}
-/** The directory Claude Code writes this cwd's session transcripts into. */
-export function claudeProjectDir(cwd, home = homedir()) {
-    return join(home, ".claude", "projects", encodeClaudeProjectDir(cwd));
-}
-/** The transcript file for a specific claude session id. */
-export function claudeTranscriptPath(cwd, sessionId, home = homedir()) {
-    return join(claudeProjectDir(cwd, home), `${sessionId}.jsonl`);
-}
 /** A sub-agent (Task) writes its own transcript to
  *  `<project>/<sessionId>/subagents/agent-<agentId>.jsonl`, alongside the parent
  *  `<sessionId>.jsonl`. Derive that path from the parent transcript path. */

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

@@ -67,7 +67,8 @@ export declare class CodexAppServerClient {
     threadFork(params: ThreadForkParams): Promise<{
         thread: {
             id: string;
-        };
+            forkedFromId?: string | null;
+        } & Record<string, unknown>;
     } & Record<string, unknown>>;
     /** Update per-thread settings (model / mode / personality / sandbox …). */
     threadSettingsUpdate(params: ThreadSettingsUpdateParams): Promise<Record<string, unknown>>;

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

@@ -37,9 +37,12 @@ export interface CodexForwarderSink {
     /** 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;
+    /** 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;
     /** A thread was announced on the app-server (a `--remote` TUI creating a thread,
      *  or a resume). The host persists the id + starts the subscribe loop. */
-    onThreadStarted?(threadId: string): void;
+    onThreadStarted?(threadId: string, forkedFromId?: string): void;
     /** 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;

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

@@ -115,11 +115,29 @@ export class CodexSessionForwarder {
         if (method === "thread/started" || method === "thread.started") {
             const tid = threadIdFrom(params);
             if (tid && tid !== this.currentThreadIdValue) {
+                const forkedFromId = params?.thread?.forkedFromId;
+                const normalizedForkedFromId = typeof forkedFromId === "string" ? forkedFromId : undefined;
+                if (this.sink.shouldIgnoreThreadStarted?.(tid, normalizedForkedFromId)) {
+                    return;
+                }
+                this.flushPendingCompletion();
+                this.flushDeferredAssistantMessage();
+                if (this.turnOpen) {
+                    this.turnOpen = false;
+                    this.sink.onTurnEnd();
+                }
+                this.currentTurnIdValue = null;
+                this.activeSignaled = false;
                 this.currentThreadIdValue = tid;
-                this.sink.onThreadStarted?.(tid);
+                this.sink.onThreadStarted?.(tid, normalizedForkedFromId);
             }
             return;
         }
+        const notificationThreadId = threadIdFrom(params);
+        if (this.currentThreadIdValue &&
+            notificationThreadId &&
+            notificationThreadId !== this.currentThreadIdValue)
+            return;
         // Release a parked resume as soon as the thread shows activity (rollout now
         // exists). Fire once.
         if (!this.activeSignaled && indicatesActive(method, params)) {

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

@@ -58,14 +58,46 @@ export interface GetAuthStatusResponse {
 }
 export type AskForApproval = "untrusted" | "on-failure" | "on-request" | "never";
 export type SandboxMode = "read-only" | "workspace-write" | "danger-full-access";
+export type SandboxPolicy = {
+    type: "readOnly";
+    networkAccess: boolean;
+} | {
+    type: "externalSandbox";
+    networkAccess: "restricted" | "enabled";
+} | {
+    type: "workspaceWrite";
+    writableRoots: string[];
+    networkAccess: boolean;
+    excludeTmpdirEnvVar: boolean;
+    excludeSlashTmp: boolean;
+} | {
+    type: "dangerFullAccess";
+};
+/** Traex 0.200 named permission profile selection. Codex currently accepts a
+ * string profile id instead, so callers must choose the runtime-specific shape. */
+export interface PermissionProfileSelectionParams {
+    type: "profile";
+    id: string;
+    modifications?: PermissionProfileModificationParams[] | null;
+}
+export interface PermissionProfileModificationParams {
+    type: "additionalWritableRoot";
+    path: string;
+}
+export type PermissionSelection = string | PermissionProfileSelectionParams;
 /** Open since Codex App Server 0.144; values are advertised by `model/list`. */
 export type ReasoningEffort = string;
 export interface ThreadStartParams {
     model?: string | null;
     modelProvider?: string | null;
     cwd?: string | null;
+    /** Codex-only runtime workspace roots. Traex uses a permission selection with
+     * `additionalWritableRoot` modifications instead. */
+    runtimeWorkspaceRoots?: string[] | null;
     approvalPolicy?: AskForApproval | null;
     sandbox?: SandboxMode | null;
+    /** Named permissions profile. Cannot be combined with `sandbox`. */
+    permissions?: PermissionSelection | null;
     config?: Record<string, unknown> | null;
     baseInstructions?: string | null;
     developerInstructions?: string | null;
@@ -115,7 +147,12 @@ export interface TurnStartParams {
     threadId: string;
     input: UserInput[];
     cwd?: string | null;
+    /** Codex-only sticky runtime workspace roots. */
+    runtimeWorkspaceRoots?: string[] | null;
     approvalPolicy?: AskForApproval | null;
+    sandboxPolicy?: SandboxPolicy | null;
+    /** Named permissions profile. Cannot be combined with `sandboxPolicy`. */
+    permissions?: PermissionSelection | null;
     model?: string | null;
     effort?: ReasoningEffort | null;
 }
@@ -240,18 +277,25 @@ export interface ThreadListResponse {
 }
 export interface ThreadForkParams {
     threadId: string;
+    /** Omit the copied turn backlog from the RPC response. The Provider still
+     * persists and inherits the complete thread context. */
+    excludeTurns?: boolean;
     path?: string | null;
     model?: string | null;
     modelProvider?: string | null;
     cwd?: string | null;
+    /** Codex-only runtime workspace roots. */
+    runtimeWorkspaceRoots?: string[] | null;
     approvalPolicy?: AskForApproval | null;
     sandbox?: SandboxMode | null;
+    /** Named permissions profile. Cannot be combined with `sandbox`. */
+    permissions?: PermissionSelection | null;
 }
 export interface ThreadSettingsUpdateParams {
     threadId: string;
     cwd?: string | null;
     approvalPolicy?: AskForApproval | null;
-    sandboxPolicy?: Record<string, unknown> | null;
+    sandboxPolicy?: SandboxPolicy | null;
     /** Named permissions profile id; cannot be combined with `sandboxPolicy`. */
     permissions?: string | null;
     model?: string | null;

package/dist/codex-home.d.ts

@@ -1,11 +1,11 @@
 import { type AgentRuntimeId } from "@rynx-ai/core";
 export type CodexLineageRuntime = Exclude<AgentRuntimeId, "claude">;
 /**
- * The deterministic private CODEX_HOME path for a rynx session. PER-SESSION
- * (uid-scoped + `sha256(sessionId)[:32]`), mirroring reference implementation's per-session
+ * The deterministic private CODEX_HOME path for a rynx session. PER-SESSION,
+ * under the daemon-owned RYNX_HOME runtime tree,
  * `bridge_dir/codex-home` and rynx's own `claudeBridgeDir`. Pure — computes the
- * path without touching disk, so the daemon (rollout-synth) and the runner child
- * (app-server) both locate the SAME session's home from `sessionId` alone.
+ * path without touching disk, so the runner child and its app-server locate the
+ * SAME Rynx-owned runtime home from `sessionId` alone.
  */
 export declare function codexHomePath(sessionId: string): string;
 /** Deterministic private home for a Codex-lineage runtime. */
@@ -16,9 +16,9 @@ export declare function legacyCodexHomePath(): string;
 /**
  * Prepare a private CODEX_HOME that inherits the user's login (symlinked
  * `auth.json`) and settings (copied `config.toml`) but NOT the real home's pending
- * update / first-run (NUX) state — so a co-driven `codex` app-server + `--remote`
- * TUI never block on an "Update now / Press enter to continue" prompt (which would
- * wedge terminal injection). Ports reference implementation's `_CODEX_HOME_SYMLINK_FILES` /
+ * update / first-run (NUX) state. Managed TUI launches separately disable
+ * startup update checks, while keeping this mutable state isolated from the
+ * user's real home. Ports reference implementation's `_CODEX_HOME_SYMLINK_FILES` /
  * `_CODEX_HOME_COPY_FILES`.
  *
  * PER-SESSION: one private home per rynx session (matching reference implementation), so concurrent
@@ -32,25 +32,8 @@ export declare function prepareCodexHome(sessionId: string, realHome?: string):
  * real home and cannot wedge a managed app-server/TUI pair.
  */
 export declare function prepareRuntimeHome(sessionId: string, runtime: CodexLineageRuntime, realHome?: string): string;
-/**
- * Link a resolved skill set into `<codexHome>/skills/<name>/` so the native Codex
- * discovers them at `$CODEX_HOME/skills/` — the SAME filesystem mechanism reference implementation
- * uses (`populate_codex_skills_from_bundle` → `_populate_codex_skills`), NOT a
- * `<skills_instructions>` block injected into the prompt. Codex's app-server
- * watches this dir and re-scans on change, so a live `codex --remote` TUI — whose
- * thread rynx never creates, so it can't carry `threadStart.developerInstructions`
- * — still sees the agent's skills.
- *
- * Each skill is a symlink to its source dir; a filesystem without symlink support
- * falls back to a recursive copy (matches reference implementation's fallback).
- *
- * reference implementation boots a fresh per-session CODEX_HOME, so it only ever links into an
- * empty dir. rynx shares ONE private home per runtime (see {@link prepareCodexHome}),
- * so this CONVERGES the dir to `skills`: it links the missing ones and removes
- * entries no longer selected, honouring the agent spec's gating. (Concurrent
- * sessions of DIFFERENT agents on one runtime share this dir — the same shared-home
- * tradeoff already accepted for auth/config.)
- */
+/** Persist immutable skill copies in a native Provider home. Fork descendants
+ * share that home, so entries must outlive every runner's temporary sources. */
 export declare function populateCodexSkills(codexHome: string, skills: {
     name: string;
     dir: string;

package/dist/codex-home.js

@@ -1,8 +1,9 @@
-import { copyFileSync, cpSync, existsSync, mkdirSync, readdirSync, rmSync, symlinkSync } from "node:fs";
-import { createHash } from "node:crypto";
-import { homedir, tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+import { copyFileSync, cpSync, existsSync, mkdirSync, renameSync, rmSync, symlinkSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-import { getRuntimeProfile, resolveRuntimeHome, } from "@rynx-ai/core";
+import { getRuntimeProfile, resolveRuntimeHome, SAFE_SKILL_NAME, } from "@rynx-ai/core";
+import { adoptLegacyRuntimeDirectory, legacyRuntimeStateRoot, runtimeSessionDigest, runtimeSessionStateDir, } from "./runtime-state-paths.js";
 /** Inherit the user's LIVE login by symlink (stays in sync). */
 const SYMLINK_FILES = ["auth.json"];
 /** Inherit the user's settings by snapshot copy (not the mutable NUX/update state). */
@@ -21,40 +22,33 @@ const RUNTIME_HOME_FILES = {
 function realCodexHome() {
     return process.env.CODEX_HOME?.trim() || join(homedir(), ".codex");
 }
-/** Uid-scoped root so other users on a shared host can't read the tree. */
-function rynxUidRoot() {
-    const uid = typeof process.getuid === "function" ? process.getuid() : "nouid";
-    return join(tmpdir(), `rynx-${uid}`);
-}
 /**
- * The deterministic private CODEX_HOME path for a rynx session. PER-SESSION
- * (uid-scoped + `sha256(sessionId)[:32]`), mirroring reference implementation's per-session
+ * The deterministic private CODEX_HOME path for a rynx session. PER-SESSION,
+ * under the daemon-owned RYNX_HOME runtime tree,
  * `bridge_dir/codex-home` and rynx's own `claudeBridgeDir`. Pure — computes the
- * path without touching disk, so the daemon (rollout-synth) and the runner child
- * (app-server) both locate the SAME session's home from `sessionId` alone.
+ * path without touching disk, so the runner child and its app-server locate the
+ * SAME Rynx-owned runtime home from `sessionId` alone.
  */
 export function codexHomePath(sessionId) {
-    const digest = createHash("sha256").update(sessionId).digest("hex").slice(0, 32);
-    return join(rynxUidRoot(), "codex-native", digest, "codex-home");
+    return join(runtimeSessionStateDir(sessionId), "codex-home");
 }
 /** Deterministic private home for a Codex-lineage runtime. */
 export function runtimeHomePath(sessionId, runtime) {
     if (runtime === "codex")
         return codexHomePath(sessionId);
-    const digest = createHash("sha256").update(sessionId).digest("hex").slice(0, 32);
-    return join(rynxUidRoot(), "traex-native", digest, "trae-home");
+    return join(runtimeSessionStateDir(sessionId), "trae-home");
 }
 /** The OLD uid-scoped shared home (pre per-session). Kept ONLY for back-compat
  *  resume fallback — a session's rollout may still live under here. */
 export function legacyCodexHomePath() {
-    return join(rynxUidRoot(), "codex-home");
+    return join(legacyRuntimeStateRoot(), "codex-home");
 }
 /**
  * Prepare a private CODEX_HOME that inherits the user's login (symlinked
  * `auth.json`) and settings (copied `config.toml`) but NOT the real home's pending
- * update / first-run (NUX) state — so a co-driven `codex` app-server + `--remote`
- * TUI never block on an "Update now / Press enter to continue" prompt (which would
- * wedge terminal injection). Ports reference implementation's `_CODEX_HOME_SYMLINK_FILES` /
+ * update / first-run (NUX) state. Managed TUI launches separately disable
+ * startup update checks, while keeping this mutable state isolated from the
+ * user's real home. Ports reference implementation's `_CODEX_HOME_SYMLINK_FILES` /
  * `_CODEX_HOME_COPY_FILES`.
  *
  * PER-SESSION: one private home per rynx session (matching reference implementation), so concurrent
@@ -73,6 +67,11 @@ export function prepareRuntimeHome(sessionId, runtime, realHome = runtime === "c
     ? realCodexHome()
     : resolveRuntimeHome(getRuntimeProfile(runtime))) {
     const dir = runtimeHomePath(sessionId, runtime);
+    const digest = runtimeSessionDigest(sessionId);
+    const legacy = runtime === "codex"
+        ? join(legacyRuntimeStateRoot(), "codex-native", digest, "codex-home")
+        : join(legacyRuntimeStateRoot(), "traex-native", digest, "trae-home");
+    adoptLegacyRuntimeDirectory(legacy, dir);
     mkdirSync(dir, { recursive: true, mode: 0o700 });
     const files = RUNTIME_HOME_FILES[runtime];
     for (const name of files.symlink) {
@@ -109,58 +108,31 @@ export function prepareRuntimeHome(sessionId, runtime, realHome = runtime === "c
     }
     return dir;
 }
-/**
- * Link a resolved skill set into `<codexHome>/skills/<name>/` so the native Codex
- * discovers them at `$CODEX_HOME/skills/` — the SAME filesystem mechanism reference implementation
- * uses (`populate_codex_skills_from_bundle` → `_populate_codex_skills`), NOT a
- * `<skills_instructions>` block injected into the prompt. Codex's app-server
- * watches this dir and re-scans on change, so a live `codex --remote` TUI — whose
- * thread rynx never creates, so it can't carry `threadStart.developerInstructions`
- * — still sees the agent's skills.
- *
- * Each skill is a symlink to its source dir; a filesystem without symlink support
- * falls back to a recursive copy (matches reference implementation's fallback).
- *
- * reference implementation boots a fresh per-session CODEX_HOME, so it only ever links into an
- * empty dir. rynx shares ONE private home per runtime (see {@link prepareCodexHome}),
- * so this CONVERGES the dir to `skills`: it links the missing ones and removes
- * entries no longer selected, honouring the agent spec's gating. (Concurrent
- * sessions of DIFFERENT agents on one runtime share this dir — the same shared-home
- * tradeoff already accepted for auth/config.)
- */
+/** Persist immutable skill copies in a native Provider home. Fork descendants
+ * share that home, so entries must outlive every runner's temporary sources. */
 export function populateCodexSkills(codexHome, skills) {
     const skillsDir = join(codexHome, "skills");
-    const want = new Map(skills.map((s) => [s.name, s.dir]));
-    // Converge: drop entries no longer selected (shared-home adaptation; reference implementation's
-    // per-session home never needs this). `.system` holds codex's own embedded system
-    // skills (the app-server installs them into `$CODEX_HOME/skills/.system`) — never
-    // rynx-managed, so leave it untouched; only converge the entries we linked.
-    if (existsSync(skillsDir)) {
-        for (const name of readdirSync(skillsDir)) {
-            if (name === ".system")
-                continue;
-            if (!want.has(name))
-                rmSync(join(skillsDir, name), { recursive: true, force: true });
+    for (const skill of skills) {
+        if (!SAFE_SKILL_NAME.test(skill.name)) {
+            throw new Error(`unsafe skill name: ${skill.name}`);
         }
     }
-    if (want.size === 0)
+    if (skills.length === 0)
         return;
     mkdirSync(skillsDir, { recursive: true });
-    for (const [name, src] of want) {
-        const link = join(skillsDir, name);
-        rmSync(link, { recursive: true, force: true });
+    for (const { name, dir } of skills) {
+        const target = join(skillsDir, name);
+        if (existsSync(target))
+            continue;
+        const staged = join(skillsDir, `.rynx-${name}-${process.pid}-${randomUUID()}`);
         try {
-            symlinkSync(src, link);
+            cpSync(dir, staged, { recursive: true, errorOnExist: true, force: false });
+            renameSync(staged, target);
         }
-        catch {
-            // no symlink support (e.g. some Windows configs) → copy. A skill-link failure
-            // must not break the terminal launch, so swallow a copy failure too.
-            try {
-                cpSync(src, link, { recursive: true });
-            }
-            catch {
-                // best-effort
-            }
+        catch (error) {
+            rmSync(staged, { recursive: true, force: true });
+            if (!existsSync(target))
+                throw error;
         }
     }
 }

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

@@ -1,17 +1,20 @@
-import { type AgentRuntimeId, type ReasoningEffort } from "@rynx-ai/core";
 import type { AppConfig } from "@rynx-ai/core";
 export interface CodexSessionRecord {
     localThreadId: string;
     codexSessionId: string;
-    cwd: string;
-    model: string;
-    reasoningEffort?: ReasoningEffort;
-    /** Runtime this thread is bound to. Legacy records backfill to `codex`. */
-    runtime: AgentRuntimeId;
-    /** Declarative agent spec name bound to this thread, if any. */
-    agent?: string;
-    /** The source rynx session this one was derived from (claude `/fork`). */
+    /** The source rynx Session this Provider-native fork was derived from. */
     parentSessionId?: string;
+    /** Provider-internal durable home ownership for native forks. Machine Session
+     * metadata remains self-contained; this only tells a runner where the
+     * Provider persisted its rollout/state. */
+    runtimeHomeOwnerSessionId?: string;
+    updatedAt: string;
+}
+export interface ClaudeForkIntent {
+    targetSessionId: string;
+    sourceSessionId: string;
+    sourceClaudeSessionId: string;
+    targetClaudeSessionId: string;
     updatedAt: string;
 }
 export interface CodexSessionStore {
@@ -25,6 +28,11 @@ export interface CodexSessionStore {
     listAll(): Promise<CodexSessionRecord[]>;
     /** Reverse lookup by Codex thread id (the rollout-file UUID). */
     findByCodexSessionId(codexSessionId: string): Promise<CodexSessionRecord | null>;
+    /** A Claude fork is not a Provider binding until the target TUI has emitted a
+     * matching SessionStart. Keep its launch intent in a separate namespace. */
+    getClaudeForkIntent?(targetSessionId: string): Promise<ClaudeForkIntent | null>;
+    setClaudeForkIntent?(intent: ClaudeForkIntent): Promise<void>;
+    deleteClaudeForkIntent?(targetSessionId: string): Promise<void>;
 }
 export declare class FileCodexSessionStore implements CodexSessionStore {
     readonly filePath: string;
@@ -35,9 +43,13 @@ export declare class FileCodexSessionStore implements CodexSessionStore {
     delete(localThreadId: string): Promise<void>;
     listAll(): Promise<CodexSessionRecord[]>;
     findByCodexSessionId(codexSessionId: string): Promise<CodexSessionRecord | null>;
+    getClaudeForkIntent(targetSessionId: string): Promise<ClaudeForkIntent | null>;
+    setClaudeForkIntent(intent: ClaudeForkIntent): Promise<void>;
+    deleteClaudeForkIntent(targetSessionId: string): Promise<void>;
     isWritable(): Promise<boolean>;
     private readAll;
     private writeAll;
     private runExclusive;
+    private acquireFileLock;
 }
-export declare function resolveCodexSessionStorePath(config: AppConfig): string;
+export declare function resolveCodexSessionStorePath(config: AppConfig, env?: NodeJS.ProcessEnv): string;