@openscout/scout 0.2.76 → 0.2.78

package/dist/openscout-terminal-relay.mjs

@@ -2,7 +2,7 @@
 import { createServer } from "node:http";
 import { mkdir, writeFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
-import { join as join6 } from "node:path";
+import { join as join7 } from "node:path";
 import { createRequire as createRequire2 } from "node:module";
 
 // packages/web/server/relay.ts
@@ -15,6 +15,21 @@ function sanitizeUploadName(name) {
   return base;
 }
 
+// packages/web/server/process-parent-watchdog.ts
+function startProcessParentWatchdog(expectedParentPidRaw, options = {}) {
+  const expectedParentPid = Number.parseInt(expectedParentPidRaw?.trim() ?? "", 10);
+  if (!Number.isFinite(expectedParentPid) || expectedParentPid <= 0)
+    return null;
+  const parentPid = options.parentPid ?? (() => process.ppid);
+  const onOrphan = options.onOrphan ?? (() => process.kill(process.pid, "SIGTERM"));
+  const timer = setInterval(() => {
+    if (parentPid() !== expectedParentPid)
+      onOrphan();
+  }, options.intervalMs ?? 500);
+  timer.unref?.();
+  return timer;
+}
+
 // packages/web/server/terminal-relay-session.ts
 import { createRequire } from "module";
 
@@ -533,7 +548,7 @@ var SCOUT_HOST_PROBE_SCHEMA_VERSIONS = {
   "git.mergeBase": 1,
   "git.logLastCommitUnix": 1,
   "git.worktreeListPorcelain": 1,
-  "tmux.sessions": 1,
+  "tmux.sessions": 2,
   "tmux.panes": 1,
   "zellij.sessions": 1,
   "ps.runtime": 1,
@@ -2605,7 +2620,7 @@ function zellijSocketKey(input) {
 }
 function parseTmuxSessionList(output) {
   return output.split(/\r?\n/gu).map((line) => line.trim()).filter(Boolean).map((line) => {
-    const [name, windows, attached, createdAt, currentCommand, currentPath] = line.includes("|") ? splitDelimitedLine(line, "|", 6) : splitDelimitedLine(line, "\t", 6);
+    const [name, windows, attached, createdAt, activityAt, currentCommand, currentPath] = line.includes("|") ? splitDelimitedLine(line, "|", 7) : splitDelimitedLine(line, "\t", 7);
     if (!name)
       return null;
     return {
@@ -2613,6 +2628,7 @@ function parseTmuxSessionList(output) {
       windows: parsePositiveInteger(windows, 1),
       attached: parsePositiveInteger(attached, 0),
       createdAt: createdAt ? Number.parseInt(createdAt, 10) || null : null,
+      activityAt: activityAt ? Number.parseInt(activityAt, 10) || null : null,
       currentCommand: cleanOptionalString(currentCommand),
       currentPath: cleanOptionalString(currentPath)
     };
@@ -2639,7 +2655,7 @@ async function readTmuxSessionsLocal(key, ctx) {
       ...tmuxSocketArgs(key),
       "list-sessions",
       "-F",
-      "#{session_name}|#{session_windows}|#{session_attached}|#{session_created}|#{pane_current_command}|#{pane_current_path}"
+      "#{session_name}|#{session_windows}|#{session_attached}|#{session_created}|#{session_activity}|#{pane_current_command}|#{pane_current_path}"
     ], {
       maxStdoutBytes: 512 * 1024,
       maxStderrBytes: 64 * 1024
@@ -2789,10 +2805,102 @@ async function readZellijSessionExists(sessionName, options = {}) {
   const snapshot = await zellijSessionsProbe.for({ env: options.env, socketDir: options.socketDir }).fresh({ maxAgeMs: options.maxAgeMs ?? TMUX_TTL_MS });
   return Boolean(snapshot.value?.some((session) => session.name === name));
 }
+// packages/runtime/dist/system-probes/herdr.js
+import { homedir as homedir3 } from "node:os";
+var HERDR_TTL_MS = 5000;
+var HERDR_TIMEOUT_MS = 2000;
+function herdrBin(env = process.env) {
+  return env.OPENSCOUT_HERDR_BIN?.trim() || "herdr";
+}
+function herdrProbeTarget(env) {
+  return {
+    bin: herdrBin(env),
+    path: env.PATH ?? "",
+    home: env.XDG_CONFIG_HOME?.trim() || env.HOME?.trim() || homedir3()
+  };
+}
+function parseHerdrProbeKey(key) {
+  try {
+    const parsed = JSON.parse(key);
+    if (typeof parsed?.bin === "string" && typeof parsed.path === "string" && typeof parsed.home === "string") {
+      return { bin: parsed.bin, path: parsed.path, home: parsed.home };
+    }
+  } catch {}
+  return herdrProbeTarget(process.env);
+}
+function isUnavailable5(error) {
+  return error instanceof ProbeCommandError && (error.code === "ENOENT" || error.code === "spawn" || error.code === "exit");
+}
+function herdrProbeKey(input) {
+  if (typeof input === "string")
+    return input.trim() || "default";
+  return JSON.stringify(herdrProbeTarget(input?.env ?? process.env));
+}
+function parseHerdrSessionListJson(output) {
+  const trimmed = output.trim();
+  if (!trimmed)
+    return [];
+  let parsed;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    return [];
+  }
+  const sessions = Array.isArray(parsed) ? parsed : parsed && typeof parsed === "object" && Array.isArray(parsed.sessions) ? parsed.sessions : [];
+  const out = [];
+  for (const entry of sessions) {
+    if (!entry || typeof entry !== "object")
+      continue;
+    const record = entry;
+    const name = typeof record.name === "string" ? record.name.trim() : "";
+    if (!name)
+      continue;
+    const isDefault = record.default === true || name === "default";
+    const running = record.running === true;
+    const sessionDir = typeof record.session_dir === "string" && record.session_dir.trim() ? record.session_dir.trim() : typeof record.sessionDir === "string" && record.sessionDir.trim() ? record.sessionDir.trim() : null;
+    out.push({ name, isDefault, running, sessionDir });
+  }
+  return out;
+}
+async function readHerdrSessionsLocal(key, ctx) {
+  const target = parseHerdrProbeKey(key);
+  try {
+    const { stdout } = await execProbeFile(ctx, target.bin, ["session", "list", "--json"], {
+      env: { ...process.env, PATH: target.path, HOME: target.home, XDG_CONFIG_HOME: target.home },
+      maxStdoutBytes: 512 * 1024,
+      maxStderrBytes: 64 * 1024
+    });
+    return parseHerdrSessionListJson(stdout);
+  } catch (error) {
+    if (isUnavailable5(error))
+      return [];
+    throw error;
+  }
+}
+var herdrSessionsProbe = defineProbeFamily({
+  id: "herdr.sessions",
+  ttlMs: HERDR_TTL_MS,
+  timeoutMs: HERDR_TIMEOUT_MS,
+  maxKeys: 8,
+  idleKeyTtlMs: 5 * 60000,
+  maxConcurrentKeys: 1,
+  normalizeKey: herdrProbeKey,
+  run: (key, ctx) => {
+    if (key !== herdrProbeKey(process.env ? { env: process.env } : null)) {
+      return readHerdrSessionsLocal(key, ctx).then((value) => probeRunOutput(value, { backend: "local" }));
+    }
+    return runWithScoutdFallback({
+      probeId: "herdr.sessions",
+      key,
+      ctx,
+      local: () => readHerdrSessionsLocal(key, ctx)
+    });
+  }
+});
 // packages/runtime/dist/system-probes/sessions.js
 import { createReadStream } from "node:fs";
 import { readdir, stat } from "node:fs/promises";
-import { homedir as homedir3 } from "node:os";
+import { homedir as homedir4 } from "node:os";
 import { basename as basename2, dirname as dirname2, join as join4, resolve as resolve2 } from "node:path";
 import { createInterface } from "node:readline";
 function positiveInteger2(value, fallback, max) {
@@ -2800,7 +2908,7 @@ function positiveInteger2(value, fallback, max) {
 }
 function normalizeScanKey(input) {
   return {
-    home: resolve2(input.home?.trim() || homedir3()),
+    home: resolve2(input.home?.trim() || homedir4()),
     workspaceRoot: input.workspaceRoot?.trim() ? resolve2(input.workspaceRoot) : null,
     maxAgeDays: positiveInteger2(input.maxAgeDays, 14, 3650),
     limit: positiveInteger2(input.limit, 250, 1e4)
@@ -3001,7 +3109,7 @@ function canonicalCertPath(path) {
     return resolve3(path);
   }
 }
-function isUnavailable5(error) {
+function isUnavailable6(error) {
   return error instanceof ProbeCommandError && (error.code === "ENOENT" || error.code === "spawn" || error.code === "exit");
 }
 var certStatusProbe = defineProbeFamily({
@@ -3031,7 +3139,7 @@ var certStatusProbe = defineProbeFamily({
       });
       validAtLeast24h = true;
     } catch (error) {
-      if (!isUnavailable5(error)) {
+      if (!isUnavailable6(error)) {
         throw error;
       }
     }
@@ -3045,7 +3153,7 @@ var certStatusProbe = defineProbeFamily({
       issuer = stdout.match(/^issuer=(.*)$/m)?.[1]?.trim() || null;
       subject = stdout.match(/^subject=(.*)$/m)?.[1]?.trim() || null;
     } catch (error) {
-      if (!isUnavailable5(error)) {
+      if (!isUnavailable6(error)) {
         throw error;
       }
     }
@@ -3059,6 +3167,30 @@ var certStatusProbe = defineProbeFamily({
     };
   }
 });
+// packages/runtime/dist/terminal-environment.js
+var INHERITED_CLAUDE_SESSION_ENV_KEYS = [
+  "CLAUDECODE",
+  "CLAUDE_CODE_CHILD_SESSION",
+  "CLAUDE_CODE_SESSION_ID",
+  "CLAUDE_SESSION_ID",
+  "CLAUDE_CODE_REMOTE",
+  "CLAUDE_CODE_REMOTE_SESSION_ID",
+  "CLAUDE_PID"
+];
+function buildInteractiveTerminalEnvironment(base = process.env, overrides = {}) {
+  const env = {
+    ...base,
+    ...overrides,
+    COLORTERM: overrides.COLORTERM || base.COLORTERM || "truecolor",
+    FORCE_COLOR: overrides.FORCE_COLOR || base.FORCE_COLOR || "1"
+  };
+  delete env.NO_COLOR;
+  for (const key of INHERITED_CLAUDE_SESSION_ENV_KEYS) {
+    delete env[key];
+  }
+  return env;
+}
+
 // packages/web/server/terminal-relay-session.ts
 import { randomBytes, timingSafeEqual } from "crypto";
 import { existsSync as existsSync5, mkdirSync as mkdirSync2, writeFileSync as writeFileSync2, rmSync } from "fs";
@@ -3211,6 +3343,180 @@ function buildZellijAttachArgs({
   return args;
 }
 
+// packages/agent-sessions/dist/codex-executable.js
+import { execFileSync } from "node:child_process";
+import { accessSync, constants } from "node:fs";
+import { delimiter, join as join6 } from "node:path";
+function isExecutable(filePath) {
+  if (!filePath)
+    return false;
+  if (filePath === "codex")
+    return true;
+  try {
+    accessSync(filePath, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function readCodexVersion(candidate) {
+  if (!isExecutable(candidate)) {
+    return { version: null, versionRaw: null };
+  }
+  try {
+    const raw = execFileSync(candidate, ["--version"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 3000
+    }).trim();
+    const version = raw.match(/\b(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)\b/)?.[1] ?? null;
+    return { version, versionRaw: raw || null };
+  } catch {
+    return { version: null, versionRaw: null };
+  }
+}
+function uniqueCandidates(candidates) {
+  const seen = new Set;
+  const unique = [];
+  for (const candidate of candidates) {
+    if (!candidate.path || seen.has(candidate.path))
+      continue;
+    seen.add(candidate.path);
+    unique.push(candidate);
+  }
+  return unique;
+}
+function codexAppBundleCandidates(env) {
+  const appNames = ["Codex.app", "ChatGPT.app"];
+  const candidates = appNames.flatMap((appName) => [
+    {
+      path: join6("/Applications", appName, "Contents", "Resources", "codex"),
+      source: "codex_app_bundle"
+    },
+    {
+      path: join6(env.HOME ?? "", "Applications", appName, "Contents", "Resources", "codex"),
+      source: "codex_app_bundle"
+    }
+  ]);
+  return candidates.filter((candidate) => candidate.path.trim().length > 0);
+}
+function pathCandidates(env) {
+  return (env.PATH ?? "").split(delimiter).filter(Boolean).map((directory) => ({
+    path: join6(directory, "codex"),
+    source: "path"
+  }));
+}
+function commonCandidates(env) {
+  return [
+    `${env.HOME ?? ""}/.local/bin`,
+    `${env.HOME ?? ""}/.bun/bin`,
+    "/opt/homebrew/bin",
+    "/usr/local/bin"
+  ].filter(Boolean).map((directory) => ({
+    path: join6(directory, "codex"),
+    source: "common"
+  }));
+}
+function resolveCodexExecutableCandidateInputs(env = process.env) {
+  const explicit = [];
+  if (env.OPENSCOUT_CODEX_BIN) {
+    explicit.push({ path: env.OPENSCOUT_CODEX_BIN, source: "env:OPENSCOUT_CODEX_BIN" });
+  }
+  if (env.CODEX_BIN) {
+    explicit.push({ path: env.CODEX_BIN, source: "env:CODEX_BIN" });
+  }
+  return uniqueCandidates([
+    ...explicit,
+    ...codexAppBundleCandidates(env),
+    ...pathCandidates(env),
+    ...commonCandidates(env),
+    { path: "codex", source: "fallback" }
+  ]);
+}
+function parseVersion(value) {
+  if (!value)
+    return null;
+  const match = value.match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
+  if (!match)
+    return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] ?? null
+  };
+}
+function compareVersions(left, right) {
+  const lhs = parseVersion(left);
+  const rhs = parseVersion(right);
+  if (!lhs && !rhs)
+    return 0;
+  if (!lhs)
+    return -1;
+  if (!rhs)
+    return 1;
+  for (const key of ["major", "minor", "patch"]) {
+    if (lhs[key] !== rhs[key]) {
+      return lhs[key] - rhs[key];
+    }
+  }
+  if (lhs.prerelease === rhs.prerelease)
+    return 0;
+  if (!lhs.prerelease)
+    return 1;
+  if (!rhs.prerelease)
+    return -1;
+  return lhs.prerelease.localeCompare(rhs.prerelease);
+}
+function sourceRank(source) {
+  switch (source) {
+    case "env:OPENSCOUT_CODEX_BIN":
+      return 0;
+    case "env:CODEX_BIN":
+      return 1;
+    case "codex_app_bundle":
+      return 2;
+    case "path":
+      return 3;
+    case "common":
+      return 4;
+    case "fallback":
+      return 5;
+  }
+}
+function selectCodexCandidate(candidates) {
+  const executable = candidates.filter((candidate) => candidate.executable);
+  if (executable.length === 0)
+    return null;
+  const explicit = executable.find((candidate) => candidate.source === "env:OPENSCOUT_CODEX_BIN" || candidate.source === "env:CODEX_BIN");
+  if (explicit)
+    return explicit;
+  return executable.slice().sort((left, right) => {
+    const versionComparison = compareVersions(right.version, left.version);
+    if (versionComparison !== 0)
+      return versionComparison;
+    return sourceRank(left.source) - sourceRank(right.source);
+  })[0] ?? null;
+}
+function resolveCodexExecutableInventory(env = process.env) {
+  const candidates = resolveCodexExecutableCandidateInputs(env).map((candidate) => {
+    const executable = isExecutable(candidate.path);
+    const version = readCodexVersion(candidate.path);
+    return {
+      ...candidate,
+      executable,
+      version: version.version,
+      versionRaw: version.versionRaw
+    };
+  });
+  const selected = selectCodexCandidate(candidates);
+  return {
+    selectedPath: selected?.path ?? "codex",
+    selected,
+    candidates
+  };
+}
+
 // packages/web/server/terminal-relay-session.ts
 var require2 = createRequire(import.meta.url);
 var pty = (() => {
@@ -3239,7 +3545,7 @@ function verifyReconnectToken(session, token) {
     return false;
   return timingSafeEqual(expected, supplied);
 }
-var MULTIPLEXER_NAME_RE = /^[A-Za-z0-9_][A-Za-z0-9_-]{0,63}$/;
+var MULTIPLEXER_NAME_RE = /^[A-Za-z0-9_][A-Za-z0-9_-]*$/;
 function isValidMultiplexerName(name) {
   return MULTIPLEXER_NAME_RE.test(name);
 }
@@ -3311,18 +3617,31 @@ function writeSession(session, data) {
     throw err;
   }
 }
-function resizeSession(session, cols, rows) {
+async function resizeSession(session, cols, rows) {
   if (session.exited)
     return false;
-  if (session.controlMode === "observe" && session.backend !== "zellij")
+  let acceptedCols = cols;
+  let acceptedRows = rows;
+  if (session.controlMode === "observe" && session.backend === "tmux" && session.tmuxSession) {
+    const source = await readTmuxDimensions(session.tmuxSession);
+    const accepted = clampObserverDimensions({ cols, rows }, source);
+    acceptedCols = accepted.cols;
+    acceptedRows = accepted.rows;
+    session.tmuxSourceCols = source.cols;
+    session.tmuxSourceRows = source.rows;
+  } else if (session.controlMode === "observe" && session.backend !== "zellij") {
     return false;
+  }
   try {
-    session.pty.resize(cols, rows);
+    session.pty.resize(acceptedCols, acceptedRows);
     if (session.backend === "tmux" && session.tmuxSession) {
-      resizeTmuxWindow(session.tmuxSession, cols, rows);
+      if (session.controlMode !== "observe") {
+        await resizeTmuxWindow(session.tmuxSession, acceptedCols, acceptedRows);
+      }
     }
-    session.cols = cols;
-    session.rows = rows;
+    session.cols = acceptedCols;
+    session.rows = acceptedRows;
+    send(session.ws, { type: "terminal:dimensions", cols: acceptedCols, rows: acceptedRows });
     return true;
   } catch (err) {
     if (ptyFdClosed(err)) {
@@ -3410,6 +3729,14 @@ async function findClaudeBin() {
 async function findPiBin() {
   return findBin("pi", "PI_BIN");
 }
+async function findCodexBin() {
+  const selected = resolveCodexExecutableInventory().selected;
+  if (!selected?.executable)
+    return null;
+  if (selected.path === "codex")
+    return findBin("codex", "CODEX_BIN");
+  return selected.path;
+}
 async function findShellBin() {
   const configured = process.env.SHELL;
   if (configured && existsSync5(configured))
@@ -3451,6 +3778,26 @@ async function resizeTmuxWindow(name, cols, rows) {
     return false;
   }
 }
+function clampObserverDimensions(requested, source) {
+  return {
+    cols: Math.max(1, Math.min(requested.cols, source.cols)),
+    rows: Math.max(1, Math.min(requested.rows, source.rows))
+  };
+}
+async function readTmuxDimensions(name) {
+  const result = await execSystemFile("tmux", [
+    "display-message",
+    "-p",
+    "-t",
+    name,
+    "#{window_width} #{window_height}"
+  ], { timeoutMs: 2000 });
+  const match = /^(\d+)\s+(\d+)$/.exec(result.stdout.trim());
+  if (!match) {
+    throw new Error(`Could not read terminal dimensions for tmux session '${name}'`);
+  }
+  return { cols: Number(match[1]), rows: Number(match[2]) };
+}
 function resolveBootstrapPath(cwd, relPath) {
   const base = pathResolve(cwd);
   const absPath = pathResolve(base, relPath);
@@ -3478,8 +3825,28 @@ function bootstrapFiles(cwd, files, sessionId) {
     }
   }
 }
+function buildTmuxAttachArgs(tmuxName, controlMode) {
+  return controlMode === "observe" ? ["-u", "attach", "-r", "-t", tmuxName] : ["-u", "attach", "-t", tmuxName];
+}
+function bufferPtyOutput(ptyProcess) {
+  const pending = [];
+  let handler = null;
+  ptyProcess.onData((data) => {
+    if (handler)
+      handler(data);
+    else
+      pending.push(data);
+  });
+  return (nextHandler) => {
+    handler = nextHandler;
+    for (const data of pending.splice(0))
+      nextHandler(data);
+  };
+}
 async function spawnTmuxSession(tmuxName, cols, rows, cwd, commandBin, commandArgs, env, controlMode) {
   const exists = await tmuxSessionExists(tmuxName);
+  let dimensions = { cols, rows };
+  let sourceDimensions;
   if (!exists) {
     if (controlMode === "observe") {
       throw new Error(`tmux session '${tmuxName}' does not exist`);
@@ -3508,14 +3875,19 @@ async function spawnTmuxSession(tmuxName, cols, rows, cwd, commandBin, commandAr
     }
     console.log(`[relay] Attaching to existing tmux session: ${tmuxName}${controlMode === "observe" ? " (observe)" : ""}`);
     markMuxSessionInUse("tmux", tmuxName);
+    if (controlMode === "observe") {
+      sourceDimensions = await readTmuxDimensions(tmuxName);
+      dimensions = clampObserverDimensions(dimensions, sourceDimensions);
+    }
   }
-  return pty.spawn("tmux", ["attach", "-t", tmuxName], {
+  const ptyProcess = pty.spawn("tmux", buildTmuxAttachArgs(tmuxName, controlMode), {
     name: "xterm-256color",
-    cols,
-    rows,
+    cols: dimensions.cols,
+    rows: dimensions.rows,
     cwd,
     env
   });
+  return { ptyProcess, attachOutput: bufferPtyOutput(ptyProcess), dimensions, sourceDimensions };
 }
 function spawnZellijSession(zellijBin2, zellijName, cols, rows, cwd, commandBin, commandArgs, env, controlMode) {
   const layoutPath = controlMode === "observe" ? undefined : createZellijLayoutFile({ cwd, commandBin, commandArgs });
@@ -3538,22 +3910,34 @@ function spawnZellijSession(zellijBin2, zellijName, cols, rows, cwd, commandBin,
 }
 async function createSession(ws, msg) {
   const id = generateId();
-  const cols = Math.max(msg.cols || 80, 20);
-  const rows = Math.max(msg.rows || 24, 4);
+  let cols = Math.max(msg.cols || 80, 20);
+  let rows = Math.max(msg.rows || 24, 4);
   const backend = msg.backend || "pty";
   const controlMode = msg.controlMode || "owner";
   const tmuxName = msg.tmuxSession || `hudson-${id}`;
   const zellijName = msg.zellijSession || `hudson-${id}`;
+  const herdrName = msg.herdrSession || msg.tmuxSession || `scout-herdr-${id}`;
   const agent = msg.agent || "claude";
-  const multiplexerName = backend === "tmux" ? tmuxName : backend === "zellij" ? zellijName : null;
+  const multiplexerName = backend === "tmux" ? tmuxName : backend === "zellij" ? zellijName : backend === "herdr" ? herdrName : null;
   if (multiplexerName && !isValidMultiplexerName(multiplexerName)) {
-    const reason = `Invalid ${backend} session name. Use letters, digits, dashes, and underscores (max 64 chars).`;
+    const reason = `Invalid ${backend} session name. Use only letters, digits, dashes, and underscores.`;
     console.error(`[relay] Session ${id} failed: ${reason}`);
     send(ws, { type: "session:error", error: reason });
     return null;
   }
-  let agentBin;
-  if (agent === "shell") {
+  let agentBin = null;
+  let agentArgs = [];
+  const herdrBin2 = backend === "herdr" ? await findBin("herdr", "OPENSCOUT_HERDR_BIN") : null;
+  if (backend === "herdr") {
+    if (!herdrBin2) {
+      const reason = "herdr not found. Install it from https://herdr.dev/docs/install/";
+      console.error(`[relay] Session ${id} failed: ${reason}`);
+      send(ws, { type: "session:error", error: reason });
+      return null;
+    }
+    agentBin = herdrBin2;
+    agentArgs = !herdrName || herdrName === "default" ? [] : ["--session", herdrName];
+  } else if (agent === "shell") {
     agentBin = await findShellBin();
     if (!agentBin) {
       const reason = "No login shell found. Set SHELL or install zsh, bash, or sh.";
@@ -3561,6 +3945,14 @@ async function createSession(ws, msg) {
       send(ws, { type: "session:error", error: reason });
       return null;
     }
+  } else if (agent === "codex") {
+    agentBin = await findCodexBin();
+    if (!agentBin) {
+      const reason = "Codex CLI not found. Install it with: npm install -g @openai/codex";
+      console.error(`[relay] Session ${id} failed: ${reason}`);
+      send(ws, { type: "session:error", error: reason });
+      return null;
+    }
   } else if (agent === "pi") {
     agentBin = await findPiBin();
     if (!agentBin) {
@@ -3578,8 +3970,8 @@ async function createSession(ws, msg) {
       return null;
     }
   }
-  if (!existsSync5(agentBin)) {
-    const reason = `${agent} binary not found at ${agentBin}`;
+  if (!agentBin || !existsSync5(agentBin)) {
+    const reason = `${backend === "herdr" ? "herdr" : agent} binary not found${agentBin ? ` at ${agentBin}` : ""}`;
     console.error(`[relay] Session ${id} failed: ${reason}`);
     send(ws, { type: "session:error", error: reason });
     return null;
@@ -3601,37 +3993,44 @@ async function createSession(ws, msg) {
   if (msg.workspaceFiles) {
     bootstrapFiles(cwd, msg.workspaceFiles, id);
   }
-  let agentArgs;
-  if (agent === "shell") {
-    const shellName = agentBin.split("/").pop() ?? "";
-    agentArgs = shellName === "sh" ? [] : ["-l"];
-  } else if (agent === "pi") {
-    agentArgs = ["--verbose"];
-    const provider = normalizePiProviderForCli(msg.provider);
-    if (provider)
-      agentArgs.push("--provider", provider);
-    if (msg.model)
-      agentArgs.push("--model", msg.model);
-    if (msg.systemPrompt)
-      agentArgs.push("--system-prompt", msg.systemPrompt);
-  } else {
-    agentArgs = ["--verbose"];
-    if (msg.systemPrompt)
-      agentArgs.push("--system-prompt", msg.systemPrompt);
+  if (backend !== "herdr") {
+    if (agent === "shell") {
+      const shellName = agentBin.split("/").pop() ?? "";
+      agentArgs = shellName === "sh" ? [] : ["-l"];
+    } else if (agent === "codex") {
+      agentArgs = [];
+    } else if (agent === "pi") {
+      agentArgs = ["--verbose"];
+      const provider = normalizePiProviderForCli(msg.provider);
+      if (provider)
+        agentArgs.push("--provider", provider);
+      if (msg.model)
+        agentArgs.push("--model", msg.model);
+      if (msg.systemPrompt)
+        agentArgs.push("--system-prompt", msg.systemPrompt);
+    } else {
+      agentArgs = ["--verbose"];
+      if (msg.systemPrompt)
+        agentArgs.push("--system-prompt", msg.systemPrompt);
+    }
   }
-  const env = {
-    ...process.env,
+  const env = buildInteractiveTerminalEnvironment(process.env, {
     ...prepareZellijSocketDir(backend === "zellij" ? msg.zellijSocketDir : undefined),
-    TERM: "xterm-256color",
-    FORCE_COLOR: "1"
-  };
-  delete env.CLAUDECODE;
+    TERM: "xterm-256color"
+  });
   let ptyProcess;
+  let attachPtyOutput = null;
   let zellijLayoutPath;
+  let tmuxSourceDimensions;
   try {
     if (backend === "tmux") {
       console.log(`[relay] Session ${id}: tmux backend (session: ${tmuxName}) in ${cwd} [agent: ${agent}]`);
-      ptyProcess = await spawnTmuxSession(tmuxName, cols, rows, cwd, agentBin, agentArgs, env, controlMode);
+      const spawned = await spawnTmuxSession(tmuxName, cols, rows, cwd, agentBin, agentArgs, env, controlMode);
+      ptyProcess = spawned.ptyProcess;
+      attachPtyOutput = spawned.attachOutput;
+      cols = spawned.dimensions.cols;
+      rows = spawned.dimensions.rows;
+      tmuxSourceDimensions = spawned.sourceDimensions;
     } else if (backend === "zellij") {
       console.log(`[relay] Session ${id}: zellij backend (session: ${zellijName}, mode: ${controlMode}) in ${cwd} [agent: ${agent}]`);
       const trackZellij = muxTtlMs() > 0 && controlMode !== "observe" && !await zellijSessionExists(zellijBin2, zellijName, env);
@@ -3642,6 +4041,15 @@ async function createSession(ws, msg) {
         trackCreatedMuxSession("zellij", zellijName);
       else
         markMuxSessionInUse("zellij", zellijName);
+    } else if (backend === "herdr") {
+      console.log(`[relay] Session ${id}: herdr backend (session: ${herdrName}) in ${cwd}`);
+      ptyProcess = pty.spawn(agentBin, agentArgs, {
+        name: "xterm-256color",
+        cols,
+        rows,
+        cwd,
+        env
+      });
     } else {
       console.log(`[relay] Session ${id}: pty backend, spawning ${agentBin} in ${cwd} [agent: ${agent}]`);
       ptyProcess = pty.spawn(agentBin, agentArgs, {
@@ -3672,21 +4080,33 @@ async function createSession(ws, msg) {
     backend,
     controlMode,
     ...backend === "tmux" ? { tmuxSession: tmuxName } : {},
+    ...tmuxSourceDimensions ? {
+      tmuxSourceCols: tmuxSourceDimensions.cols,
+      tmuxSourceRows: tmuxSourceDimensions.rows
+    } : {},
     ...backend === "zellij" ? {
       zellijSession: zellijName,
       ...msg.zellijSocketDir ? { zellijSocketDir: msg.zellijSocketDir } : {},
       ...zellijLayoutPath ? { zellijLayoutPath } : {}
     } : {},
+    ...backend === "herdr" ? { herdrSession: herdrName } : {},
     flowControl: createTerminalFlowControlState(),
     flowControlEnabled: clientSupportsAck(msg.clientCapabilities),
     exited: false,
     exitCode: null
   };
   const startTime = Date.now();
-  ptyProcess.onData((data) => {
-    session.outputBuffer = truncateOutputBuffer(session.outputBuffer + data, MAX_BUFFER_SIZE);
+  const handlePtyData = (data) => {
+    if (session.controlMode !== "observe") {
+      session.outputBuffer = truncateOutputBuffer(session.outputBuffer + data, MAX_BUFFER_SIZE);
+    }
     sendTerminalOutput(session, data);
-  });
+  };
+  send(ws, { type: "terminal:dimensions", cols, rows });
+  if (attachPtyOutput)
+    attachPtyOutput(handlePtyData);
+  else
+    ptyProcess.onData(handlePtyData);
   ptyProcess.onExit(({ exitCode }) => {
     session.exited = true;
     session.exitCode = exitCode;
@@ -3710,7 +4130,7 @@ async function createSession(ws, msg) {
   console.log(`[relay] Session ${id} created (${cols}x${rows})`);
   return session;
 }
-function attachSession(session, ws, cols, rows, clientCapabilities) {
+async function attachSession(session, ws, cols, rows, clientCapabilities) {
   if (session.reapTimer) {
     clearTimeout(session.reapTimer);
     session.reapTimer = null;
@@ -3722,7 +4142,7 @@ function attachSession(session, ws, cols, rows, clientCapabilities) {
     const c = Math.max(cols, 20);
     const r = Math.max(rows, 4);
     if (c !== session.cols || r !== session.rows) {
-      resizeSession(session, c, r);
+      await resizeSession(session, c, r);
     }
   }
   if (session.exited) {
@@ -3778,6 +4198,8 @@ function destroy(sessionId) {
     console.log(`[relay] Session ${sessionId} bridge destroyed (zellij session '${session.zellijSession}' still alive)`);
     if (session.zellijSession)
       markMuxSessionDetached("zellij", session.zellijSession);
+  } else if (session.backend === "herdr") {
+    console.log(`[relay] Session ${sessionId} bridge destroyed (herdr session '${session.herdrSession}' still alive)`);
   } else {
     console.log(`[relay] Session ${sessionId} destroyed`);
   }
@@ -3810,6 +4232,7 @@ var require3 = createRequire2(import.meta.url);
 var { WebSocketServer } = require3("ws");
 var hostname = process.env.OPENSCOUT_WEB_TERMINAL_RELAY_HOST?.trim() || "127.0.0.1";
 var port = Number.parseInt(process.env.OPENSCOUT_WEB_TERMINAL_RELAY_PORT?.trim() || "3201", 10);
+var parentWatchdog = startProcessParentWatchdog(process.env.OPENSCOUT_WEB_RELAY_PARENT_PID);
 var UPLOAD_DIR = "/tmp/scout-uploads";
 var OUTPUT_BATCH_INTERVAL_MS = 8;
 var OUTPUT_BATCH_DRAIN_CONTINUE_MS = 1;
@@ -3969,7 +4392,7 @@ class FlowControlledRelaySocket {
 function sessionMatchesSurface(session, backend, sessionName) {
   if (!backend || !sessionName || session.backend !== backend)
     return false;
-  return session.terminalSession === sessionName || session.tmuxSession === sessionName || session.zellijSession === sessionName;
+  return session.tmuxSession === sessionName || session.zellijSession === sessionName;
 }
 var pendingCommand = null;
 function queueTerminalCommand(input) {
@@ -4058,7 +4481,7 @@ var server = createServer(async (req, res) => {
       return;
     }
     await mkdir(UPLOAD_DIR, { recursive: true, mode: 448 });
-    const filepath = join6(UPLOAD_DIR, `${randomUUID()}-${safeName}`);
+    const filepath = join7(UPLOAD_DIR, `${randomUUID()}-${safeName}`);
     await writeFile(filepath, Buffer.from(body.data, "base64"), { mode: 384 });
     writeJson(res, 200, { path: filepath });
     return;
@@ -4143,7 +4566,13 @@ wss.on("connection", (ws) => {
           }
           relaySocket.bindSession(session);
           sessionId = session.id;
-          send(ws, { type: "session:ready", sessionId: session.id, reconnectToken: session.reconnectToken });
+          send(ws, {
+            type: "session:ready",
+            sessionId: session.id,
+            reconnectToken: session.reconnectToken,
+            cols: session.cols,
+            rows: session.rows
+          });
           if (pending) {
             setTimeout(() => writeSession(session, pending.command + `
 `), 400);
@@ -4172,14 +4601,20 @@ wss.on("connection", (ws) => {
             }
             relaySocket.bindSession(session);
             sessionId = session.id;
-            send(ws, { type: "session:ready", sessionId: session.id, reconnectToken: session.reconnectToken });
+            send(ws, {
+              type: "session:ready",
+              sessionId: session.id,
+              reconnectToken: session.reconnectToken,
+              cols: session.cols,
+              rows: session.rows
+            });
             setTimeout(() => writeSession(session, pending.command + `
 `), 400);
             break;
           }
           const existing = sessions2.get(msg.sessionId);
           const requestedControlMode = msg.controlMode || "owner";
-          const canReconnect = existing && !existing.exited && existing.controlMode === requestedControlMode && verifyReconnectToken(existing, msg.reconnectToken);
+          const canReconnect = existing && !existing.exited && existing.controlMode !== "observe" && existing.controlMode === requestedControlMode && verifyReconnectToken(existing, msg.reconnectToken);
           if (canReconnect) {
             if (sessionId && sessionId !== msg.sessionId) {
               const previous = sessions2.get(sessionId);
@@ -4192,12 +4627,14 @@ wss.on("connection", (ws) => {
             }
             sessionId = existing.id;
             relaySocket.bindSession(existing);
-            attachSession(existing, relaySocket, msg.cols, msg.rows, []);
+            await attachSession(existing, relaySocket, msg.cols, msg.rows, []);
             send(ws, {
               type: "session:ready",
               sessionId: existing.id,
               reconnectToken: existing.reconnectToken,
-              reconnected: true
+              reconnected: true,
+              cols: existing.cols,
+              rows: existing.rows
             });
             if (pending) {
               setTimeout(() => writeSession(existing, pending.command + `
@@ -4230,7 +4667,7 @@ wss.on("connection", (ws) => {
           if (session && sessionOwnsSocket(session, relaySocket)) {
             const cols = Math.max(msg.cols || 80, 20);
             const rows = Math.max(msg.rows || 24, 4);
-            resizeSession(session, cols, rows);
+            await resizeSession(session, cols, rows);
           }
           break;
         }
@@ -4266,7 +4703,13 @@ wss.on("connection", (ws) => {
 server.listen(port, hostname, () => {
   console.log(`[relay] Server listening on http://${hostname}:${port} (HTTP + WebSocket)`);
 });
+var shuttingDown = false;
 var shutdown = () => {
+  if (shuttingDown)
+    return;
+  shuttingDown = true;
+  if (parentWatchdog)
+    clearInterval(parentWatchdog);
   console.log(`
 [relay] Shutting down...`);
   for (const [id] of sessions2) {