@sagentlab/navarch-runtime 0.1.141 → 0.1.143

package/README.md

@@ -592,7 +592,7 @@ unchanged across the deployment.
 | `NAVARCH_MCP_CONFIG_PATH` | — | Path to the platform MCP config passed as `--mcp-config`. |
 | `NAVARCH_WORKTREE_GUARD` | on | Host-mode sessions get an adapter-native per-session worktree boundary guard (see below). Set `off` to disable it for every runtime on the machine — required to run OpenCode or Muse on an already-isolated host. |
 | `NAVARCH_NAVI_CONVERSATIONS` | on | Serve read-only Navi repository conversations on this machine. Only the `claude-code` adapter on the host sandbox with the worktree guard on is supported; `navarch-runtime doctor` prints the `navi_chat:` state and reason. Set `off` to stop polling for conversations. |
-| `NAVARCH_NAVI_WORKSPACE_CHAT` | off | Explicitly enable writable Navi chat on a supported Claude Code host runtime. Owners can choose **Edit and run commands**; automatic permission review and the worktree guard remain active. Commands run on this host, not in a hard sandbox. Changes stay under `<workspaceRoot>/chat-workspaces/<conversationId>/repo` until the operator removes them. See [workspace chat](../docs/navarch/navi-workspace-chat.md). |
+| `NAVARCH_NAVI_WORKSPACE_CHAT` | off | Explicitly enable writable Navi chat on a supported Claude Code or Codex host runtime. Generated host connect and supervise commands for both adapters include it; remove it from both lines to keep chat read-only. Owners can choose **Edit and run commands**; Claude uses automatic permission review and its worktree hook, while Codex uses a native checkout permission profile with escalation disabled. Commands run on this host, not in a hard sandbox. Changes stay under `<workspaceRoot>/chat-workspaces/<conversationId>/repo` until the operator removes them. See [workspace chat](../docs/navarch/navi-workspace-chat.md). |
 | `NAVARCH_CONVERSATION_POLL_MS` | `5000` | Idle poll interval for queued conversation turns (1000–30000). |
 | `NAVARCH_CONVERSATION_MIRROR` | on | Seed new conversation checkouts from a per-repository mirror under `<workspaceRoot>/conversation-mirrors/` (fetch + local clone with independent object files) instead of a full network clone. Set `off` to always clone directly. |
 | `NAVARCH_CONVERSATION_TURN_TIMEOUT_MS` | `540000` | Time limit for one conversation turn's agent process (at most nine minutes). |

package/bin/worktree-guard-hook.cjs

@@ -26,7 +26,10 @@
  *    standard system prefixes (/usr, /etc, ...) so toolchains keep working.
  *  - Bash commands are screened lexically: absolute, `~`/$HOME, and
  *    `..`-traversal path references must land inside the allowed roots or
