@sagentlab/navarch-runtime 0.1.140 → 0.1.142

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 host runtime. Generated Claude Code host connect and supervise commands include it; remove it from both lines to keep chat read-only. 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_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/local-browser.cjs

@@ -97,6 +97,7 @@ function createLocalBrowser(options) {
         await context?.close().catch(() => undefined);
         context = undefined;
         page = undefined;
+        notes = [];
         try {
             browser ??= await options.launch();
         }
@@ -159,14 +160,20 @@ function createLocalBrowser(options) {
         }
         if (tree.length > MAX_SNAPSHOT_CHARS)
             tree = `${tree.slice(0, MAX_SNAPSHOT_CHARS)}\n… (truncated)`;
+        const title = await active.title().catch(() => "");
+        // Take the notes only after the last await, so a tab that opens while
+        // this snapshot is being built is reported here (its body may still show
+        // the previous tab) instead of being cleared unreported.
+        const reported = notes;
+        notes = [];
         const lines = [
             ...(heading ? [heading] : []),
-            ...notes,
+            ...reported,
             ...(active.url().startsWith("chrome-error://")
                 ? ["The last navigation failed or tried to leave this machine and was blocked. Use local_browser_open to continue."]
                 : []),
             `URL: ${active.url()}`,
-            `Title: ${await active.title().catch(() => "")}`,
+            `Title: ${title}`,
             `Viewport: ${viewport}`,
             ...(logs.length ? ["Recent console/page errors:", ...logs.map((line) => `  ${line}`)] : []),
             ...(blocked.size
@@ -175,7 +182,6 @@ function createLocalBrowser(options) {
             "",
             tree,
         ];
-        notes = [];
         return [{ type: "text", text: lines.join("\n") }];
     }
     /** Runs tool calls one at a time; a lease ending stops further use. */

package/package.json

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