codexteer 0.14.1

package/src/rpc.mjs

@@ -0,0 +1,162 @@
+import { EventEmitter } from "node:events";
+import net from "node:net";
+import { randomUUID } from "node:crypto";
+import WebSocket from "ws";
+import { VERSION } from "./help.mjs";
+
+export class RpcFailure extends Error {
+  constructor(message, { code = "CONNECTION_FAILED", uncertain = false, rpcCode } = {}) {
+    super(message);
+    this.code = code;
+    this.uncertain = uncertain;
+    this.rpcCode = rpcCode;
+  }
+}
+
+function connectionCode(error) {
+  if (["EACCES", "EPERM"].includes(error?.code)) return "PERMISSION_DENIED";
+  if (error?.code === "ETIMEDOUT") return "TIMEOUT";
+  if (["ENOENT", "ECONNREFUSED", "ECONNRESET", "ECONNABORTED", "EPIPE"].includes(error?.code)) return "CONNECTION_FAILED";
+  return "PROTOCOL_ERROR";
+}
+
+export function connectSocket(socketPath, { timeoutMs = 8000, signal } = {}) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) { reject(new RpcFailure("App Server connection cancelled.", { code: "CANCELLED" })); return; }
+    const socket = new WebSocket("ws://localhost/rpc", {
+      createConnection: () => net.createConnection(socketPath),
+      perMessageDeflate: false,
+      maxPayload: 64 * 1024 * 1024,
+    });
+    let settled = false;
+    const finish = error => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", cancel);
+      if (error) { socket.terminate(); reject(error); }
+      else resolve(socket);
+    };
+    const cancel = () => finish(new RpcFailure("App Server connection cancelled.", { code: "CANCELLED" }));
+    const timer = setTimeout(() => finish(new RpcFailure("App Server connection timed out.", { code: "TIMEOUT" })), timeoutMs);
+    // Keep an error listener even after connection so a peer reset never throws globally.
+    socket.on("error", () => {});
+    socket.once("error", error => finish(new RpcFailure("Could not connect to the shared App Server.", { code: connectionCode(error) })));
+    socket.once("close", () => finish(new RpcFailure("App Server connection closed before initialization.")));
+    socket.once("open", () => finish());
+    signal?.addEventListener("abort", cancel, { once: true });
+    if (signal?.aborted) cancel();
+  });
+}
+
+export class RpcClient extends EventEmitter {
+  constructor(socket, { timeoutMs = 8000 } = {}) {
+    super();
+    this.socket = socket;
+    this.timeoutMs = timeoutMs;
+    this.pending = new Map();
+    this.failure = null;
+    socket.on("message", (data, binary) => {
+      let message;
+      try {
+        if (binary) throw new Error();
+        message = JSON.parse(data.toString());
+        if (!message || typeof message !== "object" || Array.isArray(message)) throw new Error();
+      } catch {
+        this.abort("App Server returned an invalid protocol message.");
+        return;
+      }
+      this.emit("message", message);
+      if (Object.hasOwn(message, "method")) {
+        if (typeof message.method !== "string" || !message.method) {
+          this.abort("App Server returned an invalid protocol method.");
+          return;
+        }
+        this.emit(message.id == null ? "notification" : "serverRequest", message);
+        return;
+      }
+      const request = this.pending.get(message.id);
+      if (!request) return;
+      clearTimeout(request.timer);
+      this.pending.delete(message.id);
+      if (message.error && typeof message.error === "object" && !Array.isArray(message.error)
+        && Number.isSafeInteger(message.error.code) && !Object.hasOwn(message, "result")) {
+        request.reject(new RpcFailure(`${request.method} was rejected by App Server.`, {
+          code: "RPC_REJECTED", rpcCode: message.error.code,
+        }));
+      } else if (Object.hasOwn(message, "result") && message.error == null) request.resolve(message.result);
+      else {
+        request.reject(new RpcFailure("App Server returned an invalid response.", { code: "PROTOCOL_ERROR", uncertain: request.mutation }));
+        this.abort("App Server returned an invalid response.");
+      }
+    });
+    socket.on("close", () => this.rejectPending("App Server connection closed."));
+    socket.on("error", error => this.abort("App Server connection failed.", connectionCode(error)));
+  }
+
+  static async connect(socketPath, options = {}) {
+    const client = new RpcClient(await connectSocket(socketPath, options), options);
+    const cancel = () => client.abort("App Server initialization cancelled.", "CANCELLED");
+    options.signal?.addEventListener("abort", cancel, { once: true });
+    try {
+      if (options.signal?.aborted) cancel();
+      client.initialization = await client.request("initialize", {
+        clientInfo: { name: "codexteer", title: "Codexteer", version: VERSION },
+        capabilities: { experimentalApi: true },
+      });
+      if (!client.initialization || typeof client.initialization !== "object" || Array.isArray(client.initialization)) {
+        throw new RpcFailure("App Server returned invalid initialization data.", { code: "PROTOCOL_ERROR" });
+      }
+      client.notify("initialized", {});
+      return client;
+    } catch (error) {
+      client.close();
+      throw error;
+    } finally { options.signal?.removeEventListener("abort", cancel); }
+  }
+
+  request(method, params = {}, { mutation = false } = {}) {
+    if (this.socket.readyState !== WebSocket.OPEN) {
+      return Promise.reject(new RpcFailure(this.failure?.message ?? "App Server is not connected.", { code: this.failure?.code }));
+    }
+    const id = randomUUID();
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new RpcFailure(`${method} timed out.`, { code: "TIMEOUT", uncertain: mutation }));
+      }, this.timeoutMs);
+      this.pending.set(id, { resolve, reject, timer, method, mutation });
+      this.socket.send(JSON.stringify({ id, method, params }), (error) => {
+        if (error) this.rejectPending("App Server connection failed.");
+      });
+    });
+  }
+
+  notify(method, params) {
+    this.socket.send(JSON.stringify({ method, params }));
+  }
+
+  rejectPending(message, code = "CONNECTION_FAILED") {
+    for (const request of this.pending.values()) {
+      clearTimeout(request.timer);
+      request.reject(new RpcFailure(this.failure?.message ?? message, { code: this.failure?.code ?? code, uncertain: request.mutation }));
+    }
+    this.pending.clear();
+  }
+
+  abort(message, code = "PROTOCOL_ERROR") {
+    this.failure ??= { message, code };
+    this.rejectPending(message, code);
+    this.socket.terminate();
+  }
+
+  close() {
+    this.rejectPending("App Server client closed.");
+    if (this.socket.readyState === WebSocket.OPEN) {
+      this.socket.close();
+      const timer = setTimeout(() => this.socket.terminate(), 500);
+      timer.unref();
+      this.socket.once("close", () => clearTimeout(timer));
+    } else if (this.socket.readyState !== WebSocket.CLOSED) this.socket.terminate();
+  }
+}

