@livedesk/hub 0.1.41 → 0.1.43

package/src/agents/codex-agent-runtime.js

@@ -1,34 +1,34 @@
-import crypto from 'node:crypto';
-import { existsSync } from 'node:fs';
-import { access, link, mkdir, stat, unlink } from 'node:fs/promises';
+import crypto from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { access, link, mkdir, stat, unlink } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
-import { createRequire } from 'node:module';
-import { AgentRuntimeError } from './agent-runtime-error.js';
-import { AGENT_TOOL_NAMES } from './agent-tool-registry.js';
+import { createRequire } from 'node:module';
+import { AgentRuntimeError } from './agent-runtime-error.js';
+import { AGENT_TOOL_NAMES } from './agent-tool-registry.js';
 import { createAgentPermissionPolicy, hashAgentPermissionPolicy } from './agent-permissions.js';
 
 const require = createRequire(import.meta.url);
-const MAX_EVENTS = 240;
-const MAX_RUNS = 500;
-const RUN_TTL_MS = 60 * 60 * 1000;
-const MAX_CODEX_CLI_OUTPUT_BYTES = 64 * 1024;
-const MAX_CODEX_CLI_OUTPUT_CHUNKS = 256;
-const CODEX_CLI_TERMINATE_GRACE_MS = 200;
-const CODEX_CLI_FORCE_CLOSE_MS = 1000;
-const activeCliProcessOwners = new Map();
-let nextCliProcessOwnerId = 0;
-let bundledCodexCliPathCache;
-const CODEX_NATIVE_TARGETS = Object.freeze({
-  'linux:x64': ['@openai/codex-linux-x64', 'x86_64-unknown-linux-musl', 'codex'],
-  'linux:arm64': ['@openai/codex-linux-arm64', 'aarch64-unknown-linux-musl', 'codex'],
-  'darwin:x64': ['@openai/codex-darwin-x64', 'x86_64-apple-darwin', 'codex'],
-  'darwin:arm64': ['@openai/codex-darwin-arm64', 'aarch64-apple-darwin', 'codex'],
-  'win32:x64': ['@openai/codex-win32-x64', 'x86_64-pc-windows-msvc', 'codex.exe'],
-  'win32:arm64': ['@openai/codex-win32-arm64', 'aarch64-pc-windows-msvc', 'codex.exe']
-});
-const SAFE_ENV_KEYS = [
+const MAX_EVENTS = 240;
+const MAX_RUNS = 500;
+const RUN_TTL_MS = 60 * 60 * 1000;
+const MAX_CODEX_CLI_OUTPUT_BYTES = 64 * 1024;
+const MAX_CODEX_CLI_OUTPUT_CHUNKS = 256;
+const CODEX_CLI_TERMINATE_GRACE_MS = 200;
+const CODEX_CLI_FORCE_CLOSE_MS = 1000;
+const activeCliProcessOwners = new Map();
+let nextCliProcessOwnerId = 0;
+let bundledCodexCliPathCache;
+const CODEX_NATIVE_TARGETS = Object.freeze({
+  'linux:x64': ['@openai/codex-linux-x64', 'x86_64-unknown-linux-musl', 'codex'],
+  'linux:arm64': ['@openai/codex-linux-arm64', 'aarch64-unknown-linux-musl', 'codex'],
+  'darwin:x64': ['@openai/codex-darwin-x64', 'x86_64-apple-darwin', 'codex'],
+  'darwin:arm64': ['@openai/codex-darwin-arm64', 'aarch64-apple-darwin', 'codex'],
+  'win32:x64': ['@openai/codex-win32-x64', 'x86_64-pc-windows-msvc', 'codex.exe'],
+  'win32:arm64': ['@openai/codex-win32-arm64', 'aarch64-pc-windows-msvc', 'codex.exe']
+});
+const SAFE_ENV_KEYS = [
   'Path',
   'PATH',
   'SystemRoot',
@@ -71,23 +71,23 @@ function isAbortError(error) {
     || /aborted|abort/i.test(String(error?.message || ''));
 }
 
-function normalizeCodexError(error) {
-  const message = safeText(error?.message, 800) || 'Codex run failed.';
-  if (error instanceof AgentRuntimeError && error.code !== 'codex-run-failed') return error;
-  if (/out of credits|usage limit|rate limit|too many requests/i.test(message)) return new AgentRuntimeError('codex-usage-limit-reached', 'The Codex workspace has no remaining usage.', { status: 402, retryable: true });
-  if (/refresh[_ -]?token[_ -]?(?:already[_ -]?)?used|token refresh|refresh credential/i.test(message)) return new AgentRuntimeError('codex-auth-stale', 'The saved Codex sign-in is stale. LiveDesk refreshed its Codex authentication bridge and will retry.', { status: 401, retryable: true });
-  if (/not authenticated|not logged in|authentication|unauthorized|login required/i.test(message)) return new AgentRuntimeError('codex-auth-required', 'Sign in with the Codex CLI first.', { status: 401 });
-  if (/user cancelled MCP tool call/i.test(message)) return new AgentRuntimeError('codex-mcp-tool-rejected', 'Codex rejected the LiveDesk MCP tool before it reached the Hub.', { status: 502 });
-  return new AgentRuntimeError('codex-run-failed', message, { status: 502, retryable: true });
-}
-
-function codexThreadOptions(workspace) {
-  return {
-    sandboxMode: 'read-only',
-    approvalPolicy: 'never',
-    workingDirectory: workspace,
-    skipGitRepoCheck: true,
-    networkAccessEnabled: false,
+function normalizeCodexError(error) {
+  const message = safeText(error?.message, 800) || 'Codex run failed.';
+  if (error instanceof AgentRuntimeError && error.code !== 'codex-run-failed') return error;
+  if (/out of credits|usage limit|rate limit|too many requests/i.test(message)) return new AgentRuntimeError('codex-usage-limit-reached', 'The Codex workspace has no remaining usage.', { status: 402, retryable: true });
+  if (/refresh[_ -]?token[_ -]?(?:already[_ -]?)?used|token refresh|refresh credential/i.test(message)) return new AgentRuntimeError('codex-auth-stale', 'The saved Codex sign-in is stale. LiveDesk refreshed its Codex authentication bridge and will retry.', { status: 401, retryable: true });
+  if (/not authenticated|not logged in|authentication|unauthorized|login required/i.test(message)) return new AgentRuntimeError('codex-auth-required', 'Sign in with the Codex CLI first.', { status: 401 });
+  if (/user cancelled MCP tool call/i.test(message)) return new AgentRuntimeError('codex-mcp-tool-rejected', 'Codex rejected the LiveDesk MCP tool before it reached the Hub.', { status: 502 });
+  return new AgentRuntimeError('codex-run-failed', message, { status: 502, retryable: true });
+}
+
+function codexThreadOptions(workspace) {
+  return {
+    sandboxMode: 'read-only',
+    approvalPolicy: 'never',
+    workingDirectory: workspace,
+    skipGitRepoCheck: true,
+    networkAccessEnabled: false,
     webSearchMode: 'disabled',
     webSearchEnabled: false,
     additionalDirectories: []
@@ -161,342 +161,342 @@ function safeCodexEnv(codexHome) {
   return env;
 }
 
-function sameFile(left, right) {
-  return left.dev === right.dev && left.ino === right.ino;
-}
-
-async function replaceAuthHardLink(sourceAuthPath, targetAuthPath) {
-  await unlink(targetAuthPath).catch(error => {
-    if (error?.code !== 'ENOENT') throw error;
-  });
-  try {
-    await link(sourceAuthPath, targetAuthPath);
-  } catch (error) {
-    if (error?.code !== 'EEXIST') throw error;
-  }
-}
-
-async function ensureCodexHome(codexHome, globalCodexHome, { preferGlobalAuth = false } = {}) {
-  const resolvedHome = path.resolve(codexHome);
-  const globalHome = path.resolve(globalCodexHome);
-  if (!resolvedHome || resolvedHome === globalHome) {
-    throw new AgentRuntimeError('codex-isolation-unavailable', 'Codex requires a dedicated LiveDesk home.', { status: 503 });
-  }
+function sameFile(left, right) {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+
+async function replaceAuthHardLink(sourceAuthPath, targetAuthPath) {
+  await unlink(targetAuthPath).catch(error => {
+    if (error?.code !== 'ENOENT') throw error;
+  });
+  try {
+    await link(sourceAuthPath, targetAuthPath);
+  } catch (error) {
+    if (error?.code !== 'EEXIST') throw error;
+  }
+}
+
+async function ensureCodexHome(codexHome, globalCodexHome, { preferGlobalAuth = false } = {}) {
+  const resolvedHome = path.resolve(codexHome);
+  const globalHome = path.resolve(globalCodexHome);
+  if (!resolvedHome || resolvedHome === globalHome) {
+    throw new AgentRuntimeError('codex-isolation-unavailable', 'Codex requires a dedicated LiveDesk home.', { status: 503 });
+  }
   try {
     await mkdir(resolvedHome, { recursive: true, mode: 0o700 });
     if (await access(path.join(resolvedHome, 'config.toml')).then(() => true, () => false)) {
-      throw new AgentRuntimeError('codex-environment-isolation-failed', 'The dedicated Codex home contains an unmanaged config.toml.', { status: 503 });
+      throw new AgentRuntimeError('codex-environment-isolation-failed', 'The dedicated Codex home contains an unmanaged config.toml.', { status: 503 });
     }
   } catch (error) {
-    if (error instanceof AgentRuntimeError) throw error;
-    const wrapped = new AgentRuntimeError('codex-environment-isolation-failed', 'The dedicated Codex home could not be prepared.', { status: 503 });
+    if (error instanceof AgentRuntimeError) throw error;
+    const wrapped = new AgentRuntimeError('codex-environment-isolation-failed', 'The dedicated Codex home could not be prepared.', { status: 503 });
     wrapped.cause = error;
     throw wrapped;
-  }
-  const targetAuthPath = path.join(resolvedHome, 'auth.json');
-  const sourceAuthPath = path.join(globalHome, 'auth.json');
-  if (!(await access(sourceAuthPath).then(() => true, () => false))) return;
-  try {
-    const sourceStatus = await stat(sourceAuthPath);
-    const targetStatus = await stat(targetAuthPath).catch(error => {
-      if (error?.code === 'ENOENT') return null;
-      throw error;
-    });
-    if (!targetStatus) {
-      await link(sourceAuthPath, targetAuthPath);
-      return;
-    }
-    if (sameFile(sourceStatus, targetStatus)) return;
-
-    // Codex may atomically replace auth.json while refreshing a token. That
-    // breaks a hard link even though both paths still exist. Follow the newer
-    // credential owner, or explicitly recover from a stale-refresh failure,
-    // without ever reading or copying credential contents.
-    if (preferGlobalAuth || sourceStatus.mtimeMs > targetStatus.mtimeMs || targetStatus.size === 0) {
-      await replaceAuthHardLink(sourceAuthPath, targetAuthPath);
-    }
-  } catch (error) {
-    const wrapped = new AgentRuntimeError('codex-environment-isolation-failed', 'The Codex authentication bridge could not be prepared.', { status: 503 });
-    wrapped.cause = error;
+  }
+  const targetAuthPath = path.join(resolvedHome, 'auth.json');
+  const sourceAuthPath = path.join(globalHome, 'auth.json');
+  if (!(await access(sourceAuthPath).then(() => true, () => false))) return;
+  try {
+    const sourceStatus = await stat(sourceAuthPath);
+    const targetStatus = await stat(targetAuthPath).catch(error => {
+      if (error?.code === 'ENOENT') return null;
+      throw error;
+    });
+    if (!targetStatus) {
+      await link(sourceAuthPath, targetAuthPath);
+      return;
+    }
+    if (sameFile(sourceStatus, targetStatus)) return;
+
+    // Codex may atomically replace auth.json while refreshing a token. That
+    // breaks a hard link even though both paths still exist. Follow the newer
+    // credential owner, or explicitly recover from a stale-refresh failure,
+    // without ever reading or copying credential contents.
+    if (preferGlobalAuth || sourceStatus.mtimeMs > targetStatus.mtimeMs || targetStatus.size === 0) {
+      await replaceAuthHardLink(sourceAuthPath, targetAuthPath);
+    }
+  } catch (error) {
+    const wrapped = new AgentRuntimeError('codex-environment-isolation-failed', 'The Codex authentication bridge could not be prepared.', { status: 503 });
+    wrapped.cause = error;
     throw wrapped;
   }
 }
 
-function boundedCliOption(value, fallback, minimum = 1) {
-  const number = Number(value);
-  if (!Number.isFinite(number)) return fallback;
-  return Math.min(fallback, Math.max(minimum, Math.floor(number)));
-}
-
-export function resolveBundledCodexCliPath() {
-  if (bundledCodexCliPathCache !== undefined) return bundledCodexCliPathCache;
-  const target = CODEX_NATIVE_TARGETS[`${process.platform}:${process.arch}`];
-  if (!target) {
-    bundledCodexCliPathCache = '';
-    return bundledCodexCliPathCache;
-  }
-  const [platformPackage, targetTriple, executableName] = target;
-  try {
-    const packageJsonPath = require.resolve(`${platformPackage}/package.json`);
-    const executablePath = path.join(
-      path.dirname(packageJsonPath),
-      'vendor',
-      targetTriple,
-      'bin',
-      executableName
-    );
-    if (existsSync(executablePath)) {
-      bundledCodexCliPathCache = executablePath;
-      return bundledCodexCliPathCache;
-    }
-  } catch {
-    // Older Codex packages may keep the platform payload under the portable
-    // package. That fallback remains a native executable, never the JS wrapper.
-  }
-  try {
-    const portableCliPath = require.resolve('@openai/codex/bin/codex.js');
-    const executablePath = path.join(
-      path.dirname(portableCliPath),
-      '..',
-      'vendor',
-      targetTriple,
-      'bin',
-      executableName
-    );
-    bundledCodexCliPathCache = existsSync(executablePath) ? executablePath : '';
-    return bundledCodexCliPathCache;
-  } catch {
-    bundledCodexCliPathCache = '';
-    return bundledCodexCliPathCache;
-  }
-}
-
-export function getCodexCliProcessOwnerSnapshot() {
-  const owners = [...activeCliProcessOwners.values()];
-  return {
-    activeOwners: owners.length,
-    activeProcesses: owners.filter(owner => owner.child !== null).length,
-    activeStdoutStreams: owners.filter(owner => owner.stdoutStream !== null).length,
-    activeStderrStreams: owners.filter(owner => owner.stderrStream !== null).length,
-    activeListeners: owners.reduce((total, owner) => total + owner.listenerCount, 0),
-    activeTimers: owners.reduce((total, owner) => total
-      + Number(owner.timeoutTimer !== null)
-      + Number(owner.forceKillTimer !== null)
-      + Number(owner.forceCloseTimer !== null), 0),
-    retainedOutputBytes: owners.reduce((total, owner) => total + owner.retainedOutputBytes, 0)
-  };
-}
-
-export function runCli(
-  cliPath,
-  args,
-  timeoutMs = 5000,
-  env = process.env,
-  lifecycleOptions = {}
-) {
-  const maxOutputBytes = boundedCliOption(
-    lifecycleOptions.maxOutputBytes,
-    MAX_CODEX_CLI_OUTPUT_BYTES
-  );
-  const terminateGraceMs = boundedCliOption(
-    lifecycleOptions.terminateGraceMs,
-    CODEX_CLI_TERMINATE_GRACE_MS
-  );
-  const forceCloseMs = boundedCliOption(
-    lifecycleOptions.forceCloseMs,
-    CODEX_CLI_FORCE_CLOSE_MS
-  );
-  const boundedTimeoutMs = Math.max(1, Math.floor(Number(timeoutMs) || 5000));
-  return new Promise((resolve, reject) => {
-    let child;
-    try {
-      const usesNodeLauncher = /\.(?:c|m)?js$/i.test(cliPath);
-      child = spawn(usesNodeLauncher ? process.execPath : cliPath, [
-        ...(usesNodeLauncher ? [cliPath] : []),
-        ...args
-      ], {
-        env,
-        windowsHide: true,
-        stdio: ['ignore', 'pipe', 'pipe']
-      });
-    } catch (error) {
-      reject(error);
-      return;
-    }
-
-    const owner = {
-      id: ++nextCliProcessOwnerId,
-      child,
-      stdoutStream: child.stdout,
-      stderrStream: child.stderr,
-      stdoutChunks: [],
-      stderrChunks: [],
-      stdoutBytes: 0,
-      stderrBytes: 0,
-      retainedOutputBytes: 0,
-      listenerCount: 6,
-      acceptingOutput: true,
-      failure: null,
-      settled: false,
-      timeoutTimer: null,
-      forceKillTimer: null,
-      forceCloseTimer: null
-    };
-    activeCliProcessOwners.set(owner.id, owner);
-
-    const clearOwnerTimer = key => {
-      if (owner[key] === null) return;
-      clearTimeout(owner[key]);
-      owner[key] = null;
-    };
-
-    const removeOutputDataListeners = () => {
-      if (!owner.acceptingOutput) return;
-      owner.acceptingOutput = false;
-      owner.stdoutStream?.removeListener('data', onStdoutData);
-      owner.stderrStream?.removeListener('data', onStderrData);
-      owner.listenerCount = Math.max(0, owner.listenerCount - 2);
-      owner.stdoutStream?.resume();
-      owner.stderrStream?.resume();
-    };
-
-    const cleanupOwner = () => {
-      clearOwnerTimer('timeoutTimer');
-      clearOwnerTimer('forceKillTimer');
-      clearOwnerTimer('forceCloseTimer');
-      owner.child?.removeListener('error', onChildError);
-      owner.child?.removeListener('close', onChildClose);
-      owner.stdoutStream?.removeListener('data', onStdoutData);
-      owner.stdoutStream?.removeListener('error', onStdoutError);
-      owner.stderrStream?.removeListener('data', onStderrData);
-      owner.stderrStream?.removeListener('error', onStderrError);
-      owner.stdoutStream?.destroy();
-      owner.stderrStream?.destroy();
-      owner.child?.unref?.();
-      owner.child = null;
-      owner.stdoutStream = null;
-      owner.stderrStream = null;
-      owner.stdoutChunks.length = 0;
-      owner.stderrChunks.length = 0;
-      owner.stdoutBytes = 0;
-      owner.stderrBytes = 0;
-      owner.retainedOutputBytes = 0;
-      owner.listenerCount = 0;
-      activeCliProcessOwners.delete(owner.id);
-    };
-
-    const finish = code => {
-      if (owner.settled) return;
-      owner.settled = true;
-      const failure = owner.failure;
-      const result = failure ? null : {
-        code,
-        stdout: Buffer.concat(owner.stdoutChunks, owner.stdoutBytes).toString('utf8').trim(),
-        stderr: Buffer.concat(owner.stderrChunks, owner.stderrBytes).toString('utf8').trim()
-      };
-      cleanupOwner();
-      if (failure) reject(failure);
-      else resolve(result);
-    };
-
-    const killExactChild = signal => {
-      if (owner.child === null || owner.child.exitCode !== null || owner.child.signalCode !== null) return;
-      try {
-        owner.child.kill(signal);
-      } catch {
-        // The bounded forced-close owner below still releases every local
-        // handle if the OS reports that this exact child already disappeared.
-      }
-    };
-
-    const failAfterExactChildStops = error => {
-      if (owner.failure || owner.settled) return;
-      owner.failure = error;
-      clearOwnerTimer('timeoutTimer');
-      removeOutputDataListeners();
-      killExactChild('SIGTERM');
-      owner.forceKillTimer = setTimeout(() => {
-        owner.forceKillTimer = null;
-        killExactChild('SIGKILL');
-        owner.forceCloseTimer = setTimeout(() => {
-          owner.forceCloseTimer = null;
-          error.cleanupTimedOut = true;
-          killExactChild('SIGKILL');
-          finish(null);
-        }, forceCloseMs);
-        owner.forceCloseTimer.unref?.();
-      }, terminateGraceMs);
-      owner.forceKillTimer.unref?.();
-    };
-
-    const retainOutput = (channel, chunk) => {
-      if (!owner.acceptingOutput || owner.settled) return;
-      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-      const nextBytes = owner.retainedOutputBytes + buffer.length;
-      const nextChunks = owner.stdoutChunks.length + owner.stderrChunks.length + 1;
-      if (nextBytes > maxOutputBytes || nextChunks > MAX_CODEX_CLI_OUTPUT_CHUNKS) {
-        failAfterExactChildStops(Object.assign(
-          new Error(`Codex CLI status output exceeded its bounded retention budget.`),
-          {
-            code: 'codex-status-output-limit',
-            maxOutputBytes,
-            observedOutputBytes: nextBytes,
-            maxOutputChunks: MAX_CODEX_CLI_OUTPUT_CHUNKS,
-            observedOutputChunks: nextChunks
-          }
-        ));
-        return;
-      }
-      owner.retainedOutputBytes = nextBytes;
-      if (channel === 'stdout') {
-        owner.stdoutChunks.push(buffer);
-        owner.stdoutBytes += buffer.length;
-      } else {
-        owner.stderrChunks.push(buffer);
-        owner.stderrBytes += buffer.length;
-      }
-    };
-
-    function onStdoutData(chunk) {
-      retainOutput('stdout', chunk);
-    }
-
-    function onStderrData(chunk) {
-      retainOutput('stderr', chunk);
-    }
-
-    function onStdoutError(error) {
-      failAfterExactChildStops(error);
-    }
-
-    function onStderrError(error) {
-      failAfterExactChildStops(error);
-    }
-
-    function onChildError(error) {
-      failAfterExactChildStops(error);
-    }
-
-    function onChildClose(code) {
-      finish(code);
-    }
-
-    child.stdout.on('data', onStdoutData);
-    child.stdout.once('error', onStdoutError);
-    child.stderr.on('data', onStderrData);
-    child.stderr.once('error', onStderrError);
-    child.once('error', onChildError);
-    child.once('close', onChildClose);
-    owner.timeoutTimer = setTimeout(() => {
-      owner.timeoutTimer = null;
-      failAfterExactChildStops(Object.assign(
-        new Error('Codex CLI status check timed out.'),
-        { code: 'codex-status-timeout' }
-      ));
-    }, boundedTimeoutMs);
-    owner.timeoutTimer.unref?.();
-  });
-}
+function boundedCliOption(value, fallback, minimum = 1) {
+  const number = Number(value);
+  if (!Number.isFinite(number)) return fallback;
+  return Math.min(fallback, Math.max(minimum, Math.floor(number)));
+}
+
+export function resolveBundledCodexCliPath() {
+  if (bundledCodexCliPathCache !== undefined) return bundledCodexCliPathCache;
+  const target = CODEX_NATIVE_TARGETS[`${process.platform}:${process.arch}`];
+  if (!target) {
+    bundledCodexCliPathCache = '';
+    return bundledCodexCliPathCache;
+  }
+  const [platformPackage, targetTriple, executableName] = target;
+  try {
+    const packageJsonPath = require.resolve(`${platformPackage}/package.json`);
+    const executablePath = path.join(
+      path.dirname(packageJsonPath),
+      'vendor',
+      targetTriple,
+      'bin',
+      executableName
+    );
+    if (existsSync(executablePath)) {
+      bundledCodexCliPathCache = executablePath;
+      return bundledCodexCliPathCache;
+    }
+  } catch {
+    // Older Codex packages may keep the platform payload under the portable
+    // package. That fallback remains a native executable, never the JS wrapper.
+  }
+  try {
+    const portableCliPath = require.resolve('@openai/codex/bin/codex.js');
+    const executablePath = path.join(
+      path.dirname(portableCliPath),
+      '..',
+      'vendor',
+      targetTriple,
+      'bin',
+      executableName
+    );
+    bundledCodexCliPathCache = existsSync(executablePath) ? executablePath : '';
+    return bundledCodexCliPathCache;
+  } catch {
+    bundledCodexCliPathCache = '';
+    return bundledCodexCliPathCache;
+  }
+}
+
+export function getCodexCliProcessOwnerSnapshot() {
+  const owners = [...activeCliProcessOwners.values()];
+  return {
+    activeOwners: owners.length,
+    activeProcesses: owners.filter(owner => owner.child !== null).length,
+    activeStdoutStreams: owners.filter(owner => owner.stdoutStream !== null).length,
+    activeStderrStreams: owners.filter(owner => owner.stderrStream !== null).length,
+    activeListeners: owners.reduce((total, owner) => total + owner.listenerCount, 0),
+    activeTimers: owners.reduce((total, owner) => total
+      + Number(owner.timeoutTimer !== null)
+      + Number(owner.forceKillTimer !== null)
+      + Number(owner.forceCloseTimer !== null), 0),
+    retainedOutputBytes: owners.reduce((total, owner) => total + owner.retainedOutputBytes, 0)
+  };
+}
+
+export function runCli(
+  cliPath,
+  args,
+  timeoutMs = 5000,
+  env = process.env,
+  lifecycleOptions = {}
+) {
+  const maxOutputBytes = boundedCliOption(
+    lifecycleOptions.maxOutputBytes,
+    MAX_CODEX_CLI_OUTPUT_BYTES
+  );
+  const terminateGraceMs = boundedCliOption(
+    lifecycleOptions.terminateGraceMs,
+    CODEX_CLI_TERMINATE_GRACE_MS
+  );
+  const forceCloseMs = boundedCliOption(
+    lifecycleOptions.forceCloseMs,
+    CODEX_CLI_FORCE_CLOSE_MS
+  );
+  const boundedTimeoutMs = Math.max(1, Math.floor(Number(timeoutMs) || 5000));
+  return new Promise((resolve, reject) => {
+    let child;
+    try {
+      const usesNodeLauncher = /\.(?:c|m)?js$/i.test(cliPath);
+      child = spawn(usesNodeLauncher ? process.execPath : cliPath, [
+        ...(usesNodeLauncher ? [cliPath] : []),
+        ...args
+      ], {
+        env,
+        windowsHide: true,
+        stdio: ['ignore', 'pipe', 'pipe']
+      });
+    } catch (error) {
+      reject(error);
+      return;
+    }
+
+    const owner = {
+      id: ++nextCliProcessOwnerId,
+      child,
+      stdoutStream: child.stdout,
+      stderrStream: child.stderr,
+      stdoutChunks: [],
+      stderrChunks: [],
+      stdoutBytes: 0,
+      stderrBytes: 0,
+      retainedOutputBytes: 0,
+      listenerCount: 6,
+      acceptingOutput: true,
+      failure: null,
+      settled: false,
+      timeoutTimer: null,
+      forceKillTimer: null,
+      forceCloseTimer: null
+    };
+    activeCliProcessOwners.set(owner.id, owner);
+
+    const clearOwnerTimer = key => {
+      if (owner[key] === null) return;
+      clearTimeout(owner[key]);
+      owner[key] = null;
+    };
+
+    const removeOutputDataListeners = () => {
+      if (!owner.acceptingOutput) return;
+      owner.acceptingOutput = false;
+      owner.stdoutStream?.removeListener('data', onStdoutData);
+      owner.stderrStream?.removeListener('data', onStderrData);
+      owner.listenerCount = Math.max(0, owner.listenerCount - 2);
+      owner.stdoutStream?.resume();
+      owner.stderrStream?.resume();
+    };
+
+    const cleanupOwner = () => {
+      clearOwnerTimer('timeoutTimer');
+      clearOwnerTimer('forceKillTimer');
+      clearOwnerTimer('forceCloseTimer');
+      owner.child?.removeListener('error', onChildError);
+      owner.child?.removeListener('close', onChildClose);
+      owner.stdoutStream?.removeListener('data', onStdoutData);
+      owner.stdoutStream?.removeListener('error', onStdoutError);
+      owner.stderrStream?.removeListener('data', onStderrData);
+      owner.stderrStream?.removeListener('error', onStderrError);
+      owner.stdoutStream?.destroy();
+      owner.stderrStream?.destroy();
+      owner.child?.unref?.();
+      owner.child = null;
+      owner.stdoutStream = null;
+      owner.stderrStream = null;
+      owner.stdoutChunks.length = 0;
+      owner.stderrChunks.length = 0;
+      owner.stdoutBytes = 0;
+      owner.stderrBytes = 0;
+      owner.retainedOutputBytes = 0;
+      owner.listenerCount = 0;
+      activeCliProcessOwners.delete(owner.id);
+    };
+
+    const finish = code => {
+      if (owner.settled) return;
+      owner.settled = true;
+      const failure = owner.failure;
+      const result = failure ? null : {
+        code,
+        stdout: Buffer.concat(owner.stdoutChunks, owner.stdoutBytes).toString('utf8').trim(),
+        stderr: Buffer.concat(owner.stderrChunks, owner.stderrBytes).toString('utf8').trim()
+      };
+      cleanupOwner();
+      if (failure) reject(failure);
+      else resolve(result);
+    };
+
+    const killExactChild = signal => {
+      if (owner.child === null || owner.child.exitCode !== null || owner.child.signalCode !== null) return;
+      try {
+        owner.child.kill(signal);
+      } catch {
+        // The bounded forced-close owner below still releases every local
+        // handle if the OS reports that this exact child already disappeared.
+      }
+    };
+
+    const failAfterExactChildStops = error => {
+      if (owner.failure || owner.settled) return;
+      owner.failure = error;
+      clearOwnerTimer('timeoutTimer');
+      removeOutputDataListeners();
+      killExactChild('SIGTERM');
+      owner.forceKillTimer = setTimeout(() => {
+        owner.forceKillTimer = null;
+        killExactChild('SIGKILL');
+        owner.forceCloseTimer = setTimeout(() => {
+          owner.forceCloseTimer = null;
+          error.cleanupTimedOut = true;
+          killExactChild('SIGKILL');
+          finish(null);
+        }, forceCloseMs);
+        owner.forceCloseTimer.unref?.();
+      }, terminateGraceMs);
+      owner.forceKillTimer.unref?.();
+    };
+
+    const retainOutput = (channel, chunk) => {
+      if (!owner.acceptingOutput || owner.settled) return;
+      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      const nextBytes = owner.retainedOutputBytes + buffer.length;
+      const nextChunks = owner.stdoutChunks.length + owner.stderrChunks.length + 1;
+      if (nextBytes > maxOutputBytes || nextChunks > MAX_CODEX_CLI_OUTPUT_CHUNKS) {
+        failAfterExactChildStops(Object.assign(
+          new Error(`Codex CLI status output exceeded its bounded retention budget.`),
+          {
+            code: 'codex-status-output-limit',
+            maxOutputBytes,
+            observedOutputBytes: nextBytes,
+            maxOutputChunks: MAX_CODEX_CLI_OUTPUT_CHUNKS,
+            observedOutputChunks: nextChunks
+          }
+        ));
+        return;
+      }
+      owner.retainedOutputBytes = nextBytes;
+      if (channel === 'stdout') {
+        owner.stdoutChunks.push(buffer);
+        owner.stdoutBytes += buffer.length;
+      } else {
+        owner.stderrChunks.push(buffer);
+        owner.stderrBytes += buffer.length;
+      }
+    };
+
+    function onStdoutData(chunk) {
+      retainOutput('stdout', chunk);
+    }
+
+    function onStderrData(chunk) {
+      retainOutput('stderr', chunk);
+    }
+
+    function onStdoutError(error) {
+      failAfterExactChildStops(error);
+    }
+
+    function onStderrError(error) {
+      failAfterExactChildStops(error);
+    }
+
+    function onChildError(error) {
+      failAfterExactChildStops(error);
+    }
+
+    function onChildClose(code) {
+      finish(code);
+    }
+
+    child.stdout.on('data', onStdoutData);
+    child.stdout.once('error', onStdoutError);
+    child.stderr.on('data', onStderrData);
+    child.stderr.once('error', onStderrError);
+    child.once('error', onChildError);
+    child.once('close', onChildClose);
+    owner.timeoutTimer = setTimeout(() => {
+      owner.timeoutTimer = null;
+      failAfterExactChildStops(Object.assign(
+        new Error('Codex CLI status check timed out.'),
+        { code: 'codex-status-timeout' }
+      ));
+    }, boundedTimeoutMs);
+    owner.timeoutTimer.unref?.();
+  });
+}
 
 function isTerminalStatus(status) {
   return ['completed', 'failed', 'cancelled'].includes(status);
@@ -507,7 +507,7 @@ function runAgeMs(run) {
 }
 
 function codexAbortError(code, message) {
-  return new AgentRuntimeError(code, message, { status: code === 'codex-run-timeout' ? 504 : 409, retryable: code === 'codex-run-timeout' });
+  return new AgentRuntimeError(code, message, { status: code === 'codex-run-timeout' ? 504 : 409, retryable: code === 'codex-run-timeout' });
 }
 
 function safeAgentDeviceIds(value) {
@@ -528,41 +528,41 @@ export function createCodexAgentRuntime({
   settingsStore,
   dataDir = path.join(os.homedir(), '.livedesk'),
   mcpServerPath,
-  createMcpSession,
-  destroyMcpSession,
-  createCodexClient: injectedCodexClient,
-  getCodexStatus: injectedCodexStatus,
-  onProgress,
-  globalCodexHome = path.join(os.homedir(), '.codex')
-} = {}) {
+  createMcpSession,
+  destroyMcpSession,
+  createCodexClient: injectedCodexClient,
+  getCodexStatus: injectedCodexStatus,
+  onProgress,
+  globalCodexHome = path.join(os.homedir(), '.codex')
+} = {}) {
   const runs = new Map();
   let activeCount = 0;
   let codexModulePromise;
   let securityVerificationState = 'configured';
-  const workspace = path.resolve(dataDir, 'agent-workspace');
-  const codexHome = path.resolve(dataDir, 'codex-home');
-  const resolvedGlobalCodexHome = path.resolve(globalCodexHome);
-  let codexHomePreparation = Promise.resolve();
-
-  function reportProgress(run, stage, message, extra = {}) {
-    run.stage = safeText(stage, 80);
-    run.progressMessage = safeText(message, 500);
-    if (typeof onProgress !== 'function') return;
-    try {
-      onProgress({
-        runId: run.runId,
-        deviceIds: [...run.deviceIds],
-        stage: safeText(stage, 80),
-        message: safeText(message, 500),
-        status: run.status,
-        ...extra
-      });
-    } catch {
-      // Client-side developer progress is best effort and must never affect a
-      // Codex run or its enforced permission boundary.
-    }
-  }
-
+  const workspace = path.resolve(dataDir, 'agent-workspace');
+  const codexHome = path.resolve(dataDir, 'codex-home');
+  const resolvedGlobalCodexHome = path.resolve(globalCodexHome);
+  let codexHomePreparation = Promise.resolve();
+
+  function reportProgress(run, stage, message, extra = {}) {
+    run.stage = safeText(stage, 80);
+    run.progressMessage = safeText(message, 500);
+    if (typeof onProgress !== 'function') return;
+    try {
+      onProgress({
+        runId: run.runId,
+        deviceIds: [...run.deviceIds],
+        stage: safeText(stage, 80),
+        message: safeText(message, 500),
+        status: run.status,
+        ...extra
+      });
+    } catch {
+      // Client-side developer progress is best effort and must never affect a
+      // Codex run or its enforced permission boundary.
+    }
+  }
+
   function securityStatus() {
     const configured = codexHome !== path.resolve(os.homedir(), '.codex')
       && typeof createMcpSession === 'function'
@@ -578,24 +578,24 @@ export function createCodexAgentRuntime({
     };
   }
 
-  async function prepareCodexHome(options = {}) {
-    const operation = codexHomePreparation.then(async () => {
-      try {
-        await ensureCodexHome(codexHome, resolvedGlobalCodexHome, options);
-        securityVerificationState = 'verified';
-      } catch (error) {
-        securityVerificationState = 'unavailable';
-        throw error;
-      }
-    });
-    codexHomePreparation = operation.catch(() => undefined);
-    return operation;
+  async function prepareCodexHome(options = {}) {
+    const operation = codexHomePreparation.then(async () => {
+      try {
+        await ensureCodexHome(codexHome, resolvedGlobalCodexHome, options);
+        securityVerificationState = 'verified';
+      } catch (error) {
+        securityVerificationState = 'unavailable';
+        throw error;
+      }
+    });
+    codexHomePreparation = operation.catch(() => undefined);
+    return operation;
   }
 
   function assertSecurityConfiguration() {
     const status = securityStatus();
     if (!status.isolatedCodexHome || !status.restrictedEnvironment || !status.livedeskMcpOnly || !status.selectedDeviceScopeEnforced) {
-      throw new AgentRuntimeError('codex-unsupported-security-config', 'Codex security isolation is not available.', { status: 503 });
+      throw new AgentRuntimeError('codex-unsupported-security-config', 'Codex security isolation is not available.', { status: 503 });
     }
   }
 
@@ -628,16 +628,16 @@ export function createCodexAgentRuntime({
 
   async function loadCodex() {
     if (!codexModulePromise) codexModulePromise = import('@openai/codex-sdk').catch(error => {
-      const wrapped = new AgentRuntimeError('codex-sdk-not-installed', 'Codex SDK is not installed in this LiveDesk package.', { status: 503 });
+      const wrapped = new AgentRuntimeError('codex-sdk-not-installed', 'Codex SDK is not installed in this LiveDesk package.', { status: 503 });
       wrapped.cause = error;
       throw wrapped;
     });
     return codexModulePromise;
   }
 
-  function cliPath() {
-    return resolveBundledCodexCliPath();
-  }
+  function cliPath() {
+    return resolveBundledCodexCliPath();
+  }
 
   async function getStatus() {
     if (typeof injectedCodexStatus === 'function') return injectedCodexStatus();
@@ -655,7 +655,7 @@ export function createCodexAgentRuntime({
         ? 'signed-in'
         : 'not-signed-in';
     } catch (error) {
-      if (error instanceof AgentRuntimeError) throw error;
+      if (error instanceof AgentRuntimeError) throw error;
       detail = safeText(error?.message, 300);
     }
     return { installed: true, authenticated, status: authenticated === 'signed-in' ? 'ready' : 'auth-required', codexPath: pathToCli, detail };
@@ -665,8 +665,8 @@ export function createCodexAgentRuntime({
     assertSecurityConfiguration();
     const startedAt = Date.now();
     const status = await getStatus();
-    if (!status.installed) throw new AgentRuntimeError('codex-sdk-not-installed', 'Codex SDK is not installed.', { status: 503 });
-    if (status.authenticated !== 'signed-in') throw new AgentRuntimeError('codex-auth-required', 'Sign in with the Codex CLI first.', { status: 401 });
+    if (!status.installed) throw new AgentRuntimeError('codex-sdk-not-installed', 'Codex SDK is not installed.', { status: 503 });
+    if (status.authenticated !== 'signed-in') throw new AgentRuntimeError('codex-auth-required', 'Sign in with the Codex CLI first.', { status: 401 });
     const settings = await settingsStore.get();
     await mkdir(workspace, { recursive: true });
     await prepareCodexHome();
@@ -674,10 +674,10 @@ export function createCodexAgentRuntime({
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), Math.min(30000, settings.codexTaskTimeoutMs));
     try {
-      const thread = codex.startThread(codexThreadOptions(workspace));
-      const turn = await thread.run('Reply with the single word READY. Do not use tools.', { signal: controller.signal });
-      if (!String(turn.finalResponse || '').trim()) throw new AgentRuntimeError('codex-empty-response', 'Codex returned an empty response.', { status: 502 });
-      return { ok: true, latencyMs: Date.now() - startedAt, threadId: thread.id || '' };
+      const thread = codex.startThread(codexThreadOptions(workspace));
+      const turn = await thread.run('Reply with the single word READY. Do not use tools.', { signal: controller.signal });
+      if (!String(turn.finalResponse || '').trim()) throw new AgentRuntimeError('codex-empty-response', 'Codex returned an empty response.', { status: 502 });
+      return { ok: true, latencyMs: Date.now() - startedAt, threadId: thread.id || '' };
     } catch (error) {
       throw normalizeCodexError(error);
     } finally {
@@ -686,18 +686,18 @@ export function createCodexAgentRuntime({
   }
 
   function publicRun(run) {
-    return {
-      runId: run.runId,
-      status: run.status,
-      instruction: run.instruction,
+    return {
+      runId: run.runId,
+      status: run.status,
+      instruction: run.instruction,
       threadId: run.threadId,
-      finalResponse: run.finalResponse,
-      error: run.error,
-      errorMessage: run.errorMessage,
-      errorStage: run.errorStage,
-      stage: run.stage,
-      progressMessage: run.progressMessage,
-      createdAt: run.createdAt,
+      finalResponse: run.finalResponse,
+      error: run.error,
+      errorMessage: run.errorMessage,
+      errorStage: run.errorStage,
+      stage: run.stage,
+      progressMessage: run.progressMessage,
+      createdAt: run.createdAt,
       updatedAt: run.updatedAt,
       toolCallCount: run.toolCallCount,
       permissionMode: run.permissionPolicy?.mode || 'ask',
@@ -728,20 +728,20 @@ export function createCodexAgentRuntime({
       'Never use arbitrary MCP servers, change permissions, forge approvals, request credentials, or invent a tool result.',
       `The Hub has fixed this run to permission mode ${permissionPolicy?.mode || 'ask'} and enforces the policy independently of your instructions.`,
       'Use only the selected connected device IDs below. If the Hub asks for user approval, wait for that approval result and do not work around it.',
-      'You may perform multiple safe read-only checks when the request requires a sequence. For example, find Clients missing a named process, then check a related service only on those Clients.',
+      'You may perform multiple safe read-only checks when the request requires a sequence. For example, find Clients missing a named process, then check a related service only on those Clients.',
       `Selected device IDs: ${JSON.stringify(deviceIds)}`,
       'Return a concise Korean or English summary grounded only in tool results. Do not invent results.',
       `User request: ${safeText(instruction, 4000)}`
     ].join('\n');
   }
 
-  async function execute(run, input) {
-    activeCount += 1;
-    let session;
-    let timeoutTimer;
-    try {
-      reportProgress(run, 'checking-codex', 'Checking Codex SDK installation and sign-in.');
-      assertSecurityConfiguration();
+  async function execute(run, input) {
+    activeCount += 1;
+    let session;
+    let timeoutTimer;
+    try {
+      reportProgress(run, 'checking-codex', 'Checking Codex SDK installation and sign-in.');
+      assertSecurityConfiguration();
       const settings = await settingsStore.get();
       const timeoutMs = Math.max(1000, Number(settings.codexTaskTimeoutMs) || 600000);
       timeoutTimer = setTimeout(() => {
@@ -752,16 +752,16 @@ export function createCodexAgentRuntime({
       timeoutTimer.unref?.();
       await mkdir(workspace, { recursive: true });
       if (activeCount > settings.maxConcurrentRequests) {
-        throw new AgentRuntimeError('agent-concurrency-limit', 'The LiveDesk Agent concurrency limit is reached.', { status: 429, retryable: true });
+        throw new AgentRuntimeError('agent-concurrency-limit', 'The LiveDesk Agent concurrency limit is reached.', { status: 429, retryable: true });
       }
       if (run.abortController.signal.aborted) {
         if (run.abortReason === 'timeout') throw codexAbortError('codex-run-timeout', 'The Codex task exceeded its timeout.');
         throw Object.assign(new Error('The Codex task was cancelled.'), { name: 'AbortError' });
       }
-      const status = await getStatus();
-      if (!status.installed) throw new AgentRuntimeError('codex-sdk-not-installed', 'Codex SDK is not installed.', { status: 503 });
-      if (status.authenticated !== 'signed-in') throw new AgentRuntimeError('codex-auth-required', 'Sign in with the Codex CLI first.', { status: 401 });
-      reportProgress(run, 'preparing-tools', 'Codex is ready. Preparing the LiveDesk tools for this Client.');
+      const status = await getStatus();
+      if (!status.installed) throw new AgentRuntimeError('codex-sdk-not-installed', 'Codex SDK is not installed.', { status: 503 });
+      if (status.authenticated !== 'signed-in') throw new AgentRuntimeError('codex-auth-required', 'Sign in with the Codex CLI first.', { status: 401 });
+      reportProgress(run, 'preparing-tools', 'Codex is ready. Preparing the LiveDesk tools for this Client.');
       session = createMcpSession({
         runId: run.runId,
         signal: run.abortController.signal,
@@ -787,120 +787,120 @@ export function createCodexAgentRuntime({
         if (run.abortReason === 'timeout') throw codexAbortError('codex-run-timeout', 'The Codex task exceeded its timeout.');
         throw Object.assign(new Error('The Codex task was cancelled.'), { name: 'AbortError' });
       }
-      const threadOptions = codexThreadOptions(workspace);
-      run.status = 'running';
-      run.updatedAt = new Date().toISOString();
-      for (let attempt = 0; attempt < 2; attempt += 1) {
-        let turnCompleted = false;
-        try {
-          await prepareCodexHome({ preferGlobalAuth: attempt > 0 && run.authRecoveryRequested === true });
-          reportProgress(run, 'thinking', attempt === 0 ? 'Codex is analyzing the request.' : 'Codex is retrying the request with a refreshed runtime.');
-          const codex = await createCodexClient({ env: safeCodexEnv(codexHome), config: codexConfig({ mcpServerPath, mcpUrl: session.url, token: session.token, workspace }) });
-          const thread = attempt === 0 && input.resumeThreadId && settings.codexResumeSessions
-            ? codex.resumeThread(String(input.resumeThreadId), threadOptions)
-            : codex.startThread(threadOptions);
-          const streamed = await thread.runStreamed(promptFor({ instruction: run.instruction, deviceIds: input.deviceIds, permissionPolicy: run.permissionPolicy }), { signal: run.abortController.signal });
-          for await (const event of streamed.events) {
-            emit(run, event);
-            if (event.type === 'item.started' && event.item?.type === 'mcp_tool_call') {
-              reportProgress(run, 'tool-running', `Running ${safeText(event.item.tool, 120) || 'a LiveDesk tool'}.`, {
-                toolName: safeText(event.item.tool, 120)
-              });
-            }
-            if (event.type === 'turn.started') {
-              run.turnCount += 1;
-              if (run.turnCount > settings.codexMaxTurns) {
-                run.abortReason = 'turn-limit';
-                run.abortController.abort();
-                session.cancel();
-                throw new AgentRuntimeError('codex-turn-limit-reached', 'Codex exceeded the LiveDesk turn limit.', { status: 409 });
-              }
-            }
-            if (run.toolCallCount > run.permissionPolicy.maxToolCalls) {
-              run.abortReason = 'tool-limit';
-              run.abortController.abort();
-              session.cancel();
-              throw new AgentRuntimeError('codex-tool-limit-reached', 'Codex exceeded the LiveDesk tool-call limit.', { status: 409 });
-            }
-            if (event.type === 'item.completed' && event.item?.type === 'mcp_tool_call' && event.item?.status === 'failed') {
-              throw new Error(safeText(event.item?.error?.message, 800) || `LiveDesk tool ${safeText(event.item?.tool, 120) || 'call'} failed.`);
-            }
-            if (event.type === 'item.completed' && event.item?.type === 'agent_message') run.finalResponse = safeText(event.item.text, 4000);
-            if (event.type === 'turn.completed') turnCompleted = true;
-            if (event.type === 'turn.failed') throw new Error(safeText(event.error?.message, 800) || 'Codex run failed.');
-            if (event.type === 'error') throw new Error(safeText(event.message, 800) || 'Codex run failed.');
-          }
-          if (!turnCompleted) {
-            throw new AgentRuntimeError(
-              'codex-incomplete-turn',
-              'Codex ended without a completed turn.',
-              { status: 502 }
-            );
-          }
-          if (!safeText(run.finalResponse, 4000)) {
-            throw new AgentRuntimeError(
-              'codex-empty-response',
-              'Codex completed without a final response.',
-              { status: 502 }
-            );
-          }
-          // Terminal state is externally observable. Publish it only after the
-          // complete event stream has drained and its final response is owned.
-          run.status = 'completed';
-          break;
-        } catch (error) {
-          const normalized = normalizeCodexError(error);
-          const retryBeforeTools = attempt === 0
-            && run.toolCallCount === 0
-            && run.abortController.signal.aborted !== true
-            && normalized.retryable === true;
-          if (!retryBeforeTools) throw normalized;
-          run.authRecoveryRequested = ['codex-auth-stale', 'codex-auth-required'].includes(normalized.code);
-          run.finalResponse = '';
-          run.status = 'running';
-          reportProgress(
-            run,
-            'recovering',
-            `Codex did not start cleanly (${normalized.code}). Refreshing the runtime and retrying once.`,
-            { errorCode: normalized.code, errorMessage: safeText(normalized.message, 500), attempt: 2 }
-          );
-          await new Promise(resolve => setTimeout(resolve, 250));
-        }
-      }
-      if (run.status !== 'completed') {
-        throw new AgentRuntimeError(
-          'codex-incomplete-turn',
-          'Codex did not reach a completed terminal state.',
-          { status: 502 }
-        );
-      }
+      const threadOptions = codexThreadOptions(workspace);
+      run.status = 'running';
+      run.updatedAt = new Date().toISOString();
+      for (let attempt = 0; attempt < 2; attempt += 1) {
+        let turnCompleted = false;
+        try {
+          await prepareCodexHome({ preferGlobalAuth: attempt > 0 && run.authRecoveryRequested === true });
+          reportProgress(run, 'thinking', attempt === 0 ? 'Codex is analyzing the request.' : 'Codex is retrying the request with a refreshed runtime.');
+          const codex = await createCodexClient({ env: safeCodexEnv(codexHome), config: codexConfig({ mcpServerPath, mcpUrl: session.url, token: session.token, workspace }) });
+          const thread = attempt === 0 && input.resumeThreadId && settings.codexResumeSessions
+            ? codex.resumeThread(String(input.resumeThreadId), threadOptions)
+            : codex.startThread(threadOptions);
+          const streamed = await thread.runStreamed(promptFor({ instruction: run.instruction, deviceIds: input.deviceIds, permissionPolicy: run.permissionPolicy }), { signal: run.abortController.signal });
+          for await (const event of streamed.events) {
+            emit(run, event);
+            if (event.type === 'item.started' && event.item?.type === 'mcp_tool_call') {
+              reportProgress(run, 'tool-running', `Running ${safeText(event.item.tool, 120) || 'a LiveDesk tool'}.`, {
+                toolName: safeText(event.item.tool, 120)
+              });
+            }
+            if (event.type === 'turn.started') {
+              run.turnCount += 1;
+              if (run.turnCount > settings.codexMaxTurns) {
+                run.abortReason = 'turn-limit';
+                run.abortController.abort();
+                session.cancel();
+                throw new AgentRuntimeError('codex-turn-limit-reached', 'Codex exceeded the LiveDesk turn limit.', { status: 409 });
+              }
+            }
+            if (run.toolCallCount > run.permissionPolicy.maxToolCalls) {
+              run.abortReason = 'tool-limit';
+              run.abortController.abort();
+              session.cancel();
+              throw new AgentRuntimeError('codex-tool-limit-reached', 'Codex exceeded the LiveDesk tool-call limit.', { status: 409 });
+            }
+            if (event.type === 'item.completed' && event.item?.type === 'mcp_tool_call' && event.item?.status === 'failed') {
+              throw new Error(safeText(event.item?.error?.message, 800) || `LiveDesk tool ${safeText(event.item?.tool, 120) || 'call'} failed.`);
+            }
+            if (event.type === 'item.completed' && event.item?.type === 'agent_message') run.finalResponse = safeText(event.item.text, 4000);
+            if (event.type === 'turn.completed') turnCompleted = true;
+            if (event.type === 'turn.failed') throw new Error(safeText(event.error?.message, 800) || 'Codex run failed.');
+            if (event.type === 'error') throw new Error(safeText(event.message, 800) || 'Codex run failed.');
+          }
+          if (!turnCompleted) {
+            throw new AgentRuntimeError(
+              'codex-incomplete-turn',
+              'Codex ended without a completed turn.',
+              { status: 502 }
+            );
+          }
+          if (!safeText(run.finalResponse, 4000)) {
+            throw new AgentRuntimeError(
+              'codex-empty-response',
+              'Codex completed without a final response.',
+              { status: 502 }
+            );
+          }
+          // Terminal state is externally observable. Publish it only after the
+          // complete event stream has drained and its final response is owned.
+          run.status = 'completed';
+          break;
+        } catch (error) {
+          const normalized = normalizeCodexError(error);
+          const retryBeforeTools = attempt === 0
+            && run.toolCallCount === 0
+            && run.abortController.signal.aborted !== true
+            && normalized.retryable === true;
+          if (!retryBeforeTools) throw normalized;
+          run.authRecoveryRequested = ['codex-auth-stale', 'codex-auth-required'].includes(normalized.code);
+          run.finalResponse = '';
+          run.status = 'running';
+          reportProgress(
+            run,
+            'recovering',
+            `Codex did not start cleanly (${normalized.code}). Refreshing the runtime and retrying once.`,
+            { errorCode: normalized.code, errorMessage: safeText(normalized.message, 500), attempt: 2 }
+          );
+          await new Promise(resolve => setTimeout(resolve, 250));
+        }
+      }
+      if (run.status !== 'completed') {
+        throw new AgentRuntimeError(
+          'codex-incomplete-turn',
+          'Codex did not reach a completed terminal state.',
+          { status: 502 }
+        );
+      }
     } catch (error) {
-      if (run.abortReason === 'timeout') {
-        run.status = 'failed';
-        run.error = 'codex-run-timeout';
-        run.errorMessage = 'The Codex task exceeded its timeout.';
-        run.errorStage = run.stage || 'unknown';
-      } else if (run.abortReason === 'tool-limit') {
-        run.status = 'failed';
-        run.error = 'codex-tool-limit-reached';
-        run.errorMessage = 'Codex exceeded the LiveDesk tool-call limit.';
-        run.errorStage = run.stage || 'unknown';
-      } else if (run.abortReason === 'turn-limit') {
-        run.status = 'failed';
-        run.error = 'codex-turn-limit-reached';
-        run.errorMessage = 'Codex exceeded the LiveDesk turn limit.';
-        run.errorStage = run.stage || 'unknown';
-      } else if (isAbortError(error) || run.abortController.signal.aborted) {
-        run.status = 'cancelled';
-        run.error = 'cancelled-by-user';
-        run.errorMessage = 'The Codex request was cancelled.';
-        run.errorStage = run.stage || 'unknown';
+      if (run.abortReason === 'timeout') {
+        run.status = 'failed';
+        run.error = 'codex-run-timeout';
+        run.errorMessage = 'The Codex task exceeded its timeout.';
+        run.errorStage = run.stage || 'unknown';
+      } else if (run.abortReason === 'tool-limit') {
+        run.status = 'failed';
+        run.error = 'codex-tool-limit-reached';
+        run.errorMessage = 'Codex exceeded the LiveDesk tool-call limit.';
+        run.errorStage = run.stage || 'unknown';
+      } else if (run.abortReason === 'turn-limit') {
+        run.status = 'failed';
+        run.error = 'codex-turn-limit-reached';
+        run.errorMessage = 'Codex exceeded the LiveDesk turn limit.';
+        run.errorStage = run.stage || 'unknown';
+      } else if (isAbortError(error) || run.abortController.signal.aborted) {
+        run.status = 'cancelled';
+        run.error = 'cancelled-by-user';
+        run.errorMessage = 'The Codex request was cancelled.';
+        run.errorStage = run.stage || 'unknown';
       } else {
-        const normalized = normalizeCodexError(error);
-        run.status = 'failed';
-        run.error = safeText(normalized.code, 240) || 'codex-run-failed';
-        run.errorMessage = safeText(normalized.message, 800) || 'Codex run failed.';
-        run.errorStage = run.stage || 'unknown';
+        const normalized = normalizeCodexError(error);
+        run.status = 'failed';
+        run.error = safeText(normalized.code, 240) || 'codex-run-failed';
+        run.errorMessage = safeText(normalized.message, 800) || 'Codex run failed.';
+        run.errorStage = run.stage || 'unknown';
       }
     } finally {
       activeCount = Math.max(0, activeCount - 1);
@@ -908,44 +908,44 @@ export function createCodexAgentRuntime({
         try { session.cancel(); } catch { /* best effort */ }
         destroyMcpSession(session.token);
       }
-      clearTimeout(timeoutTimer);
-      run.updatedAt = new Date().toISOString();
-      reportProgress(
-        run,
-        run.status,
-        run.status === 'completed'
-          ? 'Codex completed the request.'
-          : run.status === 'cancelled'
-            ? 'The Codex request was cancelled.'
-            : `Codex stopped (${run.error || 'codex-run-failed'}): ${run.errorMessage || 'Codex run failed.'}`
-      );
-      if (isTerminalStatus(run.status)) scheduleRunCleanup(run);
+      clearTimeout(timeoutTimer);
+      run.updatedAt = new Date().toISOString();
+      reportProgress(
+        run,
+        run.status,
+        run.status === 'completed'
+          ? 'Codex completed the request.'
+          : run.status === 'cancelled'
+            ? 'The Codex request was cancelled.'
+            : `Codex stopped (${run.error || 'codex-run-failed'}): ${run.errorMessage || 'Codex run failed.'}`
+      );
+      if (isTerminalStatus(run.status)) scheduleRunCleanup(run);
     }
   }
 
   async function start(input = {}) {
     const instruction = safeText(input.instruction, 4000);
-    if (!instruction) throw new AgentRuntimeError('agent-invalid-instruction', 'Instruction is required.', { status: 400 });
+    if (!instruction) throw new AgentRuntimeError('agent-invalid-instruction', 'Instruction is required.', { status: 400 });
     const deviceIds = safeAgentDeviceIds(input.deviceIds);
-    if (deviceIds.length === 0) throw new AgentRuntimeError('agent-no-target-devices', 'Select at least one connected device.', { status: 400 });
+    if (deviceIds.length === 0) throw new AgentRuntimeError('agent-no-target-devices', 'Select at least one connected device.', { status: 400 });
     const settings = await settingsStore.get();
-    if (!settings.enabled) throw new AgentRuntimeError('agent-disabled', 'Codex Agent is disabled in Settings.', { status: 409 });
+    if (!settings.enabled) throw new AgentRuntimeError('agent-disabled', 'Codex Agent is disabled in Settings.', { status: 409 });
     assertSecurityConfiguration();
     pruneRuns();
-    if (runs.size >= MAX_RUNS) throw new AgentRuntimeError('agent-run-limit', 'The LiveDesk Agent run history is full.', { status: 429, retryable: true });
+    if (runs.size >= MAX_RUNS) throw new AgentRuntimeError('agent-run-limit', 'The LiveDesk Agent run history is full.', { status: 429, retryable: true });
     const permissionPolicy = freezeAgentPermissionPolicy(input.permissionPolicy && typeof input.permissionPolicy === 'object'
       ? input.permissionPolicy
       : createAgentPermissionPolicy({ mode: input.permissionMode || 'safe-auto', deviceIds, maxToolCalls: settings.codexMaxToolCalls }));
-    const run = {
-      runId: crypto.randomUUID(),
-      status: 'queued',
-      instruction,
-      deviceIds,
-      threadId: '',
-      finalResponse: '',
-      error: '',
-      errorMessage: '',
-      errorStage: '',
+    const run = {
+      runId: crypto.randomUUID(),
+      status: 'queued',
+      instruction,
+      deviceIds,
+      threadId: '',
+      finalResponse: '',
+      error: '',
+      errorMessage: '',
+      errorStage: '',
       createdAt: new Date().toISOString(),
       updatedAt: new Date().toISOString(),
       toolCallCount: 0,
@@ -955,15 +955,15 @@ export function createCodexAgentRuntime({
       batchIds: new Set(),
       events: [],
       abortController: new AbortController(),
-      abortReason: '',
-      authRecoveryRequested: false,
-      stage: 'queued',
-      progressMessage: '',
-      mcpToken: ''
-    };
-    runs.set(run.runId, run);
-    reportProgress(run, 'queued', 'Codex request queued on the Hub.');
-    void execute(run, { deviceIds, resumeThreadId: input.resumeThreadId });
+      abortReason: '',
+      authRecoveryRequested: false,
+      stage: 'queued',
+      progressMessage: '',
+      mcpToken: ''
+    };
+    runs.set(run.runId, run);
+    reportProgress(run, 'queued', 'Codex request queued on the Hub.');
+    void execute(run, { deviceIds, resumeThreadId: input.resumeThreadId });
     return publicRun(run);
   }