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

package/dist/codex-app-server/ws-channel.js

@@ -16,6 +16,7 @@ import { spawn } from "node:child_process";
 import { createServer } from "node:net";
 import { WebSocket } from "ws";
 import { createCodexChildEnv } from "../codex-child-env.js";
+import { newRuntimeProcessTag, reconcileRuntimeProcesses, registerRuntimeProcess, runtimeProcessArgv0, runtimeProcessOwnerIdentity, unregisterRuntimeProcess, withRuntimeProcessStateArg, } from "./process-registry.js";
 /** Reserve a free loopback TCP port (best-effort; racy but fine for local use). */
 async function freeLoopbackPort() {
     return await new Promise((resolve, reject) => {
@@ -28,6 +29,7 @@ async function freeLoopbackPort() {
         });
     });
 }
+const DEFAULT_CONNECT_TIMEOUT_MS = 10_000;
 export class WsRpcChannel {
     opts;
     child = null;
@@ -35,12 +37,14 @@ export class WsRpcChannel {
     lineCb = null;
     closeCb = null;
     closedEmitted = false;
+    processTag = null;
+    stopTask = null;
     readyTimeoutMs;
     /** The `ws://IP:PORT` the app-server listens on — pass to the TUI's `--remote`. */
     url = "";
     constructor(opts) {
         this.opts = opts;
-        this.readyTimeoutMs = opts.readyTimeoutMs ?? 15_000;
+        this.readyTimeoutMs = opts.readyTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
     }
     onLine(cb) {
         this.lineCb = cb;
@@ -52,16 +56,48 @@ export class WsRpcChannel {
         return this.ws?.readyState === WebSocket.OPEN;
     }
     async start() {
+        this.stopTask = null;
+        this.closedEmitted = false;
+        if (this.opts.stateDir) {
+            reconcileRuntimeProcesses();
+        }
         const port = await freeLoopbackPort();
         this.url = `ws://127.0.0.1:${port}`;
-        const args = [...this.opts.baseArgs, "--listen", this.url];
+        const baseArgs = this.opts.stateDir
+            ? withRuntimeProcessStateArg(this.opts.baseArgs, this.opts.stateDir)
+            : this.opts.baseArgs;
+        const args = [...baseArgs, "--listen", this.url];
+        const processTag = this.opts.stateDir ? newRuntimeProcessTag() : null;
+        this.processTag = processTag;
         this.child = spawn(this.opts.cliPath, args, {
             stdio: ["ignore", "ignore", "pipe"],
             env: { ...createCodexChildEnv(process.env), ...(this.opts.extraEnv ?? {}) },
+            detached: process.platform !== "win32",
+            ...(processTag ? { argv0: runtimeProcessArgv0(this.opts.cliPath, processTag) } : {}),
+        });
+        const childPid = this.child.pid;
+        if (processTag && this.opts.stateDir && childPid) {
+            registerRuntimeProcess({
+                pid: childPid,
+                pgid: childPid,
+                ownerPid: process.pid,
+                ownerIdentity: runtimeProcessOwnerIdentity(process.pid),
+                sessionTag: processTag,
+                stateDir: this.opts.stateDir,
+            });
+        }
+        this.child.on("exit", (code, signal) => {
+            this.unregisterProcess();
+            this.emitClose(code, signal, null);
         });
-        this.child.on("exit", (code, signal) => this.emitClose(code, signal, null));
         this.child.on("error", (error) => this.emitClose(null, null, error));
-        this.ws = await this.connectWithRetry(this.url);
+        try {
+            this.ws = await this.connectWithRetry(this.url);
+        }
+        catch (error) {
+            await this.stop();
+            throw error;
+        }
         this.ws.on("message", (data) => {
             // One JSON-RPC object per frame (codex ws framing).
             this.lineCb?.(data.toString());
@@ -85,6 +121,12 @@ export class WsRpcChannel {
         });
     }
     async stop(signal = "SIGTERM") {
+        if (this.stopTask)
+            return await this.stopTask;
+        this.stopTask = this.stopOwnedProcess(signal);
+        return await this.stopTask;
+    }
+    async stopOwnedProcess(signal) {
         try {
             this.ws?.close();
         }
@@ -92,14 +134,33 @@ export class WsRpcChannel {
             /* already closing */
         }
         const child = this.child;
-        if (child) {
-            try {
-                child.kill(signal);
-            }
-            catch {
-                /* already gone */
+        if (child && child.exitCode === null && child.signalCode === null) {
+            this.signalChild(child, signal);
+            if (!await waitForExit(child, 5_000)) {
+                this.signalChild(child, "SIGKILL");
+                await waitForExit(child, 2_000);
             }
         }
+        this.unregisterProcess();
+        this.child = null;
+        this.ws = null;
+    }
+    signalChild(child, signal) {
+        try {
+            if (process.platform !== "win32" && child.pid)
+                process.kill(-child.pid, signal);
+            else
+                child.kill(signal);
+        }
+        catch {
+            // Already gone.
+        }
+    }
+    unregisterProcess() {
+        const tag = this.processTag;
+        this.processTag = null;
+        if (tag)
+            unregisterRuntimeProcess(tag);
     }
     emitClose(code, signal, error) {
         if (this.closedEmitted)
@@ -114,7 +175,7 @@ export class WsRpcChannel {
         // eslint-disable-next-line no-constant-condition
         while (Date.now() < deadline) {
             try {
-                return await this.tryConnect(url);
+                return await this.tryConnect(url, Math.max(1, deadline - Date.now()));
             }
             catch (error) {
                 lastError = error;
@@ -123,9 +184,9 @@ export class WsRpcChannel {
         }
         throw new Error(`codex app-server ws did not become ready at ${url}: ${lastError?.message ?? "timeout"}`);
     }
-    tryConnect(url) {
+    tryConnect(url, handshakeTimeout) {
         return new Promise((resolve, reject) => {
-            const ws = new WebSocket(url);
+            const ws = new WebSocket(url, { handshakeTimeout });
             const onOpen = () => {
                 ws.off("error", onError);
                 resolve(ws);
@@ -145,6 +206,22 @@ export class WsRpcChannel {
         });
     }
 }
+function waitForExit(child, timeoutMs) {
+    if (child.exitCode !== null || child.signalCode !== null)
+        return Promise.resolve(true);
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            child.off("exit", onExit);
+            resolve(false);
+        }, timeoutMs);
+        timer.unref?.();
+        const onExit = () => {
+            clearTimeout(timer);
+            resolve(true);
+        };
+        child.once("exit", onExit);
+    });
+}
 /**
  * Connect-only {@link RpcChannel}: attaches an ADDITIONAL client to an app-server
  * someone else already started (a {@link WsRpcChannel}'s `url`) — no spawn. This
@@ -166,7 +243,7 @@ export class ExternalWsChannel {
     /** The `ws://IP:PORT` of the already-running app-server to attach to. */
     url, opts = {}) {
         this.url = url;
-        this.readyTimeoutMs = opts.readyTimeoutMs ?? 15_000;
+        this.readyTimeoutMs = opts.readyTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
     }
     onLine(cb) {
         this.lineCb = cb;
@@ -178,20 +255,16 @@ export class ExternalWsChannel {
         return this.ws?.readyState === WebSocket.OPEN;
     }
     async start() {
-        const deadline = Date.now() + this.readyTimeoutMs;
-        let lastError;
-        while (Date.now() < deadline) {
-            try {
-                this.ws = await this.connect(this.url);
-                break;
-            }
-            catch (error) {
-                lastError = error;
-                await new Promise((r) => setTimeout(r, 150));
-            }
+        // A channel instance is reusable after an observer disconnect. Do not let
+        // the prior closed socket make a failed reconnect look successful, and arm
+        // close delivery for the newly connected socket.
+        this.ws = null;
+        this.closedEmitted = false;
+        try {
+            this.ws = await this.connect(this.url);
         }
-        if (!this.ws) {
-            throw new Error(`could not attach to app-server ws ${this.url}: ${lastError?.message ?? "timeout"}`);
+        catch (error) {
+            throw new Error(`could not attach to app-server ws ${this.url}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
         }
         this.ws.on("message", (data) => this.lineCb?.(data.toString()));
         this.ws.on("close", (code) => this.emitClose(code ?? null, null, null));
@@ -227,7 +300,10 @@ export class ExternalWsChannel {
     }
     connect(url) {
         return new Promise((resolve, reject) => {
-            const ws = new WebSocket(url);
+            // The app-server owner has already completed its readiness probe. Use one
+            // bounded attach, then reuse this exact connection as the forwarder
+            // instead of running a second startup retry stage.
+            const ws = new WebSocket(url, { handshakeTimeout: this.readyTimeoutMs });
             const onOpen = () => {
                 ws.off("error", onError);
                 resolve(ws);

package/dist/codex-home.d.ts

@@ -1,5 +1,16 @@
-import { type AgentRuntimeId } from "@rynx-ai/core";
+import { type AgentRuntimeId, type ResolvedRetryPolicy } from "@rynx-ai/core";
 export type CodexLineageRuntime = Exclude<AgentRuntimeId, "claude">;
+export type CodexAuthMode = "chatgpt" | "apikey" | "pat";
+export type CodexConfigAuth = "provider-ready" | "provider-auth-missing" | "codex-login";
+/** Read the credential mode from Codex's optional-field auth.json shape. */
+export declare function codexAuthEffectiveMode(authPath: string): CodexAuthMode | null;
+/** Mirror Codex's provider-specific auth decision without spawning the CLI. */
+export declare function codexConfigEffectiveAuth(configPath: string, env?: NodeJS.ProcessEnv): CodexConfigAuth;
+/** True only when this exact launch would defer to an absent Codex login. */
+export declare function codexLaunchRequiresLogin(codexHome: string, env?: NodeJS.ProcessEnv): boolean;
+/** Resolve the user's auth/config source without nesting a parent Session's
+ * private CODEX_HOME into a child Session. */
+export declare function resolveCodexHomeConfigSource(candidate: string, defaultHome?: string): string;
 /**
  * The deterministic private CODEX_HOME path for a rynx session. PER-SESSION,
  * under the daemon-owned RYNX_HOME runtime tree,
@@ -22,8 +33,8 @@ export declare function legacyCodexHomePath(): string;
  * `_CODEX_HOME_COPY_FILES`.
  *
  * PER-SESSION: one private home per rynx session (matching reference implementation), so concurrent
- * agents never share a `skills/` dir. Idempotent: the symlink/copy are refreshed each
- * call so a re-login/config change propagates. Returns the private home dir.
+ * agents never share a `skills/` dir. Idempotent: existing Session-owned entries stay
+ * unchanged; live symlinks still observe source credential updates. Returns the private home dir.
  */
 export declare function prepareCodexHome(sessionId: string, realHome?: string): string;
 /**
@@ -32,6 +43,27 @@ 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;
+/** Trust a runner-selected workspace only in the Session's private config so
+ * Codex cannot stop a detached TUI at its project-trust prompt. */
+export declare function trustCodexProject(codexHome: string, cwd: string): void;
+/** Apply the Session retry budget through Codex's supported provider settings.
+ * A config with no provider definitions is left untouched. */
+export declare function applyCodexProviderRetryPolicy(codexHome: string, retry?: ResolvedRetryPolicy | null): void;
+/** Preserve the user's private-home base instructions and append only the raw
+ * Agent-authored text. Repeated launches replace the managed suffix instead of
+ * accumulating it. Invalid user TOML is intentionally left untouched. */
+export declare function syncCodexDeveloperInstructions(codexHome: string, instructions?: string | null): void;
+export type CodexDeveloperInstructionsState = {
+    state: "present";
+    value: string;
+} | {
+    state: "absent";
+} | {
+    state: "unreadable";
+};
+/** Read the active private-home instructions without conflating a definite
+ * absence with malformed or temporarily unreadable config. */
+export declare function readCodexDeveloperInstructionsState(codexHome: string): CodexDeveloperInstructionsState;
 /** 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: {

package/dist/codex-home.js

@@ -1,26 +1,174 @@
 import { randomUUID } from "node:crypto";
-import { copyFileSync, cpSync, existsSync, mkdirSync, renameSync, rmSync, symlinkSync } from "node:fs";
+import { copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
-import { getRuntimeProfile, resolveRuntimeHome, SAFE_SKILL_NAME, } from "@rynx-ai/core";
+import { basename, dirname, join, resolve } from "node:path";
+import { parse, stringify } from "smol-toml";
+import { assertSkillPathComponent, getRuntimeProfile, resolveRuntimeHome, } 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"];
+/** Codex-owned files that must stay live across every private home. */
+const CODEX_SYMLINK_FILES = [
+    "auth.json",
+    ".credentials.json",
+    "memories_1.sqlite",
+    "AGENTS.md",
+    "AGENTS.override.md",
+    "hooks.json",
+];
+/** Large/shared Codex state and cross-process coordination directories. */
+const CODEX_SYMLINK_DIRS = [
+    join("plugins", "cache"),
+    "mcp-oauth-locks",
+    "memories",
+    "rules",
+];
 /** Inherit the user's settings by snapshot copy (not the mutable NUX/update state). */
 const COPY_FILES = ["config.toml"];
 const RUNTIME_HOME_FILES = {
-    codex: { symlink: SYMLINK_FILES, copy: COPY_FILES },
+    codex: {
+        symlink: CODEX_SYMLINK_FILES,
+        symlinkDirs: CODEX_SYMLINK_DIRS,
+        copy: COPY_FILES,
+    },
     traex: {
         // Traex keeps credentials below `cli/`, while its user configuration lives
         // at the TRAE_HOME root. Keep both the current TOML name and the legacy YAML
         // name so existing installations remain usable without an implicit migrate.
         symlink: ["cli/auth.json"],
+        symlinkDirs: [],
         copy: ["traecli.toml", "traecli.yaml"],
     },
 };
+const CODEX_BUILTIN_PROVIDERS = new Set([
+    "openai",
+    "amazon-bedrock",
+    "amazon-bedrock-runtime",
+    "ollama",
+    "lmstudio",
+]);
+function isTomlTable(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Resolve the effective native Provider, honoring the selected profile first. */
+function effectiveCodexModelProvider(config) {
+    let provider = config.model_provider;
+    const activeProfile = config.profile;
+    if (typeof activeProfile === "string" && activeProfile.trim() && isTomlTable(config.profiles)) {
+        const profile = config.profiles[activeProfile];
+        if (isTomlTable(profile) && typeof profile.model_provider === "string") {
+            provider = profile.model_provider;
+        }
+    }
+    return typeof provider === "string" && provider.trim() ? provider : null;
+}
+/** Read the credential mode from Codex's optional-field auth.json shape. */
+export function codexAuthEffectiveMode(authPath) {
+    let data;
+    try {
+        data = JSON.parse(readFileSync(authPath, "utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return null;
+    const auth = data;
+    const tokens = auth.tokens;
+    if (tokens && typeof tokens === "object" && !Array.isArray(tokens)) {
+        const tokenRecord = tokens;
+        for (const field of ["access_token", "refresh_token"]) {
+            const value = tokenRecord[field];
+            if (typeof value === "string" && value.trim())
+                return "chatgpt";
+        }
+    }
+    if (typeof auth.OPENAI_API_KEY === "string" && auth.OPENAI_API_KEY.trim())
+        return "apikey";
+    if (typeof auth.personal_access_token === "string" &&
+        auth.personal_access_token.trim())
+        return "pat";
+    return null;
+}
+/** Mirror Codex's provider-specific auth decision without spawning the CLI. */
+export function codexConfigEffectiveAuth(configPath, env = process.env) {
+    let config;
+    try {
+        config = parse(readFileSync(configPath, "utf8"));
+    }
+    catch {
+        return "codex-login";
+    }
+    const providerId = effectiveCodexModelProvider(config);
+    if (!providerId)
+        return "codex-login";
+    if (CODEX_BUILTIN_PROVIDERS.has(providerId)) {
+        return providerId === "openai" ? "codex-login" : "provider-ready";
+    }
+    const provider = isTomlTable(config.model_providers)
+        ? config.model_providers[providerId]
+        : undefined;
+    if (!isTomlTable(provider))
+        return "provider-auth-missing";
+    if (provider.requires_openai_auth === true)
+        return "codex-login";
+    const envKey = provider.env_key;
+    if (typeof envKey !== "string" || !envKey.trim())
+        return "provider-ready";
+    const value = env[envKey.trim()];
+    return typeof value === "string" && value.trim()
+        ? "provider-ready"
+        : "provider-auth-missing";
+}
+/** True only when this exact launch would defer to an absent Codex login. */
+export function codexLaunchRequiresLogin(codexHome, env = process.env) {
+    return codexConfigEffectiveAuth(join(codexHome, "config.toml"), env) === "codex-login" &&
+        codexAuthEffectiveMode(join(codexHome, "auth.json")) === null;
+}
+function pathExistsOrIsSymlink(path) {
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isPrivateCodexHome(candidate) {
+    const normalized = resolve(candidate);
+    if (basename(normalized) !== "codex-home")
+        return false;
+    const ownerDir = dirname(normalized);
+    const namespace = dirname(ownerDir);
+    const root = dirname(namespace);
+    return (basename(namespace) === "sessions" && basename(root) === "runtime") || basename(namespace) === "codex-native";
+}
+function privateCodexHomeSource(candidate) {
+    const sourceDirs = new Set();
+    for (const name of ["auth.json", ".credentials.json", "memories_1.sqlite"]) {
+        const file = join(candidate, name);
+        try {
+            if (lstatSync(file).isSymbolicLink())
+                sourceDirs.add(dirname(realpathSync(file)));
+        }
+        catch {
+            // Missing or unreadable links do not identify a source home.
+        }
+    }
+    return sourceDirs.size === 1 ? [...sourceDirs][0] : null;
+}
+/** Resolve the user's auth/config source without nesting a parent Session's
+ * private CODEX_HOME into a child Session. */
+export function resolveCodexHomeConfigSource(candidate, defaultHome = join(homedir(), ".codex")) {
+    const source = resolve(candidate);
+    const fallback = resolve(defaultHome);
+    if (source !== fallback && isPrivateCodexHome(source)) {
+        return privateCodexHomeSource(source) ?? fallback;
+    }
+    return source;
+}
 /** The user's real CODEX_HOME (env override, else `~/.codex`). */
 function realCodexHome() {
-    return process.env.CODEX_HOME?.trim() || join(homedir(), ".codex");
+    const fallback = join(homedir(), ".codex");
+    return resolveCodexHomeConfigSource(process.env.CODEX_HOME?.trim() || fallback, fallback);
 }
 /**
  * The deterministic private CODEX_HOME path for a rynx session. PER-SESSION,
@@ -52,8 +200,8 @@ export function legacyCodexHomePath() {
  * `_CODEX_HOME_COPY_FILES`.
  *
  * PER-SESSION: one private home per rynx session (matching reference implementation), so concurrent
- * agents never share a `skills/` dir. Idempotent: the symlink/copy are refreshed each
- * call so a re-login/config change propagates. Returns the private home dir.
+ * agents never share a `skills/` dir. Idempotent: existing Session-owned entries stay
+ * unchanged; live symlinks still observe source credential updates. Returns the private home dir.
  */
 export function prepareCodexHome(sessionId, realHome = realCodexHome()) {
     return prepareRuntimeHome(sessionId, "codex", realHome);
@@ -77,13 +225,9 @@ export function prepareRuntimeHome(sessionId, runtime, realHome = runtime === "c
     for (const name of files.symlink) {
         const src = join(realHome, name);
         const dst = join(dir, name);
+        if (pathExistsOrIsSymlink(dst))
+            continue;
         mkdirSync(dirname(dst), { recursive: true, mode: 0o700 });
-        try {
-            rmSync(dst, { recursive: true, force: true });
-        }
-        catch {
-            // absent — fine
-        }
         if (existsSync(src)) {
             try {
                 symlinkSync(src, dst);
@@ -93,11 +237,35 @@ export function prepareRuntimeHome(sessionId, runtime, realHome = runtime === "c
             }
         }
     }
+    for (const name of files.symlinkDirs) {
+        const src = join(realHome, name);
+        const dst = join(dir, name);
+        let sourceIsDirectory = false;
+        try {
+            sourceIsDirectory = statSync(src).isDirectory();
+        }
+        catch {
+            // Missing/unreadable shared state is optional.
+        }
+        if (!sourceIsDirectory)
+            continue;
+        if (pathExistsOrIsSymlink(dst))
+            continue;
+        mkdirSync(dirname(dst), { recursive: true, mode: 0o700 });
+        try {
+            symlinkSync(src, dst, "dir");
+        }
+        catch {
+            // Best-effort: Codex recreates absent cache/state in its private home.
+        }
+    }
     for (const name of files.copy) {
         const src = join(realHome, name);
         if (existsSync(src)) {
             try {
                 const dst = join(dir, name);
+                if (pathExistsOrIsSymlink(dst))
+                    continue;
                 mkdirSync(dirname(dst), { recursive: true, mode: 0o700 });
                 copyFileSync(src, dst);
             }
@@ -108,14 +276,151 @@ export function prepareRuntimeHome(sessionId, runtime, realHome = runtime === "c
     }
     return dir;
 }
+/** Trust a runner-selected workspace only in the Session's private config so
+ * Codex cannot stop a detached TUI at its project-trust prompt. */
+export function trustCodexProject(codexHome, cwd) {
+    const configPath = join(codexHome, "config.toml");
+    let config = {};
+    if (existsSync(configPath))
+        config = parse(readFileSync(configPath, "utf8"));
+    const projects = isTomlTable(config.projects) ? config.projects : {};
+    config.projects = projects;
+    let projectPath;
+    try {
+        projectPath = realpathSync(cwd);
+    }
+    catch {
+        projectPath = resolve(cwd);
+    }
+    const existingProject = projects[projectPath];
+    const project = isTomlTable(existingProject) ? existingProject : {};
+    project.trust_level = "trusted";
+    projects[projectPath] = project;
+    writeCodexConfig(configPath, config);
+}
+const DEFAULT_CODEX_MAX_RETRIES = 7;
+const DEFAULT_CODEX_REQUEST_TIMEOUT_SECONDS = 120;
+const DEVELOPER_INSTRUCTIONS_BASE_FILE = ".rynx-developer-instructions-base";
+/** Apply the Session retry budget through Codex's supported provider settings.
+ * A config with no provider definitions is left untouched. */
+export function applyCodexProviderRetryPolicy(codexHome, retry) {
+    const configPath = join(codexHome, "config.toml");
+    if (!existsSync(configPath) || lstatSync(configPath).isSymbolicLink())
+        return;
+    const config = parse(readFileSync(configPath, "utf8"));
+    if (!isTomlTable(config.model_providers))
+        return;
+    const maxRetries = retry?.maxRetries ?? DEFAULT_CODEX_MAX_RETRIES;
+    const timeoutSeconds = retry?.timeoutPerRequestSeconds ??
+        DEFAULT_CODEX_REQUEST_TIMEOUT_SECONDS;
+    let changed = false;
+    for (const provider of Object.values(config.model_providers)) {
+        if (!isTomlTable(provider))
+            continue;
+        provider.request_max_retries = maxRetries;
+        provider.stream_max_retries = maxRetries;
+        provider.stream_idle_timeout_ms = Math.trunc(timeoutSeconds * 1_000);
+        changed = true;
+    }
+    if (changed)
+        writeCodexConfig(configPath, config);
+}
+/** Preserve the user's private-home base instructions and append only the raw
+ * Agent-authored text. Repeated launches replace the managed suffix instead of
+ * accumulating it. Invalid user TOML is intentionally left untouched. */
+export function syncCodexDeveloperInstructions(codexHome, instructions) {
+    mkdirSync(codexHome, { recursive: true, mode: 0o700 });
+    const configPath = join(codexHome, "config.toml");
+    if (pathExistsOrIsSymlink(configPath) && lstatSync(configPath).isSymbolicLink()) {
+        try {
+            const source = realpathSync(configPath);
+            const content = readFileSync(source, "utf8");
+            rmSync(configPath, { force: true });
+            writeFileSync(configPath, content, { encoding: "utf8", mode: 0o600 });
+        }
+        catch {
+            return;
+        }
+    }
+    let config;
+    try {
+        config = existsSync(configPath) ? parse(readFileSync(configPath, "utf8")) : {};
+    }
+    catch {
+        return;
+    }
+    const current = config.developer_instructions;
+    if (current !== undefined && typeof current !== "string")
+        return;
+    const addition = instructions?.trim() ?? "";
+    const basePath = join(codexHome, DEVELOPER_INSTRUCTIONS_BASE_FILE);
+    let base;
+    if (existsSync(basePath)) {
+        base = readFileSync(basePath, "utf8");
+    }
+    else {
+        base = typeof current === "string" ? current.trim() : "";
+        if (addition && base === addition) {
+            base = "";
+        }
+        else if (addition && base.endsWith(`\n\n${addition}`)) {
+            base = base.slice(0, -(`\n\n${addition}`).length).trimEnd();
+        }
+        writeFileSync(basePath, base, { encoding: "utf8", mode: 0o600 });
+    }
+    const active = base && addition ? `${base}\n\n${addition}` : base || addition;
+    if (active)
+        config.developer_instructions = active;
+    else
+        delete config.developer_instructions;
+    writeCodexConfig(configPath, config);
+}
+/** Read the active private-home instructions without conflating a definite
+ * absence with malformed or temporarily unreadable config. */
+export function readCodexDeveloperInstructionsState(codexHome) {
+    const configPath = join(codexHome, "config.toml");
+    let source;
+    try {
+        source = readFileSync(configPath, "utf8");
+    }
+    catch (error) {
+        const code = error.code;
+        return code === "ENOENT" || code === "ENOTDIR"
+            ? { state: "absent" }
+            : { state: "unreadable" };
+    }
+    let config;
+    try {
+        config = parse(source);
+    }
+    catch {
+        return { state: "unreadable" };
+    }
+    if (!Object.prototype.hasOwnProperty.call(config, "developer_instructions")) {
+        return { state: "absent" };
+    }
+    const instructions = config.developer_instructions;
+    return typeof instructions === "string" && instructions.trim()
+        ? { state: "present", value: instructions }
+        : { state: "unreadable" };
+}
+function writeCodexConfig(configPath, config) {
+    mkdirSync(dirname(configPath), { recursive: true, mode: 0o700 });
+    const staged = join(dirname(configPath), `.config.toml.${process.pid}.${randomUUID()}`);
+    try {
+        writeFileSync(staged, stringify(config), { encoding: "utf8", mode: 0o600 });
+        renameSync(staged, configPath);
+    }
+    finally {
+        rmSync(staged, { force: true });
+    }
+}
 /** 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");
     for (const skill of skills) {
-        if (!SAFE_SKILL_NAME.test(skill.name)) {
-            throw new Error(`unsafe skill name: ${skill.name}`);
-        }
+        assertSkillPathComponent(skill.name);
     }
     if (skills.length === 0)
         return;