package/src/runner.mjs

@@ -0,0 +1,32 @@
+import { spawn } from "node:child_process";
+
+export function runCommand(argv, { cwd, timeoutMs = 0, onStart = async () => {}, signal: abortSignal } = {}) {
+  if (!argv.length || !argv[0] || !Number.isInteger(timeoutMs) || timeoutMs < 0 || timeoutMs > 86400000) throw new Error("A command and timeout-ms between 0 and 86400000 are required.");
+  return new Promise((resolve, reject) => {
+    const started = new Date().toISOString();
+    let output = "", truncated = false, timedOut = false, failure, killer, timer, startUpdate = Promise.resolve(), closed = false;
+    const child = spawn(argv[0], argv.slice(1), { cwd, shell: false, detached: true, stdio: ["ignore", "pipe", "pipe"] });
+    const terminate = signal => {
+      if (!child.pid || closed) return;
+      try { process.kill(-child.pid, signal); } catch (e) { if (e.code !== "ESRCH") failure ??= e; }
+    };
+    const stop = () => { terminate("SIGTERM"); killer ??= setTimeout(() => terminate("SIGKILL"), 1000); };
+    const interrupt = () => { failure ??= new Error("Command interrupted."); stop(); };
+    process.on("SIGINT", interrupt); process.on("SIGTERM", interrupt);
+    abortSignal?.addEventListener("abort", interrupt, { once: true });
+    for (const stream of [child.stdout, child.stderr]) {
+      stream.setEncoding("utf8"); stream.on("data", data => { output += data; if (output.length > 32768) { truncated = true; output = output.slice(-32768); } });
+    }
+    child.once("spawn", () => { if (abortSignal?.aborted) interrupt(); startUpdate = Promise.resolve(onStart(child.pid)).catch(e => { failure = e; stop(); }); });
+    child.once("error", e => { failure = e; });
+    if (timeoutMs) timer = setTimeout(() => { timedOut = true; stop(); }, timeoutMs);
+    child.once("close", async (code, signal) => {
+      closed = true;
+      clearTimeout(timer); clearTimeout(killer); process.off("SIGINT", interrupt); process.off("SIGTERM", interrupt);
+      abortSignal?.removeEventListener("abort", interrupt);
+      await startUpdate;
+      const result = { pid: child.pid ?? null, exit_code: code, signal, timed_out: timedOut, started_at: started, completed_at: new Date().toISOString(), output_tail: output, output_truncated: truncated, error: failure?.message ?? null };
+      resolve(result);
+    });
+  });
+}

