clay-server 3.4.0-beta.1 → 3.4.0-beta.2

package/lib/project-shell-command.js

@@ -0,0 +1,160 @@
+var { spawn } = require("child_process");
+var { buildUserEnv } = require("./build-user-env");
+var { wrapSpawnAsUser } = require("./os-users");
+
+var MAX_COMMAND_LENGTH = 16 * 1024;
+var MAX_OUTPUT_LENGTH = 64 * 1024;
+var COMMAND_TIMEOUT_MS = 30 * 1000;
+
+function stripTerminalCodes(value) {
+  return String(value || "")
+    .replace(/\x1b\][^\x07]*(?:\x07|\x1b\\)/g, "")
+    .replace(/\x1b\[[0-?]*[ -\/]*[@-~]/g, "")
+    .replace(/\r/g, "");
+}
+
+function attachShellCommand(ctx) {
+  var runningBySocket = new WeakMap();
+
+  function sendResult(ws, data) {
+    ctx.sendTo(ws, Object.assign({ type: "shell_command_result" }, data));
+  }
+
+  function handleShellCommand(ws, msg) {
+    if (msg.type !== "shell_command") return false;
+
+    var requestId = typeof msg.requestId === "string" ? msg.requestId.slice(0, 100) : "";
+    var command = typeof msg.command === "string" ? msg.command.trim() : "";
+    if (!requestId || !command) {
+      sendResult(ws, { requestId: requestId, error: "Enter a command to run." });
+      return true;
+    }
+    if (command.length > MAX_COMMAND_LENGTH) {
+      sendResult(ws, { requestId: requestId, error: "Command is too long." });
+      return true;
+    }
+
+    if (ws._clayUser) {
+      var permissions = ctx.usersModule.getEffectivePermissions(ws._clayUser, ctx.osUsers);
+      if (!permissions.terminal) {
+        sendResult(ws, { requestId: requestId, error: "Terminal access is not permitted." });
+        return true;
+      }
+    }
+    if (runningBySocket.get(ws)) {
+      sendResult(ws, { requestId: requestId, error: "Another shell command is still running." });
+      return true;
+    }
+
+    var session = ctx.getSessionForWs(ws);
+    if (!session) {
+      sendResult(ws, { requestId: requestId, error: "No active session." });
+      return true;
+    }
+
+    var osUserInfo = ctx.getOsUserInfoForWs(ws);
+    var shell = (osUserInfo && osUserInfo.shell)
+      || process.env.SHELL
+      || (process.platform === "win32" ? process.env.COMSPEC || "cmd.exe" : "/bin/sh");
+    var args = process.platform === "win32" ? ["/d", "/s", "/c", command] : ["-lc", command];
+    var spawnOptions = {
+      cwd: ctx.cwd,
+      env: buildUserEnv(osUserInfo),
+      stdio: ["ignore", "pipe", "pipe"],
+    };
+    if (osUserInfo) {
+      spawnOptions.uid = osUserInfo.uid;
+      spawnOptions.gid = osUserInfo.gid;
+    }
+
+    var wrapped = wrapSpawnAsUser(shell, args, spawnOptions);
+    var child;
+    try {
+      child = spawn(wrapped.command, wrapped.args, wrapped.options);
+    } catch (e) {
+      sendResult(ws, { requestId: requestId, error: e.message || "Failed to start command." });
+      return true;
+    }
+
+    runningBySocket.set(ws, child);
+    var chunks = [];
+    var outputLength = 0;
+    var truncated = false;
+    var timedOut = false;
+    var finished = false;
+
+    function collect(data) {
+      if (outputLength >= MAX_OUTPUT_LENGTH) {
+        truncated = true;
+        return;
+      }
+      var text = data.toString("utf8");
+      var remaining = MAX_OUTPUT_LENGTH - outputLength;
+      if (text.length > remaining) {
+        text = text.slice(0, remaining);
+        truncated = true;
+      }
+      chunks.push(text);
+      outputLength += text.length;
+    }
+
+    child.stdout.on("data", collect);
+    child.stderr.on("data", collect);
+
+    var timer = setTimeout(function () {
+      timedOut = true;
+      try { child.kill("SIGTERM"); } catch (e) {}
+      setTimeout(function () {
+        if (!finished) {
+          try { child.kill("SIGKILL"); } catch (e) {}
+        }
+      }, 1000).unref();
+    }, COMMAND_TIMEOUT_MS);
+    timer.unref();
+
+    child.on("error", function (error) {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer);
+      runningBySocket.delete(ws);
+      sendResult(ws, { requestId: requestId, command: command, error: error.message || "Command failed." });
+    });
+
+    child.on("close", function (code, signal) {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer);
+      runningBySocket.delete(ws);
+
+      var output = stripTerminalCodes(chunks.join(""));
+      if (truncated) output += "\n… output truncated at 64 KB";
+      if (timedOut) output += (output ? "\n" : "") + "Command timed out after 30 seconds.";
+      var exitCode = typeof code === "number" ? code : null;
+      var context = [
+        "[Shell command executed by the user]",
+        "$ " + command,
+        output || "(no output)",
+        "[Exit code: " + (exitCode == null ? (signal || "unknown") : exitCode) + "]",
+      ].join("\n");
+      if (!session.pendingShellContexts) session.pendingShellContexts = [];
+      session.pendingShellContexts.push(context);
+
+      sendResult(ws, {
+        requestId: requestId,
+        sessionId: session.localId,
+        command: command,
+        output: output,
+        exitCode: exitCode,
+        signal: signal || null,
+        timedOut: timedOut,
+        truncated: truncated,
+      });
+    });
+
+    return true;
+  }
+
+  return { handleShellCommand: handleShellCommand };
+}
+
+module.exports = { attachShellCommand: attachShellCommand };

