clay-server 2.40.0-beta.2 → 2.40.0-beta.4

package/lib/claude-hook-installer.js

@@ -16,28 +16,25 @@
 
 var fs = require("fs");
 var path = require("path");
+var { buildClayBashAllowPatterns, isClayManagedBashPattern } = require("./safe-bash-commands");
 
 // Substring that uniquely identifies a Clay-installed hook entry so we can
 // safely remove/replace it without touching user-authored hooks.
 var CLAY_HOOK_MARKER = "clay:tui-notify";
 
 // Allow-patterns Clay manages in ~/.claude/settings.json `permissions.allow`.
-// These mirror sdk-bridge.js `checkToolWhitelist` so TUI sessions get the
-// same auto-approval convenience as SDK sessions. Conservative: only
-// commands that stay safe even under Claude Code's wildcard matching
-// (compound commands like `ls && rm -rf /` would otherwise sneak past
-// `Bash(ls *)`).
+// The Bash(...) patterns are GENERATED from safe-bash-commands.js so this
+// list and sdk-bridge.js `checkToolWhitelist` can never drift - there is one
+// source of truth for which bash commands Clay auto-approves.
 //
-// Pattern syntax note: claude 2.x uses space-wildcard form `Bash(cmd *)`
+// Pattern syntax note: claude 2.x uses the space-wildcard form `Bash(cmd *)`
 // for prefix matching. The older colon form `Bash(cmd:*)` is flagged as
-// legacy in the CLI and no longer reliably matches argument-bearing
-// commands - the TUI was still prompting for read-only invocations like
-// `ls -la` even with the allow-list installed. Patterns below use the
-// modern form. The bare command (e.g. `Bash(ls)`) is included alongside
-// the wildcard so zero-arg invocations are also covered.
+// legacy in the CLI and no longer reliably matches argument-bearing commands
+// (the TUI kept prompting for read-only invocations like `ls -la`). The
+// generator emits the modern form plus a bare `Bash(cmd)` for zero-arg use.
 //