package/src/runtime.mjs

@@ -0,0 +1,130 @@
+import { createHash, randomUUID } from "node:crypto";
+import { lstat, mkdir, readFile, rename, rm, writeFile, realpath } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+const runtimeFailure = (message, code) => Object.assign(new Error(message), { code });
+
+export function codexHome() {
+  return path.resolve(process.env.CODEX_HOME || path.join(os.homedir(), ".codex"));
+}
+
+export async function runtimePaths(home = codexHome()) {
+  const canonicalHome = await canonicalPath(path.resolve(home));
+  const key = createHash("sha256").update(canonicalHome).digest("hex").slice(0, 20);
+  // macOS sockaddr_un allows only 104 bytes, including the trailing NUL.
+  // Keep the namespace stable so codexteer discovers already-running wrappers.
+  const root = `/private/tmp/codex-steer-${process.getuid()}`;
+  const directory = path.join(root, key);
+  const lease = path.join(directory, "lease");
+  return { home: canonicalHome, root, directory, lease, state: path.join(lease, "state.json"), socket: path.join(lease, "rpc.sock"), control: path.join(lease, "ui.sock") };
+}
+
+async function canonicalPath(input) {
+  try { return await realpath(input); } catch (error) {
+    if (error.code !== "ENOENT" || path.dirname(input) === input) throw error;
+    return path.join(await canonicalPath(path.dirname(input)), path.basename(input));
+  }
+}
+
+async function checkOwned(file, type) {
+  const info = await lstat(file);
+  if (info.uid !== process.getuid() || (info.mode & 0o077) !== 0 || info.isSymbolicLink()
+    || (type === "directory" ? !info.isDirectory() : type === "socket" ? !info.isSocket() : !info.isFile())) {
+    throw runtimeFailure("Shared App Server runtime has unsafe ownership, permissions, or file type.", "RUNTIME_UNSAFE");
+  }
+  return info;
+}
+
+export function isAlive(pid) {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch (error) {
+    if (error.code === "ESRCH") return false;
+    // An inspection denial is not evidence of a dead process.
+    throw runtimeFailure("Cannot verify the shared App Server process. Run this command from your terminal.", "PERMISSION_DENIED");
+  }
+}
+
+export async function readRuntime(paths) {
+  for (const dir of [paths.root, paths.directory, paths.lease]) await checkOwned(dir, "directory");
+  await checkOwned(paths.state, "file");
+  let state;
+  try { state = JSON.parse(await readFile(paths.state, "utf8")); }
+  catch (error) {
+    if (error instanceof SyntaxError) throw runtimeFailure("Invalid shared App Server runtime record.", "RUNTIME_INVALID");
+    throw error;
+  }
+  if (state?.schema !== 1 || state.codex_home !== paths.home || typeof state.instance !== "string" || !/^[0-9a-f-]{36}$/.test(state.instance)
+    || !Number.isSafeInteger(state.pid) || state.pid <= 0) throw runtimeFailure("Invalid shared App Server runtime record.", "RUNTIME_INVALID");
+  return state;
+}
+
+export async function verifyControlEndpoint(paths) {
+  try { await checkOwned(paths.control, "socket"); }
+  catch (error) {
+    if (error.code === "ENOENT") throw runtimeFailure("Desktop subscription is unavailable. Only --new-turn requires this endpoint.", "DESKTOP_SUBSCRIPTION_UNAVAILABLE");
+    if (["EACCES", "EPERM"].includes(error.code)) throw runtimeFailure("Cannot inspect the Desktop subscription endpoint. Check access permissions.", "PERMISSION_DENIED");
+    throw error;
+  }
+}
+
+export async function discoverRuntime(home) {
+  const paths = await runtimePaths(home);
+  try {
+    const state = await readRuntime(paths);
+    if (!isAlive(state.pid) || !isAlive(state.server_pid) || !state.desktop_connected) {
+      throw runtimeFailure("Shared App Server is not ready. Finish current tasks, quit Desktop, then run: codexteer desktop start", "RUNTIME_NOT_READY");
+    }
+    await checkOwned(paths.socket, "socket");
+    return { paths, state };
+  } catch (error) {
+    if (error.code === "ENOENT") throw runtimeFailure("Shared App Server is unavailable. Finish current tasks, quit Desktop, then run: codexteer desktop start", "RUNTIME_UNAVAILABLE");
+    if (["EACCES", "EPERM"].includes(error.code)) throw runtimeFailure("Cannot inspect the shared App Server runtime. Check access permissions.", "PERMISSION_DENIED");
+    throw error;
+  }
+}
+
+export async function claimRuntime(home, details = {}) {
+  const paths = await runtimePaths(home);
+  for (const dir of [paths.root, paths.directory]) {
+    await mkdir(dir, { mode: 0o700 }).catch(error => { if (error.code !== "EEXIST") throw error; });
+    await checkOwned(dir, "directory");
+  }
+  try { await mkdir(paths.lease, { mode: 0o700 }); } catch (error) {
+    if (error.code !== "EEXIST") throw error;
+    const old = await readRuntime(paths);
+    if (isAlive(old.pid) || isAlive(old.server_pid)) throw new Error("A shared App Server already owns this CODEX_HOME.");
+    const recovery = path.join(paths.directory, `recover-${old.instance}`);
+    await mkdir(recovery, { mode: 0o700 });
+    try {
+      const current = await readRuntime(paths);
+      if (current.instance !== old.instance || isAlive(current.pid) || isAlive(current.server_pid)) {
+        throw new Error("Shared App Server ownership changed during startup. Retry once startup finishes.");
+      }
+      const stale = path.join(recovery, "stale");
+      await rename(paths.lease, stale);
+      await mkdir(paths.lease, { mode: 0o700 });
+    } finally { await rm(recovery, { recursive: true, force: true }); }
+  }
+  let state = { schema: 1, instance: randomUUID(), codex_home: paths.home, pid: process.pid, server_pid: null, desktop_connected: false, ...details };
+  let writes = Promise.resolve();
+  const update = patch => {
+    state = { ...state, ...patch };
+    const snapshot = JSON.stringify(state);
+    writes = writes.then(async () => {
+      const temp = `${paths.state}.${state.instance}.tmp`;
+      await writeFile(temp, snapshot, { mode: 0o600 });
+      await rename(temp, paths.state);
+    });
+    return writes;
+  };
+  await update({});
+  return {
+    paths, update,
+    async release() {
+      await writes.catch(() => {});
+      const current = await readRuntime(paths).catch(() => null);
+      if (current?.instance === state.instance) await rm(paths.lease, { recursive: true, force: true });
+    },
+  };
+}