package/lib/project-user-message.js

@@ -374,6 +374,16 @@ function attachUserMessage(ctx) {
       fullText = mentionPrefix + "\n\n" + fullText;
     }
 
+    // Inject one-shot shell results captured from the composer command mode.
+    if (session.pendingShellContexts && session.pendingShellContexts.length > 0) {
+      var shellPrefix = session.pendingShellContexts.join("\n\n");
+      session.pendingShellContexts = [];
+      fullText = shellPrefix + "\n\n" + fullText;
+    }
+    if (msg.shellCommandResponse) {
+      fullText += "\n\n[Respond to the shell command result above now.]";
+    }
+
     // Inject active terminal context sources (delta only: send new output since last message)
     var TERM_CONTEXT_MAX = 8192; // 8KB max per terminal per message
     var TERM_HEAD_SIZE = 2048;   // keep first 2KB for error context

package/lib/project.js

@@ -28,6 +28,7 @@ var { attachKnowledge } = require("./project-knowledge");
 var { attachFilesystem } = require("./project-filesystem");
 var { attachSessions } = require("./project-sessions");
 var { attachUserMessage } = require("./project-user-message");
+var { attachShellCommand } = require("./project-shell-command");
 var { attachConnection } = require("./project-connection");
 var { attachMcp } = require("./project-mcp");
 var { createLocalMcp } = require("./mcp-local");
@@ -1176,6 +1177,9 @@ function createProjectContext(opts) {
     // --- Filesystem, settings, env (delegated to project-filesystem.js) ---
     if (_filesystem.handleFilesystemMessage(ws, msg)) return;
 
+    // --- Shell command context ---
+    if (_shellCommand.handleShellCommand(ws, msg)) return;
+
     // --- Notes, terminals, context, user message (delegated to project-user-message.js) ---
     if (_userMessage.handleUserMessage(ws, msg)) return;
   }
@@ -1424,6 +1428,15 @@ function createProjectContext(opts) {
     _email: _email,
   });
 
