@modelprofile.com/mcp-crossharness 5.4.0 → 5.5.0

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@modelprofile.com/mcp-crossharness',
-    version: '5.4.0',
+    version: '5.5.0',
     description: 'Connection-first MCP server for explicit OpenCode HTTP and Codex WebSocket session servers'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSxvQ0FBb0M7SUFDMUMsT0FBTyxFQUFFLE9BQU87SUFDaEIsV0FBVyxFQUFFLDRGQUE0RjtDQUMxRyxDQUFBIn0=

package/dist_ts/functions.codexunixsocket.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Codex's `--listen unix://PATH` contract since Codex 0.156.0 (codex-rs/app-server-transport,
+ * `protected_socket_path`): the socket is bound in the fixed per-user directory
+ * `<realpath /tmp>/codex-daemon-<euid>` under the SHA-256 of PATH with its parent canonicalised,
+ * and PATH itself is only a symlink to it. Earlier releases bound PATH directly; that layout is
+ * not this contract and is refused like any other foreign entry.
+ */
+export interface ICodexUnixSocketOptions {
+    /**
+     * Codex's per-user socket directory. Defaults to `<realpath /tmp>/codex-daemon-<euid>`, which
+     * Codex derives without HOME, TMPDIR or CODEX_HOME; override it only for fixtures.
+     */
+    daemonDirectory?: string;
+}
+/** `absent`: nothing exists at the path. `published`: Codex's own alias to a private socket. */
+export type TCodexUnixSocketPublication = 'absent' | 'published';
+/** Where Codex binds the socket it publishes at `socketPathArg`. The parent directory must exist. */
+export declare const codexUnixSocketTarget: (socketPathArg: string, optionsArg?: ICodexUnixSocketOptions) => Promise<string>;
+/**
+ * Reports whether Codex has published an app-server socket at `socketPathArg`. Anything present
+ * must be exactly Codex's own same-user link to its target, in a parent other users cannot
+ * rewrite (Codex's own startup condition), pointing at a same-user socket in a 0700 same-user
+ * directory; every other entry throws instead of being connected to.
+ */
+export declare const observeCodexUnixSocket: (socketPathArg: string, optionsArg?: ICodexUnixSocketOptions) => Promise<TCodexUnixSocketPublication>;

package/dist_ts/functions.codexunixsocket.js