package/src/settings.mjs

@@ -0,0 +1,49 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+
+const DEFAULTS = Object.freeze({
+  follow_up_mode: "steer",
+  composer_enter_behavior: "enter",
+  submit_shortcut: "plain",
+});
+
+export function parseDesktopSettings(source) {
+  let section = "";
+  const values = {};
+
+  for (const rawLine of source.split(/\r?\n/u)) {
+    const line = rawLine.trim();
+    const sectionMatch = line.match(/^\[([^\]]+)\]$/u);
+    if (sectionMatch) {
+      section = sectionMatch[1];
+      continue;
+    }
+    if (section !== "desktop" || line === "" || line.startsWith("#")) continue;
+
+    const valueMatch = line.match(/^([A-Za-z][A-Za-z0-9_]*)\s*=\s*"([^"]*)"/u);
+    if (valueMatch) values[valueMatch[1]] = valueMatch[2];
+  }
+
+  const followUpMode = values.followUpQueueMode === "queue" ? "queue" : "steer";
+  const composerEnterBehavior = ["cmdIfMultiline", "cmdAlways"].includes(values.composerEnterBehavior)
+    ? values.composerEnterBehavior
+    : "enter";
+  const submitShortcut = followUpMode === "queue"
+    ? composerEnterBehavior === "enter" ? "command" : "command-shift"
+    : "plain";
+
+  return {
+    follow_up_mode: followUpMode,
+    composer_enter_behavior: composerEnterBehavior,
+    submit_shortcut: submitShortcut,
+  };
+}
+
+export function readDesktopSettings(configPath = path.join(
+  process.env.CODEX_HOME || path.join(homedir(), ".codex"),
+  "config.toml",
+)) {
+  if (!existsSync(configPath)) return { ...DEFAULTS };
+  return parseDesktopSettings(readFileSync(configPath, "utf8"));
+}

