The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
feat(runner): isolate Codex runtime context (#12376)
Dottafd7cb77d8e95
diff --git a/packages/paperclip-runner/src/drivers/native-mcp.ts b/packages/paperclip-runner/src/drivers/native-mcp.tsnew file mode 100644index 0000000000..41dfa96652--- /dev/null+++ b/packages/paperclip-runner/src/drivers/native-mcp.ts@@ -0,0 +1,41 @@+export interface NativeMcpLaunchBinding {+ name: string;+ url: string;+ token: string;+}++export function nativeMcpLaunchBinding(+ environment: NodeJS.ProcessEnv = process.env,+): NativeMcpLaunchBinding | null {+ const name = environment.PAPERCLIP_NATIVE_MCP_NAME?.trim();+ const url = environment.PAPERCLIP_NATIVE_MCP_URL?.trim();+ const token = environment.PAPERCLIP_NATIVE_MCP_TOKEN?.trim();+ if (!name && !url && !token) return null;+ if (+ !name+ || !url+ || !token+ || token.length < 32+ || token.length > 4096+ || url.length > 2048+ ) {+ throw new Error("assigned native MCP launch binding is incomplete");+ }+ if (!/^[a-zA-Z0-9_.-]{1,128}$/.test(name)) {+ throw new Error("assigned native MCP name is invalid");+ }+ const endpoint = new URL(url);+ if (endpoint.username || endpoint.password || endpoint.hash) {+ throw new Error("assigned native MCP endpoint contains forbidden URL data");+ }+ if (+ endpoint.protocol !== "https:"+ && !(endpoint.protocol === "http:"+ && ["127.0.0.1", "localhost"].includes(endpoint.hostname))+ ) {+ throw new Error(+ "assigned native MCP endpoint requires HTTPS or loopback HTTP",+ );+ }+ return { name, url: endpoint.toString(), token };+}diff --git a/packages/paperclip-runner/src/drivers/runtime-context-materializer.test.ts b/packages/paperclip-runner/src/drivers/runtime-context-materializer.test.tsnew file mode 100644index 0000000000..0c562665dd--- /dev/null+++ b/packages/paperclip-runner/src/drivers/runtime-context-materializer.test.ts@@ -0,0 +1,463 @@+import {+ chmod,+ lstat,+ mkdtemp,+ mkdir,+ readFile,+ readdir,+ rm,+ stat,+ symlink,+ writeFile,+} from "node:fs/promises";+import { tmpdir } from "node:os";+import { dirname, join } from "node:path";+import { afterEach, describe, expect, it } from "vitest";++import {+ NATIVE_RUNTIME_ASSET_SCHEMA,+ PAPERCLIP_EXECUTION_PROMPT,+ PAPERCLIP_EXECUTION_PROMPT_REVISION,+ canonicalNativeRuntimeContextDigest,+ nativeRuntimePromptDigest,+ type NativeRuntimeContextSnapshot,+} from "../contracts/runtime-context.js";+import { nativeMcpLaunchBinding } from "./native-mcp.js";+import {+ materializeNativeRuntimeSkills,+ prepareIsolatedCodexHome,+} from "./runtime-context-materializer.js";++const roots: string[] = [];++async function makeWritable(root: string): Promise<void> {+ const info = await lstat(root).catch(() => null);+ if (!info || info.isSymbolicLink()) return;+ if (info.isDirectory()) {+ await chmod(root, 0o700);+ for (const entry of await readdir(root)) {+ await makeWritable(join(root, entry));+ }+ } else {+ await chmod(root, 0o600);+ }+}++afterEach(async () => {+ await Promise.all(roots.splice(0).map(async (root) => {+ await makeWritable(root);+ await rm(root, { recursive: true, force: true });+ }));+});++function context(+ skillRoot: string,+ instructionRoot: string,+ runtimeName = "assigned",+): NativeRuntimeContextSnapshot {+ const digest = "0".repeat(64);+ const value = {+ prompt: {+ revision: PAPERCLIP_EXECUTION_PROMPT_REVISION,+ text: PAPERCLIP_EXECUTION_PROMPT,+ digest: nativeRuntimePromptDigest(),+ },+ instructions: {+ entryPath: "AGENTS.md",+ bundle: {+ schema: NATIVE_RUNTIME_ASSET_SCHEMA,+ digest,+ manifestDigest: digest,+ rootPath: instructionRoot,+ fileCount: 2,+ totalBytes: 2,+ },+ },+ skills: [{+ key: `company/${runtimeName}`,+ runtimeName,+ versionId: "version-1",+ bundle: {+ schema: NATIVE_RUNTIME_ASSET_SCHEMA,+ digest,+ manifestDigest: digest,+ rootPath: skillRoot,+ fileCount: 2,+ totalBytes: 2,+ },+ }],+ mcp: { assignmentSetId: runtimeName, digest, bindingId: "binding" },+ } satisfies Omit<NativeRuntimeContextSnapshot, "aggregateDigest">;+ return { ...value, aggregateDigest: canonicalNativeRuntimeContextDigest(value) };+}++describe("runtime context materialization", () => {+ it("validates native MCP launch bindings before they reach Codex", () => {+ expect(nativeMcpLaunchBinding({})).toBeNull();+ expect(() => nativeMcpLaunchBinding({+ PAPERCLIP_NATIVE_MCP_NAME: "paperclip",+ PAPERCLIP_NATIVE_MCP_URL: "http://paperclip.example/mcp",+ PAPERCLIP_NATIVE_MCP_TOKEN: "x".repeat(40),+ })).toThrow("requires HTTPS or loopback HTTP");+ expect(() => nativeMcpLaunchBinding({+ PAPERCLIP_NATIVE_MCP_NAME: "paperclip",+ PAPERCLIP_NATIVE_MCP_URL: "https://user:[email protected]/mcp#secret",+ PAPERCLIP_NATIVE_MCP_TOKEN: "x".repeat(40),+ })).toThrow("contains forbidden URL data");+ });++ it("copies only assigned skills and writes an isolated MCP config", async () => {+ const root = await mkdtemp(join(tmpdir(), "paperclip-runtime-context-"));+ roots.push(root);+ const assigned = join(root, "assigned-source");+ const instructions = join(root, "instructions-source");+ const hostSkills = join(root, "host-home", "skills", "unassigned");+ const codexHome = join(root, "codex-home");+ await Promise.all([+ mkdir(join(assigned, "references"), { recursive: true }),+ mkdir(instructions),+ mkdir(hostSkills, { recursive: true }),+ ]);+ await writeFile(join(assigned, "SKILL.md"), "# Assigned\n");+ await writeFile(+ join(assigned, "references", "support.md"),+ "support\n",+ );+ await writeFile(join(instructions, "AGENTS.md"), "Instructions\n");+ await writeFile(join(hostSkills, "SKILL.md"), "# Must not leak\n");++ await prepareIsolatedCodexHome({+ context: context(assigned, instructions),+ codexHome,+ sourceCodexHome: join(root, "host-home"),+ nativeMcp: nativeMcpLaunchBinding({+ PAPERCLIP_NATIVE_MCP_NAME: "paperclip-assigned",+ PAPERCLIP_NATIVE_MCP_URL: "https://paperclip.example/mcp",+ PAPERCLIP_NATIVE_MCP_TOKEN: "x".repeat(40),+ }),+ });++ await expect(readFile(+ join(codexHome, "skills", "assigned", "references", "support.md"),+ "utf8",+ )).resolves.toBe("support\n");+ await expect(stat(join(codexHome, "skills", "unassigned"))).rejects.toThrow();+ expect(+ (await stat(join(codexHome, "skills", "assigned", "SKILL.md"))).mode+ & 0o222,+ ).toBe(0);+ const config = await readFile(join(codexHome, "config.toml"), "utf8");+ expect(config).toContain("shell_snapshot = false");+ expect(config).toContain("paperclip-assigned");+ expect(config).toContain("Bearer ");+ expect(config).not.toContain("unassigned");+ });++ it("rejects repeated assignments without changing the current assignment", async () => {+ const root = await mkdtemp(join(tmpdir(), "paperclip-runtime-repeat-"));+ roots.push(root);+ const assigned = join(root, "assigned-source");+ const replacement = join(root, "replacement-source");+ const instructions = join(root, "instructions-source");+ const codexHome = join(root, "codex-home");+ await Promise.all([mkdir(assigned), mkdir(replacement), mkdir(instructions)]);+ await writeFile(join(assigned, "SKILL.md"), "# Assigned\n");+ await writeFile(join(replacement, "SKILL.md"), "# Replacement\n");+ await writeFile(join(instructions, "AGENTS.md"), "Instructions\n");++ await prepareIsolatedCodexHome({+ context: context(assigned, instructions),+ codexHome,+ });+ await expect(prepareIsolatedCodexHome({+ context: context(replacement, instructions, "replacement"),+ codexHome,+ })).rejects.toThrow("skills home must be a fresh destination");+ await expect(prepareIsolatedCodexHome({+ context: null,+ codexHome,+ })).rejects.toThrow("skills home must be a fresh destination");++ await expect(readFile(+ join(codexHome, "skills", "assigned", "SKILL.md"),+ "utf8",+ )).resolves.toBe("# Assigned\n");+ await expect(stat(join(codexHome, "skills", "replacement"))).rejects+ .toThrow();+ });++ it("rejects source symlinks without changing the current assignment", async () => {+ const root = await mkdtemp(join(tmpdir(), "paperclip-runtime-symlink-"));+ roots.push(root);+ const assigned = join(root, "assigned-source");+ const unsafe = join(root, "unsafe-source");+ const instructions = join(root, "instructions-source");+ const external = join(root, "external.txt");+ const codexHome = join(root, "codex-home");+ await Promise.all([mkdir(assigned), mkdir(unsafe), mkdir(instructions)]);+ await writeFile(join(assigned, "SKILL.md"), "# Assigned\n");+ await writeFile(join(instructions, "AGENTS.md"), "Instructions\n");+ await writeFile(external, "secret\n");+ await symlink(external, join(unsafe, "SKILL.md"));++ await prepareIsolatedCodexHome({+ context: context(assigned, instructions),+ codexHome,+ });+ await expect(prepareIsolatedCodexHome({+ context: context(unsafe, instructions, "unsafe"),+ codexHome,+ })).rejects.toThrow("runtime context asset contains a symlink");+ await expect(readFile(+ join(codexHome, "skills", "assigned", "SKILL.md"),+ "utf8",+ )).resolves.toBe("# Assigned\n");+ });++ it("rejects overlapping portable names without changing the current assignment", async () => {+ const root = await mkdtemp(join(tmpdir(), "paperclip-runtime-atomic-"));+ roots.push(root);+ const assigned = join(root, "assigned-source");+ const replacement = join(root, "replacement-source");+ const instructions = join(root, "instructions-source");+ const codexHome = join(root, "codex-home");+ await Promise.all([mkdir(assigned), mkdir(replacement), mkdir(instructions)]);+ await writeFile(join(assigned, "SKILL.md"), "# Assigned\n");+ await writeFile(join(replacement, "SKILL.md"), "# Replacement\n");+ await writeFile(join(instructions, "AGENTS.md"), "Instructions\n");++ await prepareIsolatedCodexHome({+ context: context(assigned, instructions),+ codexHome,+ });+ const replacementContext = context(replacement, instructions, "group/child");+ for (const runtimeName of ["group", "GROUP", "group.", "group "]) {+ const collidingSkill = {+ ...replacementContext.skills[0]!,+ key: `company/${runtimeName}`,+ runtimeName,+ };+ for (const skills of [+ [...replacementContext.skills, collidingSkill],+ [collidingSkill, ...replacementContext.skills],+ ]) {+ const value = { ...replacementContext, skills };+ const collidingContext = {+ ...value,+ aggregateDigest: canonicalNativeRuntimeContextDigest(value),+ };++ await expect(prepareIsolatedCodexHome({+ context: collidingContext,+ codexHome,+ })).rejects.toThrow("skill names must not overlap");+ await expect(readFile(+ join(codexHome, "skills", "assigned", "SKILL.md"),+ "utf8",+ )).resolves.toBe("# Assigned\n");+ await expect(stat(join(codexHome, "skills", "group"))).rejects.toThrow();+ }+ }++ const win32AliasedChild = {+ ...replacementContext.skills[0]!,+ key: "company/group-dot-child",+ runtimeName: "group./child",+ };+ const value = {+ ...replacementContext,+ skills: [...replacementContext.skills, win32AliasedChild],+ };+ await expect(prepareIsolatedCodexHome({+ context: {+ ...value,+ aggregateDigest: canonicalNativeRuntimeContextDigest(value),+ },+ codexHome,+ })).rejects.toThrow("skill names must not overlap");+ });++ it("rejects an existing destination before filesystem mutation", async () => {+ const root = await mkdtemp(join(tmpdir(), "paperclip-runtime-existing-"));+ roots.push(root);+ const assigned = join(root, "assigned-source");+ const replacement = join(root, "replacement-source");+ const instructions = join(root, "instructions-source");+ const skillsHome = join(root, "codex-home", "skills");+ await Promise.all([+ mkdir(assigned),+ mkdir(replacement),+ mkdir(instructions),+ ]);+ await writeFile(join(assigned, "SKILL.md"), "# Assigned\n");+ await writeFile(join(replacement, "SKILL.md"), "# Replacement\n");+ await writeFile(join(instructions, "AGENTS.md"), "Instructions\n");++ await materializeNativeRuntimeSkills(+ context(assigned, instructions),+ skillsHome,+ );+ const originalBytes = await readFile(+ join(skillsHome, "assigned", "SKILL.md"),+ );+ let dependencyCalls = 0;+ await expect(+ materializeNativeRuntimeSkills(+ context(replacement, instructions, "replacement"),+ skillsHome,+ {+ renameTree: async () => {+ dependencyCalls += 1;+ },+ removeTree: async () => {+ dependencyCalls += 1;+ },+ },+ ),+ ).rejects.toThrow("skills home must be a fresh destination");++ expect(dependencyCalls).toBe(0);+ expect(await readFile(join(skillsHome, "assigned", "SKILL.md"))).toEqual(+ originalBytes,+ );+ await expect(stat(join(skillsHome, "replacement"))).rejects.toThrow();+ expect(+ (await readdir(dirname(skillsHome))).filter((entry) =>+ entry.startsWith(".paperclip-skills-"),+ ),+ ).toEqual([]);+ });++ it("cleans private staging when fresh publication fails", async () => {+ const root = await mkdtemp(join(tmpdir(), "paperclip-runtime-publish-"));+ roots.push(root);+ const assigned = join(root, "assigned-source");+ const instructions = join(root, "instructions-source");+ const skillsHome = join(root, "codex-home", "skills");+ await Promise.all([mkdir(assigned), mkdir(instructions)]);+ await writeFile(join(assigned, "SKILL.md"), "# Assigned\n");+ await writeFile(join(instructions, "AGENTS.md"), "Instructions\n");++ await expect(materializeNativeRuntimeSkills(+ context(assigned, instructions),+ skillsHome,+ {+ renameTree: async (source) => {+ await expect(+ readFile(join(source, "assigned", "SKILL.md"), "utf8"),+ ).resolves.toBe("# Assigned\n");+ throw new Error("simulated publication failure");+ },+ },+ )).rejects.toThrow("simulated publication failure");++ await expect(stat(skillsHome)).rejects.toThrow();+ expect(+ (await readdir(dirname(skillsHome))).filter((entry) =>+ entry.startsWith(".paperclip-skills-staging-"),+ ),+ ).toEqual([]);+ });++ it("rejects skill names that can escape or alias the skills home", async () => {+ const root = await mkdtemp(join(tmpdir(), "paperclip-runtime-name-"));+ roots.push(root);+ const assigned = join(root, "assigned-source");+ const instructions = join(root, "instructions-source");+ const codexHome = join(root, "codex-home");+ await Promise.all([mkdir(assigned), mkdir(instructions)]);+ await writeFile(join(assigned, "SKILL.md"), "# Assigned\n");+ await writeFile(join(instructions, "AGENTS.md"), "Instructions\n");++ await expect(prepareIsolatedCodexHome({+ context: context(assigned, instructions, "../outside"),+ codexHome,+ })).rejects.toThrow("skill name must be a safe relative path");+ for (const runtimeName of [+ "CON",+ "con.txt",+ "CON .txt",+ "aux .json",+ "COM1 .md",+ "group/AUX",+ "Lpt1.json",+ "group:name",+ "group?name",+ "group*name",+ 'group"name',+ "group<name",+ "group>name",+ "group|name",+ "group\u0001name",+ "...",+ ". .",+ "group/...",+ "group/. . ",+ ]) {+ await expect(prepareIsolatedCodexHome({+ context: context(assigned, instructions, runtimeName),+ codexHome,+ })).rejects.toThrow("skill name must be a safe relative path");+ }+ await expect(stat(join(root, "outside"))).rejects.toThrow();+ });++ it("writes API login state as an owner-only file and removes stale auth", async () => {+ const root = await mkdtemp(join(tmpdir(), "paperclip-runtime-auth-"));+ roots.push(root);+ const codexHome = join(root, "codex-home");+ const emptyCodexHome = join(root, "empty-codex-home");+ await Promise.all([+ mkdir(codexHome, { recursive: true }),+ mkdir(emptyCodexHome, { recursive: true }),+ ]);+ await Promise.all([+ writeFile(join(codexHome, "auth.json"), "stale", { mode: 0o600 }),+ writeFile(join(emptyCodexHome, "auth.json"), "stale", { mode: 0o600 }),+ ]);++ await prepareIsolatedCodexHome({+ context: null,+ codexHome,+ apiKey: "fresh-ephemeral-key",+ });++ await expect(readFile(join(codexHome, "auth.json"), "utf8")).resolves.toBe(+ JSON.stringify({ OPENAI_API_KEY: "fresh-ephemeral-key" }),+ );+ expect((await stat(join(codexHome, "auth.json"))).mode & 0o777).toBe(0o600);++ await prepareIsolatedCodexHome({ context: null, codexHome: emptyCodexHome });+ await expect(stat(join(emptyCodexHome, "auth.json"))).rejects.toThrow();+ });++ it("copies regular host auth but refuses symlinked auth", async () => {+ const root = await mkdtemp(join(tmpdir(), "paperclip-runtime-host-auth-"));+ roots.push(root);+ const codexHome = join(root, "codex-home");+ const symlinkCodexHome = join(root, "symlink-codex-home");+ const sourceHome = join(root, "source-home");+ const secret = join(root, "secret.json");+ await mkdir(sourceHome);+ await writeFile(join(sourceHome, "auth.json"), "host-auth", { mode: 0o600 });++ await prepareIsolatedCodexHome({+ context: null,+ codexHome,+ sourceCodexHome: sourceHome,+ });+ await expect(readFile(join(codexHome, "auth.json"), "utf8")).resolves.toBe(+ "host-auth",+ );++ await rm(join(sourceHome, "auth.json"));+ await writeFile(secret, "must-not-copy");+ await symlink(secret, join(sourceHome, "auth.json"));+ await prepareIsolatedCodexHome({+ context: null,+ codexHome: symlinkCodexHome,+ sourceCodexHome: sourceHome,+ });+ await expect(stat(join(symlinkCodexHome, "auth.json"))).rejects.toThrow();+ });+});diff --git a/packages/paperclip-runner/src/drivers/runtime-context-materializer.ts b/packages/paperclip-runner/src/drivers/runtime-context-materializer.tsnew file mode 100644index 0000000000..8ae9e08ea6--- /dev/null+++ b/packages/paperclip-runner/src/drivers/runtime-context-materializer.ts@@ -0,0 +1,293 @@+import { randomUUID } from "node:crypto";+import { constants } from "node:fs";+import {+ chmod,+ cp,+ lstat,+ mkdir,+ open,+ readdir,+ rename,+ rm,+ writeFile,+} from "node:fs/promises";+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";++import type { NativeRuntimeContextSnapshot } from "../contracts/runtime-context.js";+import type { NativeMcpLaunchBinding } from "./native-mcp.js";++async function assertSafeTree(root: string, child = ""): Promise<void> {+ const directory = child ? join(root, child) : root;+ const directoryStat = await lstat(directory);+ if (directoryStat.isSymbolicLink()) {+ throw new Error(+ `runtime context asset contains a symlink: ${child || "."}`,+ );+ }+ if (!directoryStat.isDirectory()) {+ throw new Error("runtime context asset root must be a directory");+ }+ for (const entry of await readdir(directory, { withFileTypes: true })) {+ const childRelative = child ? `${child}/${entry.name}` : entry.name;+ const stat = await lstat(join(root, childRelative));+ if (stat.isSymbolicLink()) {+ throw new Error(+ `runtime context asset contains a symlink: ${childRelative}`,+ );+ }+ if (stat.isDirectory()) await assertSafeTree(root, childRelative);+ else if (!stat.isFile()) {+ throw new Error(+ `runtime context asset contains an unsupported file: ${childRelative}`,+ );+ }+ }+}++function safeMaterializationTarget(root: string, runtimeName: string): string {+ const segments = runtimeName.split("/");+ if (+ runtimeName.startsWith("/")+ || runtimeName.includes("\\")+ || runtimeName.includes("\0")+ || segments.some((segment) => /[<>:"|?*\u0000-\u001f\u007f]/u.test(segment))+ || segments.some((segment) => !segment || segment === "." || segment === "..")+ || segments.some((segment) => !segment.replace(/[ .]+$/u, ""))+ || segments.some(isWin32ReservedPathSegment)+ ) {+ throw new Error("runtime context skill name must be a safe relative path");+ }+ const target = resolve(root, runtimeName);+ const relation = relative(resolve(root), target);+ if (+ relation === ""+ || relation === ".."+ || relation.startsWith(`..${sep}`)+ || isAbsolute(relation)+ ) {+ throw new Error("runtime context skill name must stay inside the skills home");+ }+ return target;+}++function isWin32ReservedPathSegment(segment: string): boolean {+ const basename = segment+ .normalize("NFC")+ .split(".", 1)[0]!+ .replace(/[ .]+$/u, "")+ .toUpperCase();+ return /^(?:CON|PRN|AUX|NUL|CONIN\$|CONOUT\$|COM[1-9¹²³]|LPT[1-9¹²³])$/u.test(+ basename,+ );+}++function portableRuntimeNameKey(runtimeName: string): string {+ // Skill assignments must remain unambiguous when the same context is moved+ // between the case-sensitive Linux runner and the case-insensitive default+ // filesystems on macOS or Windows. NFC also catches composed/decomposed+ // aliases, while per-segment trimming matches Win32's treatment of trailing+ // dots and spaces before either spelling reaches the staging tree.+ return runtimeName+ .normalize("NFC")+ .split("/")+ .map((segment) => segment.replace(/[ .]+$/u, ""))+ .join("/")+ .toLowerCase();+}++async function protectStagedTree(root: string): Promise<void> {+ const rootHandle = await open(+ root,+ constants.O_RDONLY+ | (constants.O_NOFOLLOW ?? 0)+ | (constants.O_DIRECTORY ?? 0),+ );+ try {+ const opened = await rootHandle.stat();+ if (!opened.isDirectory()) {+ throw new Error("staged runtime context root must be a directory");+ }+ // Keep directories owner-writable so the private staging tree can be+ // removed without a second path-based chmod traversal.+ await rootHandle.chmod(0o700);+ for (const entry of await readdir(root, { withFileTypes: true })) {+ const child = join(root, entry.name);+ if (entry.isDirectory()) {+ await protectStagedTree(child);+ continue;+ }+ const childHandle = await open(+ child,+ constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0),+ );+ try {+ const openedChild = await childHandle.stat();+ if (!openedChild.isFile()) {+ throw new Error("staged runtime context asset must be a regular file");+ }+ await childHandle.chmod(openedChild.mode & 0o555);+ } finally {+ await childHandle.close();+ }+ }+ } finally {+ await rootHandle.close();+ }+}++export async function materializeNativeRuntimeSkills(+ context: NativeRuntimeContextSnapshot | null,+ skillsHome: string,+ dependencies: {+ /** Internal test seam for failed staging cleanup coverage. */+ removeTree?: (path: string) => Promise<void>;+ /** Internal test seam for publication failure coverage. */+ renameTree?: (source: string, destination: string) => Promise<void>;+ } = {},+): Promise<void> {+ const removeTree =+ dependencies.removeTree ??+ ((path: string) => rm(path, { recursive: true, force: true }));+ const renameTree = dependencies.renameTree ?? rename;+ if (context) {+ const runtimeNames = new Set<string>();+ for (const skill of context.skills) {+ safeMaterializationTarget(skillsHome, skill.runtimeName);+ const runtimeName = portableRuntimeNameKey(skill.runtimeName);+ if (runtimeNames.has(runtimeName)) {+ throw new Error("runtime context skill names must not overlap");+ }+ runtimeNames.add(runtimeName);+ }+ for (const runtimeName of runtimeNames) {+ const segments = runtimeName.split("/");+ for (let length = 1; length < segments.length; length += 1) {+ if (runtimeNames.has(segments.slice(0, length).join("/"))) {+ throw new Error("runtime context skill names must not overlap");+ }+ }+ }+ for (const skill of context.skills) {+ await assertSafeTree(skill.bundle.rootPath);+ }+ }++ const skillsHomeExists = await lstat(skillsHome).then(+ () => true,+ (error: NodeJS.ErrnoException) => {+ if (error.code === "ENOENT") return false;+ throw error;+ },+ );+ if (skillsHomeExists) {+ throw new Error(+ "runtime context skills home must be a fresh destination",+ );+ }++ const parent = dirname(skillsHome);+ const nonce = randomUUID();+ const stagingHome = join(parent, `.paperclip-skills-staging-${nonce}`);+ await mkdir(parent, { recursive: true, mode: 0o700 });+ await chmod(parent, 0o700);+ await mkdir(stagingHome, { mode: 0o700 });+ try {+ for (const skill of context?.skills ?? []) {+ const target = safeMaterializationTarget(stagingHome, skill.runtimeName);+ await cp(skill.bundle.rootPath, target, {+ recursive: true,+ force: false,+ errorOnExist: true,+ dereference: false,+ verbatimSymlinks: true,+ });+ await assertSafeTree(target);+ await protectStagedTree(target);+ }++ // The caller supplies a new isolated home for each provider launch. Never+ // move an existing assignment out of its canonical path: a failed bounded+ // rollback cannot portably guarantee that name is restored on every+ // filesystem. Publication therefore targets only a fresh destination.+ await renameTree(stagingHome, skillsHome);+ } catch (error) {+ await removeTree(stagingHome).catch(() => undefined);+ throw error;+ }+}++async function readSourceCodexAuth(sourceAuth: string): Promise<Buffer | null> {+ const handle = await open(+ sourceAuth,+ constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0),+ ).catch((error: NodeJS.ErrnoException) => {+ if (error.code === "ENOENT" || error.code === "ELOOP") return null;+ throw error;+ });+ if (!handle) return null;+ try {+ const stat = await handle.stat();+ if (!stat.isFile()) return null;+ if (stat.size > 1024 * 1024) {+ throw new Error("source Codex auth file exceeds the 1 MiB limit");+ }+ return await handle.readFile();+ } finally {+ await handle.close();+ }+}++export async function prepareIsolatedCodexHome(input: {+ context: NativeRuntimeContextSnapshot | null;+ codexHome: string;+ sourceCodexHome?: string | null;+ nativeMcp?: NativeMcpLaunchBinding | null;+ apiKey?: string | null;+}): Promise<void> {+ await materializeNativeRuntimeSkills(+ input.context,+ join(input.codexHome, "skills"),+ );++ const configPath = join(input.codexHome, "config.toml");+ await rm(configPath, { force: true });+ await writeFile(configPath, [+ // Codex shell snapshots serialize the provider process environment. The+ // native runner injects short-lived provider and MCP bindings, so a+ // snapshot would turn ephemeral credentials into durable session state.+ "[features]",+ "shell_snapshot = false",+ "",+ ...(input.nativeMcp+ ? [+ `[mcp_servers.${JSON.stringify(input.nativeMcp.name)}]`,+ `url = ${JSON.stringify(input.nativeMcp.url)}`,+ `http_headers = { Authorization = ${JSON.stringify(`Bearer ${input.nativeMcp.token}`)} }`,+ "",+ ]+ : []),+ ].join("\n"), { mode: 0o600 });++ const targetAuth = join(input.codexHome, "auth.json");+ await rm(targetAuth, { force: true });+ const apiKey = input.apiKey?.trim();+ if (apiKey) {+ // The pinned Codex app-server authenticates API-key automation through its+ // login cache rather than the CLI-only CODEX_API_KEY path. Keep this file+ // owner-only in the disposable session home.+ await writeFile(+ targetAuth,+ JSON.stringify({ OPENAI_API_KEY: apiKey }),+ { mode: 0o600 },+ );+ await chmod(targetAuth, 0o600);+ return;+ }++ const sourceHome = input.sourceCodexHome?.trim();+ if (!sourceHome) return;+ const sourceAuth = await readSourceCodexAuth(join(sourceHome, "auth.json"));+ if (!sourceAuth) return;+ await writeFile(targetAuth, sourceAuth, { mode: 0o600 });+ await chmod(targetAuth, 0o600);+}