+  var _shellCommand = attachShellCommand({
+    cwd: cwd,
+    osUsers: osUsers,
+    usersModule: usersModule,
+    sendTo: sendTo,
+    getSessionForWs: getSessionForWs,
+    getOsUserInfoForWs: getOsUserInfoForWs,
+  });
+
   // --- Filesystem handler (delegated to project-filesystem.js) ---
   var _filesystem = attachFilesystem({
     cwd: cwd,

package/lib/public/app.js

@@ -51,6 +51,7 @@ import { initTooltips, registerTooltip } from './modules/tooltip.js';
 import { initMateWizard, openMateWizard, closeMateWizard, handleMateCreated } from './modules/mate-wizard.js';
 import { initCommandPalette, handlePaletteSessionSwitch, setPaletteVersion } from './modules/command-palette.js';
 import { initLongPress } from './modules/longpress.js';
+import { initShellCommand } from './modules/shell-command.js';
 import { initConnection, connect as _connConnect, setStatus as _connSetStatus, scheduleReconnect as _connScheduleReconnect, cancelReconnect as _connCancelReconnect } from './modules/app-connection.js';
 import { processMessage as _msgProcessMessage } from './modules/app-messages.js';
 import { getWs as _getWsRef, setWs as _setWsRef } from './modules/ws-ref.js';
@@ -308,6 +309,9 @@ import { initDebate, handleDebatePreparing, handleDebateStarted, handleDebateRes
     returningFromMateDm: false,
     pendingMateInterview: null,
     pendingTermCommand: null,
+    shellCommandMode: false,
+    shellCommandRunning: false,
+    pendingShellCommandId: null,
     mateProjectSlug: null,
     myUserId: null,
     isMultiUserMode: false,
@@ -793,6 +797,8 @@ import { initDebate, handleDebatePreparing, handleDebateStarted, handleDebateRes
     },
   });
 
+  initShellCommand();
+
   // --- @Mention module ---
   initMention({
     get ws() { return _getWsRef(); },
@@ -879,6 +885,10 @@ import { initDebate, handleDebatePreparing, handleDebateStarted, handleDebateRes
         if (termBtn) termBtn.style.display = "none";
         var termSideBtn = document.getElementById("terminal-sidebar-btn");
         if (termSideBtn) termSideBtn.style.display = "none";
+        var shellCommandBtn = document.getElementById("shell-command-btn");
+        if (shellCommandBtn) shellCommandBtn.style.display = "none";
+        var mobileShellCommandBtn = document.getElementById("input-more-shell");
+        if (mobileShellCommandBtn) mobileShellCommandBtn.style.display = "none";
       }
       if (!_perms.fileBrowser) {
         var fbBtn = document.getElementById("file-browser-btn");

package/lib/public/css/input.css

@@ -826,6 +826,7 @@
 
 #attach-file-btn,
 #attach-image-btn,
+#shell-command-btn,
 #schedule-btn,
 #input-more-btn {
   width: 36px;
@@ -844,14 +845,76 @@
 
 #attach-file-btn .lucide,
 #attach-image-btn .lucide,
+#shell-command-btn .lucide,
 #schedule-btn .lucide,
 #input-more-btn .lucide { width: 20px; height: 20px; flex-shrink: 0; }
 
 #attach-file-btn:hover,
 #attach-image-btn:hover,
+#shell-command-btn:hover,
 #schedule-btn:hover,
 #input-more-btn:hover { background: rgba(var(--overlay-rgb), 0.06); color: var(--text); }
 
+#shell-command-btn.active {
+  background: var(--accent-12);
+  color: var(--accent);
+}
+
+#input-row.shell-command-mode {
+  box-shadow: 0 0 0 1px var(--accent);
+}
+
+#input-row.shell-command-mode #input {
+  font-family: var(--font-mono, "SFMono-Regular", Consolas, monospace);
+}
+
+.shell-command-card {
+  width: min(760px, calc(100% - 24px));
+  margin: 10px auto;
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  background: var(--input-bg);
+  overflow: hidden;
+}
+
+.shell-command-card.error { border-color: rgba(239, 68, 68, 0.45); }
+
+.shell-command-header {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 9px 12px;
+  border-bottom: 1px solid var(--border);
+  color: var(--text-secondary);
+  font-size: 12px;
+}
+
+.shell-command-header code {
+  min-width: 0;
+  flex: 1;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  color: var(--text);
+}
+
+.shell-command-icon { display: inline-flex; }
+.shell-command-icon .lucide { width: 16px; height: 16px; }
+.shell-command-status { flex-shrink: 0; color: var(--text-muted); }
+
+.shell-command-card.running .shell-command-status { color: var(--accent); }
+
+.shell-command-output {
+  max-height: 320px;
+  margin: 0;
+  padding: 12px;
+  overflow: auto;
+  color: var(--text-secondary);
+  font: 12px/1.5 var(--font-mono, "SFMono-Regular", Consolas, monospace);
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
 #ask-mate-btn {
   width: 36px;
   height: 36px;

package/lib/public/index.html

@@ -505,6 +505,7 @@
               <button id="input-more-btn" type="button" aria-label="More options" title="More options" class="mobile-only"><i data-lucide="plus"></i></button>
               <button id="attach-file-btn" type="button" aria-label="Attach file" title="Attach file" class="desktop-only"><i data-lucide="paperclip"></i></button>
               <button id="attach-image-btn" type="button" aria-label="Attach image" title="Attach image" class="desktop-only"><i data-lucide="image"></i></button>
+              <button id="shell-command-btn" type="button" aria-label="Run shell command" aria-pressed="false" title="Run a shell command and add its output to the next agent message" class="desktop-only"><i data-lucide="square-terminal"></i></button>
               <button id="stt-btn" type="button" aria-label="Voice input" title="Voice input"><i data-lucide="mic"></i></button>
               <button id="schedule-btn" type="button" aria-label="Schedule message" title="Schedule message"><i data-lucide="clock"></i></button>
               <button id="ask-mate-btn" type="button" aria-label="Ask Mate" title="Ask a Mate for advice on this session"><i data-lucide="at-sign"></i></button>
@@ -615,6 +616,10 @@
           <i data-lucide="image"></i>
           <span>Image</span>
         </button>
+        <button class="input-more-action" id="input-more-shell">
+          <i data-lucide="square-terminal"></i>
+          <span>Shell command</span>
+        </button>
       </div>
       <div class="input-more-divider"></div>
       <div class="input-more-section-label">

package/lib/public/modules/app-messages.js

@@ -22,7 +22,7 @@ import { handleFindInSessionResults } from './session-search.js';
 import { syncPaneTitles, maybeRestoreSplitGroup, openGroup } from './split-view.js';
 import { showPairDialog, handlePairCreated, handleSplitDelegation, showWorkerDelegationNotice, hideWorkerDelegationNotice } from './split-pair-ui.js';
 import { renderWorkerProposal, updateWorkerProposal } from './worker-proposal.js';
-import { handleInputSync, autoResize, builtinCommands, setScheduleBtnDisabled } from './input.js';
+import { handleInputSync, autoResize, builtinCommands, setScheduleBtnDisabled, sendShellResultToAgent } from './input.js';
 import { startThinking, appendThinking, stopThinking, resetThinkingGroup, createToolItem, updateToolExecuting, updateToolResult, markAllToolsDone, closeToolGroup, removeToolFromGroup, resetToolState, getTools, getPlanContent, setPlanContent, renderPlanBanner, renderPlanCard, getTodoTools, handleTodoWrite, handleTaskCreate, handleTaskUpdate, applyDeadSessionTodoCompaction, isPlanFilePath, enableMainInput, addTurnMeta, updateSubagentActivity, addSubagentToolEntry, markSubagentDone, initSubagentStop, updateSubagentProgress, updateSubagentTaskStatus, renderAskUserQuestion, markAskUserAnswered, renderPermissionRequest, markPermissionCancelled, markPermissionResolved, renderElicitationRequest, markElicitationResolved, renderUserDialogRequest, markUserDialogResolved, updateThinkingTokens } from './tools.js';
 import { showDoneNotification, playDoneSound, isNotifAlertEnabled, isNotifSoundEnabled } from './notifications.js';
 import { handleFsList, handleFsRead, handleFileChanged, handleDirChanged, handleFileHistory, handleGitDiff, handleFileAt, refreshIfOpen, getPendingNavigate, handleFsSearch, presentMarkdownEdit } from './filebrowser.js';
@@ -42,6 +42,7 @@ import { checkAdminAccess } from './admin.js';
 import { mateAvatarUrl } from './avatar.js';
 import { showImageModal, sendExtensionCommand, handleMcpToolCallMessage } from './app-misc.js';
 import { handleMcpServersState } from './mcp-ui.js';
+import { handleShellCommandResult } from './shell-command.js';
 import { handleLoopRegistryUpdated, handleScheduleRunStarted, handleScheduleRunFinished, handleLoopScheduled, isSchedulerOpen, enterCraftingMode, exitCraftingMode, handleLoopRegistryFiles } from './scheduler.js';
 
 // --- App module imports ---
@@ -1209,6 +1210,15 @@ export function processMessage(msg) {
         addConflictMessage(msg);
         break;
 
+      case "session_writer_conflict":
+        removeMatePreThinking();
+        setActivity(null);
+        stopThinking();
+        markAllToolsDone();
+        closeToolGroup();
+        addSystemMessage(msg.text || "This session is already open in another process.", true);
+        break;
+
       case "context_overflow":
         removeMatePreThinking();
         setActivity(null);
@@ -1371,6 +1381,11 @@ export function processMessage(msg) {
         updateTerminalList(msg.terminals);
         break;
 
+      case "shell_command_result":
+        handleShellCommandResult(msg);
+        if (!msg.error) sendShellResultToAgent(msg);
+        break;
+
       case "context_sources_state":
         handleContextSourcesState(msg);
         break;

package/lib/public/modules/app-projects.js

@@ -24,6 +24,7 @@ import { isSchedulerOpen, closeScheduler, resetScheduler } from './scheduler.js'
 import { connect, cancelReconnect, setStatus } from './app-connection.js';
 import { setTurnCounter, setPrependAnchor, setActivityEl, setIsUserScrolledUp, hideSuggestionChips } from './app-rendering.js';
 import { resetToolState, enableMainInput, resetTurnMetaCost } from './tools.js';
+import { resetShellCommand } from './shell-command.js';
 import { clearPendingImages } from './input.js';
 import { clearAllMentionActive } from './sidebar-mates.js';
 import { setRewindMode } from './rewind.js';
@@ -368,6 +369,7 @@ export function resetClientState() {
   store.set({ currentFullText: "" });
   resetToolState();
   clearPendingImages();
+  resetShellCommand();
   clearAllMentionActive();
   setActivityEl(null);
   store.set({ processing: false });

package/lib/public/modules/input.js

@@ -7,6 +7,7 @@ import { mateAvatarUrl } from './avatar.js';
 import { tuiIsActive, tuiSubmitText } from './session-tui-view.js';
 import { VENDOR_AVATARS, VENDOR_NAMES } from './app-rendering.js';
 import { showToast } from './utils.js';
+import { isShellCommandMode, submitShellCommand } from './shell-command.js';
 
 var ctx;
 
@@ -75,6 +76,37 @@ export var builtinCommands = [
   { name: "status", desc: "Process status and resource usage" },
 ];
 
+function commitVendorForTurn() {
+  var committedVendor = store.get('currentVendor');
+  var vendorToggle = document.getElementById("vendor-toggle-wrap");
+  var activeIndicator = document.getElementById("active-vendor-indicator");
+  var activeIcon = document.getElementById("active-vendor-icon");
+  if (committedVendor) {
+    if (vendorToggle) {
+      vendorToggle.classList.add("hidden");
+      vendorToggle.classList.remove("locked");
+    }
+    if (activeIndicator && activeIcon) {
+      activeIcon.src = VENDOR_AVATARS[committedVendor] || VENDOR_AVATARS.claude;
+      activeIcon.alt = VENDOR_NAMES[committedVendor] || VENDOR_NAMES.claude;
+      activeIndicator.title = (VENDOR_NAMES[committedVendor] || VENDOR_NAMES.claude) + " session";
+      activeIndicator.classList.remove("hidden");
+    }
+  } else if (vendorToggle) {
+    vendorToggle.classList.remove("hidden");
+    vendorToggle.classList.add("locked");
+  }
+  store.set({ vendorSelectionLocked: false, sessionHasHistory: true });
+}
+
+function showPreThinkingForTurn() {
+  if (ctx.isMateDm && ctx.isMateDm()) {
+    ctx.showMatePreThinking();
+  } else if (ctx.showClaudePreThinking) {
+    ctx.showClaudePreThinking();
+  }
+}
+
 // --- Send ---
 export function sendMessage() {
   // Debate ended mode intercept: route to resume handler
@@ -92,6 +124,14 @@ export function sendMessage() {
     ctx.handleDebateFloorSend();
     return;
   }
+  if (isShellCommandMode()) {
+    var shellText = ctx.inputEl.value.trim();
+    if (!shellText || !submitShellCommand(shellText)) return;
+    ctx.inputEl.value = "";
+    sendInputSync();
+    autoResize();
+    return;
+  }
   // DM mode intercept: if in DM mode, route to DM handler instead
   if (ctx.isDmMode && ctx.isDmMode() && ctx.handleDmSend) {
     ctx.handleDmSend();
@@ -304,36 +344,10 @@ export function sendMessage() {
   // Bumping sessionHasHistory drives in-session lock states (e.g. the
   // Codex model picker that becomes informational once the thread is
   // bound to a model).
-  var _committedVendor = store.get('currentVendor');
-  var _vtw2 = document.getElementById("vendor-toggle-wrap");
-  var _avi = document.getElementById("active-vendor-indicator");
-  var _avIcon = document.getElementById("active-vendor-icon");
-  if (_committedVendor) {
-    if (_vtw2) {
-      _vtw2.classList.add("hidden");
-      _vtw2.classList.remove("locked");
-    }
-    if (_avi && _avIcon) {
-      _avIcon.src = VENDOR_AVATARS[_committedVendor] || VENDOR_AVATARS.claude;
-      _avIcon.alt = VENDOR_NAMES[_committedVendor] || VENDOR_NAMES.claude;
-      _avi.title = (VENDOR_NAMES[_committedVendor] || VENDOR_NAMES.claude) + " session";
-      _avi.classList.remove("hidden");
-    }
-  } else if (_vtw2) {
-    // No committed vendor (defensive — shouldn't happen because the
-    // input is otherwise gated on a vendor pick). Fall back to the
-    // locked toggle so the running vendor is still visible.
-    _vtw2.classList.remove("hidden");
-    _vtw2.classList.add("locked");
-  }
-  store.set({ vendorSelectionLocked: false, sessionHasHistory: true });
+  commitVendorForTurn();
 
   // Show pre-thinking dots before server responds
-  if (ctx.isMateDm && ctx.isMateDm()) {
-    ctx.showMatePreThinking();
-  } else if (ctx.showClaudePreThinking) {
-    ctx.showClaudePreThinking();
-  }
+  showPreThinkingForTurn();
 
   ctx.inputEl.value = "";
   sendInputSync();
@@ -354,6 +368,22 @@ export function sendTextMessage(text) {
   return true;
 }
 
+export function sendShellResultToAgent(msg) {
+  if (!ctx || !ctx.connected || !msg || msg.error || !msg.command) return false;
+  if (String(msg.sessionId) !== String(store.get("activeSessionId"))) return false;
+  var payload = {
+    type: "message",
+    text: "$ " + msg.command,
+    shellCommandResponse: true,
+  };
+  var selectedVendor = store.get("currentVendor") || null;
+  if (selectedVendor) payload.vendor = selectedVendor;
+  ctx.ws.send(JSON.stringify(payload));
+  commitVendorForTurn();
+  showPreThinkingForTurn();
+  return true;
+}
+
 export function autoResize() {
   ctx.inputEl.style.height = "auto";
   ctx.inputEl.style.height = Math.min(ctx.inputEl.scrollHeight, 120) + "px";

package/lib/public/modules/shell-command.js

@@ -0,0 +1,148 @@
+import { store } from './store.js';
+import { getWs } from './ws-ref.js';
+import { iconHtml, refreshIcons } from './icons.js';
+import { showToast } from './utils.js';
+
+var defaultPlaceholder = "";
+
+function getInput() {
+  return document.getElementById("input");
+}
+
+function appendToMessages(element) {
+  var messages = document.getElementById("messages");
+  if (!messages) return;
+  messages.appendChild(element);
+  requestAnimationFrame(function () { messages.scrollTop = messages.scrollHeight; });
+}
+
+function setMode(active) {
+  var input = getInput();
+  var button = document.getElementById("shell-command-btn");
+  var row = document.getElementById("input-row");
+  store.set({ shellCommandMode: active });
+  if (button) {
+    button.classList.toggle("active", active);
+    button.setAttribute("aria-pressed", active ? "true" : "false");
+  }
+  if (row) row.classList.toggle("shell-command-mode", active);
+  if (input) {
+    if (!defaultPlaceholder) defaultPlaceholder = input.placeholder;
+    input.placeholder = active ? "Run a shell command in this project…" : defaultPlaceholder;
+    input.focus();
+  }
+}
+
+export function isShellCommandMode() {
+  return !!store.get("shellCommandMode");
+}
+
+export function toggleShellCommandMode() {
+  if (store.get("shellCommandRunning")) return;
+  var target = store.get("dmTargetUser");
+  if (store.get("dmMode") && target && !target.isMate) {
+    showToast("Shell commands are available in agent sessions, not user DMs.", "error");
+    return;
+  }
+  setMode(!isShellCommandMode());
+}
+
+function renderPendingCommand(requestId, command) {
+  var card = document.createElement("div");
+  card.className = "shell-command-card running";
+  card.dataset.requestId = requestId;
+  card.innerHTML =
+    '<div class="shell-command-header">' +
+      '<span class="shell-command-icon">' + iconHtml("square-terminal") + '</span>' +
+      '<code></code><span class="shell-command-status">Running…</span>' +
+    '</div>' +
+    '<pre class="shell-command-output">Waiting for output…</pre>';
+  card.querySelector("code").textContent = "$ " + command;
+  appendToMessages(card);
+  refreshIcons();
+}
+
+export function submitShellCommand(command) {
+  command = String(command || "").trim();
+  if (!command || store.get("shellCommandRunning")) return false;
+  var ws = getWs();
+  if (!ws || ws.readyState !== 1) {
+    showToast("Not connected — command not run.", "error");
+    return false;
+  }
+
+  var requestId = "shell_" + Date.now() + "_" + Math.random().toString(36).slice(2, 9);
+  store.set({ shellCommandRunning: true, pendingShellCommandId: requestId });
+  var input = getInput();
+  if (input) {
+    input.disabled = true;
+    input.placeholder = "Running command…";
+  }
+  renderPendingCommand(requestId, command);
+  ws.send(JSON.stringify({ type: "shell_command", requestId: requestId, command: command }));
+  return true;
+}
+
+export function handleShellCommandResult(msg) {
+  var cards = document.querySelectorAll(".shell-command-card[data-request-id]");
+  var card = null;
+  for (var i = 0; i < cards.length; i++) {
+    if (cards[i].dataset.requestId === (msg.requestId || "")) {
+      card = cards[i];
+      break;
+    }
+  }
+  if (card) {
+    var status = card.querySelector(".shell-command-status");
+    var output = card.querySelector(".shell-command-output");
+    card.classList.remove("running");
+    if (msg.error) {
+      card.classList.add("error");
+      if (status) status.textContent = "Failed";
+      if (output) output.textContent = msg.error;
+    } else {
+      card.classList.toggle("error", msg.exitCode !== 0);
+      if (status) status.textContent = msg.timedOut ? "Timed out" : "Exit " + (msg.exitCode == null ? "—" : msg.exitCode);
+      if (output) output.textContent = msg.output || "(no output)";
+    }
+  }
+
+  store.set({ shellCommandRunning: false, pendingShellCommandId: null });
+  var input = getInput();
+  if (input) input.disabled = false;
+  if (msg.error) {
+    setMode(true);
+  } else {
+    setMode(false);
+  }
+  var messages = document.getElementById("messages");
+  if (messages) requestAnimationFrame(function () { messages.scrollTop = messages.scrollHeight; });
+}
+
+export function initShellCommand() {
+  var button = document.getElementById("shell-command-btn");
+  var mobileButton = document.getElementById("input-more-shell");
+  if (button) button.addEventListener("click", toggleShellCommandMode);
+  if (mobileButton) {
+    mobileButton.addEventListener("click", function () {
+      var sheet = document.getElementById("input-more-sheet");
+      if (sheet) {
+        sheet.classList.remove("open");
+        setTimeout(function () { sheet.classList.add("hidden"); }, 250);
+      }
+      toggleShellCommandMode();
+    });
+  }
+  store.subscribe(function (state, previous) {
+    if (previous.connected && !state.connected && state.shellCommandRunning) {
+      resetShellCommand();
+    }
+  });
+}
+
+export function resetShellCommand() {
+  store.set({ shellCommandMode: false, shellCommandRunning: false, pendingShellCommandId: null });
+  var input = getInput();
+  if (input) input.disabled = false;
+  setMode(false);
+}

package/lib/sdk-message-processor.js

@@ -792,7 +792,16 @@ function attachMessageProcessor(ctx) {
       // processQueryStream can finish the turn when the iterator closes.
       var adapterErrorText = parsed.text || parsed.message || parsed.error || "Agent runtime error";
       session._lastAdapterError = adapterErrorText;
-      sendAndRecord(session, { type: "error", text: adapterErrorText });
+      var isSessionWriterConflict = /thread-store conflict|already has an active writer/i.test(adapterErrorText);
+      if (isSessionWriterConflict) {
+        sendAndRecord(session, {
+          type: "session_writer_conflict",
+          vendor: session.vendor || "codex",
+          text: "This Codex session is already open in another Clay or Codex process. Stop the other server or close the other session, then try again.",
+        });
+      } else {
+        sendAndRecord(session, { type: "error", text: adapterErrorText });
+      }
 
     } else if (parsed.yokeType === "model_refusal") {
       // Model declined the request. "fallback" => the CLI retried on another

package/lib/ws-schema.js

@@ -145,6 +145,7 @@ var schema = {
   "kill_process":             { direction: "c2s", handler: "lib/project-sessions.js", description: "Kill a system process by PID" },
   "process_killed":           { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Process was successfully killed" },
   "process_conflict":         { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Conflict: another process is using the session" },
+  "session_writer_conflict":  { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Codex session is already open in another process" },
 
   // -----------------------------------------------------------------------
   // Context / usage
@@ -353,6 +354,8 @@ var schema = {
   "term_closed":              { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Terminal session was closed" },
   "term_list":                { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Full list of open terminals" },
   "term_error":               { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Terminal error (e.g. access denied)" },
+  "shell_command":            { direction: "c2s", handler: "lib/project-shell-command.js", description: "Run a one-shot shell command for agent context" },
+  "shell_command_result":     { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "One-shot shell command output and exit status" },
 
   // -----------------------------------------------------------------------
   // Sticky notes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clay-server",
-  "version": "3.4.0-beta.1",
+  "version": "3.4.0-beta.2",
   "description": "Self-hosted team workspace for Claude Code and Codex. Multi-user, browser-based, with persistent AI mates.",
   "bin": {
     "clay-server": "./bin/cli.js",