clay-server 5.2.0-beta.5 → 5.2.0-beta.7

package/lib/sessions.js

@@ -3,7 +3,7 @@ var path = require("path");
 var config = require("./config");
 var utils = require("./utils");
 var users = require("./users");
-var { CODEX_DEFAULTS } = require("./codex-defaults");
+var providerDefaults = require("./yoke/settings").defaults();
 var hygiene = require("./session-hygiene");
 var backgroundTaskTiming = require("./background-task-timing");
 var sessionProvenance = require("./session-provenance");
@@ -39,16 +39,16 @@ function createSessionManager(opts) {
   var permissionRequestIndex = {}; // requestId -> sessionLocalId (O(1) lookup)
   var capabilitiesByVendor = null; // set by sdk-bridge after adapter init
   var defaultVendor = null;        // set by sdk-bridge
-  var codexApproval = CODEX_DEFAULTS.approval;
-  var codexSandbox = CODEX_DEFAULTS.sandbox;
-  var codexWebSearch = CODEX_DEFAULTS.webSearch;
+  var codexApproval = providerDefaults.codexApproval;
+  var codexSandbox = providerDefaults.codexSandbox;
+  var codexWebSearch = providerDefaults.codexWebSearch;
 
   // --- Session persistence (centralized in ~/.clay/sessions/{encoded-cwd}/) ---
   var sessionsBase = opts.sessionsBase || path.join(config.CONFIG_DIR, "sessions");
   var encodedCwd = utils.resolveEncodedDir(sessionsBase, cwd);
   var sessionsDir = path.join(sessionsBase, encodedCwd);
   fs.mkdirSync(sessionsDir, { recursive: true });
-  var cliSessionsDir = opts.cliSessionsDir || path.join(config.REAL_HOME, ".claude", "projects", utils.encodeCwd(cwd));
+  var cliSessionsDir = opts.cliSessionsDir || require("./yoke/legacy-sessions").directory(config.REAL_HOME, cwd);
   var deletedCliSessionsPath = path.join(sessionsDir, "deleted-cli-sessions.json");
   var deletedCliSessionIds = new Set();
   try {
@@ -77,29 +77,6 @@ function createSessionManager(opts) {
     }
   }
 
-  function readCliTranscriptHead(filePath) {
-    var MAX_READ = 64 * 1024;
-    try {
-      var stat = fs.statSync(filePath);
-      var fd = fs.openSync(filePath, "r");
-      var bytesToRead = Math.min(stat.size, MAX_READ);
-      var buf = Buffer.alloc(bytesToRead);
-      fs.readSync(fd, buf, 0, bytesToRead, 0);
-      fs.closeSync(fd);
-      var lines = buf.toString("utf8").split("\n");
-      var events = [];
-      for (var i = 0; i < lines.length; i++) {
-        if (!lines[i]) continue;
-        try {
-          var event = JSON.parse(lines[i]);
-          if (event && typeof event === "object") events.push(event);
-        } catch (e) {}
-      }
-      return events;
-    } catch (e) {
-      return null;
-    }
-  }
 
   // Auto-migrate sessions from legacy locations:
   //   v1: {cwd}/.claude-relay/sessions/
@@ -234,8 +211,11 @@ function createSessionManager(opts) {
       if (session.claySchedulingReceipts) metaObj.claySchedulingReceipts = session.claySchedulingReceipts;
       if (session.mateCreationMode) metaObj.mateCreationMode = true;
       if (session.homeMateCreationPhase) metaObj.homeMateCreationPhase = session.homeMateCreationPhase;
+      if (session.contextualCreationMateStamp) metaObj.contextualCreationMateStamp = session.contextualCreationMateStamp;
+      if (session.contextualCreationRequestId) metaObj.contextualCreationRequestId = session.contextualCreationRequestId;
       if (session.homeClayEntryRequestId) metaObj.homeClayEntryRequestId = session.homeClayEntryRequestId;
       if (session.homeClayEntryMode) metaObj.homeClayEntryMode = session.homeClayEntryMode;
+      if (session.homeClayEntryText) metaObj.homeClayEntryText = session.homeClayEntryText;
       metaObj.sessionOriginId = provenanceMeta.sessionOriginId;
       if (provenanceMeta.sessionProvenance) metaObj.sessionProvenance = provenanceMeta.sessionProvenance;
       if (Array.isArray(session._workerGenerations)) metaObj.workerGenerations = session._workerGenerations;
@@ -398,8 +378,11 @@ function createSessionManager(opts) {
       if (Array.isArray(m.claySchedulingReceipts)) session.claySchedulingReceipts = m.claySchedulingReceipts;
       if (m.mateCreationMode) session.mateCreationMode = true;
       if (m.homeMateCreationPhase) session.homeMateCreationPhase = m.homeMateCreationPhase;
+      if (m.contextualCreationMateStamp) session.contextualCreationMateStamp = m.contextualCreationMateStamp;
+      if (m.contextualCreationRequestId) session.contextualCreationRequestId = m.contextualCreationRequestId;
       if (m.homeClayEntryRequestId) session.homeClayEntryRequestId = m.homeClayEntryRequestId;
       if (m.homeClayEntryMode) session.homeClayEntryMode = m.homeClayEntryMode;
+      if (m.homeClayEntryText) session.homeClayEntryText = m.homeClayEntryText;
       if (m.ownerId) session.ownerId = m.ownerId;
       session.sessionOriginId = m.sessionOriginId || null;
       session._provenanceMigrationNeeded = sessionProvenance.restore(m, session);
@@ -470,9 +453,6 @@ function createSessionManager(opts) {
   //   - Warmup shape: 1 real "hi" prompt, optional automatic interruption,
   //     and 0 assistant messages (covered by daemon cleanup but defensive)
   function adoptOrphanedCliSessions() {
-    var files;
-    try { files = fs.readdirSync(cliSessionsDir); } catch (e) { return; }
-
     // Build set of cliSessionIds Clay already tracks
     var knownCliIds = new Set();
     sessions.forEach(function (s) {
@@ -481,56 +461,10 @@ function createSessionManager(opts) {
 
     var adopted = 0;
 
-    for (var i = 0; i < files.length; i++) {
-      if (!files[i].endsWith(".jsonl")) continue;
-      var cliSid = files[i].slice(0, -".jsonl".length);
-      if (knownCliIds.has(cliSid)) continue;
-      if (deletedCliSessionIds.has(cliSid)) continue;
-
-      var fp = path.join(cliSessionsDir, files[i]);
-      var events = readCliTranscriptHead(fp);
-      if (!events) continue;
-      var userCount = 0;
-      var firstUserText = null;
-      var createdAtIso = null;
-      for (var li = 0; li < events.length; li++) {
-        var ev = events[li];
-        if (ev.type === "user" && ev.message && ev.message.role === "user") {
-          userCount++;
-          if (firstUserText == null) {
-            var c = ev.message.content;
-            if (typeof c === "string") {
-              firstUserText = c;
-            } else if (Array.isArray(c)) {
-              var parts = [];
-              for (var ci = 0; ci < c.length; ci++) {
-                if (c[ci] && c[ci].type === "text" && typeof c[ci].text === "string") parts.push(c[ci].text);
-              }
-              firstUserText = parts.join("");
-            }
-            if (ev.timestamp && !createdAtIso) createdAtIso = ev.timestamp;
-          }
-        }
-      }
-
-      if (userCount === 0) continue;
-      // Defensive warmup skip (daemon also cleans these)
-      if (hygiene.isClaudeWarmupTranscript(events)) continue;
-
-      // Title: first user message trimmed/truncated. Fall back to a
-      // neutral label so the sidebar entry is identifiable.
-      var title = (firstUserText || "").trim().replace(/\s+/g, " ");
-      if (title.length > 60) title = title.slice(0, 57) + "...";
-      if (!title) title = "Imported CLI session";
-
-      var createdAt = Date.now();
-      if (createdAtIso) {
-        var t = Date.parse(createdAtIso);
-        if (!isNaN(t)) createdAt = t;
-      }
-      var lastActivity = createdAt;
-      try { lastActivity = fs.statSync(fp).mtimeMs; } catch (e) {}
-
+    var candidates = require("./yoke/legacy-sessions").candidates(cliSessionsDir, knownCliIds, deletedCliSessionIds);
+    for (var i = 0; i < candidates.length; i++) {
+      var candidate = candidates[i], cliSid = candidate.id;
+      var title = candidate.title, createdAt = candidate.createdAt, lastActivity = candidate.lastActivity;
       var localId = nextLocalId++;
       var session = {
         localId: localId,
@@ -548,7 +482,7 @@ function createSessionManager(opts) {
         history: [],
         messageUUIDs: [],
         lastRewindUuid: null,
-        vendor: "claude",
+        vendor: candidate.vendor,
         mode: "tui",
         // Adopted from an external `claude` run in this cwd, not started by
         // Clay. Notification emitters must stay silent for these until the
@@ -580,10 +514,7 @@ function createSessionManager(opts) {
     var stale = [];
     sessions.forEach(function (session) {
       if (!session.adopted || !session.cliSessionId) return;
-      var transcriptPath = path.join(cliSessionsDir, session.cliSessionId + ".jsonl");
-      var events = readCliTranscriptHead(transcriptPath);
-      var missingEmptySource = !fs.existsSync(transcriptPath) && (!session.history || session.history.length === 0);
-      if (missingEmptySource || (events && hygiene.isClaudeWarmupTranscript(events))) stale.push(session.localId);
+      if (require("./yoke/legacy-sessions").obsolete(cliSessionsDir, session)) stale.push(session.localId);
     });
     for (var i = 0; i < stale.length; i++) deleteSessionQuiet(stale[i]);
     if (stale.length > 0) {
@@ -636,6 +567,7 @@ function createSessionManager(opts) {
     var unreadMap = wsUnread || singleUserUnread;
     return {
       id: s.localId,
+      sessionOriginId: s.sessionOriginId || null,
       cliSessionId: s.cliSessionId || null,
       createdAt: s.createdAt || 0,
       title: s.title || "New Session",
@@ -877,7 +809,8 @@ function createSessionManager(opts) {
       if (_item && (_item.type === "mention_user" || _item.type === "mention_response")) {
         console.log("[DEBUG replayHistory] sending mention at index=" + i + " from=" + fromIndex + " total=" + total + " type=" + _item.type + " mate=" + (_item.mateName || ""));
       }
-      var replayItem = transform ? transform(_item) : _item;
+      var normalizedItem = require("./yoke/usage").clientEvent(_item, session.vendor || "claude");
+      var replayItem = transform ? transform(normalizedItem) : normalizedItem;
       if (replayItem && typeof replayItem === "object") replayItem = Object.assign({}, replayItem, { _historyIndex: i });
       _send(replayItem);
     }
@@ -887,9 +820,11 @@ function createSessionManager(opts) {
     var lastModelUsage = null;
     var lastCost = null;
     var lastStreamInputTokens = null;
+    var lastContext = null;
     for (var j = total - 1; j >= 0; j--) {
       if (session.history[j].type === "result") {
-        var r = session.history[j];
+        var r = require("./yoke/usage").clientEvent(session.history[j], session.vendor || "claude");
+        lastContext = r.context || null;
         lastUsage = r.usage || null;
         lastModelUsage = r.modelUsage || null;
         lastCost = r.cost != null ? r.cost : null;
@@ -898,7 +833,7 @@ function createSessionManager(opts) {
       }
     }
 
-    _send({ type: "history_done", lastUsage: lastUsage, lastModelUsage: lastModelUsage, lastCost: lastCost, lastStreamInputTokens: lastStreamInputTokens, contextUsage: session.lastContextUsage || null });
+    _send({ type: "history_done", controlHistoryRevision: require("./clay-control-target-projection").digest(session.history || []), sessionId: session.localId, sessionOriginId: session.sessionOriginId || null, lastUsage: lastUsage, lastModelUsage: lastModelUsage, lastCost: lastCost, lastStreamInputTokens: lastStreamInputTokens, context: lastContext, contextUsage: require("./yoke/usage").context(session.lastContextUsage, session.vendor || "claude") });
     for (var vi = 0; vi < sessionViewedListeners.length; vi++) {
       try { sessionViewedListeners[vi](session, targetWs, _send); } catch (e) {}
     }

package/lib/terminal-manager.js

@@ -83,7 +83,7 @@ function createTerminalManager(opts) {
       }
 
       // Broadcast to subscribers
-      var msg = JSON.stringify({ type: "term_output", id: id, data: data });
+      var msg = JSON.stringify(Object.assign({ type: "term_output", id: id, data: data }, controlProjection(id)));
       for (var ws of session.subscribers) {
         if (ws.readyState === 1) ws.send(msg);
       }
@@ -108,7 +108,7 @@ function createTerminalManager(opts) {
       }
 
       // Broadcast updated list
-      send({ type: "term_list", terminals: list() });
+      send({ type: "term_list", terminals: list(true) });
 
       // Caller-supplied hook: e.g. TUI session manager uses this to delete
       // its session record once `claude` exits, so stale entries don't pile
@@ -181,10 +181,11 @@ function createTerminalManager(opts) {
         session.cols = cols;
         session.rows = rows;
         // Notify other subscribers about the resize so their xterm stays in sync
-        var msg = JSON.stringify({ type: "term_resized", id: id, cols: cols, rows: rows });
+        var msg = JSON.stringify(Object.assign({ type: "term_resized", id: id, cols: cols, rows: rows }, controlProjection(id)));
         for (var ws of session.subscribers) {
           if (ws.readyState === 1 && ws !== sourceWs) ws.send(msg);
         }
+        if (sourceWs && sourceWs.readyState === 1) sourceWs.send(JSON.stringify(Object.assign({ type: "term_control_projection", id: id }, controlProjection(id))));
       } catch (e) {}
     }
   }
@@ -244,15 +245,24 @@ function createTerminalManager(opts) {
     session.title = String(title).substring(0, 50);
   }
 
-  function list() {
+  function inspect(id) {
+      var terminal = terminals.get(id);
+      return terminal ? { id: id, identity: terminal.identity, ownerId: terminal.ownerId, osIdentity: terminal.osIdentity, title: terminal.title, kind: terminal.kind, exited: terminal.exited, cols: terminal.cols, rows: terminal.rows, totalBytesWritten: terminal.totalBytesWritten } : null;
+  }
+
+  function controlProjection(id) { var item = inspect(id); return item ? { controlIdentity: item.identity, controlRevision: require('./clay-control-target-projection').digest(item) } : {}; }
+
+  function list(control) {
     var result = [];
     for (var session of terminals.values()) {
-      result.push({
+      var entry = {
         id: session.id,
         title: session.title,
         kind: session.kind,
         exited: session.exited,
-      });
+      };
+      if (control) { entry.controlIdentity = session.identity; entry.controlRevision = require('./clay-control-target-projection').digest(inspect(session.id)); }
+      result.push(entry);
     }
     return result;
   }
@@ -333,10 +343,7 @@ function createTerminalManager(opts) {
     resize: resize,
     close: close,
     closeAndWait: closeAndWait,
-    inspect: function (id) {
-      var terminal = terminals.get(id);
-      return terminal ? { id: id, identity: terminal.identity, ownerId: terminal.ownerId, osIdentity: terminal.osIdentity, title: terminal.title, kind: terminal.kind, exited: terminal.exited, cols: terminal.cols, rows: terminal.rows, totalBytesWritten: terminal.totalBytesWritten } : null;
-    },
+    inspect: inspect,
     resizeExact: function (id, cols, rows, identity, revalidate) {
       revalidate();
       var terminal = terminals.get(id);
@@ -345,7 +352,7 @@ function createTerminalManager(opts) {
       revalidate();
       if (terminals.get(id) !== terminal) throw new Error('Terminal was replaced during resize.');
       terminal.cols = cols; terminal.rows = rows;
-      var message = JSON.stringify({ type: 'term_resized', id: id, cols: cols, rows: rows });
+      var message = JSON.stringify(Object.assign({ type: 'term_resized', id: id, cols: cols, rows: rows }, controlProjection(id)));
       terminal.subscribers.forEach(function (ws) { if (ws.readyState === 1) ws.send(message); });
       return true;
     },

package/lib/tool-llm.js

@@ -36,7 +36,7 @@ async function complete(opts) {
       skipProjectInstructions: true,
       skipSkills: true,
       canUseTool: function () { return Promise.resolve({ behavior: "deny", message: "Capsule LLM calls cannot use tools." }); },
-      adapterOptions: { CLAUDE: { linuxUser: opts.linuxUser || undefined, settingSources: ["user"] } },
+      adapterOptions: require("./yoke/query-options").map(adapter, { instructionSources: ["user"], readOnly: true, isolation: { user: opts.linuxUser || undefined } }),
     },
   });
   return result.text;

package/lib/tui-transcript-index.js

@@ -1,132 +1 @@
-// tui-transcript-index.js
-//
-// Build a per-session index of assistant text messages from a Claude Code
-// TUI transcript (~/.claude/projects/{encoded-cwd}/{cliSessionId}.jsonl).
-//
-// The TUI message-grab feature uses this index on the client to map a
-// hovered xterm region back to its original markdown source. We only
-// extract assistant text blocks. Tool calls and tool results render in
-// the terminal in a shape that's quite different from their JSONL form,
-// so matching them would be noisy and not particularly useful.
-//
-// Codex sessions don't write transcripts at all; callers should skip
-// indexing for non-claude vendors.
-
-var fs = require("fs");
-var path = require("path");
-var utils = require("./utils");
-var { REAL_HOME } = require("./config");
-
-var encodeCwd = utils.encodeCwd;
-
-// Min length of a normalized assistant message to bother indexing.
-// Anything shorter ("ok", "sure", "yes") would generate too many false
-// positives when matched against a hovered terminal block.
-var MIN_MATCH_LEN = 20;
-
-// Claude Code writes its JSONL under the *running user's* home, which
-// is not the daemon's home in OS-isolation mode (where each Clay user
-// gets a real Linux account like /home/clay-name). Callers from the
-// project context resolve the session owner's home and pass it in;
-// when no home is provided we fall back to REAL_HOME for single-user
-// installs.
-function transcriptFilePath(home, cwd, cliSessionId) {
-  if (!cwd || !cliSessionId) return null;
-  var base = home || REAL_HOME;
-  return path.join(base, ".claude", "projects", encodeCwd(cwd), cliSessionId + ".jsonl");
-}
-
-// matchKey is just whitespace-normalized raw markdown. We intentionally
-// do NOT strip markdown decoration here.
-//
-// Reasoning: TUI rendering drops markdown markers (**bold** -> bold,
-// `code` -> code, [text](url) -> text, etc.) and the visible text is
-// therefore always a substring of the JSONL source's character stream.
-// If we strip server-side we risk getting the rules wrong on corner
-// cases (double-backtick code spans, list-bullet rendering quirks,
-// nested formatting) and the resulting matchKey diverges from both
-// sides at once. Leaving the source alone and letting the client do a
-// multi-offset substring probe against block text is more robust and
-// much less code.
-function normalizeForMatch(s) {
-  if (!s) return "";
-  return s.replace(/\s+/g, " ").trim();
-}
-
-// Stable per-message id. Claude's JSONL usually carries one of these but
-// fall back to the parsed line index so the client always has a handle.
-function messageId(obj, index) {
-  if (obj && obj.uuid) return String(obj.uuid);
-  if (obj && obj.message && obj.message.id) return String(obj.message.id);
-  return "msg-" + index;
-}
-
-// Parse a single JSONL line into one assistant-text record, or null
-// when the line isn't one we index (user prompts, tool_use blocks,
-// tool_result records, etc.). Text-only assistant blocks get joined
-// in order so a multi-block response surfaces as a single grabbable
-// message.
-function parseAssistantTextLine(line, index) {
-  var obj;
-  try { obj = JSON.parse(line); } catch (e) { return null; }
-  if (!obj || !obj.message) return null;
-  if (obj.message.role !== "assistant") return null;
-  if (!Array.isArray(obj.message.content)) return null;
-
-  var text = "";
-  for (var i = 0; i < obj.message.content.length; i++) {
-    var block = obj.message.content[i];
-    if (block && block.type === "text" && typeof block.text === "string") {
-      text += block.text;
-    }
-  }
-  text = text.trim();
-  if (!text) return null;
-
-  var normalized = normalizeForMatch(text);
-  if (normalized.length < MIN_MATCH_LEN) return null;
-
-  return {
-    id: messageId(obj, index),
-    text: text,
-    matchKey: normalized,
-  };
-}
-
-// Read the whole transcript and return the assistant text index. The
-// transcripts are small enough (KB to a few MB) that a sync read on
-// session open or on a watcher-driven update is fine. We also return
-// the mtime/size so callers can short-circuit re-reads when nothing
-// changed.
-function readAssistantIndex(home, cwd, cliSessionId) {
-  var file = transcriptFilePath(home, cwd, cliSessionId);
-  if (!file) return { messages: [], mtimeMs: 0, byteLength: 0 };
-  var raw;
-  var stat;
-  try {
-    raw = fs.readFileSync(file, "utf8");
-    stat = fs.statSync(file);
-  } catch (e) {
-    return { messages: [], mtimeMs: 0, byteLength: 0 };
-  }
-  var lines = raw.split("\n");
-  var messages = [];
-  for (var i = 0; i < lines.length; i++) {
-    if (!lines[i]) continue;
-    var entry = parseAssistantTextLine(lines[i], i);
-    if (entry) messages.push(entry);
-  }
-  return {
-    messages: messages,
-    mtimeMs: stat.mtimeMs || 0,
-    byteLength: stat.size || raw.length,
-  };
-}
-
-module.exports = {
-  MIN_MATCH_LEN: MIN_MATCH_LEN,
-  transcriptFilePath: transcriptFilePath,
-  readAssistantIndex: readAssistantIndex,
-  parseAssistantTextLine: parseAssistantTextLine,
-  normalizeForMatch: normalizeForMatch,
-};
+module.exports = require("./yoke/tui-transcript-index");

package/lib/users-contextual-clay-preferences.js

@@ -0,0 +1,31 @@
+// Personal geometry is never a canonical product-control operation.
+function validGeometry(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  var keys = Object.keys(value);
+  if (keys.length !== 4 || keys.some(function (key) { return ['left', 'top', 'width', 'height'].indexOf(key) < 0; })) return false;
+  return keys.every(function (key) { return typeof value[key] === 'number' && Number.isFinite(value[key]); }) &&
+    value.left >= 0 && value.left <= 16384 && value.top >= 0 && value.top <= 16384 &&
+    value.width >= 340 && value.width <= 2560 && value.height >= 360 && value.height <= 2160;
+}
+function attachContextualClayPreferences(deps) {
+  function get(userId) {
+    var user = deps.loadUsers().users.find(function (entry) { return entry.id === userId; });
+    var saved = user && user.contextualClayGeometry;
+    if (!user && userId === 'default') saved = require('./config').loadConfig().contextualClayGeometry;
+    return validGeometry(saved) ? Object.assign({}, saved) : null;
+  }
+  function set(userId, geometry) {
+    if (!validGeometry(geometry)) return { error: 'Invalid popover geometry.' };
+    var value = Object.assign({}, geometry);
+    var data = deps.loadUsers();
+    var user = data.users.find(function (entry) { return entry.id === userId; });
+    if (user) { user.contextualClayGeometry = value; deps.saveUsers(data); }
+    else if (userId === 'default') {
+      var config = require('./config');
+      config.saveConfig(Object.assign({}, config.loadConfig(), { contextualClayGeometry: value }));
+    } else return { error: 'Account no longer available.' };
+    return { geometry: value };
+  }
+  return { getContextualClayGeometry: get, setContextualClayGeometry: set };
+}
+module.exports = { attachContextualClayPreferences: attachContextualClayPreferences, validGeometry: validGeometry };

package/lib/users.js

@@ -332,6 +332,7 @@ var creation = require("./users-create").attachCreation({ loadUsers: loadUsers,
 var createUser = creation.createUser;
 var createUserWithoutPin = creation.createUserWithoutPin;
 var permissions = attachPermissions({ loadUsers: loadUsers, saveUsers: saveUsers, findUserById: findUserById });
+var contextualClayPreferences = require("./users-contextual-clay-preferences").attachContextualClayPreferences({ loadUsers: loadUsers, saveUsers: saveUsers });
 var preferences = attachPreferences({ loadUsers: loadUsers, saveUsers: saveUsers });
 var projectMateFilterPreferences = attachProjectMateFilterPreferences({ loadUsers: loadUsers, saveUsers: saveUsers });
 var homeDockPreferences = attachHomeDockPreferences({ loadUsers: loadUsers, saveUsers: saveUsers });
@@ -478,6 +479,8 @@ module.exports = {
   setToolPalette: setToolPalette,
   getTerminalFont: getTerminalFont,
   setTerminalFont: setTerminalFont,
+  getContextualClayGeometry: contextualClayPreferences.getContextualClayGeometry,
+  setContextualClayGeometry: contextualClayPreferences.setContextualClayGeometry,
   getHomeDockPreference: getHomeDockPreference,
   setHomeDockPreference: setHomeDockPreference,
   getHomeSurfacePreference: getHomeSurfacePreference,

package/lib/vendor-login-browser.js

@@ -7,17 +7,7 @@ var spawn = require("child_process").spawn;
 var buildUserEnv = require("./build-user-env").buildUserEnv;
 var wrapSpawnAsUser = require("./os-users").wrapSpawnAsUser;
 
-function loginUrl(value, vendor) {
-  try {
-    var url = new URL(value);
-    var hosts = vendor === "codex" ? ["auth.openai.com"] : ["claude.ai", "claude.com", "console.anthropic.com", "platform.claude.com"];
-    if (url.protocol !== "https:" || url.username || url.password || hosts.indexOf(url.hostname) < 0) return null;
-    if (!url.searchParams.get("state") || !url.searchParams.get("code_challenge")) return null;
-    var callback = new URL(url.searchParams.get("redirect_uri"));
-    if (callback.protocol !== "http:" || ["localhost", "127.0.0.1", "[::1]"].indexOf(callback.hostname) < 0) return null;
-    return url.href;
-  } catch (e) { return null; }
-}
+var loginUrl = require("./yoke/login-protocol").loginUrl;
 
 function createLoginBrowser(options) {
   var initial = null;

package/lib/workspace-assignment-service.js

@@ -19,6 +19,8 @@ function attachWorkspaceAssignmentService(ctx) {
   var records = [];
   var unsubscribers = {};
   var pendingRestartReplay = {};
+  var presentations = new WeakMap();
+  var presentationTargets = new WeakMap();
 
   function recordFile(userId) {
     return storageDir ? path.join(storageDir, userStorageKey(userId)) : null;
@@ -130,7 +132,27 @@ function attachWorkspaceAssignmentService(ctx) {
     return { project: project, manager: manager, session: session };
   }
 
+  function present(record, principal) {
+    try {
+      var display = ctx.getPresentation && ctx.getPresentation(principal), project = exactTarget(record);
+      if (!display || !project) return;
+      var view = { project: project, session: null, origin: null }; presentationTargets.set(record, view);
+      if (record.delivery === 'follow_up') project.getSessionManager().sessions.forEach(function (session) { if (ctx.sessionRef(record.targetProjectSlug, session) === record.targetSessionRef) { view.session = session; view.origin = session.sessionOriginId; } });
+      var projection = require('./clay-control-target-projection');
+      var target = view.session ? { kind: 'session', projectSlug: record.targetProjectSlug, sessionId: view.session.localId, sessionOriginId: view.origin } : { kind: 'project', projectSlug: record.targetProjectSlug, runtimeId: projection.runtime(project.getSessionManager()) };
+      var observer = display.track('assignment', record.delivery === 'follow_up' ? 'follow_up' : 'assign', target, function () {
+        if (exactTarget(record) !== project || view.session && (project.getSessionManager().sessions.get(view.session.localId) !== view.session || view.session.sessionOriginId !== view.origin || (view.session.ownerId || null) !== (record.userId || null))) throw new Error('Assignment target changed.');
+      }, 'review');
+      if (observer) { presentations.set(record, observer); var expiry = setTimeout(function () { presentations.delete(record); }, 300000); expiry.unref(); }
+    } catch (error) { /* Presentation never changes the assignment decision. */ }
+  }
   function emit(record, eventType) {
+    var observer = presentations.get(record);
+    if (observer) {
+      if (record.status === 'starting') observer.phase('queued');
+      else if (record.status === 'running') observer.phase('running');
+      else if (record.status !== 'proposed') { observer.finish({ status: record.status === 'interrupted' ? 'failed' : record.status, outcome: record.status === 'interrupted' ? 'uncertain' : undefined }); presentations.delete(record); }
+    }
     var source = exactSource(record);
     if (!source) return;
     source.manager.sendAndRecord(source.session, {
@@ -193,6 +215,7 @@ function attachWorkspaceAssignmentService(ctx) {
     if (!exactSource(record)) throw new Error("Source conversation is no longer available.");
     records.push(record);
     saveUser(record.userId);
+    present(record, principal);
     emit(record, "project_assignment_proposal");
     return publicRecord(record);
   }
@@ -229,6 +252,7 @@ function attachWorkspaceAssignmentService(ctx) {
     if (!exactSource(record)) throw new Error("Source conversation is no longer available.");
     records.push(record);
     saveUser(record.userId);
+    present(record, principal);
     emit(record, "project_assignment_proposal");
     return publicRecord(record);
   }
@@ -267,6 +291,7 @@ function attachWorkspaceAssignmentService(ctx) {
   }
 
   function watch(record, manager, session) {
+    var view = presentationTargets.get(record); if (view) { view.session = session; view.origin = session.sessionOriginId; var observer = presentations.get(record); if (observer && observer.target) observer.target({ kind: 'session', projectSlug: record.targetProjectSlug, sessionId: session.localId, sessionOriginId: session.sessionOriginId }); }
     var unsubscribe = manager.subscribeSession(session.localId, function (event) {
       if (event.type === "session_id") {
         record.targetSessionRef = ctx.sessionRef(record.targetProjectSlug, session);

package/lib/workspace-query-mcp-server.js

@@ -32,7 +32,7 @@ function handler(bound, method) {
   };
 }
 
-var SESSION_CITATION = " When citing a returned session in user-visible text, write [clayos/<sessionRef> — short label] so Clay Studio renders an owner-validated session control.";
+var SESSION_CITATION = " Cite returned sessions as Markdown links: [short human label](session:OPAQUE_REFERENCE), replacing the entire target with the exact returned sessionRef. Do not prepend a project name, change the opaque reference, or wrap citations in backticks/code. For a specific returned entry, append #entry-<entryIndex> using its exact returned entry index. Legacy [clayos/<sessionRef> — short label] remains supported. Labels are presentation only; Clay Studio resolves the exact reference with the authenticated owner's permissions.";
 
 function commonTools(bound) {
   return [

package/lib/ws-request.js

@@ -8,6 +8,7 @@ function parseWsRequestUrl(requestUrl) {
     path: parsed.pathname || "/",
     pane: parsed.query.pane === "1",
     paneSession: paneSession,
+    contextual: parsed.query.pane === "1" && parsed.query.contextual === "1",
   };
 }
 

package/lib/ws-schema.js

@@ -11,6 +11,11 @@
  * Use it as a reference when adding new message types.
  */
 
+// message.contextualSnapshot: version=1, viewId, nullable projectTitle,
+// conversationTitle/projectSlug (160 characters), nullable positive sessionId,
+// screen=Home|Project|Direct message. Private canonical owner delivery only.
+// Persisted user_message metadata is echoed in message_ack only after recording;
+// queued admission ACK has no snapshot. Never part of user text/pastes or authority.
 var schema = {
 
   // -----------------------------------------------------------------------
@@ -62,6 +67,7 @@ var schema = {
   "project_assignment_response": { direction: "c2s", handler: "lib/workspace-assignment-service.js", description: "Approve or cancel an exact-session cross-project assignment proposal" },
   "home_clay_session_resolve": { direction: "c2s", handler: "lib/server-home-chat.js", description: "Resolve an opaque Mate session reference through the exact bound source session" },
   "home_clay_session_target": { direction: "s2c", handler: "lib/public/modules/command-palette.js", description: "Return an owner-validated navigation target for a rendered Mate session reference" },
+  "home_clay_contextual_session": { direction: "s2c", handler: "lib/public/modules/contextual-search.js", description: "Return the exact fresh canonical session for an idempotent contextual Ask request; does not submit or execute a message" },
   "issues_list": { direction: "c2s", handler: "lib/project-issues.js", description: "Project Issues issues list" },
   "issue_read": { direction: "c2s", handler: "lib/project-issues.js", description: "Project Issues issue read" },
   "issue_create": { direction: "c2s", handler: "lib/project-issues.js", description: "Project Issues issue create" },
@@ -482,6 +488,7 @@ var schema = {
   "term_resized":             { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Terminal was resized" },
   "term_exited":              { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Terminal process exited" },
   "term_closed":              { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Terminal session was closed" },
+  "term_control_projection": { direction: "s2c", handler: "lib/public/modules/terminal.js", description: "Authoritative terminal identity/revision after owner resize without echoing resize input" },
   "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" },
@@ -785,6 +792,7 @@ var schema = {
   // -----------------------------------------------------------------------
   "home_mate_open":           { direction: "c2s", handler: "lib/server-home-chat.js", description: "Open or restore the selected mate's embedded chat session" },
   "home_clay_ask":            { direction: "c2s", handler: "lib/server-home-chat.js", description: "Start a fresh builtin Clay conversation from the global search drawer" },
+  "contextual_mate_sessions_result": { direction: "s2c", handler: "lib/public/modules/contextual-mate-sessions.js", description: "Exact owner-private saved Mate conversation list or selection receipt; no transcript tap or underlying navigation" },
   "home_mate_sessions_list":  { direction: "c2s", handler: "lib/server-home-chat.js", description: "List the current user's conversations with the selected mate" },
   "home_mate_session_open":   { direction: "c2s", handler: "lib/server-home-chat.js", description: "Open one explicit conversation with the selected mate" },
   "home_mate_send":           { direction: "c2s", handler: "lib/server-home-chat.js", description: "Send a message to the selected mate from the home hub" },
@@ -814,6 +822,8 @@ var schema = {
   "clay_navigation_offer":    { direction: "s2c", handler: "lib/public/modules/clay-owner-navigation.js", description: "Offer one exact reviewed navigation to a selected owner connection" },
   "clay_navigation_claim":    { direction: "c2s", handler: "lib/server-owner-ui.js", description: "Claim an offered navigation with live source/target revalidation" },
   "clay_navigation_apply":    { direction: "s2c", handler: "lib/public/modules/clay-owner-navigation.js", description: "Invoke the shared conversation navigator after live claim" },
+  "clay_studio_rendered": { direction: "c2s", handler: "lib/project-studio-presentation.js", description: "Exact source-viewer workbench render receipt; no product effects" },
+  "clay_navigation_rendered": { direction: "c2s", handler: "lib/server-owner-ui.js", description: "Bounded exact-viewer rendered conversation evidence; acceptance alone remains separate" },
   "clay_navigation_ack":      { direction: "c2s", handler: "lib/server-owner-ui.js", description: "Client invocation acknowledgement; never proof of visible rendering" },
   "context_view_get":         { direction: "c2s", handler: "lib/server-context-view.js", description: "Read the authenticated user's context display preference" },
   "context_view_set":         { direction: "c2s", handler: "lib/server-context-view.js", description: "Persist the authenticated user's context display preference" },