@love-moon/conductor-cli 0.2.17 → 0.2.19

package/src/daemon.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
+import { createRequire } from "node:module";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
@@ -9,11 +10,13 @@ import yaml from "js-yaml";
 
 import { ConductorWebSocketClient, ConductorConfig, loadConfig, ConfigFileNotFound } from "@love-moon/conductor-sdk";
 import { DaemonLogCollector } from "./log-collector.js";
+import { filterRuntimeSupportedAllowCliList, normalizeRuntimeBackendName } from "./runtime-backends.js";
 
 dotenv.config();
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
+const moduleRequire = createRequire(import.meta.url);
 const CLI_PATH = path.resolve(__dirname, "..", "bin", "conductor-fire.js");
 const DAEMON_LOG_DIR = path.join(os.homedir(), ".conductor", "logs");
 const DAEMON_LOG_PATH = path.join(DAEMON_LOG_DIR, "conductor-daemon.log");
@@ -22,6 +25,10 @@ const PLAN_LIMIT_MESSAGES = {
   app_active_task: "Free plan limit reached: only 1 active app task is allowed.",
   daemon_active_connection: "Free plan limit reached: only 1 active daemon connection is allowed.",
 };
+const DEFAULT_TERMINAL_COLS = 120;
+const DEFAULT_TERMINAL_ROWS = 40;
+const DEFAULT_TERMINAL_RING_BUFFER_MAX_BYTES = 2 * 1024 * 1024;
+let nodePtySpawnPromise = null;
 
 function appendDaemonLog(line) {
   try {
@@ -112,16 +119,118 @@ function getPlanLimitMessage(payload) {
 const DEFAULT_CLI_LIST = {
   codex: "codex --dangerously-bypass-approvals-and-sandbox",
   claude: "claude --dangerously-skip-permissions",
+  opencode: "opencode",
 };
 
 function getAllowCliList(userConfig) {
   // If user has configured allow_cli_list, use it; otherwise use defaults
   if (userConfig.allow_cli_list && typeof userConfig.allow_cli_list === "object") {
-    return userConfig.allow_cli_list;
+    return filterRuntimeSupportedAllowCliList(userConfig.allow_cli_list);
   }
   return DEFAULT_CLI_LIST;
 }
 
+async function defaultCreatePty(command, args, options) {
+  if (!nodePtySpawnPromise) {
+    const spawnHelperInfo = ensureNodePtySpawnHelperExecutable();
+    if (spawnHelperInfo?.updated) {
+      log(`Enabled execute permission on node-pty spawn-helper: ${spawnHelperInfo.helperPath}`);
+    }
+    nodePtySpawnPromise = import("node-pty").then((mod) => {
+      if (typeof mod.spawn === "function") {
+        return mod.spawn;
+      }
+      if (mod.default && typeof mod.default.spawn === "function") {
+        return mod.default.spawn.bind(mod.default);
+      }
+      throw new Error("node-pty spawn export not found");
+    });
+  }
+  const spawnPty = await nodePtySpawnPromise;
+  return spawnPty(command, args, options);
+}
+
+export function ensureNodePtySpawnHelperExecutable(deps = {}) {
+  const platform = deps.platform || process.platform;
+  if (platform === "win32") {
+    return null;
+  }
+
+  const arch = deps.arch || process.arch;
+  const existsSyncFn = deps.existsSync || fs.existsSync;
+  const statSyncFn = deps.statSync || fs.statSync;
+  const chmodSyncFn = deps.chmodSync || fs.chmodSync;
+  let packageJsonPath = deps.packageJsonPath || null;
+
+  if (!packageJsonPath) {
+    try {
+      packageJsonPath = moduleRequire.resolve("node-pty/package.json");
+    } catch {
+      return null;
+    }
+  }
+
+  const packageDir = path.dirname(packageJsonPath);
+  const helperCandidates = [
+    path.join(packageDir, "build", "Release", "spawn-helper"),
+    path.join(packageDir, "build", "Debug", "spawn-helper"),
+    path.join(packageDir, "prebuilds", `${platform}-${arch}`, "spawn-helper"),
+  ];
+  const helperPath = helperCandidates.find((candidate) => existsSyncFn(candidate));
+  if (!helperPath) {
+    return null;
+  }
+
+  const currentMode = statSyncFn(helperPath).mode & 0o777;
+  if ((currentMode & 0o111) !== 0) {
+    return { helperPath, updated: false };
+  }
+
+  const nextMode = currentMode | 0o111;
+  chmodSyncFn(helperPath, nextMode);
+  return { helperPath, updated: true };
+}
+
+function normalizeOptionalString(value) {
+  if (typeof value !== "string") {
+    return null;
+  }
+  const normalized = value.trim();
+  return normalized || null;
+}
+
+function normalizePositiveInt(value, fallback) {
+  const parsed = Number.parseInt(String(value ?? ""), 10);
+  if (Number.isFinite(parsed) && parsed > 0) {
+    return parsed;
+  }
+  return fallback;
+}
+
+function normalizeLaunchConfig(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return {};
+  }
+  return value;
+}
+
+function normalizeTerminalEnv(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return {};
+  }
+  const env = {};
+  for (const [key, raw] of Object.entries(value)) {
+    if (typeof raw === "string") {
+      env[key] = raw;
+      continue;
+    }
+    if (typeof raw === "number" || typeof raw === "boolean") {
+      env[key] = String(raw);
+    }
+  }
+  return env;
+}
+
 export function startDaemon(config = {}, deps = {}) {
   const exitFn = deps.exit || process.exit;
   const killFn = deps.kill || process.kill;
@@ -230,6 +339,34 @@ export function startDaemon(config = {}, deps = {}) {
     process.env.CONDUCTOR_SHUTDOWN_DISCONNECT_TIMEOUT_MS,
     1000,
   );
+  const DAEMON_WATCHDOG_INTERVAL_MS = parsePositiveInt(
+    process.env.CONDUCTOR_DAEMON_WATCHDOG_INTERVAL_MS,
+    30_000,
+  );
+  const DAEMON_WATCHDOG_STALE_WS_MS = parsePositiveInt(
+    process.env.CONDUCTOR_DAEMON_WATCHDOG_STALE_WS_MS,
+    75_000,
+  );
+  const DAEMON_WATCHDOG_CONNECT_GRACE_MS = parsePositiveInt(
+    process.env.CONDUCTOR_DAEMON_WATCHDOG_CONNECT_GRACE_MS,
+    35_000,
+  );
+  const DAEMON_WATCHDOG_RECONNECT_COOLDOWN_MS = parsePositiveInt(
+    process.env.CONDUCTOR_DAEMON_WATCHDOG_RECONNECT_COOLDOWN_MS,
+    45_000,
+  );
+  const DAEMON_WATCHDOG_HTTP_TIMEOUT_MS = parsePositiveInt(
+    process.env.CONDUCTOR_DAEMON_WATCHDOG_HTTP_TIMEOUT_MS,
+    5_000,
+  );
+  const DAEMON_WATCHDOG_MAX_SELF_HEALS = parsePositiveInt(
+    process.env.CONDUCTOR_DAEMON_WATCHDOG_MAX_SELF_HEALS,
+    3,
+  );
+  const TERMINAL_RING_BUFFER_MAX_BYTES = parsePositiveInt(
+    config.TERMINAL_RING_BUFFER_MAX_BYTES || process.env.CONDUCTOR_TERMINAL_RING_BUFFER_MAX_BYTES,
+    DEFAULT_TERMINAL_RING_BUFFER_MAX_BYTES,
+  );
 
   try {
     mkdirSyncFn(WORKSPACE_ROOT, { recursive: true });
@@ -363,19 +500,45 @@ export function startDaemon(config = {}, deps = {}) {
 
   let disconnectedSinceLastConnectedLog = false;
   let didRecoverStaleTasks = false;
+  let daemonShuttingDown = false;
   const activeTaskProcesses = new Map();
+  const activePtySessions = new Map();
   const suppressedExitStatusReports = new Set();
   const seenCommandRequestIds = new Set();
+  let lastConnectedAt = null;
+  let lastPongAt = null;
+  let lastInboundAt = null;
+  let lastSuccessfulHttpAt = null;
+  let lastPresenceCheckAt = null;
+  let lastPresenceConfirmedAt = null;
+  let wsConnected = false;
+  let watchdogLastHealAt = 0;
+  let watchdogHealAttempts = 0;
+  let watchdogProbeInFlight = false;
+  let watchdogLastProbeErrorAt = 0;
+  let watchdogLastPresenceMismatchAt = 0;
+  let watchdogAwaitingHealthySignalAt = null;
+  let watchdogTimer = null;
   const logCollector = createLogCollector(BACKEND_HTTP);
+  const createPtyFn = deps.createPty || defaultCreatePty;
   const client = createWebSocketClient(sdkConfig, {
     extraHeaders: {
       "x-conductor-host": AGENT_NAME,
       "x-conductor-backends": SUPPORTED_BACKENDS.join(","),
+      "x-conductor-capabilities": "pty_task",
     },
-    onConnected: ({ isReconnect } = { isReconnect: false }) => {
+    onConnected: ({ isReconnect, connectedAt } = { isReconnect: false, connectedAt: Date.now() }) => {
+      wsConnected = true;
+      lastConnectedAt = connectedAt || Date.now();
+      lastPongAt = lastPongAt && lastPongAt > lastConnectedAt ? lastPongAt : lastConnectedAt;
       if (!isReconnect || disconnectedSinceLastConnectedLog) {
         log("Connected to backend");
       }
+      if (watchdogHealAttempts > 0) {
+        watchdogAwaitingHealthySignalAt = lastConnectedAt;
+      } else {
+        watchdogAwaitingHealthySignalAt = null;
+      }
       disconnectedSinceLastConnectedLog = false;
       sendAgentResume(isReconnect).catch((error) => {
         logError(`sendAgentResume failed: ${error?.message || error}`);
@@ -391,8 +554,24 @@ export function startDaemon(config = {}, deps = {}) {
         });
       }
     },
-    onDisconnected: () => {
+    onDisconnected: (event = {}) => {
+      wsConnected = false;
       disconnectedSinceLastConnectedLog = true;
+      if (!daemonShuttingDown) {
+        logError(
+          `[daemon-ws] Disconnected from backend: ${formatDisconnectDiagnostics(event)} (${formatDaemonHealthState({
+            connectedAt: lastConnectedAt,
+            lastPongAt,
+            lastInboundAt,
+            lastSuccessfulHttpAt,
+            lastPresenceConfirmedAt,
+          })})`,
+        );
+      }
+    },
+    onPong: ({ at }) => {
+      lastPongAt = at;
+      markWatchdogHealthy("pong", at);
     },
   });
 
@@ -404,6 +583,169 @@ export function startDaemon(config = {}, deps = {}) {
     logError(`Failed to connect: ${err}`);
   });
 
+  watchdogTimer = setInterval(() => {
+    void runDaemonWatchdog();
+  }, DAEMON_WATCHDOG_INTERVAL_MS);
+  if (typeof watchdogTimer?.unref === "function") {
+    watchdogTimer.unref();
+  }
+
+  function markBackendHttpSuccess(at = Date.now()) {
+    lastSuccessfulHttpAt = at;
+  }
+
+  async function probeAgentPresence() {
+    lastPresenceCheckAt = Date.now();
+    try {
+      const response = await withTimeout(
+        fetchFn(`${BACKEND_HTTP}/api/agents`, {
+          method: "GET",
+          headers: {
+            Authorization: `Bearer ${AGENT_TOKEN}`,
+            Accept: "application/json",
+          },
+        }),
+        DAEMON_WATCHDOG_HTTP_TIMEOUT_MS,
+        "daemon agent presence probe",
+      );
+      if (!response.ok) {
+        return {
+          ok: false,
+          status: response.status,
+          error: `HTTP ${response.status}`,
+        };
+      }
+      const at = Date.now();
+      markBackendHttpSuccess(at);
+      const payload = await response.json();
+      const agents = Array.isArray(payload) ? payload : [];
+      const selfOnline = agents.some((entry) => String(entry?.host || "").trim() === AGENT_NAME);
+      if (selfOnline) {
+        lastPresenceConfirmedAt = at;
+      }
+      return {
+        ok: true,
+        selfOnline,
+        agentCount: agents.length,
+      };
+    } catch (error) {
+      return {
+        ok: false,
+        status: null,
+        error: error?.message || String(error),
+      };
+    }
+  }
+
+  function requestWatchdogSelfHeal(reason, extra = {}) {
+    if (daemonShuttingDown || !wsConnected) {
+      return;
+    }
+    const now = Date.now();
+    if (watchdogLastHealAt && now - watchdogLastHealAt < DAEMON_WATCHDOG_RECONNECT_COOLDOWN_MS) {
+      return;
+    }
+    watchdogLastHealAt = now;
+    watchdogHealAttempts += 1;
+    logError(
+      `[watchdog] ${reason}; restarting daemon websocket (${watchdogHealAttempts}/${DAEMON_WATCHDOG_MAX_SELF_HEALS}) ${formatWatchdogExtra(extra)} (${formatDaemonHealthState({
+        connectedAt: lastConnectedAt,
+        lastPongAt,
+        lastInboundAt,
+        lastSuccessfulHttpAt,
+        lastPresenceConfirmedAt,
+      })})`,
+    );
+    if (watchdogHealAttempts > DAEMON_WATCHDOG_MAX_SELF_HEALS) {
+      daemonShuttingDown = true;
+      logError("[watchdog] Self-heal budget exceeded; exiting daemon for supervisor restart");
+      void requestShutdown("watchdog self-heal budget exceeded")
+        .catch((error) => {
+          logError(`watchdog shutdown failed: ${error?.message || error}`);
+        })
+        .finally(() => {
+          cleanupLock();
+          exitFn(1);
+        });
+      return;
+    }
+    watchdogAwaitingHealthySignalAt = null;
+    wsConnected = false;
+    disconnectedSinceLastConnectedLog = true;
+    if (typeof client.forceReconnect === "function") {
+      Promise.resolve(client.forceReconnect(`watchdog:${reason}`)).catch((error) => {
+        logError(`watchdog forceReconnect failed: ${error?.message || error}`);
+      });
+      return;
+    }
+    Promise.resolve(client.disconnect())
+      .catch((error) => {
+        logError(`watchdog disconnect failed: ${error?.message || error}`);
+      })
+      .finally(() => {
+        client.connect().catch((error) => {
+          logError(`watchdog reconnect failed: ${error?.message || error}`);
+        });
+      });
+  }
+
+  async function runDaemonWatchdog() {
+    if (daemonShuttingDown || !wsConnected || watchdogProbeInFlight) {
+      return;
+    }
+    const startedAt = Date.now();
+    if (!lastConnectedAt || startedAt - lastConnectedAt < DAEMON_WATCHDOG_CONNECT_GRACE_MS) {
+      return;
+    }
+    watchdogProbeInFlight = true;
+    try {
+      const probe = await probeAgentPresence();
+      const now = Date.now();
+      const lastWsHealthAt = Math.max(lastPongAt || 0, lastInboundAt || 0, lastConnectedAt || 0);
+      const staleWs = !lastWsHealthAt || now - lastWsHealthAt > DAEMON_WATCHDOG_STALE_WS_MS;
+
+      if (!probe.ok) {
+        if (now - watchdogLastProbeErrorAt >= DAEMON_WATCHDOG_RECONNECT_COOLDOWN_MS) {
+          watchdogLastProbeErrorAt = now;
+          logError(`[watchdog] agent presence probe failed: ${probe.error}`);
+        }
+        if (staleWs) {
+          requestWatchdogSelfHeal("stale_ws_health", {
+            probeAt: lastPresenceCheckAt,
+            probeStatus: probe.status,
+            probeError: probe.error,
+            lastWsHealthAt,
+            staleForMs: now - lastWsHealthAt,
+          });
+        }
+        return;
+      }
+
+      if (!probe.selfOnline && now - watchdogLastPresenceMismatchAt >= DAEMON_WATCHDOG_RECONNECT_COOLDOWN_MS) {
+        watchdogLastPresenceMismatchAt = now;
+        logError(`[watchdog] agent presence probe did not include current host; skipping self-heal to avoid false positives on non-sticky HTTP/WS deployments (${formatWatchdogExtra({
+          agentCount: probe.agentCount,
+          probeAt: lastPresenceCheckAt,
+        })})`);
+      }
+
+      if (staleWs) {
+        requestWatchdogSelfHeal("stale_ws_health", {
+          agentCount: probe.agentCount,
+          lastWsHealthAt,
+          staleForMs: now - lastWsHealthAt,
+          probeAt: lastPresenceCheckAt,
+        });
+      }
+    } finally {
+      watchdogProbeInFlight = false;
+    }
+  }
+
+  const getActiveTaskIds = () => [
+    ...new Set([...activeTaskProcesses.keys(), ...activePtySessions.keys()]),
+  ];
+
   async function recoverStaleTasks() {
     try {
       const response = await fetchFn(`${BACKEND_HTTP}/api/tasks`, {
@@ -417,6 +759,7 @@ export function startDaemon(config = {}, deps = {}) {
         logError(`Failed to recover stale tasks: HTTP ${response.status}`);
         return;
       }
+      markBackendHttpSuccess();
 
       const tasks = await response.json();
       if (!Array.isArray(tasks) || tasks.length === 0) {
@@ -448,6 +791,8 @@ export function startDaemon(config = {}, deps = {}) {
           });
           if (!patchResp.ok) {
             logError(`Failed to mark stale task ${taskId} as killed: HTTP ${patchResp.status}`);
+          } else {
+            markBackendHttpSuccess();
           }
         }),
       );
@@ -471,11 +816,12 @@ export function startDaemon(config = {}, deps = {}) {
         logError(`Failed to reconcile tasks: HTTP ${response.status}`);
         return;
       }
+      markBackendHttpSuccess();
       const tasks = await response.json();
       if (!Array.isArray(tasks)) {
         return;
       }
-      const localTaskIds = new Set(activeTaskProcesses.keys());
+      const localTaskIds = new Set(getActiveTaskIds());
       const assigned = tasks.filter((task) => {
         const agentHost = String(task?.agent_host || "").trim();
         const status = String(task?.status || "").trim().toLowerCase();
@@ -500,6 +846,7 @@ export function startDaemon(config = {}, deps = {}) {
         });
         if (patchResp.ok) {
           killedCount += 1;
+          markBackendHttpSuccess();
         } else {
           logError(`Failed to reconcile stale task ${taskId}: HTTP ${patchResp.status}`);
         }
@@ -519,7 +866,7 @@ export function startDaemon(config = {}, deps = {}) {
     await client.sendJson({
       type: "agent_resume",
       payload: {
-        active_tasks: [...activeTaskProcesses.keys()],
+        active_tasks: getActiveTaskIds(),
         source: "conductor-daemon",
         metadata: { is_reconnect: Boolean(isReconnect) },
       },
@@ -554,7 +901,446 @@ export function startDaemon(config = {}, deps = {}) {
     });
   }
 
+  function sendTerminalEvent(type, payload) {
+    return client.sendJson({
+      type,
+      payload,
+    });
+  }
+
+  function resolvePtyLaunchSpec(launchConfig, fallbackCwd) {
+    const normalizedLaunchConfig = normalizeLaunchConfig(launchConfig);
+    const entrypointType =
+      normalizeOptionalString(normalizedLaunchConfig.entrypoint_type) ||
+      normalizeOptionalString(normalizedLaunchConfig.entrypointType) ||
+      (normalizeOptionalString(normalizedLaunchConfig.tool_preset) ||
+      normalizeOptionalString(normalizedLaunchConfig.toolPreset)
+        ? "tool_preset"
+        : "shell");
+    const preferredShell =
+      normalizeOptionalString(normalizedLaunchConfig.shell) ||
+      process.env.SHELL ||
+      "/bin/zsh";
+    const cwd =
+      normalizeOptionalString(normalizedLaunchConfig.cwd) ||
+      fallbackCwd;
+    const env = normalizeTerminalEnv(normalizedLaunchConfig.env);
+    const cols = normalizePositiveInt(
+      normalizedLaunchConfig.cols ?? normalizedLaunchConfig.columns,
+      DEFAULT_TERMINAL_COLS,
+    );
+    const rows = normalizePositiveInt(
+      normalizedLaunchConfig.rows,
+      DEFAULT_TERMINAL_ROWS,
+    );
+
+    if (entrypointType === "tool_preset") {
+      const toolPreset =
+        normalizeOptionalString(normalizedLaunchConfig.tool_preset) ||
+        normalizeOptionalString(normalizedLaunchConfig.toolPreset) ||
+        SUPPORTED_BACKENDS[0] ||
+        "codex";
+      const cliCommand = ALLOW_CLI_LIST[toolPreset];
+      if (!cliCommand) {
+        throw new Error(`Unsupported tool preset: ${toolPreset}`);
+      }
+      return {
+        entrypointType,
+        toolPreset,
+        command: preferredShell,
+        args: ["-lc", cliCommand],
+        shell: preferredShell,
+        cwd,
+        env,
+        cols,
+        rows,
+      };
+    }
+
+    if (entrypointType === "custom") {
+      const command = normalizeOptionalString(normalizedLaunchConfig.command);
+      if (!command) {
+        throw new Error("launch_config.command is required for custom entrypoint");
+      }
+      const args = Array.isArray(normalizedLaunchConfig.args)
+        ? normalizedLaunchConfig.args.filter((value) => typeof value === "string")
+        : [];
+      return {
+        entrypointType,
+        toolPreset: null,
+        command,
+        args,
+        shell: preferredShell,
+        cwd,
+        env,
+        cols,
+        rows,
+      };
+    }
+
+    return {
+      entrypointType: "shell",
+      toolPreset: null,
+      command: preferredShell,
+      args: ["-l"],
+      shell: preferredShell,
+      cwd,
+      env,
+      cols,
+      rows,
+    };
+  }
+
+  function getTerminalChunkByteLength(data) {
+    return Buffer.byteLength(data, "utf8");
+  }
+
+  function trimTerminalChunkToTailBytes(data, maxBytes) {
+    const encoded = Buffer.from(data, "utf8");
+    if (encoded.length <= maxBytes) {
+      return data;
+    }
+    const tail = encoded.subarray(encoded.length - maxBytes);
+    let start = 0;
+    while (start < tail.length && (tail[start] & 0b1100_0000) === 0b1000_0000) {
+      start += 1;
+    }
+    return tail.subarray(start).toString("utf8");
+  }
+
+  function bufferTerminalOutput(record, data) {
+    record.outputSeq += 1;
+    let bufferedData = typeof data === "string" ? data : String(data ?? "");
+    let byteLength = getTerminalChunkByteLength(bufferedData);
+    if (byteLength > TERMINAL_RING_BUFFER_MAX_BYTES) {
+      bufferedData = trimTerminalChunkToTailBytes(bufferedData, TERMINAL_RING_BUFFER_MAX_BYTES);
+      byteLength = getTerminalChunkByteLength(bufferedData);
+    }
+    record.ringBuffer.push({ seq: record.outputSeq, data: bufferedData, byteLength });
+    record.ringBufferByteLength += byteLength;
+    while (record.ringBufferByteLength > TERMINAL_RING_BUFFER_MAX_BYTES && record.ringBuffer.length > 0) {
+      const removed = record.ringBuffer.shift();
+      record.ringBufferByteLength -= removed?.byteLength ?? 0;
+    }
+    return record.outputSeq;
+  }
+
+  function attachPtyStreamHandlers(taskId, record) {
+    const writeLogChunk = (chunk) => {
+      if (record.logStream) {
+        record.logStream.write(chunk);
+      }
+    };
+
+    record.pty.onData((data) => {
+      writeLogChunk(data);
+      const seq = bufferTerminalOutput(record, data);
+      sendTerminalEvent("terminal_output", {
+        task_id: taskId,
+        project_id: record.projectId,
+        pty_session_id: record.ptySessionId,
+        seq,
+        data,
+      }).catch((err) => {
+        logError(`Failed to report terminal_output for ${taskId}: ${err?.message || err}`);
+      });
+    });
+
+    record.pty.onExit(({ exitCode, signal }) => {
+      if (record.stopForceKillTimer) {
+        clearTimeout(record.stopForceKillTimer);
+      }
+      activePtySessions.delete(taskId);
+      if (record.logStream) {
+        const ts = new Date().toLocaleString("sv-SE", { timeZone: "Asia/Shanghai" }).replace(" ", "T");
+        record.logStream.write(
+          `[daemon ${ts}] pty exited exitCode=${exitCode ?? "null"} signal=${signal ?? "null"}\n`,
+        );
+        record.logStream.end();
+      }
+      const closedAt = new Date().toISOString();
+      log(`PTY task ${taskId} exited with code=${exitCode ?? "null"} signal=${signal ?? "null"}`);
+      sendTerminalEvent("terminal_exit", {
+        task_id: taskId,
+        project_id: record.projectId,
+        pty_session_id: record.ptySessionId,
+        exit_code: exitCode ?? null,
+        signal: signal ?? null,
+        seq: record.outputSeq,
+        closed_at: closedAt,
+      }).catch((err) => {
+        logError(`Failed to report terminal_exit for ${taskId}: ${err?.message || err}`);
+      });
+    });
+  }
+
+  function resizePty(record, cols, rows) {
+    const nextCols = normalizePositiveInt(cols, record.cols || DEFAULT_TERMINAL_COLS);
+    const nextRows = normalizePositiveInt(rows, record.rows || DEFAULT_TERMINAL_ROWS);
+    record.cols = nextCols;
+    record.rows = nextRows;
+    if (typeof record.pty.resize === "function") {
+      record.pty.resize(nextCols, nextRows);
+    }
+  }
+
+  async function handleCreatePtyTask(payload) {
+    const taskId = payload?.task_id ? String(payload.task_id) : "";
+    const projectId = payload?.project_id ? String(payload.project_id) : "";
+    const ptySessionId = payload?.pty_session_id ? String(payload.pty_session_id) : "";
+    const requestId = payload?.request_id ? String(payload.request_id) : "";
+    const launchConfig = normalizeLaunchConfig(payload?.launch_config);
+
+    if (!taskId || !projectId || !ptySessionId) {
+      logError(`Invalid create_pty_task payload: ${JSON.stringify(payload)}`);
+      sendAgentCommandAck({
+        requestId,
+        taskId,
+        eventType: "create_pty_task",
+        accepted: false,
+      }).catch(() => {});
+      return;
+    }
+
+    if (requestId && !markRequestSeen(requestId)) {
+      log(`Duplicate create_pty_task ignored for ${taskId} (request_id=${requestId})`);
+      sendAgentCommandAck({
+        requestId,
+        taskId,
+        eventType: "create_pty_task",
+        accepted: true,
+      }).catch(() => {});
+      return;
+    }
+
+    if (activeTaskProcesses.has(taskId) || activePtySessions.has(taskId)) {
+      log(`Duplicate create_pty_task ignored for ${taskId}: task already active`);
+      sendAgentCommandAck({
+        requestId,
+        taskId,
+        eventType: "create_pty_task",
+        accepted: true,
+      }).catch(() => {});
+      return;
+    }
+
+    let boundPath = await getProjectLocalPath(projectId);
+    let taskDir = normalizeOptionalString(launchConfig.cwd) || boundPath;
+    if (!taskDir) {
+      const now = new Date();
+      const dayDir = path.join(WORKSPACE_ROOT, formatWorkspaceDate(now));
+      const runTimestampPart = formatWorkspaceRunTimestamp(now);
+      const taskSuffix = taskId.replace(/[^a-zA-Z0-9]/g, "").slice(0, 8) || String(process.pid);
+      // PTY login shells can exit immediately if their cwd is renamed right after spawn.
+      const pendingRunDir = `${runTimestampPart}_pty_${taskSuffix}`;
+      taskDir = path.join(dayDir, pendingRunDir);
+    }
+
+    try {
+      mkdirSyncFn(taskDir, { recursive: true });
+    } catch (err) {
+      logError(`Failed to create PTY workspace ${taskDir}: ${err?.message || err}`);
+      sendAgentCommandAck({
+        requestId,
+        taskId,
+        eventType: "create_pty_task",
+        accepted: false,
+      }).catch(() => {});
+      return;
+    }
+
+    let launchSpec;
+    try {
+      launchSpec = resolvePtyLaunchSpec(launchConfig, taskDir);
+    } catch (error) {
+      logError(`Failed to resolve PTY launch config for ${taskId}: ${error?.message || error}`);
+      sendAgentCommandAck({
+        requestId,
+        taskId,
+        eventType: "create_pty_task",
+        accepted: false,
+      }).catch(() => {});
+      sendTerminalEvent("terminal_error", {
+        task_id: taskId,
+        project_id: projectId,
+        pty_session_id: ptySessionId,
+        message: error?.message || String(error),
+      }).catch(() => {});
+      return;
+    }
+
+    sendAgentCommandAck({
+      requestId,
+      taskId,
+      eventType: "create_pty_task",
+      accepted: true,
+    }).catch((err) => {
+      logError(`Failed to report agent_command_ack(create_pty_task) for ${taskId}: ${err?.message || err}`);
+    });
+
+    const env = {
+      ...process.env,
+      ...launchSpec.env,
+      CONDUCTOR_PROJECT_ID: projectId,
+      CONDUCTOR_TASK_ID: taskId,
+      CONDUCTOR_PTY_SESSION_ID: ptySessionId,
+    };
+    if (config.CONFIG_FILE) {
+      env.CONDUCTOR_CONFIG = config.CONFIG_FILE;
+    }
+    if (AGENT_TOKEN) {
+      env.CONDUCTOR_AGENT_TOKEN = AGENT_TOKEN;
+    }
+    if (BACKEND_HTTP) {
+      env.CONDUCTOR_BACKEND_URL = BACKEND_HTTP;
+    }
+
+    const logPath = path.join(launchSpec.cwd, "conductor-terminal.log");
+    let logStream;
+    try {
+      logStream = createWriteStreamFn(logPath, { flags: "a" });
+      if (logStream && typeof logStream.on === "function") {
+        const logPathSnapshot = logPath;
+        logStream.on("error", (err) => {
+          logError(`Terminal log stream error (${logPathSnapshot}): ${err?.message || err}`);
+        });
+      }
+    } catch (err) {
+      logError(`Failed to open PTY log file ${logPath}: ${err?.message || err}`);
+    }
+
+    try {
+      const pty = await createPtyFn(launchSpec.command, launchSpec.args, {
+        name: "xterm-256color",
+        cols: launchSpec.cols,
+        rows: launchSpec.rows,
+        cwd: launchSpec.cwd,
+        env,
+      });
+      const resolvedLogPath = path.join(taskDir, "conductor-terminal.log");
+
+      const startedAt = new Date().toISOString();
+      const record = {
+        kind: "pty",
+        pty,
+        ptySessionId,
+        projectId,
+        taskDir,
+        logPath: resolvedLogPath,
+        logStream,
+        cols: launchSpec.cols,
+        rows: launchSpec.rows,
+        shell: launchSpec.shell,
+        startedAt,
+        outputSeq: 0,
+        ringBuffer: [],
+        ringBufferByteLength: 0,
+        stopForceKillTimer: null,
+      };
+      activePtySessions.set(taskId, record);
+      attachPtyStreamHandlers(taskId, record);
+
+      log(`Created PTY task ${taskId} (${launchSpec.entrypointType}) cwd=${launchSpec.cwd}`);
+      sendTerminalEvent("terminal_opened", {
+        task_id: taskId,
+        project_id: projectId,
+        pty_session_id: ptySessionId,
+        pid: Number.isInteger(pty?.pid) ? pty.pid : null,
+        cwd: taskDir,
+        shell: launchSpec.shell,
+        cols: launchSpec.cols,
+        rows: launchSpec.rows,
+        started_at: startedAt,
+      }).catch((err) => {
+        logError(`Failed to report terminal_opened for ${taskId}: ${err?.message || err}`);
+      });
+    } catch (error) {
+      if (logStream) {
+        logStream.end();
+      }
+      logError(`Failed to create PTY task ${taskId}: ${error?.message || error}`);
+      sendTerminalEvent("terminal_error", {
+        task_id: taskId,
+        project_id: projectId,
+        pty_session_id: ptySessionId,
+        message: error?.message || String(error),
+      }).catch(() => {});
+    }
+  }
+
+  async function handleTerminalAttach(payload) {
+    const taskId = payload?.task_id ? String(payload.task_id) : "";
+    if (!taskId) return;
+    const record = activePtySessions.get(taskId);
+    if (!record) {
+      sendTerminalEvent("terminal_error", {
+        task_id: taskId,
+        pty_session_id: payload?.pty_session_id ? String(payload.pty_session_id) : null,
+        message: "terminal session not found",
+      }).catch(() => {});
+      return;
+    }
+
+    if (payload?.cols || payload?.rows) {
+      resizePty(record, payload?.cols, payload?.rows);
+    }
+
+    await sendTerminalEvent("terminal_opened", {
+      task_id: taskId,
+      project_id: record.projectId,
+      pty_session_id: record.ptySessionId,
+      pid: Number.isInteger(record.pty?.pid) ? record.pty.pid : null,
+      cwd: record.taskDir,
+      shell: record.shell,
+      cols: record.cols,
+      rows: record.rows,
+      started_at: record.startedAt,
+    }).catch((err) => {
+      logError(`Failed to report terminal_opened on attach for ${taskId}: ${err?.message || err}`);
+    });
+
+    const lastSeq = normalizePositiveInt(payload?.last_seq ?? payload?.lastSeq, 0);
+    for (const chunk of record.ringBuffer) {
+      if (chunk.seq <= lastSeq) continue;
+      await sendTerminalEvent("terminal_output", {
+        task_id: taskId,
+        project_id: record.projectId,
+        pty_session_id: record.ptySessionId,
+        seq: chunk.seq,
+        data: chunk.data,
+      }).catch((err) => {
+        logError(`Failed to replay terminal_output for ${taskId}: ${err?.message || err}`);
+      });
+    }
+  }
+
+  function handleTerminalInput(payload) {
+    const taskId = payload?.task_id ? String(payload.task_id) : "";
+    const data = typeof payload?.data === "string" ? payload.data : "";
+    if (!taskId || !data) return;
+    const record = activePtySessions.get(taskId);
+    if (!record || typeof record.pty.write !== "function") {
+      return;
+    }
+    record.pty.write(data);
+  }
+
+  function handleTerminalResize(payload) {
+    const taskId = payload?.task_id ? String(payload.task_id) : "";
+    if (!taskId) return;
+    const record = activePtySessions.get(taskId);
+    if (!record) return;
+    resizePty(record, payload?.cols, payload?.rows);
+  }
+
+  function handleTerminalDetach(_payload) {
+    // PTY sessions stay alive without viewers. Detach is currently a no-op.
+  }
+
   function handleEvent(event) {
+    const receivedAt = Date.now();
+    lastInboundAt = receivedAt;
+    markWatchdogHealthy("inbound", receivedAt);
     if (event.type === "error") {
       const payload = event?.payload && typeof event.payload === "object" ? event.payload : {};
       const planLimitMessage = getPlanLimitMessage(payload);
@@ -575,15 +1361,55 @@ export function startDaemon(config = {}, deps = {}) {
       handleCreateTask(event.payload);
       return;
     }
+    if (event.type === "create_pty_task") {
+      void handleCreatePtyTask(event.payload);
+      return;
+    }
     if (event.type === "stop_task") {
       handleStopTask(event.payload);
       return;
     }
+    if (event.type === "terminal_attach") {
+      void handleTerminalAttach(event.payload);
+      return;
+    }
+    if (event.type === "terminal_input") {
+      handleTerminalInput(event.payload);
+      return;
+    }
+    if (event.type === "terminal_resize") {
+      handleTerminalResize(event.payload);
+      return;
+    }
+    if (event.type === "terminal_detach") {
+      handleTerminalDetach(event.payload);
+      return;
+    }
     if (event.type === "collect_logs") {
       void handleCollectLogs(event.payload);
     }
   }
 
+  function markWatchdogHealthy(signal, at = Date.now()) {
+    if (!watchdogAwaitingHealthySignalAt || watchdogHealAttempts === 0) {
+      return;
+    }
+    if (at < watchdogAwaitingHealthySignalAt) {
+      return;
+    }
+    log(
+      `[watchdog] Backend websocket healthy again after self-heal via ${signal} (${formatDaemonHealthState({
+        connectedAt: lastConnectedAt,
+        lastPongAt,
+        lastInboundAt,
+        lastSuccessfulHttpAt,
+        lastPresenceConfirmedAt,
+      })})`,
+    );
+    watchdogAwaitingHealthySignalAt = null;
+    watchdogHealAttempts = 0;
+  }
+
   async function handleCollectLogs(payload) {
     const requestId = payload?.request_id ? String(payload.request_id).trim() : "";
     const taskId = payload?.task_id ? String(payload.task_id).trim() : "";
@@ -672,8 +1498,9 @@ export function startDaemon(config = {}, deps = {}) {
       });
     };
 
-    const record = activeTaskProcesses.get(taskId);
-    if (!record || !record.child) {
+    const processRecord = activeTaskProcesses.get(taskId);
+    const ptyRecord = activePtySessions.get(taskId);
+    if ((!processRecord || !processRecord.child) && !ptyRecord) {
       log(`Stop requested for task ${taskId}, but no active process found`);
       sendStopAck(false);
       return;
@@ -684,36 +1511,58 @@ export function startDaemon(config = {}, deps = {}) {
 
     sendStopAck(true);
 
-    if (record.stopForceKillTimer) {
-      clearTimeout(record.stopForceKillTimer);
-      record.stopForceKillTimer = null;
+    const activeRecord = processRecord || ptyRecord;
+    if (activeRecord?.stopForceKillTimer) {
+      clearTimeout(activeRecord.stopForceKillTimer);
+      activeRecord.stopForceKillTimer = null;
     }
 
-    try {
-      if (typeof record.child.kill === "function") {
-        record.child.kill("SIGTERM");
+    if (processRecord?.child) {
+      try {
+        if (typeof processRecord.child.kill === "function") {
+          processRecord.child.kill("SIGTERM");
+        }
+      } catch (error) {
+        logError(`Failed to stop task ${taskId}: ${error?.message || error}`);
+      }
+    } else if (ptyRecord?.pty) {
+      try {
+        if (typeof ptyRecord.pty.kill === "function") {
+          ptyRecord.pty.kill("SIGTERM");
+        }
+      } catch (error) {
+        logError(`Failed to stop PTY task ${taskId}: ${error?.message || error}`);
       }
-    } catch (error) {
-      logError(`Failed to stop task ${taskId}: ${error?.message || error}`);
     }
 
-    record.stopForceKillTimer = setTimeout(() => {
-      const latest = activeTaskProcesses.get(taskId);
-      if (!latest || latest.child !== record.child) {
+    activeRecord.stopForceKillTimer = setTimeout(() => {
+      const latestProcess = activeTaskProcesses.get(taskId);
+      const latestPty = activePtySessions.get(taskId);
+      if (latestProcess?.child && processRecord?.child && latestProcess.child === processRecord.child) {
+        try {
+          if (typeof latestProcess.child.kill === "function") {
+            log(`Task ${taskId} did not exit after SIGTERM, sending SIGKILL`);
+            latestProcess.child.kill("SIGKILL");
+          }
+        } catch (error) {
+          logError(`Failed to SIGKILL task ${taskId}: ${error?.message || error}`);
+        }
         return;
       }
-      try {
-        if (typeof latest.child.kill === "function") {
-          log(`Task ${taskId} did not exit after SIGTERM, sending SIGKILL`);
-          latest.child.kill("SIGKILL");
+      if (latestPty?.pty && ptyRecord?.pty && latestPty.pty === ptyRecord.pty) {
+        try {
+          if (typeof latestPty.pty.kill === "function") {
+            log(`PTY task ${taskId} did not exit after SIGTERM, sending SIGKILL`);
+            latestPty.pty.kill("SIGKILL");
+          }
+        } catch (error) {
+          logError(`Failed to SIGKILL PTY task ${taskId}: ${error?.message || error}`);
         }
-      } catch (error) {
-        logError(`Failed to SIGKILL task ${taskId}: ${error?.message || error}`);
       }
     }, STOP_FORCE_KILL_TIMEOUT_MS);
 
-    if (typeof record.stopForceKillTimer?.unref === "function") {
-      record.stopForceKillTimer.unref();
+    if (typeof activeRecord.stopForceKillTimer?.unref === "function") {
+      activeRecord.stopForceKillTimer.unref();
     }
   }
 
@@ -817,7 +1666,7 @@ export function startDaemon(config = {}, deps = {}) {
     }
 
     // Validate and get CLI command for the backend
-    const effectiveBackend = backendType || SUPPORTED_BACKENDS[0];
+    const effectiveBackend = normalizeRuntimeBackendName(backendType || SUPPORTED_BACKENDS[0]);
     if (!SUPPORTED_BACKENDS.includes(effectiveBackend)) {
       logError(`Unsupported backend: ${effectiveBackend}. Supported: ${SUPPORTED_BACKENDS.join(", ")}`);
       sendAgentCommandAck({
@@ -1060,7 +1909,14 @@ export function startDaemon(config = {}, deps = {}) {
     }
 
     closePromise = (async () => {
-      const activeEntries = [...activeTaskProcesses.entries()];
+      daemonShuttingDown = true;
+      if (watchdogTimer) {
+        clearInterval(watchdogTimer);
+        watchdogTimer = null;
+      }
+      const activeProcessEntries = [...activeTaskProcesses.entries()];
+      const activePtyEntries = [...activePtySessions.entries()];
+      const activeEntries = [...activeProcessEntries, ...activePtyEntries];
       if (activeEntries.length > 0) {
         log(`Shutdown requested (${reason}); stopping ${activeEntries.length} active task(s)`);
       }
@@ -1088,7 +1944,7 @@ export function startDaemon(config = {}, deps = {}) {
         }),
       );
 
-      for (const [taskId, record] of activeEntries) {
+      for (const [taskId, record] of activeProcessEntries) {
         if (record?.stopForceKillTimer) {
           clearTimeout(record.stopForceKillTimer);
         }
@@ -1101,7 +1957,21 @@ export function startDaemon(config = {}, deps = {}) {
         }
       }
 
+      for (const [taskId, record] of activePtyEntries) {
+        if (record?.stopForceKillTimer) {
+          clearTimeout(record.stopForceKillTimer);
+        }
+        try {
+          if (typeof record.pty?.kill === "function") {
+            record.pty.kill("SIGTERM");
+          }
+        } catch (error) {
+          logError(`Failed to stop PTY task ${taskId} on daemon close: ${error?.message || error}`);
+        }
+      }
+
       activeTaskProcesses.clear();
+      activePtySessions.clear();
 
       try {
         await withTimeout(
@@ -1174,6 +2044,82 @@ function parsePositiveInt(value, fallback) {
   return fallback;
 }
 
+function formatDisconnectDiagnostics(event) {
+  const parts = [];
+  const reason = typeof event?.reason === "string" && event.reason.trim()
+    ? event.reason.trim()
+    : "unknown";
+  parts.push(`reason=${reason}`);
+  if (Number.isFinite(event?.closeCode)) {
+    parts.push(`close_code=${event.closeCode}`);
+  }
+  if (typeof event?.closeReason === "string" && event.closeReason.trim()) {
+    parts.push(`close_reason=${event.closeReason.trim()}`);
+  }
+  if (typeof event?.socketError === "string" && event.socketError.trim()) {
+    parts.push(`socket_error=${event.socketError.trim()}`);
+  }
+  if (Number.isFinite(event?.missedPongs) && event.missedPongs > 0) {
+    parts.push(`missed_pongs=${event.missedPongs}`);
+  }
+  if (Number.isFinite(event?.lastPingAt)) {
+    parts.push(`last_ping_at=${formatIsoTimestamp(event.lastPingAt)}`);
+  }
+  if (Number.isFinite(event?.lastPongAt)) {
+    parts.push(`last_pong_at=${formatIsoTimestamp(event.lastPongAt)}`);
+  }
+  if (Number.isFinite(event?.lastMessageAt)) {
+    parts.push(`last_message_at=${formatIsoTimestamp(event.lastMessageAt)}`);
+  }
+  return parts.join(" ");
+}
+
+function formatDaemonHealthState({
+  connectedAt,
+  lastPongAt,
+  lastInboundAt,
+  lastSuccessfulHttpAt,
+  lastPresenceConfirmedAt,
+}) {
+  return [
+    `connected_at=${formatIsoTimestamp(connectedAt)}`,
+    `last_pong_at=${formatIsoTimestamp(lastPongAt)}`,
+    `last_inbound_at=${formatIsoTimestamp(lastInboundAt)}`,
+    `last_http_ok_at=${formatIsoTimestamp(lastSuccessfulHttpAt)}`,
+    `last_presence_at=${formatIsoTimestamp(lastPresenceConfirmedAt)}`,
+  ].join(" ");
+}
+
+function formatWatchdogExtra(extra) {
+  const parts = [];
+  if (Number.isFinite(extra?.agentCount)) {
+    parts.push(`agent_count=${extra.agentCount}`);
+  }
+  if (Number.isFinite(extra?.probeStatus)) {
+    parts.push(`probe_status=${extra.probeStatus}`);
+  }
+  if (Number.isFinite(extra?.probeAt)) {
+    parts.push(`probe_at=${formatIsoTimestamp(extra.probeAt)}`);
+  }
+  if (typeof extra?.probeError === "string" && extra.probeError.trim()) {
+    parts.push(`probe_error=${extra.probeError.trim()}`);
+  }
+  if (Number.isFinite(extra?.lastWsHealthAt)) {
+    parts.push(`last_ws_health_at=${formatIsoTimestamp(extra.lastWsHealthAt)}`);
+  }
+  if (Number.isFinite(extra?.staleForMs)) {
+    parts.push(`stale_for_ms=${extra.staleForMs}`);
+  }
+  return parts.length ? parts.join(" ") : "no-extra-diagnostics";
+}
+
+function formatIsoTimestamp(value) {
+  if (!Number.isFinite(value)) {
+    return "never";
+  }
+  return new Date(value).toISOString();
+}
+
 async function withTimeout(promise, timeoutMs, label) {
   let timer = null;
   const timeoutPromise = new Promise((_, reject) => {