clay-server 5.2.0-beta.1 → 5.2.0-beta.11

package/lib/vendor-usage-service.js

@@ -0,0 +1,281 @@
+// Shared acquisition service for vendor account usage.
+//
+// One place decides whether a direct read is allowed, runs it with a bounded
+// timeout (cancelling the underlying work), shares an in-flight read between
+// callers, caches results and backs off after failures. Provider-specific
+// parsing lives in the reader modules; the capability table says which vendors
+// have a reader at all.
+//
+// Identity: a direct read is allowed only when the credential provably belongs
+// to the requester. In account mode, vendors that run as the server's own user
+// (Muse, Kimi, Grok, Kiro) and Codex without a mapped OS user are refused with a
+// clear status instead of showing the server user's account to every owner.
+// Cache entries are keyed by owner + OS user + vendor. Where a cheap credential
+// fingerprint exists (Kimi, Grok) it is re-read before cached figures are
+// returned (including while a read is in flight) and again when a read
+// completes; rotation or deletion discards the figures. Figures from a source
+// whose account cannot be verified (Muse, Kiro, Claude, Codex) are shown for at
+// most one TTL (60 s) from the reading: after that, in peek and read alike,
+// they are replaced by an explicit "expired" state with no numbers, and a failed
+// refresh never extends them. Verified-identity figures may be kept, marked
+// stale, across a transient failure for at most `staleMaxMs`. A Claude reading
+// is bound to the exact live session and query that produced it and is dropped
+// when that source is replaced. Sign-in failures and account changes always drop
+// figures. A result is used only if the caller is still current when the work
+// starts, while it waits, and when it settles.
+
+var capabilities = require("./vendor-usage-capabilities");
+var metrics = require("./vendor-usage-metrics");
+var nativeReaders = require("./vendor-usage-native-readers");
+var httpReaders = require("./vendor-usage-http-readers");
+var acpReaders = require("./vendor-usage-acp-readers");
+
+var DEFAULTS = { ttlMs: 60 * 1000, minForceMs: 10 * 1000, timeoutMs: 15 * 1000, backoffBaseMs: 30 * 1000, backoffMaxMs: 10 * 60 * 1000, noAuthRetryMs: 5 * 60 * 1000, staleMaxMs: 10 * 60 * 1000 };
+
+// Failures that mean the credential or account is not (or no longer) the one
+// the cached figures described, so those figures must not be shown again.
+var DROPS_FIGURES = ["no_auth", "expired_auth", "unauthorized", "untrusted_origin", "account_changed", "source_changed"];
+
+var MESSAGES = {
+  identity_unprovable: "Clay cannot prove which account this vendor uses for you, so it will not read one.",
+  account_changed: "The saved sign-in changed while usage was being read; figures from the previous account were discarded.",
+  source_changed: "The session that reported this usage was replaced; its figures were discarded.",
+  expired: "The last reading is too old and its account cannot be verified, so it is not shown. Read again.",
+};
+
+function defaultFetchJson(timeoutMs) {
+  return async function (url, headers) {
+    var response = await fetch(url, { headers: headers, signal: AbortSignal.timeout(timeoutMs), redirect: "error" });
+    var body = null;
+    try { body = await response.json(); } catch (e) { body = null; }
+    return { status: response.status, body: body };
+  };
+}
+
+function createUsageService(options) {
+  options = options || {};
+  var now = typeof options.now === "function" ? options.now : Date.now;
+  var timing = Object.assign({}, DEFAULTS, options.timing || {});
+  var fs = require("fs");
+  var os = require("os");
+  var httpDeps = Object.assign({
+    readText: function (file) { return fs.promises.readFile(file, "utf8"); },
+    readTextSync: function (file) { return fs.readFileSync(file, "utf8"); },
+    fetchJson: defaultFetchJson(timing.timeoutMs),
+    env: process.env, homedir: os.homedir,
+  }, options.http || {});
+  httpDeps.now = now;
+  var acpDeps = Object.assign({
+    binary: function () { try { return require("./yoke/kiro-acp-server").findKiroPath(); } catch (e) { return null; } },
+    spawn: function (command, args, spawnOptions) { return require("child_process").spawn(command, args, spawnOptions); },
+    tmpdir: os.tmpdir, env: process.env,
+  }, options.acp || {});
+  var readers = Object.assign({
+    claude: nativeReaders.claude,
+    codex: nativeReaders.codex,
+    muse: nativeReaders.muse,
+    kimi: function () { return httpReaders.kimi(httpDeps); },
+    grok: function () { return httpReaders.grok(httpDeps); },
+    kiro: function (context) { return acpReaders.kiro(context, acpDeps); },
+  }, options.readers || {});
+  var identities = Object.assign({
+    kimi: function () { return httpReaders.identities.kimi(httpDeps); },
+    grok: function () { return httpReaders.identities.grok(httpDeps); },
+  }, options.identities || {});
+  var multiUser = typeof options.multiUser === "function" ? options.multiUser : function () { return false; };
+  var osUsersEnabled = typeof options.osUsersEnabled === "function" ? options.osUsersEnabled : function () { return false; };
+  var sourceLive = typeof options.sourceLive === "function" ? options.sourceLive : function () { return true; };
+  var getAdapter = typeof options.getAdapter === "function" ? options.getAdapter : function () { return null; };
+  var entries = Object.create(null);
+  var generations = Object.create(null);
+
+  function keyOf(owner, linuxUser, vendor) { return owner + "\u0000" + (linuxUser || "") + "\u0000" + vendor; }
+
+  function identityOf(vendor) {
+    try { return identities[vendor] ? identities[vendor]() : null; } catch (e) { return null; }
+  }
+
+  function refusal(vendor, linuxUser, hasSession) {
+    var cap = capabilities.capabilityFor(vendor);
+    if (cap.mode !== "query") return { status: "unintegrated", failureKind: "unintegrated", message: cap.reason || "No usage source is integrated." };
+    if (cap.identity === "owner-session") return hasSession === false ? { status: "idle", failureKind: null, message: null } : null;
+    if (!multiUser()) return null;
+    if (cap.identity === "owner-os-user" && osUsersEnabled() && linuxUser) return null;
+    return { status: "refused", failureKind: "identity_unprovable", message: MESSAGES.identity_unprovable };
+  }
+
+  function blank(status, failureKind, message) {
+    return { status: status, metrics: [], fetchedAtMs: null, stale: false, failureKind: failureKind || null, message: message || null, retryAtMs: null, planType: null, accountId: null, fetching: false };
+  }
+
+  function bindingOf(session) {
+    return session ? { session: session, query: session.queryInstance } : null;
+  }
+
+  function bindingLive(binding) {
+    return !binding || (binding.session.queryInstance === binding.query && sourceLive(binding.session) !== false);
+  }
+
+  function sameBinding(a, b) {
+    return (!a && !b) || (!!a && !!b && a.session === b.session && a.query === b.query);
+  }
+
+  // Figures whose account cannot be verified live only for one TTL; verified
+  // ones may stay (stale) a bounded while. Past that the numbers are removed.
+  function expire(entry) {
+    var a = entry.account;
+    if (!a.metrics.length) return;
+    var age = a.fetchedAtMs === null ? Infinity : now() - a.fetchedAtMs;
+    var limit = entry.identity ? timing.staleMaxMs : timing.ttlMs;
+    if (age < limit) return;
+    entry.account = { status: "idle", metrics: [], fetchedAtMs: null, stale: false, failureKind: "expired", message: MESSAGES.expired, planType: null, accountId: null };
+    entry.identity = null;
+  }
+
+  function snapshotOf(entry) {
+    expire(entry);
+    var a = entry.account;
+    return {
+      status: a.status, metrics: a.metrics.slice(), fetchedAtMs: a.fetchedAtMs, stale: a.stale === true,
+      failureKind: a.failureKind || null, message: a.message || null, retryAtMs: entry.retryAtMs || null,
+      planType: a.planType || null, accountId: a.accountId || null, sourceSessionId: a.sourceSessionId === undefined ? null : a.sourceSessionId,
+      fetching: !!entry.inflight,
+    };
+  }
+
+  function emptyEntry() {
+    return { account: { status: "idle", metrics: [], fetchedAtMs: null }, identity: null, binding: null, failures: 0, retryAtMs: 0, inflight: null, token: 0 };
+  }
+
+  function drop(key) {
+    var entry = entries[key];
+    if (!entry) return;
+    entry.token++;
+    delete entries[key];
+  }
+
+  // True when the cached projection no longer describes the live source: the
+  // credential fingerprint differs (rotation or deletion, even mid-read) or the
+  // session/query that produced it was replaced.
+  function sourceChanged(entry, vendor) {
+    if (entry.identity && identityOf(vendor) !== entry.identity) return true;
+    return !bindingLive(entry.binding);
+  }
+
+  // The current known state, without starting a read.
+  function peek(owner, linuxUser, vendor) {
+    var refused = refusal(vendor, linuxUser, null);
+    if (refused && refused.status !== "idle") return blank(refused.status, refused.failureKind, refused.message);
+    var key = keyOf(owner, linuxUser, vendor);
+    var entry = entries[key];
+    if (!entry) return blank("idle");
+    if (sourceChanged(entry, vendor)) { drop(key); return blank("idle"); }
+    return snapshotOf(entry);
+  }
+
+  function failureDelay(entry, kind) {
+    if (kind === "no_auth") return timing.noAuthRetryMs;
+    return Math.min(timing.backoffMaxMs, timing.backoffBaseMs * Math.pow(2, Math.max(0, entry.failures - 1)));
+  }
+
+  function settleFailure(entry, error) {
+    var kind = error && error.failureKind ? error.failureKind : "error";
+    entry.failures += 1;
+    entry.retryAtMs = now() + failureDelay(entry, kind);
+    var prior = entry.account;
+    // Only a transient failure keeps the last good figures (marked stale);
+    // a sign-in problem or account change must not leave a former account's numbers.
+    // Figures survive only when their account is verifiable (a fingerprint) and
+    // they are still inside the bounded stale window.
+    var keep = DROPS_FIGURES.indexOf(kind) === -1 && !!entry.identity && prior.metrics.length > 0 && (prior.status === "ok" || prior.stale === true) && prior.fetchedAtMs !== null && now() - prior.fetchedAtMs < timing.staleMaxMs;
+    entry.account = {
+      status: kind === "no_auth" ? "no_auth" : kind === "expired_auth" ? "expired_auth" : "error",
+      metrics: keep ? prior.metrics : [], fetchedAtMs: keep ? prior.fetchedAtMs : null, stale: keep,
+      failureKind: kind, message: error && error.failureKind ? error.message : "Usage could not be read.",
+      planType: keep ? prior.planType || null : null, accountId: keep ? prior.accountId || null : null,
+      sourceSessionId: keep ? prior.sourceSessionId : null,
+    };
+    if (!keep) { entry.identity = null; entry.binding = null; }
+  }
+
+  function withTimeout(promise, controller) {
+    var timer;
+    var limit = new Promise(function (resolve, reject) {
+      timer = setTimeout(function () {
+        controller.abort();
+        reject(nativeReaders.failure("timeout", "The usage read timed out."));
+      }, timing.timeoutMs);
+    });
+    return Promise.race([promise, limit]).then(function (v) { clearTimeout(timer); return v; }, function (e) { clearTimeout(timer); throw e; });
+  }
+
+  // Resolves to a snapshot, or null when the result must not be used because
+  // the caller or the account changed. Nothing is started for a caller that is
+  // already stale.
+  async function read(request) {
+    var owner = request.owner, linuxUser = request.linuxUser || null, vendor = request.vendor;
+    var isCurrent = typeof request.isCurrent === "function" ? request.isCurrent : function () { return true; };
+    if (!isCurrent()) return null;
+    var refused = refusal(vendor, linuxUser, !!request.session);
+    if (refused) return refused.status === "idle" ? peek(owner, linuxUser, vendor) : blank(refused.status, refused.failureKind, refused.message);
+    var key = keyOf(owner, linuxUser, vendor);
+    var entry = entries[key] || (entries[key] = emptyEntry());
+    var startedGeneration = generations[owner] || 0;
+    var before = identityOf(vendor);
+    var binding = bindingOf(request.session);
+    if ((entry.identity && before !== entry.identity) || !bindingLive(entry.binding) || (entry.binding && !sameBinding(entry.binding, binding))) {
+      drop(key);
+      entry = entries[key] = emptyEntry();
+    }
+    expire(entry);
+    var current = now();
+    var age = entry.account.fetchedAtMs === null ? Infinity : current - entry.account.fetchedAtMs;
+    var coolingDown = entry.retryAtMs > current;
+    var fresh = entry.account.status === "ok" && age < (request.force ? timing.minForceMs : timing.ttlMs);
+    if (!entry.inflight && (fresh || coolingDown)) return isCurrent() ? snapshotOf(entry) : null;
+    if (!entry.inflight) {
+      var token = ++entry.token;
+      var controller = new AbortController();
+      var context = { adapter: getAdapter(vendor), linuxUser: linuxUser, session: request.session || null, signal: controller.signal };
+      entry.binding = binding;
+      var run = Promise.resolve().then(function () { return withTimeout(readers[vendor](context), controller); });
+      entry.inflight = run.then(function (result) {
+        if (entry.token !== token || (generations[owner] || 0) !== startedGeneration) return;
+        var list = (result && Array.isArray(result.metrics) ? result.metrics : []).filter(metrics.valid);
+        if (list.length === 0) throw nativeReaders.failure("unavailable", "The vendor reported no usage figures for this account.");
+        if (!bindingLive(binding)) throw nativeReaders.failure("source_changed", MESSAGES.source_changed);
+        // The credential is re-read AFTER the response. For a fingerprinted
+        // source it must equal the one the reader used (or, failing that, the
+        // one seen before the call); rotation, deletion or first appearance
+        // mid-read means neither account's figures can be attributed.
+        var expected = result.identity || before;
+        if (identities[vendor]) {
+          var fresh = identityOf(vendor);
+          if (fresh !== expected) throw nativeReaders.failure("account_changed", MESSAGES.account_changed);
+        }
+        entry.failures = 0; entry.retryAtMs = 0;
+        entry.identity = identities[vendor] ? expected || null : null;
+        entry.account = { status: "ok", metrics: list, fetchedAtMs: Number.isFinite(result.observedAtMs) ? result.observedAtMs : now(), stale: false, planType: result.planType || null, accountId: result.accountId || null, sourceSessionId: result.sourceSessionId === undefined ? null : result.sourceSessionId };
+      }).catch(function (error) {
+        if (entry.token !== token || (generations[owner] || 0) !== startedGeneration) return;
+        settleFailure(entry, error);
+      }).then(function () { if (entry.token === token) entry.inflight = null; });
+    }
+    await entry.inflight;
+    if (!isCurrent() || (generations[owner] || 0) !== startedGeneration || entries[key] !== entry) return null;
+    return snapshotOf(entry);
+  }
+
+  // Forget everything for an owner (account switch, logout, access change);
+  // reads still in flight can no longer store or return a result.
+  function invalidate(owner) {
+    generations[owner] = (generations[owner] || 0) + 1;
+    Object.keys(entries).forEach(function (key) {
+      if (key.indexOf(owner + "\u0000") === 0) drop(key);
+    });
+  }
+
+  return { read: read, peek: peek, invalidate: invalidate, refusal: refusal };
+}
+
+module.exports = { createUsageService: createUsageService, DEFAULTS: DEFAULTS };

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-access.js