package/src/sound.mjs

@@ -0,0 +1,16 @@
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+export const SEND_NOTIFICATION_SOUND = fileURLToPath(new URL("../assets/send-pururu.wav", import.meta.url));
+
+export function playSendSound(receipt, { run = spawnSync, platform = process.platform } = {}) {
+  if (receipt.dry_run) return { played: false, reason: "dry_run" };
+  if (receipt.sent !== true || receipt.delivery_status !== "accepted") return { played: false, reason: "not_accepted" };
+  if (platform !== "darwin") return { played: false, reason: "unsupported_platform" };
+  // Audio failure must not turn an accepted send into a retryable failure.
+  try {
+    const result = run("/usr/bin/afplay", [SEND_NOTIFICATION_SOUND], { encoding: "utf8", timeout: 5000 });
+    if (!result.error && result.status === 0) return { played: true };
+  } catch { /* Preserve the send receipt even if playback cannot start. */ }
+  return { played: false, reason: "playback_failed" };
+}

package/src/store.mjs

@@ -0,0 +1,78 @@
+import { lstat, mkdir, readFile, writeFile, rename, rm, readdir, link } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { codexHome, isAlive } from "./runtime.mjs";
+
+const valid = value => typeof value === "string" && /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,150}$/.test(value);
+// The persisted namespace predates the codexteer rename; keep existing records.
+export function storePath(bucket, id, home = codexHome()) {
+  if (!valid(bucket) || (id != null && !valid(id))) throw new Error("Invalid local record identifier.");
+  return path.join(home, "codex-steer", bucket, ...(id == null ? [] : [`${id}.json`]));
+}
+
+async function owned(file, directory = false) {
+  const s = await lstat(file);
+  if (s.uid !== process.getuid() || s.isSymbolicLink() || (s.mode & 0o077) || (directory ? !s.isDirectory() : !s.isFile())) throw new Error("Unsafe local state ownership, permissions, or file type.");
+}
+
+async function directory(bucket, home, create = false) {
+  const root = path.join(home, "codex-steer"), target = storePath(bucket, null, home);
+  for (const p of [root, target]) {
+    if (create) await mkdir(p, { mode: 0o700 }).catch(e => { if (e.code !== "EEXIST") throw e; });
+    await owned(p, true);
+  }
+  return target;
+}
+
+export async function readRecord(bucket, id, { home = codexHome() } = {}) {
+  try {
+    await directory(bucket, home);
+    const file = storePath(bucket, id, home); await owned(file);
+    return JSON.parse(await readFile(file, "utf8"));
+  } catch (error) { if (error.code === "ENOENT") return null; throw error; }
+}
+
+export async function writeRecord(bucket, id, data, { home = codexHome() } = {}) {
+  await directory(bucket, home, true);
+  const target = storePath(bucket, id, home), temp = `${target}.${randomUUID()}.tmp`;
+  await owned(target).catch(e => { if (e.code !== "ENOENT") throw e; });
+  try { await writeFile(temp, JSON.stringify(data) + "\n", { mode: 0o600, flag: "wx" }); await rename(temp, target); }
+  finally { await rm(temp, { force: true }); }
+}
+
+export async function listRecords(bucket, options = {}) {
+  const home = options.home ?? codexHome(); let dir;
+  try { dir = await directory(bucket, home); } catch (e) { if (e.code === "ENOENT") return []; throw e; }
+  const files = (await readdir(dir)).filter(x => x.endsWith(".json"));
+  return Promise.all(files.map(x => readRecord(bucket, x.slice(0, -5), { home })));
+}
+
+export async function withStoreLock(key, fn, { home = codexHome() } = {}) {
+  await directory("locks", home, true);
+  const file = storePath("locks", key, home), token = randomUUID(), temp = `${file}.${token}.tmp`;
+  await writeFile(temp, JSON.stringify({ token, pid: process.pid }), { mode: 0o600, flag: "wx" });
+  let acquired = false;
+  let outcome;
+  try {
+    for (let attempt = 0; attempt < 2; attempt++) {
+      try { await link(temp, file); acquired = true; break; } catch (e) { if (e.code !== "EEXIST") throw e; }
+      const old = await readRecord("locks", key, { home });
+      if (old && !isAlive(old.pid)) {
+        const recovery = `${file}.recover`;
+        try { await mkdir(recovery, { mode: 0o700 }); } catch (e) { if (e.code !== "EEXIST") throw e; break; }
+        try {
+          const current = await readRecord("locks", key, { home });
+          if (current?.token === old.token && !isAlive(current.pid)) await rm(file);
+        } finally { await rm(recovery, { recursive: true }); }
+      } else break;
+    }
+    if (!acquired) throw Object.assign(new Error("Another operation owns this local record. Retry after it finishes."), { code: "RECORD_BUSY" });
+    outcome = await fn();
+    return outcome;
+  } finally {
+    try {
+      if (acquired && (await readRecord("locks", key, { home }))?.token === token) await rm(file);
+      await rm(temp, { force: true });
+    } catch { if (outcome && typeof outcome === "object") outcome.state_cleanup_required = true; }
+  }
+}