@@ -0,0 +1,94 @@
+import * as plugins from './plugins.js';
+import * as helpers from './helpers.js';
+const assertNormalizedAbsolute = (pathArg, messageArg) => {
+    if (typeof pathArg !== 'string' || !plugins.path.isAbsolute(pathArg) || pathArg.includes('\0')
+        || plugins.path.normalize(pathArg) !== pathArg) {
+        throw new Error(messageArg);
+    }
+};
+/**
+ * Codex splits PATH into parent and file name with Rust's `Path`, which drops `.` components and
+ * has no file name for `..`; a normalized path without a trailing separator splits identically here.
+ */
+const assertSocketPath = (socketPathArg) => {
+    const message = 'Codex Unix socket path must be a normalized absolute file path';
+    assertNormalizedAbsolute(socketPathArg, message);
+    if (socketPathArg.endsWith(plugins.path.sep))
+        throw new Error(message);
+};
+/** Codex keys its directory and checks every entry by the effective uid, so this module does too. */
+const effectiveUserId = () => {
+    const euid = process.geteuid?.();
+    if (euid === undefined)
+        throw new Error('Codex Unix socket inspection requires a POSIX effective user id');
+    return euid;
+};
+/** A malformed root is a caller error, so it throws whatever exists at the socket path. */
+const assertOptions = (optionsArg) => {
+    if (optionsArg.daemonDirectory !== undefined) {
+        assertNormalizedAbsolute(optionsArg.daemonDirectory, 'Codex daemon socket directory must be a normalized absolute path');
+    }
+};
+const daemonDirectoryFor = async (optionsArg, euidArg) => {
+    if (optionsArg.daemonDirectory !== undefined)
+        return optionsArg.daemonDirectory;
+    return plugins.path.join(await plugins.fs.promises.realpath('/tmp'), `codex-daemon-${euidArg}`);
+};
+const isMissing = (errorArg) => helpers.isRecord(errorArg) && errorArg.code === 'ENOENT';
+/** Where Codex binds the socket it publishes at `socketPathArg`. The parent directory must exist. */
+export const codexUnixSocketTarget = async (socketPathArg, optionsArg = {}) => {
+    assertSocketPath(socketPathArg);
+    assertOptions(optionsArg);
+    const euid = effectiveUserId();
+    const directory = await daemonDirectoryFor(optionsArg, euid);
+    const canonical = plugins.path.join(await plugins.fs.promises.realpath(plugins.path.dirname(socketPathArg)), plugins.path.basename(socketPathArg));
+    return plugins.path.join(directory, plugins.crypto.createHash('sha256').update(canonical).digest('hex'));
+};
+/**
+ * Reports whether Codex has published an app-server socket at `socketPathArg`. Anything present
+ * must be exactly Codex's own same-user link to its target, in a parent other users cannot
+ * rewrite (Codex's own startup condition), pointing at a same-user socket in a 0700 same-user
+ * directory; every other entry throws instead of being connected to.
+ */
+export const observeCodexUnixSocket = async (socketPathArg, optionsArg = {}) => {
+    assertSocketPath(socketPathArg);
+    assertOptions(optionsArg);
+    const euid = effectiveUserId();
+    let alias;
+    try {
+        alias = await plugins.fs.promises.lstat(socketPathArg);
+    }
+    catch (error) {
+        if (isMissing(error))
+            return 'absent';
+        throw error;
+    }
+    const target = await codexUnixSocketTarget(socketPathArg, optionsArg);
+    if (!alias.isSymbolicLink() || alias.uid !== euid || await plugins.fs.promises.readlink(socketPathArg) !== target) {
+        throw new Error('Codex Unix socket path is not the alias Codex publishes');
+    }
+    const parent = await plugins.fs.promises.stat(plugins.path.dirname(socketPathArg));
+    if (!parent.isDirectory() || (parent.uid !== 0 && parent.uid !== euid)
+        || ((parent.mode & 0o022) !== 0 && (parent.mode & 0o1000) === 0)) {
+        throw new Error('Codex Unix socket parent directory lets other users replace its entries');
+    }
+    let directory;
+    let socket;
+    try {
+        directory = await plugins.fs.promises.lstat(plugins.path.dirname(target));
+        socket = await plugins.fs.promises.lstat(target);
+    }
+    catch (error) {
+        if (isMissing(error))
+            throw new Error('Codex Unix socket alias has no socket behind it');
+        throw error;
+    }
+    if (!directory.isDirectory() || directory.uid !== euid || (directory.mode & 0o777) !== 0o700) {
+        throw new Error('Codex Unix socket directory is not private to the current user');
+    }
+    if (!socket.isSocket() || socket.uid !== euid) {
+        throw new Error('Codex Unix socket is not a socket owned by the current user');
+    }
+    return 'published';
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZnVuY3Rpb25zLmNvZGV4dW5peHNvY2tldC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL2Z1bmN0aW9ucy5jb2RleHVuaXhzb2NrZXQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSxjQUFjLENBQUM7QUFDeEMsT0FBTyxLQUFLLE9BQU8sTUFBTSxjQUFjLENBQUM7QUFvQnhDLE1BQU0sd0JBQXdCLEdBQUcsQ0FBQyxPQUFlLEVBQUUsVUFBa0IsRUFBUSxFQUFFO0lBQzdFLElBQUksT0FBTyxPQUFPLEtBQUssUUFBUSxJQUFJLENBQUMsT0FBTyxDQUFDLElBQUksQ0FBQyxVQUFVLENBQUMsT0FBTyxDQUFDLElBQUksT0FBTyxDQUFDLFFBQVEsQ0FBQyxJQUFJLENBQUM7V0FDekYsT0FBTyxDQUFDLElBQUksQ0FBQyxTQUFTLENBQUMsT0FBTyxDQUFDLEtBQUssT0FBTyxFQUFFLENBQUM7UUFDakQsTUFBTSxJQUFJLEtBQUssQ0FBQyxVQUFVLENBQUMsQ0FBQztJQUM5QixDQUFDO0FBQ0gsQ0FBQyxDQUFDO0FBRUY7OztHQUdHO0FBQ0gsTUFBTSxnQkFBZ0IsR0FBRyxDQUFDLGFBQXFCLEVBQVEsRUFBRTtJQUN2RCxNQUFNLE9BQU8sR0FBRyxnRUFBZ0UsQ0FBQztJQUNqRix3QkFBd0IsQ0FBQyxhQUFhLEVBQUUsT0FBTyxDQUFDLENBQUM7SUFDakQsSUFBSSxhQUFhLENBQUMsUUFBUSxDQUFDLE9BQU8sQ0FBQyxJQUFJLENBQUMsR0FBRyxDQUFDO1FBQUUsTUFBTSxJQUFJLEtBQUssQ0FBQyxPQUFPLENBQUMsQ0FBQztBQUN6RSxDQUFDLENBQUM7QUFFRixxR0FBcUc7QUFDckcsTUFBTSxlQUFlLEdBQUcsR0FBVyxFQUFFO0lBQ25DLE1BQU0sSUFBSSxHQUFHLE9BQU8sQ0FBQyxPQUFPLEVBQUUsRUFBRSxDQUFDO0lBQ2pDLElBQUksSUFBSSxLQUFLLFNBQVM7UUFBRSxNQUFNLElBQUksS0FBSyxDQUFDLGlFQUFpRSxDQUFDLENBQUM7SUFDM0csT0FBTyxJQUFJLENBQUM7QUFDZCxDQUFDLENBQUM7QUFFRiwyRkFBMkY7QUFDM0YsTUFBTSxhQUFhLEdBQUcsQ0FBQyxVQUFtQyxFQUFRLEVBQUU7SUFDbEUsSUFBSSxVQUFVLENBQUMsZUFBZSxLQUFLLFNBQVMsRUFBRSxDQUFDO1FBQzdDLHdCQUF3QixDQUFDLFVBQVUsQ0FBQyxlQUFlLEVBQUUsa0VBQWtFLENBQUMsQ0FBQztJQUMzSCxDQUFDO0FBQ0gsQ0FBQyxDQUFDO0FBRUYsTUFBTSxrQkFBa0IsR0FBRyxLQUFLLEVBQUUsVUFBbUMsRUFBRSxPQUFlLEVBQW1CLEVBQUU7SUFDekcsSUFBSSxVQUFVLENBQUMsZUFBZSxLQUFLLFNBQVM7UUFBRSxPQUFPLFVBQVUsQ0FBQyxlQUFlLENBQUM7SUFDaEYsT0FBTyxPQUFPLENBQUMsSUFBSSxDQUFDLElBQUksQ0FBQyxNQUFNLE9BQU8sQ0FBQyxFQUFFLENBQUMsUUFBUSxDQUFDLFFBQVEsQ0FBQyxNQUFNLENBQUMsRUFBRSxnQkFBZ0IsT0FBTyxFQUFFLENBQUMsQ0FBQztBQUNsRyxDQUFDLENBQUM7QUFFRixNQUFNLFNBQVMsR0FBRyxDQUFDLFFBQWlCLEVBQVcsRUFBRSxDQUFDLE9BQU8sQ0FBQyxRQUFRLENBQUMsUUFBUSxDQUFDLElBQUksUUFBUSxDQUFDLElBQUksS0FBSyxRQUFRLENBQUM7QUFFM0cscUdBQXFHO0FBQ3JHLE1BQU0sQ0FBQyxNQUFNLHFCQUFxQixHQUFHLEtBQUssRUFDeEMsYUFBcUIsRUFDckIsYUFBc0MsRUFBRSxFQUN2QixFQUFFO0lBQ25CLGdCQUFnQixDQUFDLGFBQWEsQ0FBQyxDQUFDO0lBQ2hDLGFBQWEsQ0FBQyxVQUFVLENBQUMsQ0FBQztJQUMxQixNQUFNLElBQUksR0FBRyxlQUFlLEVBQUUsQ0FBQztJQUMvQixNQUFNLFNBQVMsR0FBRyxNQUFNLGtCQUFrQixDQUFDLFVBQVUsRUFBRSxJQUFJLENBQUMsQ0FBQztJQUM3RCxNQUFNLFNBQVMsR0FBRyxPQUFPLENBQUMsSUFBSSxDQUFDLElBQUksQ0FBQyxNQUFNLE9BQU8sQ0FBQyxFQUFFLENBQUMsUUFBUSxDQUFDLFFBQVEsQ0FBQyxPQUFPLENBQUMsSUFBSSxDQUFDLE9BQU8sQ0FBQyxhQUFhLENBQUMsQ0FBQyxFQUN6RyxPQUFPLENBQUMsSUFBSSxDQUFDLFFBQVEsQ0FBQyxhQUFhLENBQUMsQ0FBQyxDQUFDO0lBQ3hDLE9BQU8sT0FBTyxDQUFDLElBQUksQ0FBQyxJQUFJLENBQUMsU0FBUyxFQUFFLE9BQU8sQ0FBQyxNQUFNLENBQUMsVUFBVSxDQUFDLFFBQVEsQ0FBQyxDQUFDLE1BQU0sQ0FBQyxTQUFTLENBQUMsQ0FBQyxNQUFNLENBQUMsS0FBSyxDQUFDLENBQUMsQ0FBQztBQUMzRyxDQUFDLENBQUM7QUFFRjs7Ozs7R0FLRztBQUNILE1BQU0sQ0FBQyxNQUFNLHNCQUFzQixHQUFHLEtBQUssRUFDekMsYUFBcUIsRUFDckIsYUFBc0MsRUFBRSxFQUNGLEVBQUU7SUFDeEMsZ0JBQWdCLENBQUMsYUFBYSxDQUFDLENBQUM7SUFDaEMsYUFBYSxDQUFDLFVBQVUsQ0FBQyxDQUFDO0lBQzFCLE1BQU0sSUFBSSxHQUFHLGVBQWUsRUFBRSxDQUFDO0lBQy9CLElBQUksS0FBdUIsQ0FBQztJQUM1QixJQUFJLENBQUM7UUFDSCxLQUFLLEdBQUcsTUFBTSxPQUFPLENBQUMsRUFBRSxDQUFDLFFBQVEsQ0FBQyxLQUFLLENBQUMsYUFBYSxDQUFDLENBQUM7SUFDekQsQ0FBQztJQUFDLE9BQU8sS0FBSyxFQUFFLENBQUM7UUFDZixJQUFJLFNBQVMsQ0FBQyxLQUFLLENBQUM7WUFBRSxPQUFPLFFBQVEsQ0FBQztRQUN0QyxNQUFNLEtBQUssQ0FBQztJQUNkLENBQUM7SUFDRCxNQUFNLE1BQU0sR0FBRyxNQUFNLHFCQUFxQixDQUFDLGFBQWEsRUFBRSxVQUFVLENBQUMsQ0FBQztJQUN0RSxJQUFJLENBQUMsS0FBSyxDQUFDLGNBQWMsRUFBRSxJQUFJLEtBQUssQ0FBQyxHQUFHLEtBQUssSUFBSSxJQUFJLE1BQU0sT0FBTyxDQUFDLEVBQUUsQ0FBQyxRQUFRLENBQUMsUUFBUSxDQUFDLGFBQWEsQ0FBQyxLQUFLLE1BQU0sRUFBRSxDQUFDO1FBQ2xILE1BQU0sSUFBSSxLQUFLLENBQUMseURBQXlELENBQUMsQ0FBQztJQUM3RSxDQUFDO0lBQ0QsTUFBTSxNQUFNLEdBQUcsTUFBTSxPQUFPLENBQUMsRUFBRSxDQUFDLFFBQVEsQ0FBQyxJQUFJLENBQUMsT0FBTyxDQUFDLElBQUksQ0FBQyxPQUFPLENBQUMsYUFBYSxDQUFDLENBQUMsQ0FBQztJQUNuRixJQUFJLENBQUMsTUFBTSxDQUFDLFdBQVcsRUFBRSxJQUFJLENBQUMsTUFBTSxDQUFDLEdBQUcsS0FBSyxDQUFDLElBQUksTUFBTSxDQUFDLEdBQUcsS0FBSyxJQUFJLENBQUM7V0FDakUsQ0FBQyxDQUFDLE1BQU0sQ0FBQyxJQUFJLEdBQUcsS0FBSyxDQUFDLEtBQUssQ0FBQyxJQUFJLENBQUMsTUFBTSxDQUFDLElBQUksR0FBRyxNQUFNLENBQUMsS0FBSyxDQUFDLENBQUMsRUFBRSxDQUFDO1FBQ25FLE1BQU0sSUFBSSxLQUFLLENBQUMseUVBQXlFLENBQUMsQ0FBQztJQUM3RixDQUFDO0lBQ0QsSUFBSSxTQUEyQixDQUFDO0lBQ2hDLElBQUksTUFBd0IsQ0FBQztJQUM3QixJQUFJLENBQUM7UUFDSCxTQUFTLEdBQUcsTUFBTSxPQUFPLENBQUMsRUFBRSxDQUFDLFFBQVEsQ0FBQyxLQUFLLENBQUMsT0FBTyxDQUFDLElBQUksQ0FBQyxPQUFPLENBQUMsTUFBTSxDQUFDLENBQUMsQ0FBQztRQUMxRSxNQUFNLEdBQUcsTUFBTSxPQUFPLENBQUMsRUFBRSxDQUFDLFFBQVEsQ0FBQyxLQUFLLENBQUMsTUFBTSxDQUFDLENBQUM7SUFDbkQsQ0FBQztJQUFDLE9BQU8sS0FBSyxFQUFFLENBQUM7UUFDZixJQUFJLFNBQVMsQ0FBQyxLQUFLLENBQUM7WUFBRSxNQUFNLElBQUksS0FBSyxDQUFDLGlEQUFpRCxDQUFDLENBQUM7UUFDekYsTUFBTSxLQUFLLENBQUM7SUFDZCxDQUFDO0lBQ0QsSUFBSSxDQUFDLFNBQVMsQ0FBQyxXQUFXLEVBQUUsSUFBSSxTQUFTLENBQUMsR0FBRyxLQUFLLElBQUksSUFBSSxDQUFDLFNBQVMsQ0FBQyxJQUFJLEdBQUcsS0FBSyxDQUFDLEtBQUssS0FBSyxFQUFFLENBQUM7UUFDN0YsTUFBTSxJQUFJLEtBQUssQ0FBQyxnRUFBZ0UsQ0FBQyxDQUFDO0lBQ3BGLENBQUM7SUFDRCxJQUFJLENBQUMsTUFBTSxDQUFDLFFBQVEsRUFBRSxJQUFJLE1BQU0sQ0FBQyxHQUFHLEtBQUssSUFBSSxFQUFFLENBQUM7UUFDOUMsTUFBTSxJQUFJLEtBQUssQ0FBQyw2REFBNkQsQ0FBQyxDQUFDO0lBQ2pGLENBQUM7SUFDRCxPQUFPLFdBQVcsQ0FBQztBQUNyQixDQUFDLENBQUMifQ==

package/dist_ts/index.d.ts

@@ -1,5 +1,6 @@
 export * from './interfaces.js';
 export * from './classes.codexappserverclient.js';
+export * from './functions.codexunixsocket.js';
 export * from './classes.connectionregistry.js';
 export * from './classes.dispatchregistry.js';
 export * from './classes.mcptoolregistrar.js';

package/dist_ts/index.js

@@ -1,5 +1,6 @@
 export * from './interfaces.js';
 export * from './classes.codexappserverclient.js';
+export * from './functions.codexunixsocket.js';
 export * from './classes.connectionregistry.js';
 export * from './classes.dispatchregistry.js';
 export * from './classes.mcptoolregistrar.js';
@@ -8,4 +9,4 @@ import { CrossHarnessMcpServer } from './classes.mcpserver.js';
 export const runCli = async () => {
     await new CrossHarnessMcpServer().start();
 };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxjQUFjLGlCQUFpQixDQUFDO0FBQ2hDLGNBQWMsbUNBQW1DLENBQUM7QUFDbEQsY0FBYyxpQ0FBaUMsQ0FBQztBQUNoRCxjQUFjLCtCQUErQixDQUFDO0FBQzlDLGNBQWMsK0JBQStCLENBQUM7QUFDOUMsY0FBYyx3QkFBd0IsQ0FBQztBQUV2QyxPQUFPLEVBQUUscUJBQXFCLEVBQUUsTUFBTSx3QkFBd0IsQ0FBQztBQUUvRCxNQUFNLENBQUMsTUFBTSxNQUFNLEdBQUcsS0FBSyxJQUFtQixFQUFFO0lBQzlDLE1BQU0sSUFBSSxxQkFBcUIsRUFBRSxDQUFDLEtBQUssRUFBRSxDQUFDO0FBQzVDLENBQUMsQ0FBQyJ9
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxjQUFjLGlCQUFpQixDQUFDO0FBQ2hDLGNBQWMsbUNBQW1DLENBQUM7QUFDbEQsY0FBYyxnQ0FBZ0MsQ0FBQztBQUMvQyxjQUFjLGlDQUFpQyxDQUFDO0FBQ2hELGNBQWMsK0JBQStCLENBQUM7QUFDOUMsY0FBYywrQkFBK0IsQ0FBQztBQUM5QyxjQUFjLHdCQUF3QixDQUFDO0FBRXZDLE9BQU8sRUFBRSxxQkFBcUIsRUFBRSxNQUFNLHdCQUF3QixDQUFDO0FBRS9ELE1BQU0sQ0FBQyxNQUFNLE1BQU0sR0FBRyxLQUFLLElBQW1CLEVBQUU7SUFDOUMsTUFBTSxJQUFJLHFCQUFxQixFQUFFLENBQUMsS0FBSyxFQUFFLENBQUM7QUFDNUMsQ0FBQyxDQUFDIn0=

package/dist_ts/plugins.d.ts

@@ -1,9 +1,11 @@
 import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
 import * as http from 'node:http';
 import * as net from 'node:net';
+import * as path from 'node:path';
 import * as stream from 'node:stream';
 import type { AddressInfo } from 'node:net';
-export { crypto, http, net, stream };
+export { crypto, fs, http, net, path, stream };
 export type { AddressInfo };
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { RegisteredTool } from '@modelcontextprotocol/sdk/server/mcp.js';

package/dist_ts/plugins.js

@@ -1,9 +1,11 @@
 // Node native modules
 import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
 import * as http from 'node:http';
 import * as net from 'node:net';
+import * as path from 'node:path';
 import * as stream from 'node:stream';
-export { crypto, http, net, stream };
+export { crypto, fs, http, net, path, stream };
 // Third-party modules
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
@@ -12,4 +14,4 @@ import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
 import { WebSocket as WsWebSocket, WebSocketServer } from 'ws';
 import { z } from 'zod';
 export { InMemoryTransport, McpClient, McpServer, StdioServerTransport, WebSocketServer, WsWebSocket, z, };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL3BsdWdpbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsc0JBQXNCO0FBQ3RCLE9BQU8sS0FBSyxNQUFNLE1BQU0sYUFBYSxDQUFDO0FBQ3RDLE9BQU8sS0FBSyxJQUFJLE1BQU0sV0FBVyxDQUFDO0FBQ2xDLE9BQU8sS0FBSyxHQUFHLE1BQU0sVUFBVSxDQUFDO0FBQ2hDLE9BQU8sS0FBSyxNQUFNLE1BQU0sYUFBYSxDQUFDO0FBR3RDLE9BQU8sRUFBRSxNQUFNLEVBQUUsSUFBSSxFQUFFLEdBQUcsRUFBRSxNQUFNLEVBQUUsQ0FBQztBQUdyQyxzQkFBc0I7QUFDdEIsT0FBTyxFQUFFLFNBQVMsRUFBRSxNQUFNLHlDQUF5QyxDQUFDO0FBRXBFLE9BQU8sRUFBRSxvQkFBb0IsRUFBRSxNQUFNLDJDQUEyQyxDQUFDO0FBQ2pGLE9BQU8sRUFBRSxNQUFNLElBQUksU0FBUyxFQUFFLE1BQU0sMkNBQTJDLENBQUM7QUFDaEYsT0FBTyxFQUFFLGlCQUFpQixFQUFFLE1BQU0sdUNBQXVDLENBQUM7QUFFMUUsT0FBTyxFQUFFLFNBQVMsSUFBSSxXQUFXLEVBQUUsZUFBZSxFQUFFLE1BQU0sSUFBSSxDQUFDO0FBRS9ELE9BQU8sRUFBRSxDQUFDLEVBQUUsTUFBTSxLQUFLLENBQUM7QUFFeEIsT0FBTyxFQUNMLGlCQUFpQixFQUNqQixTQUFTLEVBQ1QsU0FBUyxFQUNULG9CQUFvQixFQUNwQixlQUFlLEVBQ2YsV0FBVyxFQUNYLENBQUMsR0FDRixDQUFDIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL3BsdWdpbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsc0JBQXNCO0FBQ3RCLE9BQU8sS0FBSyxNQUFNLE1BQU0sYUFBYSxDQUFDO0FBQ3RDLE9BQU8sS0FBSyxFQUFFLE1BQU0sU0FBUyxDQUFDO0FBQzlCLE9BQU8sS0FBSyxJQUFJLE1BQU0sV0FBVyxDQUFDO0FBQ2xDLE9BQU8sS0FBSyxHQUFHLE1BQU0sVUFBVSxDQUFDO0FBQ2hDLE9BQU8sS0FBSyxJQUFJLE1BQU0sV0FBVyxDQUFDO0FBQ2xDLE9BQU8sS0FBSyxNQUFNLE1BQU0sYUFBYSxDQUFDO0FBR3RDLE9BQU8sRUFBRSxNQUFNLEVBQUUsRUFBRSxFQUFFLElBQUksRUFBRSxHQUFHLEVBQUUsSUFBSSxFQUFFLE1BQU0sRUFBRSxDQUFDO0FBRy9DLHNCQUFzQjtBQUN0QixPQUFPLEVBQUUsU0FBUyxFQUFFLE1BQU0seUNBQXlDLENBQUM7QUFFcEUsT0FBTyxFQUFFLG9CQUFvQixFQUFFLE1BQU0sMkNBQTJDLENBQUM7QUFDakYsT0FBTyxFQUFFLE1BQU0sSUFBSSxTQUFTLEVBQUUsTUFBTSwyQ0FBMkMsQ0FBQztBQUNoRixPQUFPLEVBQUUsaUJBQWlCLEVBQUUsTUFBTSx1Q0FBdUMsQ0FBQztBQUUxRSxPQUFPLEVBQUUsU0FBUyxJQUFJLFdBQVcsRUFBRSxlQUFlLEVBQUUsTUFBTSxJQUFJLENBQUM7QUFFL0QsT0FBTyxFQUFFLENBQUMsRUFBRSxNQUFNLEtBQUssQ0FBQztBQUV4QixPQUFPLEVBQ0wsaUJBQWlCLEVBQ2pCLFNBQVMsRUFDVCxTQUFTLEVBQ1Qsb0JBQW9CLEVBQ3BCLGVBQWUsRUFDZixXQUFXLEVBQ1gsQ0FBQyxHQUNGLENBQUMifQ==

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modelprofile.com/mcp-crossharness",
-  "version": "5.4.0",
+  "version": "5.5.0",
   "private": false,
   "description": "Connection-first MCP server for explicit OpenCode HTTP and Codex WebSocket session servers",
   "main": "dist_ts/index.js",
@@ -23,10 +23,10 @@
     "mcp-crossharness": "./cli.js"
   },
   "devDependencies": {
-    "@git.zone/tsbuild": "^4.4.2",
-    "@git.zone/tsrun": "^2.0.6",
-    "@git.zone/tstest": "^4.0.0",
-    "@types/node": "^26.4.1",
+    "@git.zone/tsbuild": "^5.0.0",
+    "@git.zone/tsrun": "^3.0.0",
+    "@git.zone/tstest": "^6.2.1",
+    "@types/node": "^26.6.1",
     "@types/ws": "^8.18.1"
   },
   "dependencies": {

package/readme.md

@@ -197,6 +197,56 @@ client never grants or automatically declines a permission. `close()` ends the s
 stdio streams but never kills a subprocess. The existing MCP Codex adapter delegates to
 this client and retains its conservative automatic rejection policy.
 
+### Codex Unix socket alias
+
+Since Codex 0.156.0, `codex app-server --listen unix://PATH` does not bind PATH. Codex binds
+the socket in its fixed per-user directory, `<realpath /tmp>/codex-daemon-<euid>` (mode 0700),
+under the SHA-256 of PATH with its parent directory canonicalised, and publishes PATH as a
+symlink to it. Its shared local daemon socket, `$CODEX_HOME/app-server-control/app-server-control.sock`,
+is published the same way. The unix transport connects through that link like any other
+path; these two functions let a caller check, before connecting, that the entry really is
+Codex's own:
+
+```typescript
+import { CodexAppServerClient, codexUnixSocketTarget, observeCodexUnixSocket } from '@modelprofile.com/mcp-crossharness';
+
+const target = await codexUnixSocketTarget(socketPath); // where Codex binds PATH
+if (await observeCodexUnixSocket(socketPath) === 'published') {
+  const client = new CodexAppServerClient({
+    transport: { type: 'unix', socketPath },
+    clientInfo: { name: 'my-app', title: 'My App', version: '1.0.0' },
+  });
+  await client.connect();
+}
+```
+
+`observeCodexUnixSocket(socketPath)` returns `'absent'` when nothing exists at the path and
+`'published'` only when the path is a link owned by the effective user whose text is exactly
+the derived target, in a parent directory other users cannot rewrite (owned by the user or
+root, and not group- or world-writable unless sticky, which is Codex's own startup condition),
+pointing at a socket owned by the effective user in a directory owned by that user with mode
+0700. Every other entry throws, and nothing is created, removed or connected to. Ownership is
+compared with the effective uid because Codex keys the directory by and checks against it.
+A socket bound directly at the path, as Codex 0.155 and earlier did, is not this contract
+and is refused like any other foreign entry.
+
+Both functions take an optional `{ daemonDirectory }` that replaces the per-user directory for
+fixtures; `codexUnixSocketTarget` needs the socket's parent directory to exist. They throw
+plain `Error`s with these exact messages:
+
+| Message | Cause |
+| --- | --- |
+| `Codex Unix socket path must be a normalized absolute file path` | relative, non-normalized, trailing-separator or NUL-containing path |
+| `Codex daemon socket directory must be a normalized absolute path` | invalid `daemonDirectory` |
+| `Codex Unix socket inspection requires a POSIX effective user id` | no `process.geteuid` (Windows) |
+| `Codex Unix socket path is not the alias Codex publishes` | a regular file, a direct socket, another user's link, or a link to any other target |
+| `Codex Unix socket parent directory lets other users replace its entries` | the path's parent is not safe for a published alias |
+| `Codex Unix socket alias has no socket behind it` | Codex's own link whose target is gone (a stale publication) |
+| `Codex Unix socket directory is not private to the current user` | the per-user directory is not the user's own 0700 directory |
+| `Codex Unix socket is not a socket owned by the current user` | the target is not a socket, or is another user's |
+
+Filesystem errors other than a missing path propagate unchanged.
+
 ### Composable tool registration
 
 `CrossHarnessMcpToolRegistrar` registers the same nine Crossharness tools used by the standalone

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@modelprofile.com/mcp-crossharness',
-  version: '5.4.0',
+  version: '5.5.0',
   description: 'Connection-first MCP server for explicit OpenCode HTTP and Codex WebSocket session servers'
 }

package/ts/functions.codexunixsocket.ts

@@ -0,0 +1,119 @@
+import * as plugins from './plugins.js';
+import * as helpers from './helpers.js';
+
+/**
+ * Codex's `--listen unix://PATH` contract since Codex 0.156.0 (codex-rs/app-server-transport,
+ * `protected_socket_path`): the socket is bound in the fixed per-user directory
+ * `<realpath /tmp>/codex-daemon-<euid>` under the SHA-256 of PATH with its parent canonicalised,
+ * and PATH itself is only a symlink to it. Earlier releases bound PATH directly; that layout is
+ * not this contract and is refused like any other foreign entry.
+ */
+export interface ICodexUnixSocketOptions {
+  /**
+   * Codex's per-user socket directory. Defaults to `<realpath /tmp>/codex-daemon-<euid>`, which
+   * Codex derives without HOME, TMPDIR or CODEX_HOME; override it only for fixtures.
+   */
+  daemonDirectory?: string;
+}
+
+/** `absent`: nothing exists at the path. `published`: Codex's own alias to a private socket. */
+export type TCodexUnixSocketPublication = 'absent' | 'published';
+
+const assertNormalizedAbsolute = (pathArg: string, messageArg: string): void => {
+  if (typeof pathArg !== 'string' || !plugins.path.isAbsolute(pathArg) || pathArg.includes('\0')
+    || plugins.path.normalize(pathArg) !== pathArg) {
+    throw new Error(messageArg);
+  }
+};
+
+/**
+ * Codex splits PATH into parent and file name with Rust's `Path`, which drops `.` components and
+ * has no file name for `..`; a normalized path without a trailing separator splits identically here.
+ */
+const assertSocketPath = (socketPathArg: string): void => {
+  const message = 'Codex Unix socket path must be a normalized absolute file path';
+  assertNormalizedAbsolute(socketPathArg, message);
+  if (socketPathArg.endsWith(plugins.path.sep)) throw new Error(message);
+};
+
+/** Codex keys its directory and checks every entry by the effective uid, so this module does too. */
+const effectiveUserId = (): number => {
+  const euid = process.geteuid?.();
+  if (euid === undefined) throw new Error('Codex Unix socket inspection requires a POSIX effective user id');
+  return euid;
+};
+
+/** A malformed root is a caller error, so it throws whatever exists at the socket path. */
+const assertOptions = (optionsArg: ICodexUnixSocketOptions): void => {
+  if (optionsArg.daemonDirectory !== undefined) {
+    assertNormalizedAbsolute(optionsArg.daemonDirectory, 'Codex daemon socket directory must be a normalized absolute path');
+  }
+};
+
+const daemonDirectoryFor = async (optionsArg: ICodexUnixSocketOptions, euidArg: number): Promise<string> => {
+  if (optionsArg.daemonDirectory !== undefined) return optionsArg.daemonDirectory;
+  return plugins.path.join(await plugins.fs.promises.realpath('/tmp'), `codex-daemon-${euidArg}`);
+};
+
+const isMissing = (errorArg: unknown): boolean => helpers.isRecord(errorArg) && errorArg.code === 'ENOENT';
+
+/** Where Codex binds the socket it publishes at `socketPathArg`. The parent directory must exist. */
+export const codexUnixSocketTarget = async (
+  socketPathArg: string,
+  optionsArg: ICodexUnixSocketOptions = {},
+): Promise<string> => {
+  assertSocketPath(socketPathArg);
+  assertOptions(optionsArg);
+  const euid = effectiveUserId();
+  const directory = await daemonDirectoryFor(optionsArg, euid);
+  const canonical = plugins.path.join(await plugins.fs.promises.realpath(plugins.path.dirname(socketPathArg)),
+    plugins.path.basename(socketPathArg));
+  return plugins.path.join(directory, plugins.crypto.createHash('sha256').update(canonical).digest('hex'));
+};
+
+/**
+ * Reports whether Codex has published an app-server socket at `socketPathArg`. Anything present
+ * must be exactly Codex's own same-user link to its target, in a parent other users cannot
+ * rewrite (Codex's own startup condition), pointing at a same-user socket in a 0700 same-user
+ * directory; every other entry throws instead of being connected to.
+ */
+export const observeCodexUnixSocket = async (
+  socketPathArg: string,
+  optionsArg: ICodexUnixSocketOptions = {},
+): Promise<TCodexUnixSocketPublication> => {
+  assertSocketPath(socketPathArg);
+  assertOptions(optionsArg);
+  const euid = effectiveUserId();
+  let alias: plugins.fs.Stats;
+  try {
+    alias = await plugins.fs.promises.lstat(socketPathArg);
+  } catch (error) {
+    if (isMissing(error)) return 'absent';
+    throw error;
+  }
+  const target = await codexUnixSocketTarget(socketPathArg, optionsArg);
+  if (!alias.isSymbolicLink() || alias.uid !== euid || await plugins.fs.promises.readlink(socketPathArg) !== target) {
+    throw new Error('Codex Unix socket path is not the alias Codex publishes');
+  }
+  const parent = await plugins.fs.promises.stat(plugins.path.dirname(socketPathArg));
+  if (!parent.isDirectory() || (parent.uid !== 0 && parent.uid !== euid)
+    || ((parent.mode & 0o022) !== 0 && (parent.mode & 0o1000) === 0)) {
+    throw new Error('Codex Unix socket parent directory lets other users replace its entries');
+  }
+  let directory: plugins.fs.Stats;
+  let socket: plugins.fs.Stats;
+  try {
+    directory = await plugins.fs.promises.lstat(plugins.path.dirname(target));
+    socket = await plugins.fs.promises.lstat(target);
+  } catch (error) {
+    if (isMissing(error)) throw new Error('Codex Unix socket alias has no socket behind it');
+    throw error;
+  }
+  if (!directory.isDirectory() || directory.uid !== euid || (directory.mode & 0o777) !== 0o700) {
+    throw new Error('Codex Unix socket directory is not private to the current user');
+  }
+  if (!socket.isSocket() || socket.uid !== euid) {
+    throw new Error('Codex Unix socket is not a socket owned by the current user');
+  }
+  return 'published';
+};

package/ts/index.ts

@@ -1,5 +1,6 @@
 export * from './interfaces.js';
 export * from './classes.codexappserverclient.js';
+export * from './functions.codexunixsocket.js';
 export * from './classes.connectionregistry.js';
 export * from './classes.dispatchregistry.js';
 export * from './classes.mcptoolregistrar.js';

package/ts/plugins.ts

@@ -1,11 +1,13 @@
 // Node native modules
 import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
 import * as http from 'node:http';
 import * as net from 'node:net';
+import * as path from 'node:path';
 import * as stream from 'node:stream';
 import type { AddressInfo } from 'node:net';
 
-export { crypto, http, net, stream };
+export { crypto, fs, http, net, path, stream };
 export type { AddressInfo };
 
 // Third-party modules

package/readme.hints.md

@@ -1,52 +0,0 @@
-# readme.hints.md
-
-Implementation findings for mcp-crossharness.
-
-## Server-only architecture
-
-- Every harness operation after connection setup is scoped to an opaque connection established from an explicit server origin and remote absolute directory; `list_connections` remains global.
-- Duplicate harness/origin/directory bindings are rejected and each registry is capped at 32 connections.
-- `CROSSHARNESS_ALLOWED_SERVER_URLS` is an exact-origin allowlist. Credentials are fixed environment variables, never tool inputs.
-- URLs reject user info, query strings, fragments, and non-root paths. OpenCode fetch calls use `redirect: 'error'`.
-- No production source reads harness stores, invokes harness CLIs, starts or stops processes, or discovers endpoints.
-
-## OpenCode server API
-
-Verified against OpenCode 1.18.13 docs, source, and generated SDK.
-
-- Health: `GET /global/health`.
-- Session list: `GET /session?directory=...&scope=project&roots=true&limit=...`.
-- Session ownership: `GET /session/:id?directory=...`, then verify returned `directory` exactly.
-- Transcript: `GET /session/:id/message?directory=...&limit=...`.
-- Send: `POST /session/:id/message?directory=...` with a generated `messageID` and text part.
-- OpenCode owns queuing. Crossharness intentionally does not serialize HTTP sends, subscribe to permission events, or issue session-wide aborts.
-- Aborting a fetch does not prove that a queued/running server turn stopped, so timeout errors state the ambiguity and no retry occurs.
-- Successful JSON response bodies are capped at 16 MiB; error bodies are capped at 64 KiB and only the first 2,000 characters are surfaced.
-
-## Codex app-server API
-
-Verified against Codex 0.146.0 using `codex app-server generate-ts` and official app-server documentation.
-
-- Explicit transports are `ws://` and `wss://`; one initialized WebSocket is owned per Crossharness connection.
-- Flow: `initialize` -> `initialized`; `thread/list`; `thread/read`; `thread/resume`; `turn/start`; correlated notifications; optional `turn/interrupt` on timeout.
-- `thread/list` supports exact `cwd` filtering. `thread/read` results are still verified against the connection directory before reading or sending.
-- Request responses are correlated by JSON-RPC id. Turn events are correlated by `threadId` and `turnId`; events can arrive before `turn/start` resolves, so one unbound turn per thread may claim the early id.
-- Sends to one thread are sequenced; different threads remain concurrent.
-- Codex send queues are bounded globally and per thread, outbound WebSocket buffering is capped at 4 MiB, and a send's timeout includes time spent waiting in the same-thread queue.
-- Turn output is bounded by text size and delta count, including empty streaming deltas.
-- Foreground MCP cancellation aborts the operation-scoped OpenCode request or safely interrupts the correlated Codex turn; asynchronous dispatches remain independent after acceptance.
-- A timed-out send keeps its thread queue locked until `turn/interrupt` is acknowledged and `turn/completed` reports terminal state. Missing turn correlation or incomplete interruption closes the connection fail-closed.
-- Socket close rejects all pending requests and turns. Disconnect removes the connection before closing so no new work can enter.
-- Stdio EOF closes the MCP transport and every active or handshaking connection.
-- Server requests are never ignored: command/file approvals decline, tool input returns empty answers, MCP elicitation declines, permission-profile requests grant no extra permissions for the turn, legacy approvals abort, and unknown requests receive `-32601`.
-
-## Claude Code
-
-Claude Code 2.1.219 and the current Agent SDK expose local CLI/library interfaces, not a URL-addressable session server. `connect_harness` rejects `claudecode` until such a server exists.
-
-## Testing
-
-- HTTP fixtures cover required Basic auth, allowlisting, redirect rejection, directory ownership, concurrent OpenCode sends, and disconnect state.
-- WebSocket fixtures cover initialization, list/read/send, interleaved turns, bounded deltas and send buffering, safe server-request responses, timeout interruption, directory ownership, and disconnect failure propagation.
-- Registry fixtures cover pending-connect shutdown and bounded dispatch admission before send invocation.
-- Timeout fixtures cover OpenCode validation, Codex same-thread queueing, interruption completion, malformed terminal events, and stdio EOF cleanup.