- *    the system prefixes. This cannot catch every obfuscated escape (shell
+ *    the system prefixes. Slash-led text that cannot name an existing root
+ *    entry (routes, regex, sed addresses) and bare root text inside heredoc
+ *    or quoted program bodies are not paths (extractBashPathCandidates).
+ *    This cannot catch every obfuscated escape (shell
  *    is Turing-complete) — it is a strong guardrail, not a security
  *    boundary. Operators needing a hard boundary should use
  *    NAVARCH_SANDBOX_MODE=docker (sandbox.cts).
@@ -311,23 +314,417 @@ function isCommentOrMarkupToken(command, start, token) {
   return token === "//" && /\S/.test(command.slice(end));
 }
 
+let rootEntries;
+
+/** Entry names at the filesystem root, or null when they cannot be listed. */
+function listRootEntries() {
+  if (rootEntries === undefined) {
+    try {
+      rootEntries = fs.readdirSync(path.parse(process.cwd()).root);
+    } catch {
+      rootEntries = null;
+    }
+  }
+  return rootEntries;
+}
+
+/**
+ * Glob segment to a case-insensitive regex source, as a superset of what the
+ * shell could match: `*` is `.*`, `?` and any bracket expression are `.`, and
+ * a backslash makes the next character literal.
+ */
+function globSegmentToRegexSource(segment) {
+  let source = "";
+  for (let i = 0; i < segment.length; i++) {
+    const ch = segment[i];
+    if (ch === "\\" && i + 1 < segment.length) {
+      source += segment[++i].replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
+    } else if (ch === "*") {
+      source += ".*";
+    } else if (ch === "?") {
+      source += ".";
+    } else if (ch === "[" && segment.indexOf("]", i + 2) !== -1) {
+      source += ".";
+      i = segment.indexOf("]", i + 2);
+    } else {
+      source += ch.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
+    }
+  }
+  return source;
+}
+
+/**
+ * False only when an absolute token cannot reach any existing location: its
+ * first segment neither names nor glob-matches an entry at the filesystem
+ * root. URL routes (`/dev-preview/knowledge`), regex literals (`/^export/`,
+ * `/v[0-9]+`) and sed addresses (`/pattern/,/^}/p`) fall here, while
+ * `/Users/...`, `/home/...`, `/*` and the bare root stay candidates. A first
+ * segment that expansion could change (`$`, `{`, `(` outside the quotes that
+ * make them literal, `.`/`..` segments) stays a candidate, and so does one
+ * that ends in a backslash, which can continue the word onto the next line.
+ * When a quote or backtick follows the token, the shell word may continue, so
+ * an unterminated first segment is matched as a prefix. `quote` is the plain
+ * quote character around the token when a text or program command reads the
+ * word, or "" otherwise.
+ */
+function mayNameRootEntry(token, nextChar, quote) {
+  const segment = token.replace(/^\/+/, "").split("/")[0];
+  if (segment === "") return true;
+  const expanding = quote === "'" ? null : quote === '"' ? /\$/ : /[$({]/;
+  if (expanding && expanding.test(segment)) return true;
+  if (/(^|[^\\])(\\\\)*\\$/.test(segment)) return true;
+  if (/(^|\/)\.\.?(\/|$)/.test(token)) return true;
+  const entries = listRootEntries();
+  if (!entries) return true;
+  const terminated = token.replace(/^\/+/, "").includes("/");
+  const continues = nextChar === "'" || nextChar === '"' || nextChar === "`";
+  const anchor = new RegExp(
+    `^${globSegmentToRegexSource(segment)}${terminated || !continues ? "$" : ""}`,
+    "i",
+  );
+  return entries.some((entry) => anchor.test(entry));
+}
+
+/**
+ * Commands that only read, filter or print text and never run it. Bare root
+ * text (`/`, `//`, `/*`, `/**`) in their heredoc or quoted argument is prose,
+ * a comment, or an operator rather than a path argument.
+ */
+const TEXT_COMMANDS = new Set([
+  "base64",
+  "cat",
+  "diff",
+  "egrep",
+  "envsubst",
+  "fgrep",
+  "grep",
+  "head",
+  "jq",
+  "rg",
+  "sort",
+  "tail",
+  "tee",
+  "uniq",
+  "wc",
+  "yq",
+]);
+
+/**
+ * Commands that may share a command with an exempted text without running
+ * it. Their own quoted arguments get no exemption, so `echo '.a // x'` and
+ * `ls "/"` stay screened.
+ */
+const CHAINABLE_COMMANDS = new Set([...TEXT_COMMANDS, "cd", "echo", "ls", "mkdir", "printf", "pwd", "true"]);
+
+/**
+ * Commands whose single-quoted arguments are literal patterns, so `$`, `(` and
+ * `{` there do not expand (`sed '/^$/d'`, `awk '/^$/'`). This affects only the
+ * root-entry test; these commands get no bare-root text exemption.
+ */
+const LITERAL_PATTERN_COMMANDS = new Set([...CHAINABLE_COMMANDS, "sed", "awk", "gawk", "mawk", "nawk"]);
+
+/**
+ * Non-shell interpreters whose program body may hold bare root text as a
+ * comment or operator (`a // b`, `/* x *\/`, `"/".join`). A body that can
+ * start a process (PROGRAM_SHELL_RE) gets no exemption. Languages that pipe
+ * to commands in plain syntax (awk, perl, ruby, psql, sqlite3) are excluded.
+ */
+const PROGRAM_COMMANDS = new Set(["bun", "deno", "node", "python", "python3", "tsx"]);
+
+const PROGRAM_SHELL_RE = /system|subprocess|popen|exec|spawn|child_process|shell|pty|command|\.run\b|`/i;
+
+/**
+ * git and gh run aliases, hooks and extensions through a shell, so only the
+ * message text of message subcommands is exempt: a quoted message-flag value,
+ * or a heredoc read through `--body-file`/`-F`/`--file`.
+ */
+const MESSAGE_SUBCOMMAND_RE =
+  /^\s*(?:git\s+(?:commit|tag|notes|merge)|gh\s+(?:pr|issue|release)\s+(?:create|edit|comment|review|close))\b/;
+const MESSAGE_FLAG_RE = /\s(?:-m|--message|-t|--title|-b|--body|--notes)(?:=|\s+)$/;
+const MESSAGE_FILE_RE = /\s(?:--body-file|-F|--file)(?:=|\s)/;
+
+const ASSIGNMENTS_RE = /^\s*!?\s*(?:[A-Za-z_]\w*=\S*\s+)*/;
+const LEADING_REDIRECTS_RE = /^(?:\s*\d*(?:<<?|>>?|&>>?)&?\s*[^\s;|&<>()]+)*\s*/;
+
+/** Command word of a simple-command prefix, without assignments or a directory. */
+function commandWordOf(segment) {
+  const rest = segment.replace(ASSIGNMENTS_RE, "");
+  const word = /^[^\s;|&<>()'"`]+/.exec(rest);
+  if (!word) return "";
+  return path.posix.basename(word[0]).replace(/^(python3)\.\d+$/, "$1");
+}
+
+/**
+ * Classifies the simple command starting at `start`: "empty" (nothing runs),
+ * "text" (a CHAINABLE_COMMANDS command), "active" (a PROGRAM_COMMANDS interpreter
+ * or a git/gh message subcommand), or "unsafe" (anything else, including a
+ * command word that starts with a quote, `$` or a backtick).
+ */
+function classifySegment(command, start) {
+  const end = command.slice(start).search(/[;|&\n()`]/);
+  const text = command.slice(start, end === -1 ? command.length : start + end);
+  const rest = text.replace(ASSIGNMENTS_RE, "").replace(LEADING_REDIRECTS_RE, "");
+  if (rest === "" || /^[)]/.test(command.slice(start).replace(ASSIGNMENTS_RE, ""))) return "empty";
+  const word = commandWordOf(rest);
+  if (CHAINABLE_COMMANDS.has(word)) return "text";
+  if (PROGRAM_COMMANDS.has(word)) return "active";
+  if (MESSAGE_SUBCOMMAND_RE.test(rest) && !/\s-c\s|alias/.test(command)) return "active";
+  return "unsafe";
+}
+
+/** Text of the simple command starting at `start`, up to its first separator. */
+function segmentText(command, start) {
+  const end = command.slice(start).search(/[;|&\n()`]/);
+  return command.slice(start, end === -1 ? command.length : start + end);
+}
+
+/**
+ * True when nothing else in the command can run text that an exempted body or
+ * argument supplies. Every command must be chainable text or empty, and no
+ * text may name a git or husky hook location. An active command must be the
+ * only command, without leading assignments (`GIT_EDITOR=sh`) or an editor
+ * flag. A git/gh message command may additionally take `cat`, `echo` or
+ * `printf` output through `$(...)` when those write no file
+ * (`--body "$(cat <<'EOF' ... )"`).
+ */
+function exemptionContextIsSafe(command, segments) {
+  if (/\.git\/|\.husky|hooks/i.test(command)) return false;
+  const classes = segments.map((segment) => ({ ...segment, kind: classifySegment(command, segment.at) }));
+  if (classes.some(({ kind }) => kind === "unsafe")) return false;
+  const active = classes.filter(({ kind }) => kind === "active");
+  if (active.length === 0) return true;
+  if (active.length > 1) return false;
+  const activeText = segmentText(command, active[0].at);
+  if (activeText.replace(ASSIGNMENTS_RE, "") !== activeText.trimStart()) return false;
+  const isMessage = MESSAGE_SUBCOMMAND_RE.test(activeText);
+  // git accepts unique long-option prefixes, so `--ed` also opens the editor.
+  if (isMessage && /\s(?:-e|--ed(?:i(?:t(?:or)?)?)?)(?:[\s=]|$)/.test(activeText)) return false;
+  return classes.every(({ at, kind, nested }) => {
+    if (kind === "empty" || kind === "active") return true;
+    if (!isMessage || !nested) return false;
+    const text = segmentText(command, at).replace(ASSIGNMENTS_RE, "");
+    return /^(?:cat|echo|printf)\b/.test(text) && !/>/.test(text);
+  });
+}
+
+/** True for root-only text: `/`, `//`, `/*`, `/**`, `/=`, `//=`. */
+function isBareRootText(token) {
+  return /^\/+\**=?$/.test(token);
+}
+
+/**
+ * Heredoc bodies as [{start, end, word, segment, quoted}], every simple
+ * command outside them as [{at, nested}] (nested inside `$(`, a backtick or a
+ * subshell), and `ok`. A small lexer tracks single and double quotes, `$(`,
+ * backticks, subshells and shell comments to find each `<<` operator and its
+ * body. Any construct it cannot follow (`$'`, arithmetic `((`, process
+ * substitution `<(`/`>(`, a delimiter with `$` or an unbalanced quote, an
+ * unterminated quote, substitution or heredoc, an unbalanced `)`) returns
+ * `ok: false`, so nothing is exempted on a misread.
+ */
+function scanHeredocs(command) {
+  const failed = { ok: false, bodies: [], segments: [] };
+  const bodies = [];
+  const segments = [{ at: 0, nested: false }];
+  const stack = [];
+  let pending = [];
+  let segmentStart = 0;
+  const startSegment = (at) => {
+    segmentStart = at;
+    segments.push({ at, nested: stack.some((frame) => frame !== "dq") });
+  };
+  let i = 0;
+  const n = command.length;
+  while (i < n) {
+    const ch = command[i];
+    const top = stack[stack.length - 1];
+    if (top === "dq") {
+      if (ch === "\\") i += 2;
+      else if (ch === '"') {
+        stack.pop();
+        i++;
+      } else if (ch === "$" && command[i + 1] === "(") {
+        if (command[i + 2] === "(") return failed;
+        stack.push("sub");
+        i += 2;
+        startSegment(i);
+      } else if (ch === "`") {
+        stack.push("bt");
+        i++;
+        startSegment(i);
+      } else i++;
+      continue;
+    }
+    if (ch === "\\") {
+      i += 2;
+      continue;
+    }
+    if (ch === "'") {
+      const close = command.indexOf("'", i + 1);
+      if (close === -1) return failed;
+      i = close + 1;
+      continue;
+    }
+    if (ch === '"') {
+      stack.push("dq");
+      i++;
+      continue;
+    }
+    if (ch === "$" && command[i + 1] === "'") return failed;
+    if (ch === "$" && command[i + 1] === "(") {
+      if (command[i + 2] === "(") return failed;
+      stack.push("sub");
+      i += 2;
+      startSegment(i);
+      continue;
+    }
+    if (ch === "(") {
+      if (command[i + 1] === "(" || command[i - 1] === "<" || command[i - 1] === ">") return failed;
+      stack.push("sub");
+      startSegment(++i);
+      continue;
+    }
+    if (ch === ")") {
+      if (top !== "sub") return failed;
+      stack.pop();
+      i++;
+      continue;
+    }
+    if (ch === "`") {
+      if (top === "bt") stack.pop();
+      else stack.push("bt");
+      startSegment(++i);
+      continue;
+    }
+    if (ch === "#" && (i === 0 || /[\s;|&()`]/.test(command[i - 1]))) {
+      const newline = command.indexOf("\n", i);
+      i = newline === -1 ? n : newline;
+      continue;
+    }
+    if (ch === ";" || ch === "|" || ch === "&") {
+      startSegment(++i);
+      continue;
+    }
+    if (ch === "<" && command[i + 1] === "<") {
+      if (command[i + 2] === "<") {
+        i += 3;
+        continue;
+      }
+      let j = i + 2;
+      const stripTabs = command[j] === "-";
+      if (stripTabs) j++;
+      while (command[j] === " " || command[j] === "\t") j++;
+      const word = /^[^\s;|&<>()]+/.exec(command.slice(j));
+      if (!word) return failed;
+      const delimiter = word[0].replace(/['"\\]/g, "");
+      if (!delimiter || delimiter.includes("$")) return failed;
+      if ((word[0].split("'").length - 1) % 2 !== 0) return failed;
+      if ((word[0].split('"').length - 1) % 2 !== 0) return failed;
+      const lineEnd = command.indexOf("\n", i);
+      pending.push({
+        delimiter,
+        stripTabs,
+        quoted: /['"\\]/.test(word[0]),
+        word: commandWordOf(command.slice(segmentStart, i)),
+        segment: command.slice(segmentStart, lineEnd === -1 ? n : lineEnd),
+      });
+      i = j + word[0].length;
+      continue;
+    }
+    if (ch === "\n") {
+      i++;
+      for (const doc of pending) {
+        const start = i;
+        let end = -1;
+        while (i <= n) {
+          const newline = command.indexOf("\n", i);
+          const lineEnd = newline === -1 ? n : newline;
+          let line = command.slice(i, lineEnd);
+          if (doc.stripTabs) line = line.replace(/^\t+/, "");
+          const lineStart = i;
+          i = newline === -1 ? n + 1 : newline + 1;
+          if (line === doc.delimiter) {
+            end = lineStart;
+            break;
+          }
+          if (newline === -1) break;
+        }
+        if (end === -1) return failed;
+        bodies.push({ start, end, word: doc.word, segment: doc.segment, quoted: doc.quoted });
+      }
+      if (i > n) i = n;
+      pending = [];
+      startSegment(i);
+      continue;
+    }
+    i++;
+  }
+  if (stack.length > 0 || pending.length > 0) return failed;
+  return { ok: true, bodies, segments };
+}
+
+/**
+ * True when the command in `segment` reads `text` as plain text, as a
+ * non-shell program that cannot start a process, or as a git/gh message.
+ */
+function readsAsText(segment, text, isMessage) {
+  const word = commandWordOf(segment);
+  if (TEXT_COMMANDS.has(word)) return true;
+  if (PROGRAM_COMMANDS.has(word)) return !PROGRAM_SHELL_RE.test(text);
+  return MESSAGE_SUBCOMMAND_RE.test(segment.replace(ASSIGNMENTS_RE, "")) && isMessage;
+}
+
+/**
+ * True when bare root text sits in a heredoc body or quoted argument that a
+ * text command, a non-shell program, or a git/gh message reads: a
+ * `// comment` or `a / b` prose in `cat <<'EOF'`,
+ * `gh pr create --body-file - <<'EOF'` or `python3 -c "print(a // b)"`. The
+ * quoted argument must hold more than the token itself, so `ls "/"` stays
+ * screened. An unquoted-delimiter heredoc qualifies only without `$(` or
+ * backtick expansion in its body. No exemption applies unless the rest of the
+ * command cannot run that text (exemptionContextIsSafe).
+ */
+function isProgramTextRootToken(command, start, token, heredocs) {
+  if (!isBareRootText(token)) return false;
+  const { ok, bodies, segments } = heredocs();
+  if (!ok || !exemptionContextIsSafe(command, segments)) return false;
+  const body = bodies.find((doc) => start >= doc.start && start < doc.end);
+  if (body) {
+    const text = command.slice(body.start, body.end);
+    if (!body.quoted && /`|\$\(/.test(text)) return false;
+    return readsAsText(body.segment, text, MESSAGE_FILE_RE.test(body.segment));
+  }
+  const span = quotedSpanAt(command, start);
+  if (!span) return false;
+  const text = command.slice(span[0] + 1, span[1]);
+  if (text.trim() === token) return false;
+  const prefix = command.slice(span[2], span[0]);
+  return readsAsText(prefix, text, MESSAGE_FLAG_RE.test(prefix));
+}
+
 /**
  * Pulls path-like references out of a shell command: absolute paths,
  * home-anchored paths (`~...`, `$HOME/...`), and relative `..` traversals.
  * Lexical by design — see the file header for why this is a guardrail, not
  * a parser. URLs survive untouched (the char before `//` in `https://` is
  * `:`, which is not a path delimiter here). Comment and markup text that
- * merely starts with "/" (`/** doc *\/`, `// note`, `</p>`) is not a path.
+ * merely starts with "/" (`/** doc *\/`, `// note`, `</p>`) is not a path,
+ * nor is a token whose first segment names nothing at the filesystem root
+ * (routes, regex and sed text), nor bare root text in a heredoc or quoted
+ * program body (isProgramTextRootToken).
  */
 function extractBashPathCandidates(command) {
   const candidates = [];
   const seen = new Set();
+  const clean = (raw) => raw.replace(/[)\]}"'`,]+$/, "");
   const add = (raw) => {
-    const cleaned = raw.replace(/[)\]}"'`,]+$/, "");
+    const cleaned = clean(raw);
     if (!cleaned || seen.has(cleaned)) return;
     seen.add(cleaned);
     candidates.push(cleaned);
   };
+  let heredocs;
+  const getHeredocs = () => (heredocs ??= scanHeredocs(command));
 
   const absoluteRe = /(?:^|[\s'"`=(<>;|&])(\/[^\s'"`<>;|&)]*)/g;
   const homeRe = /(?:^|[\s'"`=(<>;|&])((?:~|\$\{?HOME\}?)[^\s'"`<>;|&)]*)/g;
@@ -335,6 +732,14 @@ function extractBashPathCandidates(command) {
   while ((match = absoluteRe.exec(command))) {
     const start = match.index + match[0].length - match[1].length;
     if (isCommentOrMarkupToken(command, start, match[1])) continue;
+    const token = clean(match[1]);
+    // Quotes keep `$`, `(` and `{` literal only for a command that does not
+    // hand the word to a shell, such as `sed '/^$/d'`; `sh -c '... /$D'` expands.
+    const span = quotedSpanAt(command, start);
+    const word = span ? commandWordOf(command.slice(span[2], span[0])) : "";
+    const quote = LITERAL_PATTERN_COMMANDS.has(word) ? command[span[0]] : "";
+    if (!mayNameRootEntry(token, command[start + match[1].length], quote)) continue;
+    if (isProgramTextRootToken(command, start, token, getHeredocs)) continue;
     add(match[1]);
   }
   while ((match = homeRe.exec(command))) add(match[1]);

package/dist/adapters/claude-conversation.cjs

@@ -3,10 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.claudeConversationRunner = exports.ClaudeStreamParser = exports.CLAUDE_WORKSPACE_TOOLS = exports.CLAUDE_CONVERSATION_TOOLS = void 0;
 exports.claudeConversationArgs = claudeConversationArgs;
 exports.runClaudeConversationTurn = runClaudeConversationTurn;
-const node_child_process_1 = require("node:child_process");
-const node_perf_hooks_1 = require("node:perf_hooks");
-const kill_agent_cjs_1 = require("../kill-agent.cjs");
-const session_processes_cjs_1 = require("../session-processes.cjs");
+const conversation_process_cjs_1 = require("./conversation-process.cjs");
 /**
  * Read-only tools a Navi repository question may use. Anything not listed
  * (Bash, Edit, Write, WebFetch, Task, MCP tools) is absent from the model's
@@ -17,7 +14,6 @@ const session_processes_cjs_1 = require("../session-processes.cjs");
  */
 exports.CLAUDE_CONVERSATION_TOOLS = "Read,Grep,Glob";
 exports.CLAUDE_WORKSPACE_TOOLS = "Read,Grep,Glob,Edit,Write,Bash";
-const STDERR_TAIL_BYTES = 8 * 1024;
 /**
  * Incremental parser for `claude -p --output-format stream-json --verbose
  * --include-partial-messages`. Chunks may split a record anywhere. Text is
@@ -194,90 +190,17 @@ function claudeConversationArgs(options) {
     return args;
 }
 async function runClaudeConversationTurn(options) {
-    const idle = (aborted) => ({
-        exitCode: null, timedOut: false, aborted, succeeded: false, firstEventMs: null, firstTextMs: null, stderr: "",
-    });
-    if (options.signal.aborted)
-        return idle(true);
-    const startedAt = node_perf_hooks_1.performance.now();
-    let firstEventMs = null;
-    let firstTextMs = null;
-    let timedOut = false;
-    let aborted = false;
-    let closed = false;
-    let stderr = "";
-    const deliver = (event) => {
-        // After stop, timeout or exit, late output must not reach the caller.
-        if (closed || aborted || timedOut)
-            return;
-        if (event.type === "text" && firstTextMs === null)
-            firstTextMs = node_perf_hooks_1.performance.now() - startedAt;
-        options.onEvent(event);
-    };
-    const parser = new ClaudeStreamParser(deliver, () => {
-        if (firstEventMs === null)
-            firstEventMs = node_perf_hooks_1.performance.now() - startedAt;
-    });
-    return new Promise((resolve) => {
-        const child = (0, node_child_process_1.spawn)(options.bin, claudeConversationArgs(options), {
-            detached: process.platform !== "win32",
-            cwd: options.cwd,
-            env: options.env,
-            stdio: ["pipe", "pipe", "pipe"],
-        });
-        child.stdin?.on("error", () => undefined);
-        child.stdin?.end(options.prompt);
-        options.onProcessStarted?.(child.pid);
-        const timer = options.timeoutMs > 0 ? setTimeout(() => {
-            timedOut = true;
-            (0, kill_agent_cjs_1.killAgent)(child);
-        }, options.timeoutMs) : undefined;
-        const onAbort = () => {
-            aborted = true;
-            (0, kill_agent_cjs_1.killAgent)(child);
-        };
-        options.signal.addEventListener("abort", onAbort, { once: true });
-        child.stdout.setEncoding("utf8");
-        child.stdout.on("data", (chunk) => {
-            parser.push(chunk);
-        });
-        child.stderr.setEncoding("utf8");
-        child.stderr.on("data", (chunk) => {
-            stderr = (stderr + chunk).slice(-STDERR_TAIL_BYTES);
-        });
-        const finish = (exitCode) => {
-            if (closed)
-                return;
-            parser.flush();
-            // An answer delivered only in the final result record (no stream deltas).
-            if (!parser.hasEmittedText && parser.result && !parser.result.isError && parser.result.text) {
-                deliver({ type: "text", text: parser.result.text });
-            }
-            closed = true;
-            clearTimeout(timer);
-            options.signal.removeEventListener("abort", onAbort);
-            resolve({
-                exitCode, timedOut, aborted,
-                succeeded: exitCode === 0 && !aborted && !timedOut && !!parser.result && !parser.result.isError,
-                firstEventMs, firstTextMs, stderr,
-            });
+    return (0, conversation_process_cjs_1.runConversationProcess)(options, claudeConversationArgs(options), (emit, onRecord) => {
+        const parser = new ClaudeStreamParser(emit, onRecord);
+        return {
+            push: (chunk) => parser.push(chunk),
+            flush: () => {
+                parser.flush();
+                if (!parser.hasEmittedText && parser.result && !parser.result.isError && parser.result.text)
+                    emit({ type: "text", text: parser.result.text });
+            },
+            get succeeded() { return !!parser.result && !parser.result.isError; },
         };
-        child.on("error", (err) => {
-            stderr = (stderr + `\n${String(err)}`).slice(-STDERR_TAIL_BYTES);
-            finish(null);
-        });
-        let cleanup = Promise.resolve();
-        child.on("exit", () => {
-            if (options.mode !== "workspace")
-                return;
-            (0, kill_agent_cjs_1.killAgent)(child);
-            // Start on exit, not close: a detached tool may still hold the output
-            // pipes open. Reap only this checkout before acknowledging the turn.
-            cleanup = (0, session_processes_cjs_1.reapSessionProcesses)(options.cwd);
-        });
-        child.on("close", (code) => { void cleanup.then(() => finish(code)); });
-        if (options.signal.aborted)
-            onAbort();
     });
 }
 exports.claudeConversationRunner = { run: runClaudeConversationTurn };

package/dist/adapters/codex-conversation.cjs

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.codexConversationRunner = exports.CodexConversationParser = void 0;
+exports.codexConversationArgs = codexConversationArgs;
+const conversation_process_cjs_1 = require("./conversation-process.cjs");
+/** Codex emits completed assistant messages; reasoning and command output stay local. */
+class CodexConversationParser {
+    emit;
+    onRecord;
+    buffer = "";
+    emitted = false;
+    seen = new Set();
+    completed = false;
+    failed = false;
+    get succeeded() { return this.completed && !this.failed; }
+    constructor(emit, onRecord = () => undefined) {
+        this.emit = emit;
+        this.onRecord = onRecord;
+    }
+    push(chunk) {
+        this.buffer += chunk;
+        if (this.buffer.length > 2_000_000) {
+            this.failed = true;
+            this.buffer = "";
+            return;
+        }
+        let end;
+        while ((end = this.buffer.indexOf("\n")) >= 0) {
+            this.record(this.buffer.slice(0, end));
+            this.buffer = this.buffer.slice(end + 1);
+        }
+    }
+    flush() { if (this.buffer.trim())
+        this.record(this.buffer); this.buffer = ""; }
+    record(line) {
+        let event;
+        try {
+            event = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (!event || typeof event !== "object")
+            return;
+        this.onRecord();
+        if (event.type === "turn.failed" || event.type === "error") {
+            this.failed = true;
+            this.emit({ type: "failure", reason: "codex_turn_failed" });
+        }
+        else if (event.type === "turn.completed")
+            this.completed = true;
+        else if (event.type === "item.completed") {
+            const item = event.item;
+            if (item?.type !== "agent_message" || typeof item.text !== "string" || !item.text)
+                return;
+            if (typeof item.id === "string") {
+                if (this.seen.has(item.id))
+                    return;
+                this.seen.add(item.id);
+            }
+            this.emit({ type: "text", text: `${this.emitted ? "\n\n" : ""}${item.text}` });
+            this.emitted = true;
+        }
+    }
+}
+exports.CodexConversationParser = CodexConversationParser;
+function codexConversationArgs(options) {
+    if (!options.codexGuardArgs?.length)
+        throw new Error("Codex chat requires a native checkout permission profile.");
+    if (options.mode && options.mode !== "read_only" && options.mode !== "workspace")
+        throw new Error("Unknown conversation mode.");
+    return [
+        "exec", "-", "--json", "--ephemeral", "--ignore-rules",
+        ...options.codexGuardArgs,
+        "-c", 'approval_policy="never"',
+        "-c", `projects.${JSON.stringify(options.cwd)}.trust_level="untrusted"`,
+        "-c", 'mcp_servers={}',
+        "-c", 'features.multi_agent=false',
+        "-c", 'web_search="disabled"',
+        ...(options.model ? ["--model", options.model] : []),
+    ];
+}
+exports.codexConversationRunner = {
+    run: (options) => (0, conversation_process_cjs_1.runConversationProcess)(options, codexConversationArgs(options), (emit, onRecord) => new CodexConversationParser(emit, onRecord)),
+};

package/dist/adapters/codex.cjs

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.codexAdapter = void 0;
 exports.runCodexAdapter = runCodexAdapter;
 exports.hasExplicitPermissionPolicy = hasExplicitPermissionPolicy;
+const codex_conversation_cjs_1 = require("./codex-conversation.cjs");
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
 const exit_conditions_cjs_1 = require("../exit-conditions.cjs");
@@ -368,6 +369,7 @@ function shellQuote(value) {
 exports.codexAdapter = {
     agentType: "codex",
     run: runCodexAdapter,
+    conversation: codex_conversation_cjs_1.codexConversationRunner,
     resumesTurns: true,
     steering: types_cjs_1.TURN_RESTART_STEERING,
     // `exec resume` reports the thread's total_token_usage, not the turn's.

package/dist/adapters/conversation-process.cjs

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runConversationProcess = runConversationProcess;
+const node_child_process_1 = require("node:child_process");
+const node_perf_hooks_1 = require("node:perf_hooks");
+const kill_agent_cjs_1 = require("../kill-agent.cjs");
+const session_processes_cjs_1 = require("../session-processes.cjs");
+const STDERR_TAIL_BYTES = 8 * 1024;
+async function runConversationProcess(options, args, makeParser) {
+    const idle = (aborted) => ({
+        exitCode: null, timedOut: false, aborted, succeeded: false, firstEventMs: null, firstTextMs: null, stderr: "",
+    });
+    if (options.signal.aborted)
+        return idle(true);
+    const startedAt = node_perf_hooks_1.performance.now();
+    let firstEventMs = null;
+    let firstTextMs = null;
+    let timedOut = false;
+    let aborted = false;
+    let closed = false;
+    let stderr = "";
+    const deliver = (event) => {
+        // After stop, timeout or exit, late output must not reach the caller.
+        if (closed || aborted || timedOut)
+            return;
+        if (event.type === "text" && firstTextMs === null)
+            firstTextMs = node_perf_hooks_1.performance.now() - startedAt;
+        options.onEvent(event);
+    };
+    const parser = makeParser(deliver, () => {
+        if (firstEventMs === null)
+            firstEventMs = node_perf_hooks_1.performance.now() - startedAt;
+    });
+    return new Promise((resolve) => {
+        const child = (0, node_child_process_1.spawn)(options.bin, args, {
+            detached: process.platform !== "win32",
+            cwd: options.cwd,
+            env: options.env,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        child.stdin?.on("error", () => undefined);
+        child.stdin?.end(options.prompt);
+        options.onProcessStarted?.(child.pid);
+        const timer = options.timeoutMs > 0 ? setTimeout(() => {
+            timedOut = true;
+            (0, kill_agent_cjs_1.killAgent)(child);
+        }, options.timeoutMs) : undefined;
+        const onAbort = () => {
+            aborted = true;
+            (0, kill_agent_cjs_1.killAgent)(child);
+        };
+        options.signal.addEventListener("abort", onAbort, { once: true });
+        child.stdout.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => {
+            parser.push(chunk);
+        });
+        child.stderr.setEncoding("utf8");
+        child.stderr.on("data", (chunk) => {
+            stderr = (stderr + chunk).slice(-STDERR_TAIL_BYTES);
+        });
+        const finish = (exitCode) => {
+            if (closed)
+                return;
+            parser.flush();
+            closed = true;
+            clearTimeout(timer);
+            options.signal.removeEventListener("abort", onAbort);
+            resolve({
+                exitCode, timedOut, aborted,
+                succeeded: exitCode === 0 && !aborted && !timedOut && parser.succeeded,
+                firstEventMs, firstTextMs, stderr,
+            });
+        };
+        child.on("error", (err) => {
+            stderr = (stderr + `\n${String(err)}`).slice(-STDERR_TAIL_BYTES);
+            finish(null);
+        });
+        let cleanup = Promise.resolve();
+        child.on("exit", () => {
+            if (options.mode !== "workspace")
+                return;
+            (0, kill_agent_cjs_1.killAgent)(child);
+            // Start on exit, not close: a detached tool may still hold the output
+            // pipes open. Reap only this checkout before acknowledging the turn.
+            cleanup = (0, session_processes_cjs_1.reapSessionProcesses)(options.cwd);
+        });
+        child.on("close", (code) => { void cleanup.then(() => finish(code)); });
+        if (options.signal.aborted)
+            onAbort();
+    });
+}

package/dist/conversation/loop.cjs

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ConversationLoop = void 0;
+const node_fs_1 = require("node:fs");
 const index_cjs_1 = require("../adapters/index.cjs");
 const logger_cjs_1 = require("../logger.cjs");
 const worktree_guard_cjs_1 = require("../worktree-guard.cjs");
@@ -216,7 +217,7 @@ class ConversationLoop {
             machineId,
             journal: this.journal,
             adapter: (0, index_cjs_1.selectAdapter)(config.agentType),
-            bin: config.claudeBin,
+            bin: config.agentType === "codex" ? config.codexBin : config.claudeBin,
             ...(config.model ? { model: config.model } : {}),
             env,
             turnTimeoutMs: config.conversationTurnTimeoutMs,
@@ -230,6 +231,19 @@ class ConversationLoop {
                     ...(this.options.gitRunner ? { runner: this.options.gitRunner } : {}),
                     ...(this.mirrors ? { mirrors: this.mirrors } : {}),
                 });
+                if (config.agentType === "codex") {
+                    const tmp = (0, worktree_guard_cjs_1.sessionCodexTmpDir)(workspace.metaDir);
+                    await node_fs_1.promises.mkdir(tmp, { recursive: true, mode: 0o700 });
+                    return {
+                        cwd: workspace.checkout, settingsPath: null, env: { TMPDIR: tmp, TMP: tmp, TEMP: tmp },
+                        codexGuardArgs: (0, worktree_guard_cjs_1.codexWorktreeGuardArgs)({
+                            workDir: workspace.metaDir, worktreePath: workspace.checkout,
+                            repositoryPath: workspace.checkout, workspaceRoot: config.workspaceRoot,
+                            // Chat never imports operator extra roots or task credentials.
+                            codexBin: config.codexBin, readOnly: mode !== "workspace",
+                        }),
+                    };
+                }
                 const guard = await (0, worktree_guard_cjs_1.prepareWorktreeGuard)({
                     workDir: workspace.metaDir,
                     worktreePath: workspace.checkout,

package/dist/conversation/prompt.cjs

@@ -32,7 +32,7 @@ const WORKSPACE_INSTRUCTIONS = [
  * session, so a follow-up works the same after a runtime restart and no
  * unbounded transcript is kept on disk.
  */
-function buildConversationPrompt(snapshot, turnId) {
+function buildConversationPrompt(snapshot, turnId, readCommands = false) {
     const index = snapshot.turns.findIndex((turn) => turn.id === turnId);
     const current = snapshot.turns[index];
     if (!current || current.status !== "running")
@@ -56,7 +56,9 @@ function buildConversationPrompt(snapshot, turnId) {
     }
     const omitted = prior.length - kept.length;
     return [
-        snapshot.mode === "workspace" ? WORKSPACE_INSTRUCTIONS : INSTRUCTIONS,
+        snapshot.mode === "workspace" ? WORKSPACE_INSTRUCTIONS : readCommands
+            ? INSTRUCTIONS.replace("You cannot edit files, run commands,", "You may run sandboxed read-only inspection commands. You cannot edit files, run mutating commands,")
+            : INSTRUCTIONS,
         kept.length || omitted
             ? `\nEarlier conversation${omitted ? ` (${omitted} older turn${omitted === 1 ? "" : "s"} omitted)` : ""}:\n${kept.join("\n\n")}`
             : "",

package/dist/conversation/turn-runner.cjs

@@ -297,7 +297,7 @@ async function runConversationTurn(deps, conversationId, turnId) {
                 throw new Error("Unknown conversation mode");
             if (snapshot.mode === "workspace" && !deps.workspaceEnabled)
                 throw new Error("Workspace chat is disabled on this machine");
-            prompt = (0, prompt_cjs_1.buildConversationPrompt)(snapshot, journal.turnId);
+            prompt = (0, prompt_cjs_1.buildConversationPrompt)(snapshot, journal.turnId, deps.adapter.agentType === "codex");
             // Older servers omit the working branch: the checkout stays on the default branch.
             const workingBranch = (0, workspace_cjs_1.validWorkingBranch)(claim.workingBranch);
             prepared = await deps.prepareWorkspace({ conversationId, repositoryUrl, workingBranch, mode: snapshot.mode ?? "read_only", signal: controller.signal });
@@ -313,7 +313,7 @@ async function runConversationTurn(deps, conversationId, turnId) {
             run.launchedAt = node_perf_hooks_1.performance.now();
             const result = await deps.adapter.conversation.run({
                 prompt, bin: deps.bin, ...(deps.model ? { model: deps.model } : {}),
-                cwd: prepared.cwd, env: deps.env, settingsPath: prepared.settingsPath, mode: snapshot?.mode ?? "read_only",
+                cwd: prepared.cwd, env: { ...deps.env, ...prepared.env }, settingsPath: prepared.settingsPath, codexGuardArgs: prepared.codexGuardArgs, mode: snapshot?.mode ?? "read_only",
                 timeoutMs: deps.turnTimeoutMs, signal: controller.signal, onEvent,
             });
             metrics = { firstEventMs: result.firstEventMs, firstTextMs: result.firstTextMs };

package/dist/worktree-guard.cjs

@@ -423,8 +423,8 @@ function codexWorktreeGuardArgs(options, platform = process.platform) {
                 ":slash_tmp": "write",
                 [workspaceRoot]: "deny",
             }),
-        [node_path_1.default.resolve(options.worktreePath)]: "write",
-        [node_path_1.default.resolve(options.repositoryPath)]: "write",
+        [node_path_1.default.resolve(options.worktreePath)]: options.readOnly ? "read" : "write",
+        [node_path_1.default.resolve(options.repositoryPath)]: options.readOnly ? "read" : "write",
         [sessionGhConfigDir(options.workDir)]: "read",
     };
     // git runs the credential helper inside the sandbox. Without these grants
@@ -443,7 +443,7 @@ function codexWorktreeGuardArgs(options, platform = process.platform) {
     // the runtime-created gitdir explicitly, without reopening session metadata.
     const gitdir = linkedWorktreeGitDir(options.worktreePath, options.repositoryPath);
     if (gitdir)
-        filesystem[gitdir] = "write";
+        filesystem[gitdir] = options.readOnly ? "read" : "write";
     const canonicalWorkspace = canonicalPathWithMissingTail(workspaceRoot);
     const overlapsWorkspace = (root) => {
         const canonicalRoot = canonicalPathWithMissingTail(root);
@@ -469,7 +469,7 @@ function codexWorktreeGuardArgs(options, platform = process.platform) {
         // reopen sibling sessions or metadata inside the Navarch workspace.
         if (overlapsWorkspace(resolved))
             continue;
-        filesystem[resolved] = "write";
+        filesystem[resolved] = options.readOnly ? "read" : "write";
     }
     return [
         "--ignore-user-config",
@@ -489,7 +489,7 @@ function codexWorktreeGuardArgs(options, platform = process.platform) {
         // Auto-review escalation, while leaving every non-GitHub destination
         // blocked. The profile still constrains filesystem access independently.
         "-c",
-        `permissions.${CODEX_GUARD_PROFILE}.network.enabled=true`,
+        `permissions.${CODEX_GUARD_PROFILE}.network.enabled=${!options.readOnly}`,
         "-c",
         `permissions.${CODEX_GUARD_PROFILE}.network.domains=${tomlInlineTable({
             ...CODEX_GITHUB_NETWORK_DOMAINS,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sagentlab/navarch-runtime",
-  "version": "0.1.141",
+  "version": "0.1.143",
   "description": "Navarch machine-side session manager: claims delivery tasks and runs them through local coding agents.",
   "type": "commonjs",
   "license": "MIT",