package/src/subscription.mjs

@@ -0,0 +1,118 @@
+import net from "node:net";
+import { chmod } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { normalizeThreadId } from "./thread-id.mjs";
+
+// This is our own owner-only socket, not Desktop's private/authenticated MCP pipe.
+// It exposes only thread subscription, never generic RPC or approval decisions.
+export class DesktopSubscriptions {
+  constructor(socket, { timeoutMs = 8000 } = {}) {
+    this.socket = socket;
+    this.timeoutMs = timeoutMs;
+    this.pending = new Map();
+    this.prefix = `codexteer-subscribe-${randomUUID()}-`;
+    this.ready = false;
+  }
+
+  consume(message) {
+    if (message.method || typeof message.id !== "string" || !message.id.startsWith(this.prefix)) return true;
+    // Late replies to timed-out helper calls also belong to the helper.
+    if (!this.pending.has(message.id)) return false;
+    const request = this.pending.get(message.id);
+    this.pending.delete(message.id);
+    clearTimeout(request.timer);
+    if (message.error || message.result?.thread?.id !== request.threadId) {
+      request.reject(new Error("Desktop could not subscribe to the target task."));
+    } else request.resolve();
+    return false;
+  }
+
+  ensure(threadId) {
+    normalizeThreadId(threadId);
+    if (!this.ready) return Promise.reject(new Error("Desktop has not initialized its App Server connection."));
+    const id = this.prefix + randomUUID();
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error("Desktop subscription timed out. No message was sent."));
+      }, this.timeoutMs);
+      this.pending.set(id, { threadId, timer, resolve, reject });
+      this.socket.send(JSON.stringify({ id, method: "thread/resume", params: { threadId, excludeTurns: true } }), error => {
+        if (error && this.pending.delete(id)) { clearTimeout(timer); reject(new Error("Desktop subscription connection failed.")); }
+      });
+    });
+  }
+
+  close() {
+    this.ready = false;
+    for (const request of this.pending.values()) {
+      clearTimeout(request.timer);
+      request.reject(new Error("Desktop connection closed before subscribing."));
+    }
+    this.pending.clear();
+  }
+}
+
+export async function serveSubscriptions(socketPath, subscriptions) {
+  const sockets = new Set();
+  const server = net.createServer(socket => {
+    sockets.add(socket);
+    socket.on("close", () => sockets.delete(socket));
+    socket.on("error", () => {});
+    socket.setTimeout(10000, () => socket.destroy());
+    let text = "";
+    let handled = false;
+    socket.setEncoding("utf8");
+    socket.on("data", chunk => {
+      if (handled) return;
+      text += chunk;
+      if (Buffer.byteLength(text) > 1024) { socket.destroy(); return; }
+      if (!text.includes("\n")) return;
+      handled = true;
+      Promise.resolve().then(async () => {
+        const request = JSON.parse(text.trim());
+        if (request.method !== "subscribe" || Object.keys(request).some(key => !["method", "thread_id"].includes(key))) throw new Error();
+        const threadId = normalizeThreadId(request.thread_id);
+        await subscriptions.ensure(threadId);
+        socket.end(JSON.stringify({ ok: true, thread_id: threadId }) + "\n");
+      }).catch(() => socket.end(JSON.stringify({ ok: false, error: "Desktop subscription failed. No message was sent." }) + "\n"));
+    });
+  });
+  await new Promise((resolve, reject) => { server.once("error", reject); server.listen(socketPath, resolve); });
+  await chmod(socketPath, 0o600);
+  return async () => {
+    subscriptions.close();
+    for (const socket of sockets) socket.destroy();
+    await new Promise(resolve => server.close(resolve));
+  };
+}
+
+export async function ensureDesktopSubscription(socketPath, threadId, { timeoutMs = 10000 } = {}) {
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection(socketPath);
+    let text = "";
+    let settled = false;
+    const finish = error => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      if (error) reject(new Error("Could not establish the Desktop task subscription. No message was sent."));
+      else resolve();
+    };
+    socket.setTimeout(timeoutMs, () => finish(true));
+    socket.on("error", () => finish(true));
+    socket.on("end", () => finish(true));
+    socket.on("close", () => finish(true));
+    socket.setEncoding("utf8");
+    socket.on("connect", () => socket.write(JSON.stringify({ method: "subscribe", thread_id: threadId }) + "\n"));
+    socket.on("data", chunk => {
+      text += chunk;
+      if (Buffer.byteLength(text) > 2048) { finish(true); return; }
+      if (!text.includes("\n")) return;
+      try {
+        const response = JSON.parse(text.trim());
+        finish(!(response.ok === true && response.thread_id === threadId));
+      } catch { finish(true); }
+    });
+  });
+}