@@ -96,7 +96,10 @@ function attachWorkspaceQueryAccess(deps) {
     // as ownership would let a stale status skip the authoritative record.
     var access = record(status);
     if (!access) return denied;
-    if (access.ownerId && access.ownerId === principal.userId) return { owned: true, accessible: true };
+    if (access.ownerId && access.ownerId === principal.userId) {
+      var ownerPermitted = permitted(principal.userId, access);
+      return { owned: ownerPermitted, accessible: ownerPermitted };
+    }
     return { owned: false, accessible: permitted(principal.userId, access) };
   }
 

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/workspace-query-service.js

@@ -168,6 +168,13 @@ function attachWorkspaceQueryService(ctx) {
     } else if (source.session.ownerId) {
       return null;
     }
+    if (source.viewerId !== undefined) {
+      var viewerPrincipal = {
+        userId: isMultiUser() ? source.viewerId : null,
+        singleUserOwnerId: isMultiUser() ? null : source.viewerId,
+      };
+      if (!ownsSession(viewerPrincipal, source.session)) return null;
+    }
     return createBound({
       userId: isMultiUser() ? source.session.ownerId : null,
       sourceProjectSlug: source.projectSlug,
@@ -366,11 +373,13 @@ function attachWorkspaceQueryService(ctx) {
 
   function resolveSessionNavigation(principal, ref) {
     if (typeof ref !== "string" || !/^session:[A-Za-z0-9_-]{24}$/.test(ref)) throw new Error("Invalid session reference.");
+    var entryIndex = arguments.length > 2 ? arguments[2] : null;
+    if (entryIndex !== null && entryIndex !== undefined && (!Number.isSafeInteger(entryIndex) || entryIndex < 0)) throw new Error("Invalid session entry reference.");
     var projects = collect(principal);
     for (var p = 0; p < projects.length; p++) {
       var session = findSession(projects[p], ref);
       if (!session) continue;
-      return {
+      var target = {
         projectSlug: projects[p].projectSlug,
         projectTitle: projects[p].projectTitle,
         isMate: projects[p].isMate,
@@ -379,6 +388,8 @@ function attachWorkspaceQueryService(ctx) {
         homeSessionId: session.cliSessionId || "local:" + session.localId,
         title: cleanMetadata(session.title || "New Session", 160),
       };
+      if (entryIndex !== null && entryIndex !== undefined) target.entryIndex = entryIndex;
+      return target;
     }
     throw new Error("Session not found in the owned workspace.");
   }
@@ -450,7 +461,7 @@ function attachWorkspaceQueryService(ctx) {
         if (!principal.isClay) throw new Error("Workspace-wide activity is available only to builtin Clay.");
         return workspaceActivity(principal, args || {});
       },
-      resolveSessionNavigation: function (args) { return resolveSessionNavigation(principal, args && args.sessionRef); },
+      resolveSessionNavigation: function (args) { return resolveSessionNavigation(principal, args && args.sessionRef, args && args.entryIndex); },
       listRecentDecisions: function (args) {
         if (!principal.isClay) throw new Error("Workspace decisions are available only to builtin Clay.");
         return recentDecisions(principal, args || {});

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 = {
 
   // -----------------------------------------------------------------------
@@ -32,6 +37,8 @@ var schema = {
   "session_folders_state":    { direction: "s2c", handler: "lib/public/modules/session-folders.js", description: "Authoritative per-user, per-project session folder state; sent on connect and after every change to all of that user's sockets" },
   "new_session_options_get":  { direction: "c2s", handler: "lib/project-session-creation.js", description: "Ask for the installed providers, the project's default provider and whether the caller may set it" },
   "new_session_default_set":  { direction: "c2s", handler: "lib/project-session-creation.js", description: "Save the project-scoped default provider the inline New session row preselects" },
+  "vendor_usage_get":         { direction: "c2s", handler: "lib/vendor-usage-overview.js", description: "Ask for the caller's observed per-vendor usage overview for this project" },
+  "vendor_usage_overview":    { direction: "s2c", handler: "lib/public/modules/vendor-usage-overview.js", description: "Owner-scoped observed vendor usage windows, reset times and observation times; unknown vendors carry no windows" },
   "new_session_options":      { direction: "s2c", handler: "lib/public/modules/session-create.js", description: "Installed providers, project default provider and default-setting permission for the inline New session row" },
   "new_session_default_result": { direction: "s2c", handler: "lib/public/modules/session-create.js", description: "Outcome of saving the project New session default" },
   "new_session_project_default": { direction: "s2c", handler: "lib/public/modules/session-create.js", description: "The project New session default changed" },
@@ -62,6 +69,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" },
@@ -398,9 +406,9 @@ var schema = {
   // -----------------------------------------------------------------------
   // Projects
   // -----------------------------------------------------------------------
-  "browse_dir":               { direction: "c2s", handler: "lib/project-sessions.js", description: "Browse directory entries for project creation" },
+  "browse_dir":               { direction: "c2s", handler: "lib/project-sessions.js", description: "Browse directory entries for project creation (requestId echoed; reply adds canonical dir, prefix, permitted parent)" },
   "browse_dir_result":        { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Directory listing result" },
-  "add_project":              { direction: "c2s", handler: "lib/project-sessions.js", description: "Add an existing directory as a project" },
+  "add_project":              { direction: "c2s", handler: "lib/project-sessions.js", description: "Add an existing directory as a project (optional requestId echoed on add_project_result, also for create/clone)" },
   "add_project_result":       { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Add project result" },
   "create_project":           { direction: "c2s", handler: "lib/project-sessions.js", description: "Create a new empty project directory" },
   "clone_project":            { direction: "c2s", handler: "lib/project-sessions.js", description: "Clone a git repository as a new project" },
@@ -482,6 +490,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" },
@@ -495,10 +504,11 @@ var schema = {
   "note_written":             { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Agent created or updated a sticky note" },
   "note_update":              { direction: "c2s", handler: "lib/project-user-message.js", description: "Update a sticky note" },
   "note_updated":             { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Sticky note was updated" },
-  "note_close":               { direction: "c2s", handler: "lib/project-user-message.js", description: "Close a sticky note (reversible; never deletes)" },
+  "note_update_result":        { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Correlated sticky note update result" },
+  "note_close":               { direction: "c2s", handler: "lib/project-user-message.js", description: "Close a sticky note; human draft-aware requests remove empty notes, tool and legacy closes stay reversible" },
   "note_reopen":              { direction: "c2s", handler: "lib/project-user-message.js", description: "Reopen a closed sticky note" },
   "note_delete":              { direction: "c2s", handler: "lib/project-user-message.js", description: "Retired: older clients still send this; handled as a non-destructive close" },
-  "note_deleted":             { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Retired: never sent. Closing broadcasts note_updated instead" },
+  "note_deleted":             { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "A sticky note was permanently removed after a human-authorized storage transaction" },
   "note_list_request":        { direction: "c2s", handler: "lib/project-user-message.js", description: "Request the full notes list" },
   "note_bring_front":         { direction: "c2s", handler: "lib/project-user-message.js", description: "Bring a note to front (update z-order)" },
   "notes_list":               { direction: "s2c", handler: "lib/public/modules/app-messages.js", description: "Full list of sticky notes" },
@@ -784,6 +794,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" },
@@ -809,6 +820,13 @@ var schema = {
   "default_vendor_get":       { direction: "c2s", handler: "lib/server-default-vendor.js", description: "Read the authenticated user's New session vendor preference" },
   "default_vendor_set":       { direction: "c2s", handler: "lib/server-default-vendor.js", description: "Validate and persist the authenticated user's New session vendor preference" },
   "default_vendor_state":     { direction: "s2c", handler: "lib/public/modules/default-vendor.js", description: "Correlated or same-user-broadcast New session vendor preference" },
+  "clay_ui_ready":            { direction: "c2s", handler: "lib/server-owner-ui.js", description: "Advertise exact owner UI navigation support on this socket" },
+  "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" },
   "context_view_state":       { direction: "s2c", handler: "lib/public/modules/context-view-preference.js", description: "Correlated or same-user-broadcast context display preference" },

package/lib/yoke/acp-agent-profiles.js

@@ -9,8 +9,9 @@ var execFile = require("child_process").execFile;
 var execFileSync = require("child_process").execFileSync;
 
 function findOnPath(binaryName, overrideName) {
-  var overridePath = overrideName && process.env[overrideName];
-  if (overridePath && fs.existsSync(overridePath)) return overridePath;
+  var discovery = require("./discovery");
+  var overridePath = overrideName && discovery.explicitEntry(process.env, overrideName, false);
+  if (overridePath !== undefined && overrideName) return overridePath;
   try {
     var command = process.platform === "win32" ? "where" : "which";
     var out = execFileSync(command, [binaryName], {
@@ -18,7 +19,8 @@ function findOnPath(binaryName, overrideName) {
       encoding: "utf8",
       stdio: ["pipe", "pipe", "pipe"],
     });
-    return out.trim().split(/\r?\n/)[0] || null;
+    var resolved = out.trim().split(/\r?\n/)[0] || null;
+    return discovery.validEntry(resolved, false) ? resolved : null;
   } catch (e) {
     return null;
   }
@@ -50,7 +52,7 @@ function fetchOpenCodeResolvedConfig(binaryPath, cwd, env) {
   return new Promise(function(resolve, reject) {
     execFile(binaryPath, ["debug", "config"], {
       cwd: cwd || process.cwd(),
-      env: Object.assign({}, process.env, env || {}),
+      env: env ? Object.assign({}, env) : process.env,
       timeout: 30000,
       maxBuffer: 4 * 1024 * 1024,
     }, function(err, stdout) {
@@ -141,7 +143,7 @@ var ACP_AGENT_PROFILES = {
       });
     },
     buildProcessOptions: function(ctx, base) {
-      var existing = (base.env && base.env.OPENCODE_CONFIG_CONTENT) || process.env.OPENCODE_CONFIG_CONTENT;
+      var existing = base.env ? base.env.OPENCODE_CONFIG_CONTENT : process.env.OPENCODE_CONFIG_CONTENT;
       var config = {};
       if (existing) config = JSON.parse(existing);
       var agent = Object.assign({}, config.agent || {});

package/lib/yoke/adapters/antigravity.js

@@ -3,19 +3,7 @@ var childProcess = require("child_process");
 var readline = require("readline");
 var skillDiscovery = require("../skill-discovery");
 
-function findBinary() {
-  if (process.env.ANTIGRAVITY_CLI_PATH) return process.env.ANTIGRAVITY_CLI_PATH;
-  try {
-    var command = process.platform === "win32" ? "where" : "which";
-    return childProcess.execFileSync(command, ["agy"], {
-      encoding: "utf8",
-      timeout: 3000,
-      stdio: ["pipe", "pipe", "pipe"],
-    }).trim().split(/\r?\n/)[0] || null;
-  } catch (e) {
-    return null;
-  }
-}
+var findBinary = require("../providers/antigravity-executable").resolve;
 
 function modelValue(model) {
   if (typeof model === "string") return model;
@@ -427,7 +415,8 @@ function createAntigravityAdapter(opts) {
   var adapter = {
     vendor: "antigravity",
     init: async function(initOpts) {
-      if (!binaryPath) binaryPath = findBinary();
+      if (opts.linuxUser || initOpts && initOpts.linuxUser) throw new Error("Antigravity does not support mapped OS-user execution.");
+      if (!binaryPath) binaryPath = findBinary({ env: initOpts && initOpts.env || opts.env || process.env });
       if (!binaryPath) throw new Error("Antigravity CLI binary not found: agy");
       var fetched = opts._fetchModels ? await opts._fetchModels(binaryPath, cwd) : await fetchModels(binaryPath, cwd);
       if (fetched && fetched.length) cachedModels = fetched;

package/lib/yoke/adapters/claude-query-contract.js

@@ -0,0 +1,9 @@
+// Init-free provider transport obligations, shared by the registry and adapter.
+module.exports = {
+  questionInput: function(name, input) { return name === "AskUserQuestion" ? input : null; },
+  toolTransport: "sdk-mcp",
+  catalogLifetime: "query",
+  permissionModes: ["auto"],
+  mcpPermissionOverrides: true,
+  interruptionMessage: "Interrupted · What should Claude do instead?",
+};