agents-can-communicate 0.4.2 → 0.4.4

package/node_modules/@agents-can-communicate/adapter-codex/src/config-block.mjs

@@ -3,10 +3,8 @@ import path from "node:path";
 import { BEGIN, END, renderBlock } from "@agents-can-communicate/adapter-sdk";
 import { AccError, EXIT } from "@agents-can-communicate/protocol";
 
-const unsafe = (reason = "unrecognized TOML declaration") => {
-  throw new AccError(EXIT.CONFLICT, `cannot safely edit Codex config: ${reason}; `
-    + "repair ambiguous TOML or ACC markers before retrying", { reason });
-};
+import { statements, declaration, unsafe } from "./toml-scan.mjs";
+
 const ROOT = "# ACC sandbox writable_roots created with: ";
 export const sandboxOwnership = root => `${ROOT}${JSON.stringify(root)}`;
 
@@ -16,88 +14,6 @@ const OWNED = new Map([
   [JSON.stringify(["sandbox_workspace_write"]), ["writable_roots"]],
 ]);
 
-// A bounded lexical scan, not a TOML value parser. Newlines inside strings,
-// arrays and inline tables cannot introduce a header or a managed marker.
-function* statements(source) {
-  let start = 0, code = "", quote = null;
-  const stack = [];
-  for (let i = 0; i < source.length;) {
-    const char = source[i];
-    if (quote) {
-      if (quote[0] === '"' && char === "\\") {
-        code += source.slice(i, i + 2); i += 2; continue;
-      }
-      if (source.startsWith(quote, i)) {
-        let count = quote.length;
-        if (quote.length === 3) {
-          while (source[i + count] === quote[0]) count++;
-          if (count > 5) unsafe("unsupported string quote delimiter");
-        }
-        code += source.slice(i, i + count); i += count; quote = null; continue;
-      }
-      if (quote.length === 1 && /[\r\n]/.test(char)) unsafe("newline in single-line string");
-      code += char; i++; continue;
-    }
-    if (char === "#") {
-      while (i < source.length && source[i] !== "\n") i++;
-      continue;
-    }
-    if (char === '"' || char === "'") {
-      quote = source.startsWith(char.repeat(3), i) ? char.repeat(3) : char;
-      code += quote; i += quote.length; continue;
-    }
-    if (char === "[" || char === "{") stack.push(char);
-    if (char === "]" || char === "}") {
-      if (stack.pop() !== (char === "]" ? "[" : "{")) unsafe("mismatched collection delimiter");
-    }
-    code += char; i++;
-    if (char === "\n" && stack.length === 0) {
-      yield { raw: source.slice(start, i), code: code.trim() };
-      start = i; code = "";
-    }
-  }
-  if (quote || stack.length) unsafe(quote ? "unclosed string" : "unclosed collection");
-  if (start < source.length) yield { raw: source.slice(start), code: code.trim() };
-}
-
-function decodeKey(key) {
-  if (key[0] === "'") return key.slice(1, -1);
-  if (key[0] !== '"') return key;
-  return key.slice(1, -1).replace(/\\(U[\da-fA-F]{8}|u[\da-fA-F]{4}|[btnfr"\\])|\\./g,
-    (match, escape) => {
-      if (!escape) unsafe("unsupported quoted-key escape");
-      if (/^[uU]/.test(escape)) {
-        const point = Number.parseInt(escape.slice(1), 16);
-        if (point > 0x10ffff || (point >= 0xd800 && point <= 0xdfff)) {
-          unsafe("invalid quoted-key Unicode escape");
-        }
-        return String.fromCodePoint(point);
-      }
-      return ({ b: "\b", t: "\t", n: "\n", f: "\f", r: "\r", '"': '"', "\\": "\\" })[escape];
-    });
-}
-
-function keyPath(code) {
-  const keys = [];
-  let rest = code.trimStart();
-  for (;;) {
-    const match = /^(?:[A-Za-z0-9_-]+|'[^'\r\n]*'|"(?:[^"\\\r\n]|\\[^\r\n])*")/.exec(rest);
-    if (!match) unsafe("unrecognized TOML key");
-    keys.push(decodeKey(match[0]));
-    rest = rest.slice(match[0].length).trimStart();
-    if (!rest.startsWith(".")) return { keys, rest };
-    rest = rest.slice(1).trimStart();
-  }
-}
-
-function declaration(code) {
-  const header = code.startsWith("[");
-  const array = header && code.startsWith("[[");
-  const { keys, rest } = keyPath(header ? code.slice(array ? 2 : 1) : code);
-  if (header ? rest !== (array ? "]]" : "]") : !rest.startsWith("=")) unsafe();
-  return { keys, header, array, value: header ? null : rest.slice(1).trim() };
-}
-
 // An unchanged, newly generated sandbox has value provenance. A legacy or
 // edited sandbox belongs to the client as a whole and remains byte-preserved.
 function ownsSandbox(body) {
@@ -214,8 +130,8 @@ export async function readConfig(file) {
   });
 }
 
-export async function writeTomlBlock(file, body) {
-  const { source } = inspectConfig(await readConfig(file), file);
+export async function writeTomlBlock(file, body, preparedSource) {
+  const source = preparedSource ?? inspectConfig(await readConfig(file), file).source;
   const separator = source === "" || source.endsWith("\n") ? "" : "\n";
   await mkdir(path.dirname(file), { recursive: true });
   await writeFile(file, `${source}${separator}${renderBlock(body)}\n`);

package/node_modules/@agents-can-communicate/adapter-codex/src/install.mjs

@@ -9,7 +9,8 @@ import { bakeSkillCommand, blankJson, blankText, removeIfEmpty, removeInstalledT
   tomlString, writeForeignJson, writeHookShim }
   from "@agents-can-communicate/adapter-sdk";
 import { AccError, EXIT } from "@agents-can-communicate/protocol";
-import { inspectConfig, readConfig, removeTomlBlock, sandboxOwnership, writeTomlBlock } from "./config-block.mjs";
+import { inspectConfig, readConfig, sandboxOwnership, writeTomlBlock } from "./config-block.mjs";
+import { outgoingStatus, prepareLivePermissions, removeLivePermissions } from "./live-permissions.mjs";
 
 // Kept cohesive above 300 lines because Codex plugin install, cache, config,
 // detection, and ownership share one client topology; splitting would duplicate
@@ -159,7 +160,8 @@ const sandboxReview = (config, file, stateRoot) =>
     : [];
 
 export async function installCodexPlugin({ home, agentsHome = home,
-  codexHome = path.join(home, ".codex"), dataHome, stateRoot, runner, node, cli, preserveVersions = false }) {
+  codexHome = path.join(home, ".codex"), dataHome, stateRoot, runner, node, cli, preserveVersions = false,
+  requestedLivePolicy, livePolicy, clientVersion, platform }) {
   // Read before writing, so a manifest that will not parse is found before a
   // plugin tree is laid down that nothing will then be able to remove.
   const existing = await readJson(marketplacePath(agentsHome), { name: MARKETPLACE,
@@ -179,7 +181,10 @@ export async function installCodexPlugin({ home, agentsHome = home,
       `marketplace ${MARKETPLACE} or its plugin is already registered in this config; `
       + "remove it and install again", { config });
   }
-  const theirSandbox = foreign.sandbox;
+  const permissions = prepareLivePermissions(foreign.source, { home, codexHome, stateRoot,
+    file: config, requestedLivePolicy, livePolicy, clientVersion, platform });
+  const theirSandbox = permissions.skipLegacy || inspectConfig(permissions.source, config).sandbox;
+  const permissionActions = permissions.status?.state === "unverified" ? [permissions.status.diagnostic] : [];
 
   const target = pluginPath(agentsHome);
   await rm(target, { recursive: true, force: true });
@@ -207,7 +212,7 @@ export async function installCodexPlugin({ home, agentsHome = home,
     `[plugins.${tomlString(QUALIFIED)}]`,
     "enabled = true",
     ...sandboxTable(stateRoot, theirSandbox),
-  ]);
+  ], permissions.source);
 
   // The client runs the cached copy, so this has to happen after the shim and
   // the rewritten hooks.json are in place.
@@ -235,9 +240,11 @@ export async function installCodexPlugin({ home, agentsHome = home,
   // while ACC invented its own marketplace name and so had a root to itself.
   // make the record stale the moment the plugin version changes.
   return { ok: true, changes: [target, file, config, cachePath(codexHome)],
-    needsAction: [HOOK_REVIEW, ...sandboxReview(before, config, stateRoot)],
+    needsAction: [HOOK_REVIEW, ...permissionActions,
+      ...(permissions.skipLegacy ? [] : sandboxReview(before, config, stateRoot))],
     diagnostics: ["hooks require explicit trust in Codex before they run",
-      ...sandboxReview(before, config, stateRoot)] };
+      ...(permissions.status ? [permissions.status.diagnostic] : []),
+      ...(permissions.skipLegacy ? [] : sandboxReview(before, config, stateRoot))] };
 }
 
 /** Remove each directory that is empty, in the order given. */
@@ -255,21 +262,25 @@ export async function preflightCodexUninstall({ home, agentsHome = home,
     if (error.code === "ENOENT") return "";
     throw error;
   });
-  return { existing, withoutOurs: inspectConfig(before, configPath(codexHome)).source };
+  const permissions = removeLivePermissions(inspectConfig(before, configPath(codexHome)).source);
+  return { existing, before, withoutOurs: permissions.source, permissionState: permissions.state };
 }
 
 export async function uninstallCodexPlugin({ home, agentsHome = home,
   codexHome = path.join(home, ".codex"), keep = [] }) {
   const file = marketplacePath(agentsHome);
   // Direct adapter callers need the same check as the installer boundary.
-  const { existing, withoutOurs } = await preflightCodexUninstall({ home, agentsHome, codexHome });
+  const { existing, before, withoutOurs, permissionState } = await preflightCodexUninstall({ home, agentsHome, codexHome });
   const changes = [];
   if (existing !== null) {
     const kept = (existing.plugins ?? []).filter(entry => entry.name !== PLUGIN_NAME);
     if (kept.length !== (existing.plugins ?? []).length) changes.push(PLUGIN_NAME);
     await writeMarketplace(file, { ...existing, plugins: kept });
   }
-  if (await removeTomlBlock(configPath(codexHome))) changes.push(configPath(codexHome));
+  if (before !== withoutOurs) {
+    await writeFile(configPath(codexHome), withoutOurs);
+    changes.push(configPath(codexHome));
+  }
   // The client's `[hooks.state."<plugin>:…"]` tables stay. 0.1.9 removed them as
   // litter naming a plugin that was gone; that was wrong, and wrong in a way
   // worth writing down. The check behind it perturbed the record - a hook whose
@@ -312,13 +323,16 @@ export async function uninstallCodexPlugin({ home, agentsHome = home,
     marketplaceRoot(agentsHome),
     cacheRoot(codexHome),
   ]);
-  return { ok: true, changes, diagnostics: declaresSandbox(withoutOurs)
-    ? ["existing sandbox_workspace_write configuration was preserved; review any retained writable_roots after removal"]
-    : [] };
+  const permissionReview = permissionState === "customized"
+    ? ["customized native permissions were preserved together with their default selection and network proxy; review them in Codex config"] : [];
+  return { ok: true, changes, needsAction: permissionReview, diagnostics: [
+    ...(declaresSandbox(withoutOurs)
+      ? ["existing sandbox_workspace_write configuration was preserved; review any retained writable_roots after removal"] : []),
+    ...permissionReview] };
 }
 
 export async function detectCodex({ home, agentsHome = home,
-  codexHome = path.join(home, ".codex"), stateRoot }) {
+  codexHome = path.join(home, ".codex"), stateRoot, clientVersion, platform, nativeDelivery }) {
   const marketplace = await readJson(marketplacePath(agentsHome), null);
   const published = (marketplace?.plugins ?? []).some(entry => entry.name === PLUGIN_NAME);
   const config = await readFile(configPath(codexHome), "utf8").catch(() => "");
@@ -326,11 +340,17 @@ export async function detectCodex({ home, agentsHome = home,
   const pluginEntry = config.includes(`[plugins."${QUALIFIED}"]`);
   const cached = await stat(cachePath(codexHome))
     .then(() => true).catch(() => false);
+  const outgoingDelivery = outgoingStatus(config, { home, codexHome, stateRoot,
+    file: configPath(codexHome), clientVersion, platform });
   // Saved trust is not readiness. Codex compares every current definition's
   // hash and can disable a trusted hook. Even a commented or stale single record
   // previously suppressed this check. Leave verification to Codex's /hooks;
   // detection neither invents its hash algorithm nor starts a client service.
-  return { ok: true, changes: [], diagnostics: [
+  return { ok: true, changes: [], outgoingDelivery,
+    nativeSetup: nativeDelivery?.reasonCode === "native_endpoint_unavailable"
+      ? "Codex CLI: run codex app-server daemon start, then open a new Codex session; ACC never starts or restarts the daemon"
+      : null,
+    diagnostics: [
     published ? "acc plugin published in the marketplace" : "acc plugin not registered",
     registered && pluginEntry
       ? "marketplace and plugin entries found in config; activation not verified"
@@ -347,7 +367,8 @@ export async function detectCodex({ home, agentsHome = home,
       : []),
   ],
   needsAction: cached
-    ? [HOOK_REVIEW, ...sandboxReview(config, configPath(codexHome), stateRoot)]
+    ? [HOOK_REVIEW, ...sandboxReview(config, configPath(codexHome), stateRoot),
+      ...(outgoingDelivery.state === "unverified" ? [outgoingDelivery.diagnostic] : [])]
     : [] };
 }
 

package/node_modules/@agents-can-communicate/adapter-codex/src/live-permissions.mjs

@@ -0,0 +1,110 @@
+import path from "node:path";
+import { channelSocketDirectory, tomlString } from "@agents-can-communicate/adapter-sdk";
+import { compareStableVersions, parseStableVersion } from "./app-server-client.mjs";
+import { addPermissions, inspectPermissions } from "./permission-ownership.mjs";
+import { scanConfig } from "./toml-scan.mjs";
+
+const PROFILE = "acc-workspace";
+const MINIMUM = "0.153.4";
+const equal = (keys, expected) => JSON.stringify(keys) === JSON.stringify(expected);
+const literal = value => { try { return JSON.parse(value); } catch { return null; } };
+const supported = context => context.platform === "darwin-arm64"
+  && parseStableVersion(context.clientVersion) !== null
+  && compareStableVersions(context.clientVersion, MINIMUM) >= 0;
+const hasPermissions = entries => entries.some(entry =>
+  ["permissions", "default_permissions", "profile", "profiles"].includes(entry.keys[0]));
+const configured = (source, context) => {
+  const entries = scanConfig(source);
+  if (entries.some(entry => ["profile", "profiles"].includes(entry.keys[0]))) return false;
+  const value = keys => entries.find(entry => !entry.header && equal(entry.keys, keys))?.value;
+  const profile = literal(value(["default_permissions"]));
+  if (!profile || value(["sandbox_mode"]) || entries.some(entry => entry.keys[0] === "sandbox_workspace_write")) return false;
+  return literal(value(["permissions", profile, "extends"])) === ":workspace"
+    && value(["features", "network_proxy"]) === "true"
+    && value(["permissions", profile, "network", "enabled"]) === "true"
+    && literal(value(["permissions", profile, "filesystem", context.stateRoot])) === "write"
+    && sockets(context).every(socket => literal(value(["permissions", profile, "network", "unix_sockets", socket])) === "allow");
+};
+
+// Match the channel's per-user temporary directory and Codex's actual home.
+// Grants cover only ACC's local channel namespace, never arbitrary Unix sockets.
+const sockets = context => [channelSocketDirectory(),
+  path.join(context.codexHome ?? path.join(context.home, ".codex"), "app-server-control", "app-server-control.sock")];
+
+export function outgoingStatus(source, context) {
+  const state = inspectPermissions(source).state;
+  const ready = state === "owned" && supported(context) && configured(source, context);
+  const reasonCode = state === "customized" ? "permission_configuration_modified"
+    : !supported(context) ? "permission_configuration_uncaptured"
+      : ready ? null : "sender_permissions_unverified";
+  return { state: reasonCode === null ? "configured" : "unverified", reasonCode,
+    setup: supported(context)
+      ? "Codex outgoing setup: default workspace settings gain ACC state write access and an ACC local socket allowlist "
+        + "through the network proxy (external network stays denied); custom policies are preserved. Start a new session after installation."
+      : null,
+    diagnostic: reasonCode === null
+      ? "outgoing live delivery: local socket permissions configured for new sessions; active session overrides remain unverified"
+      : `outgoing live delivery: sender permissions unverified in ${context.file}; `
+        + (reasonCode === "permission_configuration_uncaptured"
+          ? `automatic setup requires Codex ${MINIMUM} or newer on darwin-arm64`
+          : "existing permissions were preserved; run acc install --adapter codex, then start a new session; "
+            + "custom permission policies must allow ACC state and local sockets through the network proxy") };
+}
+
+export function prepareLivePermissions(source, context) {
+  const owned = inspectPermissions(source);
+  const requested = (context.requestedLivePolicy ?? context.livePolicy ?? "off") !== "off";
+  if (owned.state === "customized") return { source, skipLegacy: true, status: outgoingStatus(source, context) };
+  if (!requested) return { source: owned.source, skipLegacy: hasPermissions(scanConfig(owned.source)) };
+  if (!supported(context) || !context.stateRoot) {
+    return { source, skipLegacy: hasPermissions(scanConfig(source)), status: outgoingStatus(source, context) };
+  }
+  if (owned.state === "owned" && configured(source, context)) {
+    return { source, skipLegacy: true, status: outgoingStatus(source, context) };
+  }
+  source = owned.source;
+  const entries = scanConfig(source);
+  const find = keys => entries.filter(entry => equal(entry.keys, keys));
+  const modes = find(["sandbox_mode"]), defaults = find(["default_permissions"]);
+  const legacy = entries.filter(entry => entry.keys[0] === "sandbox_workspace_write");
+  const features = entries.filter(entry => entry.keys[0] === "features");
+  const featureTable = find(["features"]);
+  const proxies = find(["features", "network_proxy"]);
+  const customized = entries.some(entry => ["permissions", "profile", "profiles"].includes(entry.keys[0]))
+    || modes.length > 1 || defaults.length > 1
+    || modes.some(entry => entry.header || literal(entry.value) !== "workspace-write")
+    || defaults.some(entry => entry.header || literal(entry.value) !== ":workspace")
+    || (legacy.length > 0 && (legacy.length !== 2 || !legacy[0].header || legacy[0].array
+      || !equal(legacy[1].keys, ["sandbox_workspace_write", "writable_roots"])
+      || JSON.stringify(literal(legacy[1].value)) !== JSON.stringify([context.stateRoot])))
+    || (features.length > 0 && (featureTable.length !== 1 || !featureTable[0].header || featureTable[0].array))
+    || proxies.length > 1 || proxies.some(entry => entry.header || !["true", "false"].includes(entry.value));
+  if (customized) return { source, skipLegacy: hasPermissions(entries), status: outgoingStatus(source, context) };
+  const edits = [{ id: "selection", start: 0, end: 0, body: `default_permissions = "${PROFILE}"\n` }];
+  for (const [id, values] of [["mode", modes], ["default", defaults]]) {
+    if (values.length) edits.push({ id, start: values[0].start, end: values[0].end, body: "" });
+  }
+  if (legacy.length) {
+    const end = entries.find(entry => entry.header && entry.start > legacy[0].start)?.start ?? source.length;
+    edits.push({ id: "legacy", start: legacy[0].start, end, body: "" });
+  }
+  const proxy = proxies[0], table = featureTable[0];
+  edits.push({ id: "proxy", start: proxy?.start ?? table?.end ?? source.length,
+    end: proxy?.end ?? table?.end ?? source.length, table: table ? ["features"] : null,
+    body: `${table ? "" : "[features]\n"}network_proxy = true\n` });
+  // Preserve a final line without a newline through the same ownership unit.
+  const last = entries.at(-1);
+  if (last && !source.endsWith("\n") && !edits.some(edit => edit.start <= last.start && edit.end >= last.end)) {
+    edits.push({ id: "tail", start: last.start, end: last.end, body: `${last.raw}\n` });
+  }
+  edits.push({ id: "profile", start: source.length, end: source.length, body:
+    `[permissions.${PROFILE}]\nextends = ":workspace"\n`
+    + `[permissions.${PROFILE}.filesystem]\n${tomlString(context.stateRoot)} = "write"\n`
+    + `[permissions.${PROFILE}.network]\nenabled = true\n`
+    + `[permissions.${PROFILE}.network.unix_sockets]\n`
+    + sockets(context).map(socket => `${tomlString(socket)} = "allow"\n`).join("") });
+  const prepared = addPermissions(source, edits);
+  return { source: prepared, skipLegacy: true, status: outgoingStatus(prepared, context) };
+}
+
+export const removeLivePermissions = source => inspectPermissions(source);

package/node_modules/@agents-can-communicate/adapter-codex/src/maintenance-host.mjs

@@ -0,0 +1,120 @@
+import { execFile } from "node:child_process";
+import { constants } from "node:fs";
+import { access, lstat, open, realpath } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { compareStableVersions, parseStableVersion } from "./app-server-client.mjs";
+
+export const MINIMUM_MAINTENANCE_CLI = "0.154.0";
+export const absolute = value => typeof value === "string" && path.isAbsolute(value)
+  && !/[\0\r\n]/.test(value);
+export const failMaintenance = reasonCode => { throw Object.assign(new Error(reasonCode), { reasonCode }); };
+const own = info => typeof process.getuid !== "function" || info.uid === process.getuid();
+export const startTimeValid = value => typeof value === "string"
+  && /^[A-Z][a-z]{2} [A-Z][a-z]{2} [ \d]\d \d\d:\d\d:\d\d \d{4}$/.test(value);
+export const managedExecutablePaths = codexHome => ["bin/codex", "codex"].map(name =>
+  path.join(codexHome, "packages/standalone/current", name));
+
+export function runMaintenanceCommand(command, args, options) {
+  return new Promise(resolve => execFile(command, args,
+    { ...options, timeout: 20_000, maxBuffer: 131_072, windowsHide: true },
+    (error, stdout, stderr) => resolve({ status: error ?
+      (typeof error.code === "number" ? error.code : null) : 0, stdout, stderr })));
+}
+
+export async function maintenanceContext(context = {}) {
+  const env = context.env ?? process.env;
+  const home = context.home ?? env.HOME ?? os.homedir();
+  let codexHome = env.CODEX_HOME ?? path.join(home, ".codex");
+  if (!absolute(home) || !absolute(codexHome)) failMaintenance("invalid_service_home");
+  try { codexHome = await realpath(codexHome); }
+  catch (error) { if (error.code !== "ENOENT") throw error; }
+  const [binPath, legacyPath] = managedExecutablePaths(codexHome);
+  const managedPath = await metadataExists(binPath) ? binPath : legacyPath;
+  return { codexHome, socketPath: path.join(codexHome, "app-server-control/app-server-control.sock"),
+    pidPath: path.join(codexHome, "app-server-daemon/app-server.pid"),
+    managedPath,
+    platform: context.platform ?? `${process.platform}-${process.arch}`,
+    options: { cwd: codexHome, env: { ...env, HOME: home, CODEX_HOME: codexHome } } };
+}
+
+export async function metadataExists(file) {
+  try { await lstat(file); return true; }
+  catch (error) { if (error.code === "ENOENT") return false; throw error; }
+}
+
+async function resolveCli(pathEnv) {
+  for (const directory of String(pathEnv ?? "").split(path.delimiter)) {
+    if (!absolute(directory)) continue;
+    const candidate = path.join(directory, "codex");
+    try {
+      await access(candidate, constants.X_OK);
+      const resolved = await realpath(candidate);
+      if ((await lstat(resolved)).isFile()) return resolved;
+    } catch { /* another PATH entry may be usable */ }
+  }
+  failMaintenance("maintenance_cli_unavailable");
+}
+
+const cliVersion = response => response.status === 0
+  ? /^codex-cli (\d+\.\d+\.\d+)\s*$/.exec(response.stdout)?.[1] ?? null : null;
+
+export async function probeMaintenanceInstall(paths, run) {
+  const cliPath = await resolveCli(paths.options.env.PATH);
+  const version = cliVersion(await run(cliPath, ["--version"], paths.options));
+  if (!parseStableVersion(version) || compareStableVersions(version, MINIMUM_MAINTENANCE_CLI) < 0) {
+    failMaintenance("maintenance_cli_unsupported");
+  }
+  const help = await run(cliPath, ["app-server", "daemon", "--help"], paths.options);
+  if (help.status !== 0 || ["start", "stop", "version"].some(command =>
+    !new RegExp(`^\\s+${command}\\s+`, "m").test(help.stdout))) failMaintenance("maintenance_cli_unsupported");
+  const managedVersion = cliVersion(await run(paths.managedPath, ["--version"], paths.options));
+  if (managedVersion !== version) failMaintenance("managed_binary_mismatch");
+  return { cliPath, cliVersion: version, managedVersion };
+}
+
+export async function readMaintenancePid(file) {
+  let handle;
+  try {
+    handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const info = await handle.stat();
+    if (!info.isFile() || !own(info) || info.size > 4_096 || (info.mode & 0o022) !== 0) {
+      failMaintenance("daemon_identity_unavailable");
+    }
+    const value = JSON.parse(await handle.readFile("utf8"));
+    if (!Number.isSafeInteger(value.pid) || value.pid < 2 || !startTimeValid(value.processStartTime)) {
+      failMaintenance("daemon_identity_unavailable");
+    }
+    return { pid: value.pid, processStartTime: value.processStartTime };
+  } finally { await handle?.close(); }
+}
+
+export async function observeMaintenanceProcess(pid, paths, run) {
+  const response = await run("/bin/ps", ["-p", String(pid), "-o", "lstart=,command="], paths.options);
+  if (response.status === 1 && response.stdout === "" && response.stderr === "") return { state: "dead" };
+  if (response.status !== 0) return { state: "unknown" };
+  const match = /^(.{24})\s+(.+)$/.exec(response.stdout.trim());
+  if (!match || !startTimeValid(match[1])) return { state: "unknown" };
+  return { state: "alive", processStartTime: match[1], command: match[2] };
+}
+
+export async function verifyMaintenanceProcess(snapshot, paths, run) {
+  const process = await observeMaintenanceProcess(snapshot.pid, paths, run);
+  const suffix = " app-server --listen unix://";
+  const executable = process.command?.endsWith(suffix) ? process.command.slice(0, -suffix.length) : null;
+  if (process.state !== "alive" || process.processStartTime !== snapshot.processStartTime
+    || !managedExecutablePaths(paths.codexHome).includes(executable)
+    || await realpath(executable) !== await realpath(paths.managedPath)) {
+    failMaintenance("daemon_identity_unavailable");
+  }
+  const sockets = await run("/usr/sbin/lsof", ["-n", "-a", "-p", String(snapshot.pid), "-U", "-Fn"], paths.options);
+  if (sockets.status !== 0 || !sockets.stdout.split("\n").includes(`n${paths.socketPath}`)) {
+    failMaintenance("daemon_socket_unproven");
+  }
+}
+
+export async function approvedProcessIsDead(expected, paths, run) {
+  const observed = await observeMaintenanceProcess(expected.pid, paths, run);
+  return observed.state === "dead" || (observed.state === "alive"
+    && observed.processStartTime !== expected.processStartTime);
+}

package/node_modules/@agents-can-communicate/adapter-codex/src/maintenance-threads.mjs

@@ -0,0 +1,49 @@
+import { initializeCodex } from "./app-server-client.mjs";
+import { failMaintenance } from "./maintenance-host.mjs";
+
+async function loadedThreads(peer) {
+  const ids = [], cursors = new Set();
+  let cursor = null;
+  for (let page = 0; page < 20; page += 1) {
+    const response = await peer.request("thread/loaded/list", { limit: 100, ...(cursor ? { cursor } : {}) });
+    if (!Array.isArray(response?.data) || response.data.some(id => typeof id !== "string" || !id)) {
+      failMaintenance("maintenance_protocol_unavailable");
+    }
+    ids.push(...response.data);
+    cursor = response.nextCursor ?? null;
+    if (cursor === null) {
+      if (new Set(ids).size !== ids.length) failMaintenance("maintenance_protocol_unavailable");
+      return ids.sort();
+    }
+    if (typeof cursor !== "string" || !cursor || cursors.has(cursor)) failMaintenance("maintenance_protocol_unavailable");
+    cursors.add(cursor);
+  }
+  failMaintenance("maintenance_protocol_unavailable");
+}
+
+// The caller receives counts only. No thread/list previews, turns, queue bodies,
+// notification history, or vendor errors are retained in maintenance snapshots.
+export async function maintenanceWorkload(snapshot, open) {
+  let peer;
+  try {
+    peer = await open({ socketPath: snapshot.socketPath });
+    if (await initializeCodex(peer) !== snapshot.serverVersion) failMaintenance("daemon_version_changed");
+    const ids = await loadedThreads(peer);
+    let busyThreads = 0, queuedRequests = 0;
+    for (const threadId of ids) {
+      const response = await peer.request("thread/read", { threadId, includeTurns: false });
+      const thread = response?.thread;
+      if (thread?.id !== threadId || !Array.isArray(thread.turns) || thread.turns.length !== 0
+        || !["idle", "active"].includes(thread.status?.type)) failMaintenance("maintenance_protocol_unavailable");
+      if (thread.status.type === "active") busyThreads += 1;
+      const queue = await peer.request("thread/queue/list", { threadId });
+      if (!Array.isArray(queue?.data) || queue.nextCursor != null
+        || queue.data.some(entry => typeof entry?.id !== "string" || !entry.id)) {
+        failMaintenance("maintenance_protocol_unavailable");
+      }
+      queuedRequests += queue.data.length;
+    }
+    if (JSON.stringify(await loadedThreads(peer)) !== JSON.stringify(ids)) failMaintenance("loaded_threads_changed");
+    return { busyThreads, queuedRequests };
+  } finally { await peer?.close(); }
+}

package/node_modules/@agents-can-communicate/adapter-codex/src/maintenance.mjs

@@ -0,0 +1,108 @@
+import path from "node:path";
+import { openCodexAppServer, parseStableVersion } from "./app-server-client.mjs";
+import { socketIsReady } from "./native-endpoint.mjs";
+import { absolute, approvedProcessIsDead, failMaintenance, maintenanceContext,
+  managedExecutablePaths, metadataExists, probeMaintenanceInstall, readMaintenancePid, runMaintenanceCommand,
+  startTimeValid, verifyMaintenanceProcess } from "./maintenance-host.mjs";
+import { maintenanceWorkload } from "./maintenance-threads.mjs";
+
+const identityKeys = ["serviceId", "pid", "processStartTime", "codexHome", "cliPath", "cliVersion",
+  "serverVersion", "managedPath", "managedVersion", "socketPath"];
+const installationKeys = ["codexHome", "cliPath", "cliVersion", "managedPath", "managedVersion", "socketPath"];
+const refused = (reasonCode, snapshot) => ({ ok: false, reasonCode, ...(snapshot ? { snapshot } : {}) });
+const sameFields = (left, right, fields) => fields.every(key => left?.[key] === right?.[key]);
+
+function validApproval(value) {
+  return value?.serviceId === "codex-app-server" && ["ready", "busy"].includes(value.state)
+    && Number.isSafeInteger(value.pid) && value.pid > 1 && startTimeValid(value.processStartTime)
+    && ["codexHome", "cliPath", "managedPath", "socketPath"].every(key => absolute(value[key]))
+    && ["cliVersion", "serverVersion", "managedVersion"].every(key => parseStableVersion(value[key]))
+    && value.managedVersion === value.cliVersion
+    && managedExecutablePaths(value.codexHome).includes(value.managedPath)
+    && value.socketPath === path.join(value.codexHome, "app-server-control/app-server-control.sock");
+}
+
+export function sameMaintenanceIdentity(expected, current) {
+  return validApproval(expected) && validApproval(current) && sameFields(expected, current, identityKeys);
+}
+
+export function createCodexMaintenance({ run = runMaintenanceCommand, open = openCodexAppServer } = {}) {
+  async function inspectMaintenance(context) {
+    let snapshot = { serviceId: "codex-app-server", state: "unsupported", reasonCode: null,
+      pid: null, processStartTime: null, codexHome: null, cliPath: null, cliVersion: null,
+      serverVersion: null, managedPath: null, managedVersion: null, socketPath: null,
+      busyThreads: 0, queuedRequests: 0 };
+    try {
+      const paths = await maintenanceContext(context);
+      Object.assign(snapshot, { codexHome: paths.codexHome, socketPath: paths.socketPath, managedPath: paths.managedPath });
+      if (!await metadataExists(paths.socketPath) && !await metadataExists(paths.pidPath)) return null;
+      if (paths.platform !== "darwin-arm64") failMaintenance("maintenance_platform_unsupported");
+      if (!await socketIsReady(paths.socketPath)) failMaintenance("daemon_socket_unproven");
+      Object.assign(snapshot, await probeMaintenanceInstall(paths, run));
+      const version = await run(snapshot.cliPath, ["app-server", "daemon", "version"], paths.options);
+      if (version.status !== 0) failMaintenance("daemon_version_unavailable");
+      const observed = JSON.parse(version.stdout);
+      if (observed.status !== "running" || observed.backend !== "pid") failMaintenance("maintenance_backend_unsupported");
+      if (observed.managedCodexPath !== snapshot.managedPath || observed.socketPath !== snapshot.socketPath
+        || observed.cliVersion !== snapshot.cliVersion || observed.managedCodexVersion !== snapshot.managedVersion
+        || !parseStableVersion(observed.appServerVersion)) failMaintenance("daemon_identity_unavailable");
+      snapshot.serverVersion = observed.appServerVersion;
+      Object.assign(snapshot, await readMaintenancePid(paths.pidPath));
+      await verifyMaintenanceProcess(snapshot, paths, run);
+      Object.assign(snapshot, await maintenanceWorkload(snapshot, open));
+      const finalPid = await readMaintenancePid(paths.pidPath);
+      if (!sameFields(snapshot, finalPid, ["pid", "processStartTime"])) failMaintenance("service_identity_changed");
+      await verifyMaintenanceProcess(snapshot, paths, run);
+      snapshot.state = snapshot.busyThreads || snapshot.queuedRequests ? "busy" : "ready";
+      snapshot.reasonCode = snapshot.state === "busy" ? "service_busy" : null;
+    } catch (error) { snapshot.reasonCode = error.reasonCode ?? "maintenance_inspection_failed"; }
+    return snapshot;
+  }
+
+  async function stopForMaintenance({ context, expected } = {}) {
+    let stopAttempted = false;
+    const refuseStop = (reasonCode, snapshot) => ({ ...refused(reasonCode, snapshot), stopAttempted });
+    if (!validApproval(expected)) return refuseStop("invalid_maintenance_approval");
+    try {
+      const current = await inspectMaintenance(context);
+      if (!sameMaintenanceIdentity(expected, current)) return refuseStop("service_identity_changed", current);
+      if (current.state !== "ready" || current.busyThreads !== 0 || current.queuedRequests !== 0) {
+        return refuseStop("service_busy", current);
+      }
+      const paths = await maintenanceContext(context);
+      stopAttempted = true;
+      const stopped = await run(current.cliPath, ["app-server", "daemon", "stop"], paths.options);
+      if (stopped.status !== 0) return refuseStop("daemon_stop_failed");
+      if (!await approvedProcessIsDead(expected, paths, run)) return refuseStop("daemon_death_unverified");
+      return { ok: true, reasonCode: null, stopAttempted };
+    } catch { return refuseStop("daemon_stop_failed"); }
+  }
+
+  async function startAfterMaintenance({ context, expected } = {}) {
+    if (!validApproval(expected)) return refused("invalid_maintenance_approval");
+    try {
+      const pinned = { ...context, env: { ...(context?.env ?? process.env), CODEX_HOME: expected.codexHome } };
+      const paths = await maintenanceContext(pinned);
+      if (paths.platform !== "darwin-arm64") return refused("maintenance_platform_unsupported");
+      const install = { ...paths, ...await probeMaintenanceInstall(paths, run) };
+      if (!sameFields(expected, install, installationKeys)) return refused("service_identity_changed");
+      const existing = await inspectMaintenance(pinned);
+      if (existing) {
+        if (["ready", "busy"].includes(existing.state) && sameFields(expected, existing, installationKeys)
+          && existing.serverVersion === expected.cliVersion) return { ok: true, reasonCode: null, snapshot: existing };
+        return refused("service_identity_changed", existing);
+      }
+      if (!await approvedProcessIsDead(expected, paths, run)) return refused("daemon_death_unverified");
+      const started = await run(install.cliPath, ["app-server", "daemon", "start"], paths.options);
+      if (started.status !== 0) return refused("daemon_start_failed");
+      const current = await inspectMaintenance(pinned);
+      if (!current || !["ready", "busy"].includes(current.state)
+        || !sameFields(expected, current, installationKeys) || current.serverVersion !== expected.cliVersion) {
+        return refused("daemon_start_unverified", current);
+      }
+      return { ok: true, reasonCode: null, snapshot: current };
+    } catch { return refused("daemon_start_failed"); }
+  }
+
+  return { inspectMaintenance, stopForMaintenance, startAfterMaintenance };
+}

package/node_modules/@agents-can-communicate/adapter-codex/src/native-delivery.mjs

@@ -133,6 +133,7 @@ export async function offerMessage({ binding, message, runtimeDir, timeoutMs = 5
       return { accepted: true, transport: "codex-app-server", clientVersion: endpoint.clientVersion };
     });
   } catch (error) {
+    if (["EPERM", "EACCES"].includes(error?.code)) return rejected("transport_permission_denied");
     const reason = safeReason(error);
     return rejected(reason === "request_timeout" ? "transport_error"
       : reason === "vendor_error" ? "transport_rejected" : "recipient_unavailable");