commandmate 0.49.2 → 0.50.0

package/dist/server/src/lib/agent-roles/artifacts.js

@@ -0,0 +1,638 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RoleArtifactError = exports.MAX_ARTIFACT_NAME_LENGTH = exports.AGENT_ROLE_ANTIGRAVITY_AGENTS_DIR_ENV_VAR = exports.AGENT_ROLE_ARTIFACTS_DIR_ENV_VAR = void 0;
+exports.deriveServerNamespace = deriveServerNamespace;
+exports.buildArtifactName = buildArtifactName;
+exports.resolveArtifactLocation = resolveArtifactLocation;
+exports.renderRoleArtifact = renderRoleArtifact;
+exports.writeLaunchEnvFile = writeLaunchEnvFile;
+exports.removeLaunchEnvFile = removeLaunchEnvFile;
+exports.inspectRoleArtifact = inspectRoleArtifact;
+exports.writeRoleArtifact = writeRoleArtifact;
+/**
+ * The generated files that carry a role to each CLI (§5, §6 of
+ * `docs/design/agent-roles-adapters.md`): what they contain, where they live, and
+ * the only code that writes them.
+ *
+ * Free of the database on purpose: the launcher side of the tree stays outside
+ * `better-sqlite3`'s import graph (`hooks/sources/opencode/launch-settings.ts`).
+ *
+ * ## The rules
+ *
+ * - **Immutable.** A name is fixed by the injection fingerprint, so one name means
+ *   one content. An existing file is reused only if every byte matches, and a
+ *   difference is an error rather than an overwrite. The one exception is Codex,
+ *   which writes into the profile it runs under (#4136, {@link codexProfileAsWritten}).
+ * - **Inspected.** Many CLIs run on with no role when a file is missing or broken
+ *   (§8), so the writer reads back what it wrote, and {@link inspectRoleArtifact}
+ *   is the same check for the moment before a launch.
+ * - **Never deleted.** A running process or a resumable conversation may still
+ *   read one. Copilot's `/agent` and `agy agent` therefore list them; `infer:
+ *   false` and `subagent: false` narrow the candidates, not the list.
+ *
+ * Errors carry paths, never file content: the content is the role's body.
+ *
+ * @module lib/agent-roles/artifacts
+ */
+const fs_1 = require("fs");
+const crypto_1 = require("crypto");
+const os_1 = require("os");
+const path_1 = require("path");
+const vm_1 = __importDefault(require("vm"));
+const smol_toml_1 = require("smol-toml");
+const yaml_1 = require("yaml");
+const safe_directory_1 = require("../../config/safe-directory");
+const uat_isolation_1 = require("../../config/uat-isolation");
+const hooks_config_1 = require("../../lib/hooks/sources/antigravity/hooks-config");
+const hooks_config_2 = require("../../lib/hooks/sources/codex/hooks-config");
+const hook_settings_1 = require("../../lib/hooks/sources/copilot/hook-settings");
+const fingerprint_1 = require("./fingerprint");
+const toml_basic_1 = require("./toml-basic");
+/** Moves the data root (Claude, Command Code, OpenCode V1 and V2). Honoured in production. */
+exports.AGENT_ROLE_ARTIFACTS_DIR_ENV_VAR = 'CM_AGENT_ROLE_ARTIFACTS_DIR';
+/**
+ * Moves Antigravity's agents directory, for tests and isolated runs. `agy` itself
+ * reads only `~/.gemini/config/agents`, so a file put elsewhere is one it never finds.
+ */
+exports.AGENT_ROLE_ANTIGRAVITY_AGENTS_DIR_ENV_VAR = 'CM_AGENT_ROLE_ANTIGRAVITY_AGENTS_DIR';
+/** Longest generated name. Becomes Codex's `-p`, Copilot's `--agent`, Antigravity's `name`. */
+exports.MAX_ARTIFACT_NAME_LENGTH = 64;
+/** How much of the injection fingerprint goes into a name. */
+const NAME_FINGERPRINT_LENGTH = 12;
+const NAME_SEGMENT = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const FULL_FINGERPRINT = /^[0-9a-f]{64}$/;
+class RoleArtifactError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'RoleArtifactError';
+    }
+}
+exports.RoleArtifactError = RoleArtifactError;
+/** A label for this server inside a shared home, derived from something stable such as its database path. */
+function deriveServerNamespace(seed) {
+    return (0, fingerprint_1.computeFingerprint)(Buffer.from(seed, 'utf8')).slice(0, 8);
+}
+/**
+ * `cm-role-<namespace>-<role id>-<head of the injection fingerprint>`. The
+ * injection fingerprint and not the artifact fingerprint: the name is inside the
+ * Copilot and Antigravity frontmatter, so naming a file after its own bytes would
+ * be circular (§5).
+ */
+function buildArtifactName(input) {
+    const { namespace, roleId, injectionFingerprint } = input;
+    if (!NAME_SEGMENT.test(namespace))
+        throw new RoleArtifactError('invalid-name', 'Invalid server namespace');
+    if (!NAME_SEGMENT.test(roleId))
+        throw new RoleArtifactError('invalid-name', 'Invalid role id');
+    if (!FULL_FINGERPRINT.test(injectionFingerprint)) {
+        throw new RoleArtifactError('invalid-name', 'The injection fingerprint must be a full SHA-256 hex');
+    }
+    const name = `cm-role-${namespace}-${roleId}-${injectionFingerprint.slice(0, NAME_FINGERPRINT_LENGTH)}`;
+    assertArtifactName(name);
+    return name;
+}
+function assertArtifactName(name) {
+    if (!name.startsWith('cm-role-') || !NAME_SEGMENT.test(name)) {
+        throw new RoleArtifactError('invalid-name', 'An artifact name is cm-role- plus alphanumerics and hyphens');
+    }
+    if (name.length > exports.MAX_ARTIFACT_NAME_LENGTH) {
+        throw new RoleArtifactError('invalid-name', `An artifact name is at most ${exports.MAX_ARTIFACT_NAME_LENGTH} characters`);
+    }
+}
+function defaultDataRoot() {
+    return (0, path_1.join)((0, os_1.homedir)(), '.commandmate', 'agent-roles');
+}
+/**
+ * Absolute (Issue #4210): the path of a file under this root is handed to the
+ * CLI — `--append-system-prompt-file`, `--mod`, OpenCode's `instructions` /
+ * `{file:…}` (`./adapters.ts` `buildRoleLaunchArguments`) — and the CLI runs in
+ * the worktree (`cli-tools/base.ts` `createLaunchPane`), so a relative root
+ * named another file than the one written here.
+ */
+function dataRootFor(options) {
+    const fallback = defaultDataRoot();
+    if (options.dataRoot)
+        return (0, safe_directory_1.resolveSafeAbsoluteDirectory)(options.dataRoot, fallback, 'ArtifactOptions.dataRoot');
+    const configured = (options.env ?? process.env)[exports.AGENT_ROLE_ARTIFACTS_DIR_ENV_VAR];
+    return (0, safe_directory_1.resolveSafeAbsoluteDirectory)(configured, fallback, exports.AGENT_ROLE_ARTIFACTS_DIR_ENV_VAR);
+}
+/** The path with every symlink that exists on the way followed. What is not there yet is kept as spelled. */
+function physicalPath(target) {
+    const rest = [];
+    let existing = (0, path_1.resolve)(target);
+    for (;;) {
+        try {
+            return (0, path_1.join)((0, fs_1.realpathSync)(existing), ...rest);
+        }
+        catch {
+            const parent = (0, path_1.dirname)(existing);
+            if (parent === existing)
+                return (0, path_1.join)(existing, ...rest);
+            rest.unshift((0, path_1.basename)(existing));
+            existing = parent;
+        }
+    }
+}
+function accountHomes() {
+    const homes = [(0, os_1.homedir)()];
+    try {
+        homes.push((0, os_1.userInfo)().homedir);
+    }
+    catch {
+        // No account entry for this uid: HOME is all there is to go on.
+    }
+    return homes;
+}
+/** State directories of this product and the CLIs it drives, as they sit in a home. */
+const KNOWN_HOME_STATE = ['.commandmate', '.codex', '.copilot', '.gemini', '.claude'];
+/**
+ * Known shared state, wherever it physically is. Any of these may be a symlink out
+ * of the home (a synced or shared directory), and the state is just as shared there.
+ */
+function knownSharedStatePaths() {
+    const inHomes = accountHomes().flatMap((home) => KNOWN_HOME_STATE.map((entry) => (0, path_1.join)(home, entry)));
+    return [
+        defaultDataRoot(),
+        ...inHomes,
+        (0, hooks_config_2.getCodexHome)(),
+        (0, hook_settings_1.getCopilotHomeDirectory)(),
+        (0, path_1.dirname)((0, hooks_config_1.getAntigravityHooksConfigPath)()),
+    ];
+}
+function isSameOrInside(path, parent) {
+    return path === parent || path.startsWith(`${parent}${path_1.sep}`);
+}
+/**
+ * Whether a data root is a place the user's other servers and CLIs share, judged
+ * by where it physically is and not by whether someone named it: the home itself,
+ * anything inside one of its dot-directories, or anything inside known shared
+ * state wherever a symlink has put it.
+ *
+ * Not "anywhere under the home". A UAT's run directory normally is, because the
+ * checkout is, and it belongs to that run alone (`.commandmate/uat.yaml` puts its
+ * database and hook directory there).
+ */
+function isSharedHomeState(root) {
+    const real = physicalPath(root);
+    const inHomeState = accountHomes().some((home) => {
+        const realHome = physicalPath(home);
+        if (real === realHome)
+            return true;
+        return real.startsWith(`${realHome}${path_1.sep}`) && real.slice(realHome.length + 1).startsWith('.');
+    });
+    return inHomeState || knownSharedStatePaths().some((known) => isSameOrInside(real, physicalPath(known)));
+}
+/**
+ * Antigravity has no resolver for this directory, so it is derived from the one
+ * that names `hooks.json` beside it rather than spelling `~/.gemini` a second time.
+ */
+function antigravityAgentsDir(options) {
+    const fallback = (0, path_1.join)((0, path_1.dirname)((0, hooks_config_1.getAntigravityHooksConfigPath)()), 'agents');
+    if (options.antigravityAgentsDir)
+        return options.antigravityAgentsDir;
+    return (0, safe_directory_1.resolveSafeDirectory)((options.env ?? process.env)[exports.AGENT_ROLE_ANTIGRAVITY_AGENTS_DIR_ENV_VAR], fallback, exports.AGENT_ROLE_ANTIGRAVITY_AGENTS_DIR_ENV_VAR);
+}
+/**
+ * Where an adapter's file goes. Codex, Copilot and Antigravity discover theirs in
+ * their own homes (D4); the others are handed a path, so theirs stay out of the
+ * home altogether.
+ */
+function resolveArtifactLocation(adapter, name, options = {}) {
+    assertArtifactName(name);
+    switch (adapter) {
+        case 'codex': {
+            const home = (0, hooks_config_2.getCodexHome)(options.codexHome ? { codexHome: options.codexHome } : {});
+            return { path: (0, path_1.join)(home, `${name}.config.toml`), homeDir: home, sharedDirs: [], ownedDirs: [], inSharedHome: true };
+        }
+        case 'copilot': {
+            // Absolute for getCopilotHomeDirectory()'s reason (Issue #4210): the home is
+            // handed to copilot as COPILOT_HOME.
+            const home = options.copilotHome !== undefined ? (0, path_1.resolve)(options.copilotHome) : (0, hook_settings_1.getCopilotHomeDirectory)();
+            const agents = (0, path_1.join)(home, 'agents');
+            return { path: (0, path_1.join)(agents, `${name}.agent.md`), homeDir: home, sharedDirs: [agents], ownedDirs: [], inSharedHome: true };
+        }
+        case 'antigravity': {
+            const agents = antigravityAgentsDir(options);
+            const own = (0, path_1.join)(agents, name);
+            return { path: (0, path_1.join)(own, 'agent.md'), homeDir: null, sharedDirs: [agents], ownedDirs: [own], inSharedHome: true };
+        }
+        case 'claude':
+        case 'command-code':
+        case 'opencode':
+        case 'opencode-v2': {
+            const root = dataRootFor(options);
+            const dir = (0, path_1.join)(root, adapter);
+            const extension = adapter === 'command-code' ? 'ts' : 'md';
+            // Only the default root is ours to tighten. A root someone named may be any
+            // directory, up to the home itself, and is left to its owner.
+            const rootIsOurs = physicalPath(root) === physicalPath(defaultDataRoot());
+            return {
+                path: (0, path_1.join)(dir, `${name}.${extension}`),
+                homeDir: null,
+                sharedDirs: rootIsOurs ? [] : [root],
+                ownedDirs: rootIsOurs ? [root, dir] : [dir],
+                inSharedHome: isSharedHomeState(root),
+            };
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Content
+// ---------------------------------------------------------------------------
+/**
+ * A constant, not the role's name. A rename leaves the injection fingerprint, and
+ * so the file name, unchanged; carrying the role name here would make the second
+ * launch find different bytes under the same name and refuse.
+ */
+const DEFINITION_DESCRIPTION = 'CommandMate role';
+const COMMAND_CODE_PREFIX = 'export default function (cmd) {\n  cmd.hooks({ appendSystemPrompt: () => ';
+const COMMAND_CODE_SUFFIX = ' });\n}\n';
+/**
+ * Every byte of an adapter's file. `instructions` is the text the model should
+ * get, already wrapped and composed by #4115: for Codex that includes the user's
+ * own `developer_instructions`, which the profile would otherwise replace.
+ */
+function renderRoleArtifact(adapter, name, instructions) {
+    switch (adapter) {
+        case 'codex':
+            return Buffer.from((0, toml_basic_1.renderTomlBasicDocument)({ developer_instructions: instructions }), 'utf8');
+        case 'copilot':
+            return Buffer.from(`---\nname: ${name}\ndescription: ${DEFINITION_DESCRIPTION}\ninfer: false\n---\n${instructions}`, 'utf8');
+        case 'antigravity':
+            return Buffer.from(`---\nname: ${name}\ndescription: ${DEFINITION_DESCRIPTION}\nsubagent: false\n---\n${instructions}`, 'utf8');
+        case 'command-code': {
+            // Executed by the CLI, so the text goes in only as a JSON string literal.
+            const literal = JSON.stringify(instructions).replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029');
+            return Buffer.from(`${COMMAND_CODE_PREFIX}${literal}${COMMAND_CODE_SUFFIX}`, 'utf8');
+        }
+        case 'claude':
+        case 'opencode':
+        case 'opencode-v2':
+            return Buffer.from(instructions, 'utf8');
+    }
+}
+function parseDefinition(text) {
+    if (!text.startsWith('---\n'))
+        return null;
+    const close = text.indexOf('\n---\n', 3);
+    if (close === -1)
+        return null;
+    try {
+        return { data: (0, yaml_1.parse)(text.slice(4, close)), body: text.slice(close + 5) };
+    }
+    catch {
+        return null;
+    }
+}
+/** Why these bytes would not carry a role through this adapter, or null when they would. */
+function formatProblem(adapter, name, bytes) {
+    const text = bytes.toString('utf8');
+    switch (adapter) {
+        case 'codex': {
+            let entries;
+            try {
+                entries = (0, smol_toml_1.parse)(text);
+            }
+            catch {
+                // Not the parser's message: it quotes the line, and the line is the role's body.
+                return 'not the expected TOML';
+            }
+            const value = entries.developer_instructions;
+            return typeof value !== 'string' || value.trim() === '' ? 'developer_instructions is missing or empty' : null;
+        }
+        case 'copilot':
+        case 'antigravity': {
+            const definition = parseDefinition(text);
+            if (!definition || typeof definition.data !== 'object' || definition.data === null) {
+                return 'no readable frontmatter';
+            }
+            const data = definition.data;
+            if (data.name !== name)
+                return 'the frontmatter name is not this artifact';
+            if (adapter === 'copilot' && data.infer !== false)
+                return 'infer: false is missing';
+            if (adapter === 'antigravity' && data.subagent !== false)
+                return 'subagent: false is missing';
+            return definition.body.trim() === '' ? 'the definition has no body' : null;
+        }
+        case 'command-code': {
+            // The CLI swallows a broken mod (§6.3), so this is the only check there is.
+            // Compiled, never run; `export default` would not compile as a script.
+            if (!text.startsWith(COMMAND_CODE_PREFIX) || !text.endsWith(COMMAND_CODE_SUFFIX)) {
+                return 'not the generated mod';
+            }
+            const literal = text.slice(COMMAND_CODE_PREFIX.length, text.length - COMMAND_CODE_SUFFIX.length);
+            try {
+                const value = JSON.parse(literal);
+                new vm_1.default.Script(`(function (cmd) { cmd.hooks({ appendSystemPrompt: () => ${literal} }); })`);
+                return typeof value === 'string' && value.trim() !== '' ? null : 'the mod carries no text';
+            }
+            catch {
+                return 'the mod does not parse';
+            }
+        }
+        case 'claude':
+        case 'opencode':
+        case 'opencode-v2':
+            return text.trim() === '' ? 'the file is empty' : null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Filesystem
+// ---------------------------------------------------------------------------
+function lstatOrNull(path) {
+    try {
+        return (0, fs_1.lstatSync)(path);
+    }
+    catch (error) {
+        const { code } = error;
+        // ENOTDIR: something on the way is a file, so this path does not exist either.
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return null;
+        throw error;
+    }
+}
+function currentUid() {
+    return typeof process.getuid === 'function' ? process.getuid() : null;
+}
+/** Read an existing artifact, refusing anything we could not have written. Null when absent. */
+function readExistingArtifact(path) {
+    const stat = lstatOrNull(path);
+    if (!stat)
+        return null;
+    if (stat.isSymbolicLink())
+        throw new RoleArtifactError('symlink', `${path} is a symlink`);
+    if (!stat.isFile())
+        throw new RoleArtifactError('not-regular-file', `${path} is not a regular file`);
+    const uid = currentUid();
+    if (uid !== null && stat.uid !== uid) {
+        throw new RoleArtifactError('foreign-owner', `${path} belongs to another user`);
+    }
+    if ((stat.mode & 0o077) !== 0) {
+        throw new RoleArtifactError('insecure-permissions', `${path} is accessible to other users`);
+    }
+    // O_NOFOLLOW: the check above and this read are two steps.
+    const fd = (0, fs_1.openSync)(path, fs_1.constants.O_RDONLY | fs_1.constants.O_NOFOLLOW);
+    try {
+        return (0, fs_1.readFileSync)(fd);
+    }
+    finally {
+        (0, fs_1.closeSync)(fd);
+    }
+}
+/**
+ * Check a directory that exists; one that does not has nothing to check.
+ *
+ * @param repair - Whether a directory of our own may be tightened. False when the
+ *   run only reads: a read-only caller refuses instead, and changes nothing.
+ */
+function checkDirectory(dir, owned, repair) {
+    const stat = lstatOrNull(dir);
+    if (!stat)
+        return;
+    if (stat.isSymbolicLink())
+        throw new RoleArtifactError('symlink', `${dir} is a symlink`);
+    if (!stat.isDirectory())
+        throw new RoleArtifactError('not-regular-file', `${dir} is not a directory`);
+    const uid = currentUid();
+    if (uid !== null && stat.uid !== uid) {
+        throw new RoleArtifactError('foreign-owner', `${dir} belongs to another user`);
+    }
+    if (owned) {
+        if ((stat.mode & 0o077) === 0)
+            return;
+        if (!repair)
+            throw new RoleArtifactError('insecure-permissions', `${dir} is accessible to other users`);
+        (0, fs_1.chmodSync)(dir, 0o700);
+    }
+    else if ((stat.mode & 0o022) !== 0) {
+        // Readable is the CLI's business. Writable by others is someone else being able
+        // to swap the file between this check and the launch.
+        throw new RoleArtifactError('insecure-permissions', `${dir} is writable by other users`);
+    }
+}
+/** A home may be reached through a symlink, so it is followed; what is below it is not. */
+function checkDirectories(location, repair) {
+    if (location.homeDir !== null) {
+        let mode = null;
+        try {
+            mode = Number((0, fs_1.statSync)(location.homeDir).mode);
+        }
+        catch {
+            // Absent, or a link to nothing: nothing readable is behind it, and creating it will say so.
+        }
+        if (mode !== null && (mode & 0o022) !== 0) {
+            throw new RoleArtifactError('insecure-permissions', `${location.homeDir} is writable by other users`);
+        }
+    }
+    for (const dir of location.sharedDirs)
+        checkDirectory(dir, false, repair);
+    for (const dir of location.ownedDirs)
+        checkDirectory(dir, true, repair);
+}
+function createMissingDirectories(location) {
+    const dirs = [...(location.homeDir === null ? [] : [location.homeDir]), ...location.sharedDirs, ...location.ownedDirs];
+    for (const dir of dirs)
+        (0, fs_1.mkdirSync)(dir, { recursive: true, mode: 0o700 });
+}
+/**
+ * Create `path` with exactly these bytes, or fail if anything is already there.
+ * `link` and not `rename`: rename replaces a file that appeared meanwhile, and two
+ * servers can generate the same name at once.
+ *
+ * @returns false when another writer got there first
+ */
+function publishExclusively(path, bytes) {
+    const temporary = (0, path_1.join)((0, path_1.dirname)(path), `.cm-role-${(0, crypto_1.randomBytes)(6).toString('hex')}.tmp`);
+    const fd = (0, fs_1.openSync)(temporary, fs_1.constants.O_WRONLY | fs_1.constants.O_CREAT | fs_1.constants.O_EXCL | fs_1.constants.O_NOFOLLOW, 0o600);
+    try {
+        try {
+            let written = 0;
+            while (written < bytes.length)
+                written += (0, fs_1.writeSync)(fd, bytes, written);
+            (0, fs_1.fsyncSync)(fd);
+            if (((0, fs_1.fstatSync)(fd).mode & 0o077) !== 0) {
+                throw new RoleArtifactError('insecure-permissions', `${temporary} was not created private`);
+            }
+        }
+        finally {
+            (0, fs_1.closeSync)(fd);
+        }
+        try {
+            (0, fs_1.linkSync)(temporary, path);
+            return true;
+        }
+        catch (error) {
+            if (error.code === 'EEXIST')
+                return false;
+            throw error;
+        }
+    }
+    finally {
+        (0, fs_1.unlinkSync)(temporary);
+    }
+}
+// ---------------------------------------------------------------------------
+// The composed environment (not an artifact)
+// ---------------------------------------------------------------------------
+/**
+ * Write a composed `OPENCODE_CONFIG_CONTENT` to a private file for one launch, read
+ * back with `$(cat …)` on the launch line (§7.1). It may hold the user's secrets, so
+ * unlike an artifact it has no fingerprint, is never reused, and is removed when the
+ * launch is over.
+ *
+ * @throws {RoleArtifactError} It could not be written
+ * @throws {UatIsolationLaunchRefusedError} The run may not write there
+ */
+function writeLaunchEnvFile(adapter, content, options = {}) {
+    const root = dataRootFor(options);
+    const dir = (0, path_1.join)(root, 'launch-env');
+    const path = (0, path_1.join)(dir, `${(0, crypto_1.randomBytes)(12).toString('hex')}.json`);
+    const env = options.env ?? process.env;
+    if ((0, uat_isolation_1.sharedHookWritePolicy)(adapter, [path], env) === 'read-only' && isSharedHomeState(root)) {
+        throw new uat_isolation_1.UatIsolationLaunchRefusedError(adapter, `the file ${path} may not be written by this run`, uat_isolation_1.UAT_SAME_BUILD_FIX);
+    }
+    const rootIsOurs = physicalPath(root) === physicalPath(defaultDataRoot());
+    const location = {
+        path,
+        homeDir: null,
+        sharedDirs: rootIsOurs ? [] : [root],
+        ownedDirs: rootIsOurs ? [root, dir] : [dir],
+        inSharedHome: false,
+    };
+    checkDirectories(location, true);
+    try {
+        createMissingDirectories(location);
+        if (!publishExclusively(path, Buffer.from(content, 'utf8'))) {
+            throw new RoleArtifactError('write-failed', `${path} already exists`);
+        }
+    }
+    catch (error) {
+        if (error instanceof RoleArtifactError)
+            throw error;
+        throw new RoleArtifactError('write-failed', `Could not write ${path}: ${error.code ?? 'unknown error'}`);
+    }
+    return path;
+}
+/** Remove what {@link writeLaunchEnvFile} wrote. Never throws: the launch is already over. */
+function removeLaunchEnvFile(path) {
+    try {
+        (0, fs_1.unlinkSync)(path);
+    }
+    catch {
+        // Already gone, or not ours to fix now.
+    }
+}
+/**
+ * Checks 1 and 2 of §5, for the moment before a launch: the file is where this
+ * adapter keeps it, behind directories that could not have been swapped, is what
+ * the writer said, and reads as this adapter's format. Changes nothing.
+ *
+ * @param options - The same options the file was written with
+ * @throws {RoleArtifactError}
+ */
+function inspectRoleArtifact(input, options = {}) {
+    const { adapter, name, path, expectedFingerprint } = input;
+    const location = resolveArtifactLocation(adapter, name, options);
+    if (location.path !== path) {
+        throw new RoleArtifactError('unexpected-location', `${path} is not where this adapter keeps ${name}`);
+    }
+    checkDirectories(location, false);
+    inspectFile(adapter, name, path, expectedFingerprint);
+}
+/**
+ * The bytes CommandMate wrote for this Codex profile, given what is in it now.
+ *
+ * `codex -p <profile>` saves into the profile itself: answering the folder-trust
+ * screen adds `[projects."<path>"]` there and leaves `config.toml` alone (measured
+ * on 0.166.0, #4136). That is the CLI using its own file, so it must not lock the
+ * role out, and CommandMate does not rewrite the file to undo it. What the role
+ * depends on is `developer_instructions`, so that alone decides. Everything else
+ * in the file has the standing of `config.toml`: only this user can write either.
+ *
+ * @returns null when no such text can be read from the file
+ */
+function codexProfileAsWritten(bytes) {
+    try {
+        const value = (0, smol_toml_1.parse)(bytes.toString('utf8')).developer_instructions;
+        return typeof value === 'string' ? Buffer.from((0, toml_basic_1.renderTomlBasicDocument)({ developer_instructions: value }), 'utf8') : null;
+    }
+    catch {
+        return null;
+    }
+}
+function inspectFile(adapter, name, path, expectedFingerprint) {
+    const bytes = readExistingArtifact(path);
+    if (bytes === null)
+        throw new RoleArtifactError('missing', `${path} does not exist`);
+    if ((0, fingerprint_1.computeFingerprint)(bytes) !== expectedFingerprint) {
+        const asWritten = adapter === 'codex' ? codexProfileAsWritten(bytes) : null;
+        if (asWritten === null || (0, fingerprint_1.computeFingerprint)(asWritten) !== expectedFingerprint) {
+            throw new RoleArtifactError('content-mismatch', `${path} is not the expected content`);
+        }
+    }
+    const problem = formatProblem(adapter, name, bytes);
+    if (problem)
+        throw new RoleArtifactError('format-invalid', `${path}: ${problem}`);
+}
+/**
+ * Make sure the artifact exists with exactly this content, writing it only if it
+ * is absent and the run may write there.
+ *
+ * In `CM_UAT_ISOLATION=1` nothing is changed in the user's shared state
+ * (`config/uat-isolation.ts`): an identical file behind sound directories is
+ * reused, and anything else refuses the launch. A data root that really is
+ * elsewhere (see {@link isSharedHomeState}) belongs to the run and may be written.
+ *
+ * @throws {RoleArtifactError} The file cannot be used
+ * @throws {UatIsolationLaunchRefusedError} The run may not write it
+ */
+function writeRoleArtifact(input, options = {}) {
+    const { adapter, name, instructions } = input;
+    assertArtifactName(name);
+    // §5 check 3: an empty role does not become "no role".
+    if (instructions.trim() === '') {
+        throw new RoleArtifactError('empty-instructions', 'A role artifact needs instructions');
+    }
+    const location = resolveArtifactLocation(adapter, name, options);
+    const bytes = renderRoleArtifact(adapter, name, instructions);
+    const artifactFingerprint = (0, fingerprint_1.computeFingerprint)(bytes);
+    const written = (reused) => ({
+        adapter,
+        name,
+        path: location.path,
+        artifactFingerprint,
+        reused,
+    });
+    const inspect = () => inspectFile(adapter, name, location.path, artifactFingerprint);
+    const policy = (0, uat_isolation_1.sharedHookWritePolicy)(adapter, [location.path], options.env ?? process.env);
+    const readOnly = policy === 'read-only' && location.inSharedHome;
+    // Before the file is read: a good file behind a swapped directory is not ours.
+    checkDirectories(location, !readOnly);
+    if (readExistingArtifact(location.path) !== null) {
+        inspect();
+        return written(true);
+    }
+    if (readOnly) {
+        throw new uat_isolation_1.UatIsolationLaunchRefusedError(adapter, `the role artifact ${location.path} does not exist and this run may not write it`, uat_isolation_1.UAT_SAME_BUILD_FIX);
+    }
+    let published;
+    try {
+        createMissingDirectories(location);
+        published = publishExclusively(location.path, bytes);
+    }
+    catch (error) {
+        if (error instanceof RoleArtifactError)
+            throw error;
+        throw new RoleArtifactError('write-failed', `Could not write ${location.path}: ${error.code ?? 'unknown error'}`);
+    }
+    // Read back either way. If another writer won the race this is also what proves
+    // its bytes are ours.
+    inspect();
+    return written(!published);
+}