-// User-authored entries are preserved -- on re-install we only strip
-// patterns that appear in this constant list.
+// User-authored entries are preserved -- on re-install we only strip patterns
+// that are Clay-managed (current generated list or the legacy colon shape).
 var CLAY_MANAGED_ALLOW = [
   // Read-only built-in tools (no side effects).
   "Read", "Glob", "Grep", "WebFetch", "WebSearch",
@@ -53,53 +50,7 @@ var CLAY_MANAGED_ALLOW = [
   "mcp__clay-email__clay_read_email_body",
   "mcp__clay-email__clay_search_email",
   "mcp__clay-email__clay_list_labels",
-
-  // Safe Bash commands. Match the curated set in sdk-bridge.js's
-  // safeBashCommands, restricted to ones whose pure read-only behavior
-  // doesn't depend on argument shape.
-  "Bash(ls)", "Bash(ls *)", "Bash(cat *)", "Bash(head *)", "Bash(tail *)", "Bash(wc *)",
-  "Bash(file *)", "Bash(stat *)", "Bash(find *)", "Bash(tree)", "Bash(tree *)",
-  "Bash(du *)", "Bash(df)", "Bash(df *)", "Bash(readlink *)", "Bash(realpath *)",
-  "Bash(basename *)", "Bash(dirname *)",
-  "Bash(grep *)", "Bash(rg *)", "Bash(ag *)", "Bash(ack *)",
-  "Bash(fgrep *)", "Bash(egrep *)",
-  "Bash(which *)", "Bash(type *)", "Bash(whereis *)",
-  "Bash(echo)", "Bash(echo *)", "Bash(printf *)", "Bash(env)", "Bash(env *)", "Bash(printenv)", "Bash(printenv *)",
-  "Bash(pwd)", "Bash(whoami)", "Bash(id)", "Bash(id *)", "Bash(groups)", "Bash(groups *)",
-  "Bash(date)", "Bash(date *)", "Bash(uname)", "Bash(uname *)", "Bash(hostname)", "Bash(uptime)",
-  "Bash(arch)", "Bash(nproc)", "Bash(free)", "Bash(free *)",
-  "Bash(lsb_release *)", "Bash(sw_vers)", "Bash(sw_vers *)", "Bash(locale)", "Bash(locale *)",
-  // Git read-only subcommands. Listed individually so write subcommands
-  // (commit, push, reset, etc.) still prompt.
-  "Bash(git status)", "Bash(git status *)", "Bash(git log)", "Bash(git log *)",
-  "Bash(git diff)", "Bash(git diff *)", "Bash(git show)", "Bash(git show *)",
-  "Bash(git branch)", "Bash(git branch *)", "Bash(git tag)", "Bash(git tag *)",
-  "Bash(git remote)", "Bash(git remote *)", "Bash(git config --get *)",
-  "Bash(git rev-parse *)", "Bash(git ls-files)", "Bash(git ls-files *)",
-  "Bash(git blame *)", "Bash(git describe)", "Bash(git describe *)",
-  // Package manager read-only subcommands
-  "Bash(npm list)", "Bash(npm list *)", "Bash(npm ls)", "Bash(npm ls *)",
-  "Bash(npm view *)", "Bash(npm outdated)", "Bash(npm outdated *)",
-  "Bash(npm config get *)", "Bash(yarn list)", "Bash(yarn list *)", "Bash(pnpm list)", "Bash(pnpm list *)",
-  // Version checks
-  "Bash(node --version)", "Bash(npm --version)", "Bash(python --version)",
-  "Bash(python3 --version)", "Bash(go version)", "Bash(ruby --version)",
-  // Text processing (pure stdin/stdout)
-  "Bash(jq *)", "Bash(yq *)", "Bash(sort)", "Bash(sort *)", "Bash(uniq)", "Bash(uniq *)",
-  "Bash(cut *)", "Bash(tr *)", "Bash(awk *)", "Bash(sed *)",
-  "Bash(paste *)", "Bash(column *)", "Bash(rev)", "Bash(rev *)", "Bash(tac)", "Bash(tac *)",
-  "Bash(nl)", "Bash(nl *)", "Bash(fmt)", "Bash(fmt *)", "Bash(comm *)", "Bash(join *)",
-  // Comparison / hashing (read-only)
-  "Bash(diff *)", "Bash(cmp *)", "Bash(md5sum *)", "Bash(sha256sum *)",
-  "Bash(sha1sum *)", "Bash(shasum *)", "Bash(cksum *)", "Bash(base64)", "Bash(base64 *)",
-  "Bash(xxd *)", "Bash(od *)", "Bash(hexdump *)",
-  // Calendar / math
-  "Bash(cal)", "Bash(cal *)", "Bash(bc)", "Bash(bc *)", "Bash(expr *)", "Bash(factor *)", "Bash(seq *)",
-  // Process / network introspection (read-only)
-  "Bash(ps)", "Bash(ps *)", "Bash(top)", "Bash(top *)", "Bash(htop)", "Bash(pgrep *)", "Bash(lsof)", "Bash(lsof *)",
-  "Bash(netstat)", "Bash(netstat *)", "Bash(ss)", "Bash(ss *)", "Bash(ifconfig)", "Bash(ifconfig *)", "Bash(ip *)",
-  "Bash(dig *)", "Bash(nslookup *)", "Bash(host *)",
-];
+].concat(buildClayBashAllowPatterns());
 
 function buildHookCommand(notifyUrl) {
   // Read stdin once (the JSON Claude Code pipes in), then post it. --max-time
@@ -197,27 +148,25 @@ function installNotificationHook(opts) {
   return { installed: installed, errors: errors };
 }
 
-// Pattern shapes Clay used to install in older versions. Listed here so an
-// upgrade can strip them from settings.json before re-installing the modern
-// list. Without this, users who already had Clay running would end up with
-// stale legacy-syntax entries next to the new ones - mostly harmless but
-// noisy, and confusing if anyone reads the file.
+// Old colon-prefix Bash patterns Clay wrote before claude 2.x: Bash(ls:*),
+// Bash(git status:*), etc. Stripped on upgrade so they don't linger next to
+// the modern space-wildcard form. Modern Clay patterns never contain ":)" so
+// this only catches the deprecated shape; it can't tell a user-authored colon
+// pattern apart, but claude is phasing the colon form out anyway.
 function isLegacyClayPattern(p) {
   if (typeof p !== "string") return false;
-  // Old colon-prefix Bash patterns: Bash(ls:*), Bash(git status:*), etc.
-  // Modern patterns use space-asterisk and never contain ":*", so this is
-  // a safe identifier for old Clay entries even though it can't tell apart
-  // user-authored colon patterns. The risk is judged acceptable because
-  // claude flags the colon form as legacy and is phasing it out anyway.
   if (p.indexOf("Bash(") === 0 && p.indexOf(":*)") !== -1) return true;
   return false;
 }
 
 // Merge Clay's managed allow-list into permissions.allow without disturbing
-// the user's own entries. We identify "ours" by membership in
-// CLAY_MANAGED_ALLOW (current) or isLegacyClayPattern (previous shape):
-// re-install strips both, then re-inserts the current list. User-authored
-// patterns survive unchanged.
+// the user's own entries. "Ours" = exact membership in CLAY_MANAGED_ALLOW
+// (the non-Bash built-in / MCP entries) OR isClayManagedBashPattern (any
+// shape of a bash command we own, so stale variants from older versions get
+// swept) OR the legacy colon shape. Everything else is preserved, then the
+// fresh list is appended. Because the Bash patterns are generated from
+// safe-bash-commands.js, a re-install always writes the current set and can
+// never leave a stale Clay block behind.
 function mergeAllowList(settingsPath, patterns) {
   var data = readSettings(settingsPath);
   if (!data.permissions || typeof data.permissions !== "object") data.permissions = {};
@@ -226,10 +175,9 @@ function mergeAllowList(settingsPath, patterns) {
   var managedSet = {};
   for (var i = 0; i < CLAY_MANAGED_ALLOW.length; i++) managedSet[CLAY_MANAGED_ALLOW[i]] = true;
 
-  // Strip prior Clay-managed entries (current shape + legacy colon shape),
-  // then append the fresh list.
   var preserved = allow.filter(function (p) {
     if (managedSet[p]) return false;
+    if (isClayManagedBashPattern(p)) return false;
     if (isLegacyClayPattern(p)) return false;
     return true;
   });

package/lib/cli-sessions.js

@@ -175,6 +175,53 @@ function extractText(content) {
  * history entries (user_message, delta, tool_start, tool_executing, tool_result).
  * Returns a Promise that resolves to an array of history entries.
  */
+// Convert one parsed CLI jsonl record into client history entries. Shared by
+// the streaming (async) and synchronous readers so the format stays in lockstep.
+// `state.toolCounter` carries across lines to mint unique tool ids.
+function appendCliRecord(obj, state, history) {
+  if (!obj || !obj.message) return;
+
+  // User prompt
+  if (obj.type === "user" && obj.message.role === "user") {
+    // Skip tool_result records (they have type "user" but content is tool results)
+    var content = obj.message.content;
+    if (Array.isArray(content) && content.length > 0 && content[0].type === "tool_result") {
+      return;
+    }
+    var text = extractText(content);
+    if (text) history.push({ type: "user_message", text: text });
+    return;
+  }
+
+  // Assistant message
+  if (obj.message.role === "assistant" && Array.isArray(obj.message.content)) {
+    for (var i = 0; i < obj.message.content.length; i++) {
+      var block = obj.message.content[i];
+
+      if (block.type === "text" && block.text) {
+        history.push({ type: "delta", text: block.text });
+      }
+
+      if (block.type === "tool_use") {
+        var toolId = "cli-tool-" + (++state.toolCounter);
+        var toolName = block.name || "Tool";
+        history.push({ type: "tool_start", id: toolId, name: toolName });
+        history.push({
+          type: "tool_executing",
+          id: toolId,
+          name: toolName,
+          input: block.input || {},
+        });
+        // Emit ask_user_answered so the client re-enables input after replaying AskUserQuestion
+        if (toolName === "AskUserQuestion") {
+          history.push({ type: "ask_user_answered", toolId: toolId });
+        }
+        history.push({ type: "tool_result", id: toolId, content: "" });
+      }
+    }
+  }
+}
+
 function readCliSessionHistory(cwd, sessionId) {
   var encoded = encodeCwd(cwd);
   var filePath = path.join(REAL_HOME, ".claude", "projects", encoded, sessionId + ".jsonl");
@@ -189,55 +236,12 @@ function readCliSessionHistory(cwd, sessionId) {
     }
 
     var rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
-    var toolCounter = 0;
+    var state = { toolCounter: 0 };
 
     rl.on("line", function (line) {
       var obj;
       try { obj = JSON.parse(line); } catch (e) { return; }
-
-      if (!obj.message) return;
-
-      // User prompt
-      if (obj.type === "user" && obj.message.role === "user") {
-        // Skip tool_result records (they have type "user" but content is tool results)
-        var content = obj.message.content;
-        if (Array.isArray(content) && content.length > 0 && content[0].type === "tool_result") {
-          return;
-        }
-        var text = extractText(content);
-        if (text) {
-          history.push({ type: "user_message", text: text });
-        }
-        return;
-      }
-
-      // Assistant message
-      if (obj.message.role === "assistant" && Array.isArray(obj.message.content)) {
-        for (var i = 0; i < obj.message.content.length; i++) {
-          var block = obj.message.content[i];
-
-          if (block.type === "text" && block.text) {
-            history.push({ type: "delta", text: block.text });
-          }
-
-          if (block.type === "tool_use") {
-            var toolId = "cli-tool-" + (++toolCounter);
-            var toolName = block.name || "Tool";
-            history.push({ type: "tool_start", id: toolId, name: toolName });
-            history.push({
-              type: "tool_executing",
-              id: toolId,
-              name: toolName,
-              input: block.input || {},
-            });
-            // Emit ask_user_answered so the client re-enables input after replaying AskUserQuestion
-            if (toolName === "AskUserQuestion") {
-              history.push({ type: "ask_user_answered", toolId: toolId });
-            }
-            history.push({ type: "tool_result", id: toolId, content: "" });
-          }
-        }
-      }
+      appendCliRecord(obj, state, history);
     });
 
     rl.on("close", function () {
@@ -255,10 +259,41 @@ function readCliSessionHistory(cwd, sessionId) {
   });
 }
 
+// Synchronous variant for callers that run inside a synchronous request
+// handler (e.g. switch_session, which must populate session.history before
+// the session_switched broadcast). Reads the whole jsonl - these transcripts
+// are small enough that blocking on a local read is fine.
+// Modified-time (ms) of a CLI session's jsonl, or 0 if missing. Lets callers
+// cheaply detect that the transcript grew (e.g. after a TUI turn) and re-read.
+function cliSessionFileMtime(cwd, sessionId) {
+  var encoded = encodeCwd(cwd);
+  var filePath = path.join(REAL_HOME, ".claude", "projects", encoded, sessionId + ".jsonl");
+  try { return fs.statSync(filePath).mtimeMs; } catch (e) { return 0; }
+}
+
+function readCliSessionHistorySync(cwd, sessionId) {
+  var encoded = encodeCwd(cwd);
+  var filePath = path.join(REAL_HOME, ".claude", "projects", encoded, sessionId + ".jsonl");
+  var raw;
+  try { raw = fs.readFileSync(filePath, "utf8"); } catch (e) { return []; }
+  var history = [];
+  var state = { toolCounter: 0 };
+  var lines = raw.split("\n");
+  for (var i = 0; i < lines.length; i++) {
+    if (!lines[i]) continue;
+    var obj;
+    try { obj = JSON.parse(lines[i]); } catch (e) { continue; }
+    appendCliRecord(obj, state, history);
+  }
+  return history;
+}
+
 module.exports = {
   listCliSessions: listCliSessions,
   getMostRecentCliSession: getMostRecentCliSession,
   readCliSessionHistory: readCliSessionHistory,
+  readCliSessionHistorySync: readCliSessionHistorySync,
+  cliSessionFileMtime: cliSessionFileMtime,
   parseSessionFile: parseSessionFile,
   encodeCwd: encodeCwd,
   extractText: extractText,

package/lib/project-connection.js

@@ -39,6 +39,7 @@ function attachConnection(ctx) {
   var _mcp = ctx._mcp;
   var _notifications = ctx._notifications;
   var hydrateImageRefs = ctx.hydrateImageRefs;
+  var resolveSessionForView = ctx.resolveSessionForView;
   var broadcastClientCount = ctx.broadcastClientCount;
   var broadcastPresence = ctx.broadcastPresence;
   var getProjectList = ctx.getProjectList;
@@ -221,8 +222,15 @@ function attachConnection(ctx) {
         sm.saveSessionFile(active);
       }
       ws._clayActiveSession = active.localId;
+      // Resolve the lazy-resume view (runtimeMode / runtimeTerminalId /
+      // tuiSuspended + transcript hydration) the same way switch_session does,
+      // so a born-TUI session restored on (re)connect shows the read-only
+      // history + Resume bar instead of an editable composer. No PTY spawn.
+      if (typeof resolveSessionForView === "function") {
+        try { resolveSessionForView(active, ws); } catch (e) {}
+      }
       var _vendorCaps = (sm.capabilitiesByVendor && sm.capabilitiesByVendor[active.vendor || sm.defaultVendor || "claude"]) || {};
-      sendTo(ws, { type: "session_switched", id: active.localId, cliSessionId: active.cliSessionId || null, loop: active.loop || null, vendor: active.vendor || null, hasHistory: (active.history && active.history.length > 0), capabilities: _vendorCaps, mode: active.mode || "gui", terminalId: typeof active.terminalId === "number" ? active.terminalId : null, runtimeMode: active.runtimeMode || null, runtimeTerminalId: typeof active.runtimeTerminalId === "number" ? active.runtimeTerminalId : null });
+      sendTo(ws, { type: "session_switched", id: active.localId, cliSessionId: active.cliSessionId || null, loop: active.loop || null, vendor: active.vendor || null, hasHistory: (active.history && active.history.length > 0), capabilities: _vendorCaps, mode: active.mode || "gui", terminalId: typeof active.terminalId === "number" ? active.terminalId : null, runtimeMode: active.runtimeMode || null, runtimeTerminalId: typeof active.runtimeTerminalId === "number" ? active.runtimeTerminalId : null, tuiSuspended: !!active.tuiSuspended });
       // Send per-session context sources
       var sessionSources = loadContextSources(slug, active.localId);
       sendTo(ws, { type: "context_sources_state", active: sessionSources });

package/lib/project-sessions.js

@@ -277,15 +277,25 @@ function attachSessions(ctx) {
   // every click while the user is reading the session in GUI mode).
   function prepareTuiSessionForGuiView(session) {
     if (!session || session.cliSessionId == null) return;
-    var alreadyHydrated = (typeof session.terminalId !== "number") &&
-                          Array.isArray(session.history) && session.history.length > 0;
-    if (alreadyHydrated) return;
     var cliSess;
     try { cliSess = require("./cli-sessions"); } catch (e) { return; }
+    // Re-read whenever the jsonl has changed since the last hydrate (a TUI
+    // turn appended messages), not just when history is empty. The earlier
+    // "already hydrated" short-circuit kept stale history after a
+    // Resume -> chat -> Close cycle (showed A instead of A').
+    var mtime = cliSess.cliSessionFileMtime(cwd, session.cliSessionId);
+    var fresh = (typeof session.terminalId !== "number") &&
+                Array.isArray(session.history) && session.history.length > 0 &&
+                session._historyMtime === mtime;
+    if (fresh) return;
     var history = null;
-    try { history = cliSess.readCliSessionHistory(cwd, session.cliSessionId); } catch (e) { history = null; }
+    // Synchronous read: switch_session must populate session.history before
+    // the session_switched broadcast replays it. readCliSessionHistory is
+    // Promise-based and would resolve too late (the transcript came up empty).
+    try { history = cliSess.readCliSessionHistorySync(cwd, session.cliSessionId); } catch (e) { history = null; }
     if (Array.isArray(history)) {
       session.history = history;
+      session._historyMtime = mtime;
     }
     if (typeof session.terminalId === "number" && tm) {
       try { tm.close(session.terminalId); } catch (e) {}
@@ -294,6 +304,46 @@ function attachSessions(ctx) {
     try { sm.saveSessionFile(session); } catch (e) {}
   }
 
+  // Resolve how a session should be presented to a viewer WITHOUT spawning a
+  // PTY or broadcasting: set runtimeMode / runtimeTerminalId / tuiSuspended and
+  // hydrate the transcript for the read-only and GUI cases. Single source of
+  // truth shared by switch_session (which additionally spawns for born-GUI)
+  // and the connect/restore path (project-connection.js) so a refreshed
+  // born-TUI session shows the same read-only + Resume view as a fresh click.
+  function resolveSessionForView(session, ws) {
+    if (!session) return;
+    if (session.vendor && session.vendor !== "claude") { session.tuiSuspended = false; return; }
+    var pref = getClaudeOpenModeForWs(ws);
+    if (session.mode === "tui") {
+      if (pref === "gui") {
+        prepareTuiSessionForGuiView(session);
+        session.runtimeMode = "gui";
+        session.runtimeTerminalId = null;
+        session.tuiSuspended = false;
+      } else if (tm && typeof session.terminalId === "number" && tm.has(session.terminalId)) {
+        session.runtimeMode = "tui";
+        session.runtimeTerminalId = session.terminalId;
+        session.tuiSuspended = false;
+      } else if (tm && typeof session.runtimeTerminalId === "number" && tm.has(session.runtimeTerminalId)) {
+        session.runtimeMode = "tui";
+        session.tuiSuspended = false;
+      } else {
+        prepareTuiSessionForGuiView(session);
+        session.runtimeMode = null;
+        session.runtimeTerminalId = null;
+        session.tuiSuspended = true;
+      }
+    } else {
+      // Born-GUI: reattach a live resume PTY if one exists; never spawn here.
+      if (pref === "tui" && tm && typeof session.runtimeTerminalId === "number" && tm.has(session.runtimeTerminalId)) {
+        session.runtimeMode = "tui";
+      } else {
+        session.runtimeMode = null;
+      }
+      session.tuiSuspended = false;
+    }
+  }
+
   // Compute the runtimeMode the client should render for this session given
   // the user's current preference. Pure function over session + pref; the
   // caller decides whether to also mutate state (spawn PTY, convert, etc.)
@@ -374,8 +424,17 @@ function attachSessions(ctx) {
             initialInput: tuiCmd,
             kind: "tui-session",
             title: "claude " + tuiSid.slice(0, 8),
-            onExit: function () {
-              if (sm.sessions.has(tuiLocalId)) {
+            onExit: function (termSession) {
+              var s = sm.sessions.get(tuiLocalId);
+              if (!s) return;
+              if (termSession && termSession.reclaimed) {
+                // Reclaimed (idle sweep or explicit Close), not a real /exit:
+                // keep the session (its jsonl transcript stays on disk and
+                // lazy-resume can re-spawn claude). Just drop the dead PTY link.
+                s.terminalId = null;
+                try { sm.saveSessionFile(s); } catch (e) {}
+                try { sm.broadcastSessionList(); } catch (e) {}
+              } else {
                 try { sm.deleteSessionQuiet(tuiLocalId); } catch (e) {}
                 try { sm.broadcastSessionList(); } catch (e) {}
               }
@@ -527,56 +586,16 @@ function attachSessions(ctx) {
         var xmTarget = sm.sessions.get(msg.id);
         if (xmTarget && (xmTarget.vendor === "claude" || !xmTarget.vendor)) {
           var xmPref = getClaudeOpenModeForWs(ws);
-          // Born-TUI session whose PTY is gone (typically after a daemon
-          // restart) AND the user wants TUI rendering this click. Respawn
-          // via `claude --resume <cliSessionId>` so the rest of the pipeline
-          // has a live PTY to point at. Skipped when the user's pref is GUI
-          // - we'd just tear it back down two lines later.
-          if (xmTarget.mode === "tui" && xmTarget.cliSessionId && tm && xmPref === "tui" &&
-              (typeof xmTarget.terminalId !== "number" || !tm.has(xmTarget.terminalId))) {
-            var rsSid = xmTarget.cliSessionId;
-            var rsLocalId = xmTarget.localId;
-            var rsCmd = "claude --resume " + rsSid + "; exit\n";
-            var rsTerm = tm.create(80, 24, getOsUserInfoForWs(ws), ws, {
-              initialInput: rsCmd,
-              kind: "tui-session",
-              title: "claude " + rsSid.slice(0, 8),
-              onExit: function () {
-                if (sm.sessions.has(rsLocalId)) {
-                  try { sm.deleteSessionQuiet(rsLocalId); } catch (e) {}
-                  try { sm.broadcastSessionList(); } catch (e) {}
-                }
-              },
-              onData: makeTuiActivityHook(rsLocalId),
-            });
-            if (rsTerm) xmTarget.terminalId = rsTerm.id;
-            startTitleWatcher(xmTarget);
-          }
-          var xmRuntime = computeRuntimeMode(xmTarget, xmPref);
-          if (xmRuntime === "gui" && xmTarget.mode === "tui") {
-            // Born-TUI session under GUI pref. Hydrate history + drop PTY
-            // without flipping session.mode, so flipping back to TUI later
-            // restores the embedded-terminal rendering. runtimeMode is set
-            // to 'gui' explicitly so the client doesn't fall back to
-            // session.mode (which is still 'tui').
-            prepareTuiSessionForGuiView(xmTarget);
-            xmTarget.runtimeMode = "gui";
-            xmTarget.runtimeTerminalId = null;
-          } else if (xmRuntime === "tui" && xmTarget.mode === "gui" && xmTarget.cliSessionId) {
-            var xmRid = spawnRuntimeTuiPty(xmTarget, ws);
-            if (typeof xmRid === "number") {
-              xmTarget.runtimeMode = "tui";
-              xmTarget.runtimeTerminalId = xmRid;
-            } else {
-              xmTarget.runtimeMode = null;
-              xmTarget.runtimeTerminalId = null;
-            }
-          } else {
-            // Same-mode click. Don't leak a stale runtime override into the
-            // payload, but keep any background runtime PTY alive (it may be
-            // re-attached on the next pref flip).
-            xmTarget.runtimeMode = null;
+          // Born-GUI under TUI pref with no live resume PTY: spawn a transient
+          // `claude --resume` now (only switch_session spawns; born-TUI sessions
+          // stay lazy and the connect path never spawns). resolveSessionForView
+          // then turns the live PTY into runtimeMode='tui'.
+          if (xmTarget.mode === "gui" && xmTarget.cliSessionId &&
+              computeRuntimeMode(xmTarget, xmPref) === "tui" &&
+              !(tm && typeof xmTarget.runtimeTerminalId === "number" && tm.has(xmTarget.runtimeTerminalId))) {
+            spawnRuntimeTuiPty(xmTarget, ws);
           }
+          resolveSessionForView(xmTarget, ws);
         }
         // If the target session's vendor doesn't own the currently cached
         // model, clear sm.currentModel so the UI and next query don't leak
@@ -618,6 +637,63 @@ function attachSessions(ctx) {
       return true;
     }
 
+    // Lazy-resume: the user clicked "Resume" on a TUI session shown read-only.
+    // Spawn `claude --resume <cliSessionId>` now and re-broadcast
+    // session_switched so the client swaps the transcript for the live xterm.
+    if (msg.type === "resume_tui_session") {
+      if (msg.id && sm.sessions.has(msg.id)) {
+        var rtTarget = sm.sessions.get(msg.id);
+        var rtOk = rtTarget && (rtTarget.vendor === "claude" || !rtTarget.vendor) &&
+                   rtTarget.cliSessionId && tm;
+        if (rtOk) {
+          if (usersModule.isMultiUser() && ws._clayUser &&
+              !usersModule.canAccessSession(ws._clayUser.id, rtTarget, { visibility: "public" })) {
+            return true;
+          }
+          var rtRid = spawnRuntimeTuiPty(rtTarget, ws);
+          if (typeof rtRid === "number") {
+            rtTarget.runtimeMode = "tui";
+            rtTarget.runtimeTerminalId = rtRid;
+            rtTarget.tuiSuspended = false;
+            startTitleWatcher(rtTarget);
+          }
+          ws._clayActiveSession = msg.id;
+          sm.switchSession(msg.id, ws, hydrateImageRefs);
+        }
+      }
+      return true;
+    }
+
+    // Explicit Close: the user closed a live TUI session from the title bar.
+    // Kill its PTY now (don't wait for the idle sweep) but keep the session -
+    // it drops to the read-only transcript + Resume bar, freeing resources
+    // immediately while staying resumable.
+    if (msg.type === "suspend_tui_session") {
+      if (msg.id && sm.sessions.has(msg.id)) {
+        var stTarget = sm.sessions.get(msg.id);
+        var stOk = stTarget && (stTarget.vendor === "claude" || !stTarget.vendor);
+        if (stOk && (!usersModule.isMultiUser() || !ws._clayUser ||
+            usersModule.canAccessSession(ws._clayUser.id, stTarget, { visibility: "public" }))) {
+          if (tm) {
+            var stTid = (typeof stTarget.terminalId === "number") ? stTarget.terminalId : null;
+            var stRid = (typeof stTarget.runtimeTerminalId === "number") ? stTarget.runtimeTerminalId : null;
+            if (stTid != null && tm.has(stTid)) { tm.markReclaimed(stTid); tm.close(stTid); }
+            if (stRid != null && tm.has(stRid)) { tm.markReclaimed(stRid); tm.close(stRid); }
+          }
+          stTarget.terminalId = null;
+          stTarget.runtimeTerminalId = null;
+          // Hydrate the transcript so the read-only view has content, then
+          // re-broadcast as suspended.
+          prepareTuiSessionForGuiView(stTarget);
+          stTarget.runtimeMode = null;
+          stTarget.tuiSuspended = true;
+          ws._clayActiveSession = msg.id;
+          sm.switchSession(msg.id, ws, hydrateImageRefs);
+        }
+      }
+      return true;
+    }
+
     if (msg.type === "set_mate_dm") {
       // Only store mateDm on non-mate projects (main project presence).
       // Mate projects should never hold mateDm to avoid circular restore loops.
@@ -1758,6 +1834,7 @@ function attachSessions(ctx) {
 
   return {
     handleSessionsMessage: handleSessionsMessage,
+    resolveSessionForView: resolveSessionForView,
   };
 }
 

package/lib/project.js

@@ -1429,6 +1429,7 @@ function createProjectContext(opts) {
     _loop: _loop,
     _mcp: _mcp,
     _notifications: _notifications,
+    resolveSessionForView: _sessions.resolveSessionForView,
     hydrateImageRefs: hydrateImageRefs,
     broadcastClientCount: broadcastClientCount,
     broadcastPresence: broadcastPresence,

package/lib/public/css/filebrowser.css

@@ -1414,7 +1414,7 @@
 }
 
 /* --- Terminal key toolbar (mobile) --- */
-#terminal-toolbar {
+.term-toolbar {
   display: flex;
   align-items: center;
   gap: 6px;
@@ -1426,7 +1426,7 @@
   -webkit-overflow-scrolling: touch;
 }
 
-#terminal-toolbar.hidden { display: none; }
+.term-toolbar.hidden { display: none; }
 
 .term-key {
   display: flex;

package/lib/public/css/input.css

@@ -1154,6 +1154,18 @@
   .mobile-only { display: none !important; }
 }
 
+/* Mobile TUI: the composer is a plain conduit to the PTY (session-tui-view.js
+   toggles body.tui-composer-active). Hide controls that don't apply to a
+   terminal session - scheduled send, @mentions, and model/vendor config.
+   Attach (files/images -> path injection) and voice input stay available. */
+body.tui-composer-active #schedule-btn,
+body.tui-composer-active #ask-mate-btn,
+body.tui-composer-active #vendor-toggle-wrap,
+body.tui-composer-active #active-vendor-indicator,
+body.tui-composer-active #config-chip-wrap {
+  display: none !important;
+}
+
 /* ==========================================================================
    Input More Bottom Sheet (mobile)
    ========================================================================== */

package/lib/public/css/menus.css

@@ -43,6 +43,29 @@
 #header-rename-btn:hover { color: var(--text-secondary); background: rgba(var(--overlay-rgb),0.04); border-color: var(--border); }
 #header-rename-btn .lucide { width: 13px; height: 13px; }
 
+/* "Close terminal" button: sits just left of the rename pencil during a live
+   TUI session. Matches the rename button's chrome; reds out on hover since it
+   stops the running claude (the session stays resumable). */
+#header-tui-close-btn {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 24px;
+  height: 24px;
+  border: 1px solid transparent;
+  background: none;
+  color: var(--text-dimmer);
+  cursor: pointer;
+  border-radius: 8px;
+  flex-shrink: 0;
+  padding: 0;
+  margin-left: 4px;
+  transition: color 0.15s, background 0.15s, border-color 0.15s;
+}
+#header-tui-close-btn:hover { color: var(--error); background: rgba(var(--overlay-rgb),0.04); border-color: var(--border); }
+#header-tui-close-btn .lucide { width: 14px; height: 14px; }
+#header-tui-close-btn.hidden { display: none; }
+
 #header-info-btn {
   display: flex;
   align-items: center;