package/src/supervise.mjs

@@ -0,0 +1,57 @@
+import { spawn } from "node:child_process";
+import { once } from "node:events";
+import { constants } from "node:os";
+import { realpath } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { prepareDeployment } from "./distribution.mjs";
+import { normalizeThreadId } from "./thread-id.mjs";
+import { codexHome } from "./runtime.mjs";
+
+function shellArgument(value) {
+  if (/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/u.test(value)) {
+    throw Object.assign(new Error("Cannot generate supervision commands from a path containing control characters. Use a path without them and generate the prompt again."), { code: "SUPERVISION_PATH_UNSAFE" });
+  }
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+export async function prepareSupervisorPrompt(threadInput) {
+  const threadId = normalizeThreadId(threadInput);
+  const node = { path: await realpath(process.execPath), version: process.version };
+  const home = codexHome();
+  shellArgument(node.path); shellArgument(home);
+  const deployment = await prepareDeployment(home);
+  // Bind the validated canonical profile as well as the saved executable.
+  const command = `CODEX_HOME=${shellArgument(deployment.codex_home)} ${shellArgument(node.path)} ${shellArgument(path.join(deployment.directory, "bin/codexteer.mjs"))} --require-node-version ${shellArgument(node.version)}`;
+  // Render with the saved distribution's implementation as well as its CLI.
+  // An update to the source/cache after placement cannot mix prompt and code.
+  const { supervisorPrompt } = await import(pathToFileURL(path.join(deployment.directory, "src/prompt.mjs")).href);
+  return { ...supervisorPrompt(threadId, command), deployment, node };
+}
+
+function launchFailure(agent, error) {
+  return Object.assign(new Error(`Could not start ${agent} (${error.code ?? "START_FAILED"}). Check that it is installed and executable on PATH.`), { code: error.code ?? "START_FAILED" });
+}
+
+export async function superviseAgent(threadInput, { agent, agentArgs = [] } = {}) {
+  if (agent !== "claude") throw new Error("supervise requires --agent claude. See codexteer help supervise.");
+  const { prompt } = await prepareSupervisorPrompt(threadInput);
+
+  let child;
+  try {
+    // Keep forwarded argv intact. The agent's own terminator keeps its variadic
+    // options from consuming the generated prompt as another option value.
+    child = spawn(agent, [...agentArgs, "--", prompt], { shell: false, stdio: "inherit" });
+  } catch (error) { throw launchFailure(agent, error); }
+
+  const signals = ["SIGINT", "SIGTERM", "SIGHUP"];
+  const handlers = signals.map(signal => () => {
+    if (child.exitCode === null && child.signalCode === null) child.kill(signal);
+  });
+  signals.forEach((signal, index) => process.on(signal, handlers[index]));
+  try {
+    const [code, signal] = await once(child, "exit");
+    return code ?? (signal ? 128 + (constants.signals[signal] ?? 0) : 1);
+  } catch (error) { throw launchFailure(agent, error); }
+  finally { signals.forEach((signal, index) => process.off(signal, handlers[index])); }
+}