clay-server 4.4.1-beta.1 → 4.5.0-beta.1

package/lib/project-issues.js

@@ -39,6 +39,17 @@ function attachProjectIssues(ctx) {
         else if (msg.type === "issue_comment") notify(result, "issue_commented");
         else if (msg.type === "issue_delete") notify(result, "issue_deleted");
       }
+      if (msg.type === "issue_read" && result) {
+        result = Object.assign({}, result, { githubLinks: [] });
+        (result.linkedWorkSessions || []).forEach(function (link) {
+          try {
+            var work = bound.resolveWorkSession({ ref: result.ref, sessionOriginId: link.sessionId });
+            (work.githubLinks || []).forEach(function (item) {
+              if (!result.githubLinks.some(function (existing) { return existing.url === item.url; })) result.githubLinks.push(item);
+            });
+          } catch (error) { /* Linked work may no longer be visible. */ }
+        });
+      }
       ctx.sendTo(ws, { type: "issues_result", requestId: msg.requestId, action: msg.type, result: result, canDelete: bound.canDelete === true });
     }).catch(function (error) {
       var result = error && error.sessionId ? { sessionId: error.sessionId } : undefined;

package/lib/project-session-github.js

@@ -0,0 +1,93 @@
+var github = require("./session-github");
+var buildShape = require("./session-spawn-mcp-server").buildShape;
+var CONTRACT = "GitHub work links: when an issue is clearly the task this session is implementing, or you create/work on its PR, call link_session_github with its exact GitHub URL. Mere mentions, examples, and reference material must not be linked. Do not infer a session's PR from the repository's current branch: sessions may share a checkout. This records local metadata only and does not post to GitHub. Use get_session_github to inspect/refresh linked status and discover accessible sessions already working on the same reference before starting duplicate work. Keep Issues as quiet background records, not a mandatory workflow. Unlink an incorrect association with unlink_session_github.";
+function attachSessionGithub(ctx) {
+  var inflight = new Map();
+  var attempts = new Map();
+  function authorize(session) {
+    if (!session || ctx.sm.sessions.get(session.localId) !== session || ctx.isMate || !ctx.canUse(session)) throw new Error("GitHub links require an authorized project session.");
+    var identity = ctx.identity(session);
+    // Account login does not imply OS isolation. Match the project's execution mode.
+    if (ctx.osUsers && !identity) throw new Error("GitHub requires a mapped OS user with gh authentication in OS-isolated mode.");
+    return identity;
+  }
+  function persist(session) {
+    if (ctx.sm.saveSessionFile(session) === false) throw new Error("Could not save GitHub links.");
+    ctx.sm.broadcastSessionList();
+  }
+  async function refresh(session, force) {
+    var identity = authorize(session);
+    var id = session.localId;
+    if (inflight.has(id)) return inflight.get(id);
+    if (!force && Date.now() - (attempts.get(id) || 0) < 60000) return session.githubLinks || [];
+    attempts.set(id, Date.now());
+    var pending = (async function () {
+      var links = (session.githubLinks || []).slice();
+      var updated = [];
+      for (var link of links) {
+        try { updated.push(await github.readReference(ctx.cwd, link.url, identity, ctx.run)); }
+        catch (error) { updated.push(Object.assign({}, link, { stale: true })); }
+      }
+      authorize(session);
+      // A link/unlink during the request wins over the refresh snapshot.
+      session.githubLinks = (session.githubLinks || []).map(function (link) {
+        var index = links.indexOf(link);
+        return index < 0 ? link : updated[index];
+      });
+      if (links.length) persist(session);
+      return session.githubLinks || [];
+    })();
+    inflight.set(id, pending);
+    try { return await pending; } finally { inflight.delete(id); }
+  }
+  async function invoke(session, name, args) {
+    var identity = authorize(session);
+    if (name === "get_session_github") {
+      var links = await refresh(session, false);
+      var matches = [];
+      if (args.url) {
+        var url = github.parseReference(args.url).url.toLowerCase();
+        ctx.sm.sessions.forEach(function (other) {
+          if (!other.hidden && !other.delegated && !require("./session-provenance").isWorker(other) && ctx.canRead(session, other) && (other.githubLinks || []).some(function (link) { return link.url.toLowerCase() === url; })) matches.push({ sessionId: other.localId, title: other.title });
+        });
+      }
+      return { links: links, matchingSessions: matches.slice(0, 20) };
+    }
+    var ref = github.parseReference(args.url);
+    if (name === "unlink_session_github") {
+      session.githubLinks = (session.githubLinks || []).filter(function (link) { return link.url.toLowerCase() !== ref.url.toLowerCase(); });
+    } else {
+      var verified = await github.readReference(ctx.cwd, ref.url, identity, ctx.run);
+      authorize(session);
+      var retained = (session.githubLinks || []).filter(function (link) { return link.url.toLowerCase() !== ref.url.toLowerCase(); });
+      if (retained.length >= 8) throw new Error("A session can link up to eight GitHub items.");
+      session.githubLinks = retained.concat([verified]);
+    }
+    persist(session);
+    return { links: session.githubLinks };
+  }
+  function defs(session) {
+    if (ctx.isMate || (session && !ctx.canUse(session))) return [];
+    return ["link_session_github", "get_session_github", "unlink_session_github"].map(function (name) {
+      return { name: name, permissionName: "mcp__clay-github__" + name, description: CONTRACT + " " + (name === "get_session_github" ? "Read linked status; optional URL finds visible existing work sessions." : name === "link_session_github" ? "Verify and attach one issue or PR to the current session." : "Remove one local association without modifying GitHub."), inputSchema: buildShape({ url: { type: "string", description: "Exact https://github.com/owner/repo/issues/123 or /pull/123 URL." } }, name === "get_session_github" ? [] : ["url"]), handler: async function (args) {
+        try { return { content: [{ type: "text", text: JSON.stringify(await invoke(session, name, args || {})) }] }; }
+        catch (error) { return { isError: true, content: [{ type: "text", text: error.message }] }; }
+      } };
+    });
+  }
+  return {
+    getDynamicToolDefs: defs,
+    getSystemPrompt: function () { return ctx.isMate ? "" : CONTRACT; },
+    createMcpServer: function (adapter, session) { return ctx.isMate || !adapter.createToolServer ? null : adapter.createToolServer({ name: "clay-github", version: "1.0.0", tools: defs(session) }); },
+    getBridgeTools: function (session, normalize) { return defs(session).map(function (tool) { return { server: "clay-github", name: tool.name, description: tool.description, inputSchema: normalize(tool.inputSchema) }; }); },
+    callBridgeTool: function (session, name, args) { var tool = defs(session).find(function (item) { return item.name === name; }); return tool ? tool.handler(args) : Promise.reject(new Error("GitHub tool unavailable.")); },
+    handleMessage: function (ws, msg) {
+      if (msg.type !== "session_github_refresh") return false;
+      var session = ctx.sm.sessions.get(ws._clayActiveSession);
+      if (!session || !ctx.canRefresh(ws, session) || !(session.githubLinks || []).length) return true;
+      refresh(session, false).catch(function () {});
+      return true;
+    },
+  };
+}
+module.exports = { attachSessionGithub: attachSessionGithub };

package/lib/project.js

@@ -813,6 +813,24 @@ function createProjectContext(opts) {
     service: opts.issuesService, projectSlug: slug, isMate: isMate, sm: sm,
     sendTo: sendTo, getClients: function () { return clients; }, startWork: _issueWork,
   });
+  var _sessionGithub = require("./project-session-github").attachSessionGithub({
+    cwd: cwd, sm: sm, isMate: isMate, osUsers: osUsers,
+    canUse: function (session) {
+      if (session.hidden || session.delegated || session._pairDelegation || session._delegatedBy || require("./session-provenance").isWorker(session)) return false;
+      if (!usersModule.isMultiUser()) return true;
+      var owner = session.ownerId && usersModule.findUserById(session.ownerId);
+      return !!(owner && opts.canAccessProjectSlug && opts.canAccessProjectSlug(owner.id, slug));
+    },
+    identity: function (session) {
+      return getOsUserInfoForLinuxUser(getLinuxUserForSession(session));
+    },
+    canRead: function (caller, other) {
+      return !usersModule.isMultiUser() || usersModule.canAccessSession(caller.ownerId, other, opts.getProjectAccess ? opts.getProjectAccess() : { visibility: "public" });
+    },
+    canRefresh: function (ws, session) {
+      return !usersModule.isMultiUser() || !!(ws._clayUser && ws._clayUser.id === session.ownerId);
+    },
+  });
   var _mateKnowledge = attachProjectMateKnowledge({
     service: opts.mateKnowledgeService || null,
     sm: sm,
@@ -992,6 +1010,8 @@ function createProjectContext(opts) {
     // get the read-only cross-project set only when the Mate registry confirms
     // authoritative builtin Clay.
     try {
+      var githubMcpConfig = _sessionGithub.createMcpServer(adapter, null);
+      if (githubMcpConfig) servers["clay-github"] = githubMcpConfig;
       var issuesMcpConfig = _issues.createMcpServer(adapter, null);
       if (issuesMcpConfig) servers["clay-issues"] = issuesMcpConfig;
       var projectLogsMcpConfig = _projectLogs.createMcpServer(adapter, null);
@@ -1175,6 +1195,11 @@ function createProjectContext(opts) {
         }
         continue;
       }
+      if (name === "clay-github" && forSession) {
+        var boundGithub = _sessionGithub.createMcpServer(adapter, forSession);
+        if (boundGithub) { filtered[name] = boundGithub; hasAny = true; }
+        continue;
+      }
       if (name === "clay-issues" && forSession) {
         var boundIssues = _issues.createMcpServer(adapter, forSession);
         if (boundIssues) { filtered[name] = boundIssues; hasAny = true; }
@@ -1348,6 +1373,7 @@ function createProjectContext(opts) {
         _capsuleCatalog.getSystemPrompt(session),
         _projectLogs.getSystemPrompt(session),
         _issues.getSystemPrompt(session),
+        _sessionGithub.getSystemPrompt(session),
         _scheduledTasks ? _scheduledTasks.getSystemPrompt(session) : "",
         _mateKnowledge.getSystemPrompt(session),
         _autonomousRun ? _autonomousRun.getSystemPrompt(session) : "",
@@ -1369,6 +1395,7 @@ function createProjectContext(opts) {
         .concat(_workspaceQuery.getHistoryDynamicToolDefs(session))
         .concat(_projectLogs.getDynamicToolDefs(session))
         .concat(_issues.getDynamicToolDefs(session))
+        .concat(_sessionGithub.getDynamicToolDefs(session))
         .concat(_mateKnowledge.getDynamicToolDefs(session))
         .concat(_loopInterview ? _loopInterview.getToolDefs(session) : [])
         .concat(_scheduledTasks ? _scheduledTasks.getToolDefs(session) : [])
@@ -1760,6 +1787,7 @@ function createProjectContext(opts) {
     // --- Project Logs (delegated to project-logs.js) ---
     if (_projectLogs.handleLogsMessage(ws, msg)) return;
     if (_issues.handleMessage(ws, msg)) return;
+    if (_sessionGithub.handleMessage(ws, msg)) return;
 
     // --- Notifications (delegated to project-notifications.js) ---
     if (_notifications.handleNotificationMessage(ws, msg)) return;
@@ -2328,6 +2356,7 @@ function createProjectContext(opts) {
           var historyTools = _workspaceQuery.getHistoryBridgeTools(boundSession, normalizeToolSchema);
           for (var cht = 0; cht < historyTools.length; cht++) tools.push(historyTools[cht]);
           tools = tools.concat(_issues.getBridgeTools(boundSession, normalizeToolSchema));
+          tools = tools.concat(_sessionGithub.getBridgeTools(boundSession, normalizeToolSchema));
           var logsTools = _projectLogs.getBridgeTools(boundSession, normalizeToolSchema);
           for (var plti = 0; plti < logsTools.length; plti++) tools.push(logsTools[plti]);
           var knowledgeTools = _mateKnowledge.getBridgeTools(boundSession, normalizeToolSchema);
@@ -2355,7 +2384,7 @@ function createProjectContext(opts) {
             // Debate tools were added above only when this request had an
             // exact session. Never duplicate them or advertise the static,
             // intentionally unbound proposal server.
-            if (inAppNames[i] === "clay-debate" || inAppNames[i] === "clay-mate-creation" || inAppNames[i] === "clay-workspace" || inAppNames[i] === "clay-history" || inAppNames[i] === "clay-issues" || inAppNames[i] === "clay-logs" || inAppNames[i] === "clay-knowledge") continue;
+            if (inAppNames[i] === "clay-debate" || inAppNames[i] === "clay-mate-creation" || inAppNames[i] === "clay-workspace" || inAppNames[i] === "clay-history" || inAppNames[i] === "clay-github" || inAppNames[i] === "clay-issues" || inAppNames[i] === "clay-logs" || inAppNames[i] === "clay-knowledge") continue;
             extractServerTools(inAppNames[i], localMcp[inAppNames[i]]);
           }
         }
@@ -2441,6 +2470,7 @@ function createProjectContext(opts) {
         if (boundSession && serverName === "clay-history") {
           return _workspaceQuery.callHistoryBridgeTool(boundSession, toolName, args);
         }
+        if (boundSession && serverName === "clay-github") return _sessionGithub.callBridgeTool(boundSession, toolName, args);
         if (boundSession && serverName === "clay-issues") return _issues.callBridgeTool(boundSession, toolName, args);
         if (boundSession && serverName === "clay-logs") {
           return _projectLogs.callBridgeTool(boundSession, toolName, args);
@@ -2448,7 +2478,7 @@ function createProjectContext(opts) {
         if (boundSession && serverName === "clay-knowledge") {
           return _mateKnowledge.callBridgeTool(boundSession, toolName, args);
         }
-        if (serverName === "clay-sessions" || serverName === "clay-notes" || serverName === "clay-handoff" || serverName === "clay-documents" || serverName === "clay-debate" || serverName === "clay-mate-creation" || serverName === "clay-workspace" || serverName === "clay-history" || serverName === "clay-issues" || serverName === "clay-logs" || serverName === "clay-knowledge") {
+        if (serverName === "clay-sessions" || serverName === "clay-notes" || serverName === "clay-handoff" || serverName === "clay-documents" || serverName === "clay-debate" || serverName === "clay-mate-creation" || serverName === "clay-workspace" || serverName === "clay-history" || serverName === "clay-github" || serverName === "clay-issues" || serverName === "clay-logs" || serverName === "clay-knowledge") {
           return Promise.reject(new Error("Session-bound tool requires a valid Clay session: " + serverName + "/" + toolName));
         }
         if (sessionOnly) return Promise.reject(new Error("Session tool not found: " + serverName + "/" + toolName));

package/lib/public/app.js

@@ -286,6 +286,10 @@ import { initDebate, handleDebatePreparing, handleDebateStarted, handleDebateRes
     projectName: projectName,
     cwd: "",
     currentSlug: currentSlug,
+    githubWorkPopoverBound: false,
+    githubWorkSessions: [],
+    githubWorkProject: null,
+    githubWorkRefresh: null,
     activeProjectSlug: null,
     sessionActivatedProjectSlug: null,
     sessionListProjectSlug: null,

package/lib/public/css/session-github.css

@@ -0,0 +1,112 @@
+/* Quiet work references share one visual language across sessions and Git. */
+.session-work-column {
+  display: flex;
+  flex-direction: column;
+  gap: 3px;
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+}
+.session-work-column > .session-item-text,
+.session-work-column > .mobile-session-title {
+  display: block;
+  flex: none;
+  width: 100%;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.session-github-links {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  min-width: 0;
+  overflow-x: auto;
+  scrollbar-width: none;
+  font-size: 11px;
+  line-height: 18px;
+}
+.session-github-link {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  padding: 1px 5px;
+  border: 1px solid color-mix(in srgb, var(--text, #888) 12%, transparent);
+  background: color-mix(in srgb, var(--text, #888) 3%, transparent);
+  flex-shrink: 0;
+  color: var(--text-muted, #888);
+  text-decoration: none;
+  border-radius: 5px;
+}
+.session-github-link svg { width: 13px; height: 13px; }
+.session-github-link:hover { color: var(--text); background: color-mix(in srgb, var(--text, #888) 8%, transparent); border-color: color-mix(in srgb, var(--text, #888) 24%, transparent); }
+.session-github-link:focus-visible, .github-work-action:focus-visible { outline: 2px solid var(--accent, #58a6ff); outline-offset: 2px; }
+.github-state-open .github-work-status svg { color: #3fb950; }
+.github-state-merged .github-work-status svg, .github-state-closed .github-work-status svg { color: #a371f7; }
+.github-state-draft .github-work-status svg, .github-state-unknown .github-work-status svg { color: var(--text-muted, #888); }
+#header-github-links { min-width: 0; max-width: 200px; flex: 0 0 auto; margin-left: 4px; }
+.github-work-details { flex-wrap: wrap; padding: 8px 0; gap: 8px 12px; }
+.github-work-action { color: var(--text-muted, #888); text-decoration: none; font-size: 11px; }
+.github-work-action:hover { text-decoration: underline; }
+@media (max-width: 600px) {
+  #header-github-links { max-width: 82px; }
+  .mobile-session-item .session-github-link { min-height: 28px; padding-right: 4px; }
+}
+
+.session-item:has(.session-work-column) { height: 52px; }
+
+.github-kind-pr.github-state-closed .github-work-status svg { color: #f85149; }
+@media (max-width: 600px) {
+  #header-github-links { flex: 0 0 auto; }
+  #header-github-links .session-github-link { display: none; }
+  #header-github-links .session-github-link:first-child { display: inline-flex; }
+
+}
+
+.github-work-brand, .github-work-status { display: inline-flex; align-items: center; flex: none; }
+.github-work-brand { color: var(--text); opacity: .8; padding-right: 5px; border-right: 1px solid color-mix(in srgb, var(--text, #888) 14%, transparent); }
+#header-github-links .github-work-brand { display: none; }
+@media (max-width: 600px) {
+  #header-github-links .github-work-kind { display: none; }
+}
+
+.github-work-more {
+  flex: none;
+  border: 1px solid color-mix(in srgb, var(--text, #888) 12%, transparent);
+  background: transparent;
+  color: var(--text-muted, #888);
+  border-radius: 5px;
+  font: inherit;
+  line-height: 18px;
+  padding: 1px 5px;
+  cursor: pointer;
+}
+.github-work-more:hover, .github-work-more[aria-expanded="true"] { background: color-mix(in srgb, var(--text, #888) 8%, transparent); color: var(--text); }
+.github-work-more:focus-visible { outline: 2px solid var(--accent, #58a6ff); outline-offset: 2px; }
+.github-work-popover {
+  position: fixed;
+  inset: auto;
+  margin: 0;
+  width: min(320px, calc(100vw - 16px));
+  max-height: min(420px, calc(100dvh - 16px));
+  overflow-y: auto;
+  padding: 12px;
+  box-sizing: border-box;
+  border: 1px solid var(--border, #444);
+  border-radius: 10px;
+  background: var(--bg-alt, #222);
+  color: var(--text, #eee);
+  box-shadow: 0 8px 30px #0003;
+}
+.github-work-popover > strong { display: block; font-size: 12px; margin-bottom: 10px; }
+.github-work-popover .session-github-links { display: flex; flex-direction: column; align-items: stretch; overflow: visible; gap: 0; }
+.github-work-entry { display: grid; grid-template-columns: 1fr; gap: 4px; padding: 8px 0; }
+.github-work-entry + .github-work-entry { border-top: 1px solid var(--border, #444); }
+.github-work-entry .session-github-link { justify-self: start; }
+.github-work-entry-title { font-size: 12px; overflow-wrap: anywhere; }
+.github-work-entry-meta { color: var(--text-muted, #888); font-size: 11px; overflow-wrap: anywhere; }
+@media (max-width: 600px) {
+  #header-github-links { max-width: 120px; }
+  .mobile-session-item .github-work-more { min-height: 28px; }
+}

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

@@ -1,3 +1,4 @@
+import { syncGithubSessions } from './session-github.js';
 import { handleIssuesMessageInContext as handleIssuesMessage } from './issues-context.js';
 // app-messages.js - WebSocket message router
 // Extracted from app.js (PR-23)
@@ -711,6 +712,7 @@ export function processMessage(msg) {
         break;
 
       case "session_list":
+        syncGithubSessions(msg.sessions || []);
         markProjectSessionListHydrated();
         renderMateSessionList(msg.sessions || []);
         renderSessionList(msg.sessions || []);

package/lib/public/modules/git-panel.js

@@ -1,3 +1,4 @@
+import { currentGithubWorkMarkup, refreshGithubWork, resetGithubWork } from './session-github.js';
 import { store } from './store.js';
 import { refreshIcons, iconHtml } from './icons.js';
 import { escapeHtml, showToast } from './utils.js';
@@ -205,7 +206,7 @@ function render() {
   } else if (!currentStatus.isRepository) {
     body.innerHTML = '<div class="git-panel-empty">' + iconHtml("folder-git-2") + '<span>This project is not a Git repository.</span></div>';
   } else {
-    body.innerHTML = renderRepository(currentStatus);
+    body.innerHTML = currentGithubWorkMarkup() + renderRepository(currentStatus);
   }
   refreshIcons(body);
   var changesList = body.querySelector(".git-section-changes .git-file-list");
@@ -252,6 +253,7 @@ export function refreshGitSummary() {
 // Project switch and reconnect both land here, so no stale repository ever
 // survives into another project and nothing flashes before detection lands.
 export function resetGitSurface() {
+  resetGithubWork();
   currentStatus = null;
   currentSummary = null;
   lastError = "";
@@ -263,6 +265,7 @@ export function resetGitSurface() {
 }
 
 export function refreshGitStatus() {
+  refreshGithubWork();
   if (busy) return Promise.resolve(currentStatus);
   var basePath = store.get('basePath');
   if (statusBasePath !== basePath) {
@@ -399,7 +402,7 @@ function initGitLifecycle() {
       return;
     }
     if (state.dmMode !== prev.dmMode) {
-      if (state.dmMode) hideGitPlacard();
+      if (state.dmMode) { hideGitPlacard(); resetGithubWork(); }
       else refreshGitSummary();
       return;
     }
@@ -478,6 +481,7 @@ export function initGitPanel() {
     if (summaryTicks < SUMMARY_TICKS) return;
     summaryTicks = 0;
     if (document.hidden || store.get('dmMode') || !store.get('connected') || busy) return;
+    refreshGithubWork();
     refreshGitSummary();
   }, POLL_MS);
 }

package/lib/public/modules/issues-render.js

@@ -1,3 +1,4 @@
+import { githubWorkMarkup } from './session-github.js';
 import { escapeHtml } from './utils.js';
 import { renderMarkdown } from './markdown.js';
 import { authorLine, relativeTime } from './project-logs-render.js';
@@ -34,6 +35,7 @@ export function renderIssueDetail(entry) {
   var time = entry.updatedAt || entry.createdAt;
   var byline = [authorLine(entry), time ? new Date(time).toLocaleString() : '', 'v' + entry.revision].filter(Boolean).join(' · ');
   return '<article class="issue-detail"><div class="issue-doc-chips"><span class="issue-type">' + esc(entry.type) + '</span>' + priorityChip(entry.priority) + statusChip(entry.status) + '</div>' +
+    githubWorkMarkup(entry, true) +
     '<h2 class="issue-doc-title">' + esc(entry.title) + '</h2>' + prose(entry.summary, 'issue-doc-summary') + '<div class="issue-byline">' + esc(byline) + '</div>' +
     '<div class="issue-actions">' + action('data-issue-work', 'play', 'Start work', ' class="issue-primary"' + (closed ? ' disabled title="Reopen this issue to start work"' : '')) +
     action('data-issue-edit', 'pencil', 'Edit') + action('data-issue-history', 'history', 'History') + action('data-issue-copy', 'link', 'Copy reference') +

package/lib/public/modules/session-github.js

@@ -0,0 +1,153 @@
+import { store } from './store.js';
+import { getWs } from './ws-ref.js';
+import { githubLinkTarget } from './github-links.js';
+import { iconHtml, refreshIcons } from './icons.js';
+import { escapeHtml as escapeText } from './utils.js';
+
+function escapeHtml(value) {
+  return escapeText(String(value)).replace(/"/g, '"').replace(/'/g, ''');
+}
+
+function safeLinks(session) {
+  return (session && Array.isArray(session.githubLinks) ? session.githubLinks : []).filter(function (link) {
+    var target = githubLinkTarget(link.url);
+    return target && (target.kind === 'issue' || target.kind === 'pull');
+  });
+}
+function label(link) {
+  return (link.kind === 'pr' ? 'PR #' : 'Issue #') + link.number;
+}
+function anchor(url, title, content, className) {
+  return '<a class="' + className + '" href="' + escapeHtml(url) + '" target="_blank" rel="noopener noreferrer" title="' + escapeHtml(title) + '" aria-label="' + escapeHtml(title) + '">' + content + '</a>';
+}
+export function orderedGithubWork(session) {
+  var links = safeLinks(session).slice().reverse();
+  var latestIssue = links.find(function (link) { return link.kind === 'issue'; });
+  if (latestIssue) links = [latestIssue].concat(links.filter(function (link) { return link !== latestIssue; }));
+  return links;
+}
+export function githubWorkMarkup(session, detailed, expanded) {
+  var links = orderedGithubWork(session);
+  if (!links.length) return '';
+  return '<span class="session-github-links' + (detailed ? ' github-work-details' : '') + '">' + (detailed || expanded ? links : links.slice(0, 1)).map(function (link) {
+    var state = ['open', 'closed', 'merged', 'draft'].indexOf(link.state) >= 0 ? link.state : 'unknown';
+    var icon = link.kind === 'pr' ? (state === 'merged' ? 'git-merge' : state === 'closed' ? 'git-pull-request-closed' : state === 'draft' ? 'git-pull-request-draft' : 'git-pull-request') : (state === 'closed' ? 'circle-check' : 'circle-dot');
+    var description = link.repository + ' · ' + label(link) + ' · ' + link.title + ' · ' + state + (link.checkedAt ? ' · Checked ' + new Date(link.checkedAt).toLocaleString() : '') + (link.stale ? ' (last known status; refresh unavailable)' : '');
+    var html = anchor(link.url, description, iconHtml('github', 'github-work-brand') + iconHtml(icon, 'github-work-status') + '<span><span class="github-work-kind">' + (link.kind === 'pr' ? 'PR ' : 'Issue ') + '</span>#' + escapeHtml(String(link.number)) + '</span>', 'session-github-link github-kind-' + (link.kind === 'pr' ? 'pr' : 'issue') + ' github-state-' + (link.stale ? 'unknown' : state));
+    if (expanded) html = '<span class="github-work-entry">' + html + '<span class="github-work-entry-title">' + escapeHtml(link.title || '') + '</span><span class="github-work-entry-meta">' + escapeHtml(link.repository + ' · ' + state + (link.stale ? ' · Last known status' : '')) + '</span></span>';
+    if (detailed && link.kind === 'pr') {
+      html += anchor(link.url + '/files', 'View PR changes on GitHub', 'Changes', 'github-work-action');
+      html += anchor(link.url + '#pullrequestreview', 'View PR reviews on GitHub', escapeHtml((link.review || 'Reviews').replace(/_/g, ' ').toLowerCase()), 'github-work-action');
+      (link.checks || []).forEach(function (check) {
+        if (/^https:\/\//i.test(check.url)) html += anchor(check.url, check.name + ': ' + check.state, escapeHtml(check.name + ' · ' + check.state.toLowerCase()), 'github-work-action');
+      });
+    }
+    return html;
+  }).join('') + (!detailed && !expanded && links.length > 1 ? '<button type="button" class="github-work-more" aria-label="Show all ' + links.length + ' linked GitHub items" aria-haspopup="dialog" aria-expanded="false" data-github-links="' + escapeHtml(JSON.stringify(safeLinks(session))) + '">+' + (links.length - 1) + '</button>' : '') + '</span>';
+}
+export function appendGithubWork(row, session, title) {
+  var html = githubWorkMarkup(session, false);
+  bindGithubWorkPopover();
+  if (!html) return;
+  var column = document.createElement('span');
+  column.className = 'session-work-column';
+  row.insertBefore(column, title);
+  column.appendChild(title);
+  var links = document.createElement('span');
+  links.innerHTML = html;
+  links.addEventListener('click', function (event) { if (event.target.closest('a')) event.stopPropagation(); });
+  links.addEventListener('contextmenu', function (event) { event.stopPropagation(); });
+  column.appendChild(links);
+}
+export function syncGithubSessions(sessions) {
+  bindGithubWorkPopover();
+  store.set({ githubWorkSessions: sessions || [], githubWorkProject: store.get('currentSlug') });
+  var active = (sessions || []).find(function (session) { return session.active; });
+  var title = document.getElementById('header-title');
+  var old = document.getElementById('header-github-links');
+  var html = title && !store.get('dmMode') && !store.get('splitPanes') && active ? githubWorkMarkup(active, false) : '';
+  if (!html) { if (old) old.remove(); }
+  else if (!old || old.dataset.markup !== html) {
+    var element = old || document.createElement('span');
+    element.id = 'header-github-links';
+    element.dataset.markup = html;
+    element.innerHTML = html;
+    if (!old) title.insertAdjacentElement('afterend', element);
+  }
+  refreshIcons();
+  refreshGithubWork();
+}
+export function currentGithubWorkMarkup() {
+  if (store.get('githubWorkProject') !== store.get('currentSlug')) return '';
+  var session = (store.get('githubWorkSessions') || []).find(function (item) { return item.active; });
+  return githubWorkMarkup(session, true);
+}
+export function refreshGithubWork() {
+  if (document.hidden || store.get('dmMode') || !store.get('connected')) return;
+  if (store.get('githubWorkProject') !== store.get('currentSlug')) return;
+  var session = (store.get('githubWorkSessions') || []).find(function (item) { return item.active; });
+  if (!safeLinks(session).length) return;
+  var key = store.get('currentSlug') + ':' + session.id;
+  var previous = store.get('githubWorkRefresh') || {};
+  if (previous.key === key && Date.now() - previous.at < 60000) return;
+  var ws = getWs();
+  if (!ws || ws.readyState !== 1) return;
+  store.set({ githubWorkRefresh: { key: key, at: Date.now() } });
+  ws.send(JSON.stringify({ type: 'session_github_refresh' }));
+}
+
+export function resetGithubWork() {
+  closeGithubWorkPopover();
+  store.set({ githubWorkSessions: [], githubWorkProject: null, githubWorkRefresh: null });
+  var header = document.getElementById('header-github-links');
+  if (header) header.remove();
+}
+
+function closeGithubWorkPopover() {
+  var popup = document.getElementById('github-work-popover');
+  if (popup) popup.hidePopover();
+}
+function bindGithubWorkPopover() {
+  if (store.get('githubWorkPopoverBound')) return;
+  store.set({ githubWorkPopoverBound: true });
+  document.addEventListener('click', function (event) {
+    var button = event.target.closest('.github-work-more');
+    if (!button) return;
+    event.preventDefault();
+    event.stopPropagation();
+    var existing = document.getElementById('github-work-popover');
+    var same = existing && button.getAttribute('aria-expanded') === 'true';
+    if (existing) { existing.hidePopover(); existing.remove(); }
+    if (same) return;
+    var links;
+    try { links = JSON.parse(button.dataset.githubLinks); } catch (error) { return; }
+    var popup = document.createElement('div');
+    popup.id = 'github-work-popover';
+    popup.className = 'github-work-popover';
+    popup.setAttribute('popover', 'auto');
+    popup.setAttribute('role', 'dialog');
+    popup.setAttribute('aria-label', 'Linked GitHub work');
+    popup.innerHTML = '<strong>Linked GitHub work</strong>' + githubWorkMarkup({ githubLinks: links }, false, true);
+    document.body.appendChild(popup);
+    button.setAttribute('aria-expanded', 'true');
+    popup.addEventListener('toggle', function (toggle) {
+      if (toggle.newState === 'closed') {
+        button.setAttribute('aria-expanded', 'false');
+        if (document.activeElement === document.body && button.isConnected) button.focus();
+        popup.remove();
+      }
+    });
+    popup.showPopover();
+    var rect = button.getBoundingClientRect();
+    var box = popup.getBoundingClientRect();
+    popup.style.left = Math.max(8, Math.min(rect.left, window.innerWidth - box.width - 8)) + 'px';
+    popup.style.top = Math.max(8, rect.bottom + box.height + 8 <= window.innerHeight ? rect.bottom + 6 : rect.top - box.height - 6) + 'px';
+    var first = popup.querySelector('a');
+    if (first) first.focus({ preventScroll: true });
+    refreshIcons();
+  }, true);
+  window.addEventListener('resize', closeGithubWorkPopover);
+  store.subscribe(function (state, previous) {
+    if (state.currentSlug !== previous.currentSlug || state.activeSessionId !== previous.activeSessionId || state.dmMode !== previous.dmMode) closeGithubWorkPopover();
+  });
+}

package/lib/public/modules/sidebar-mobile.js

@@ -1,3 +1,4 @@
+import { appendGithubWork } from './session-github.js';
 // sidebar-mobile.js - Mobile sheet overlays, tab bar, and mobile-specific rendering
 // Extracted from sidebar.js (PR-38)
 
@@ -384,7 +385,7 @@ function renderSheetSessions(listEl) {
 // Helper: create a mobile session item element
 function createMobileSessionItem(s, options) {
   var itemOptions = options || {};
-  var el = document.createElement("button");
+  var el = document.createElement("div");
   el.className = "mobile-session-item" + (s.active ? " active" : "");
   if (itemOptions.worker) el.classList.add("mobile-worker-item");
 
@@ -404,9 +405,15 @@ function createMobileSessionItem(s, options) {
   }
 
   var titleSpan = document.createElement("span");
+  titleSpan.tabIndex = 0;
+  titleSpan.setAttribute("role", "button");
+  titleSpan.addEventListener("keydown", function (event) {
+    if (event.key === "Enter" || event.key === " ") { event.preventDefault(); el.click(); }
+  });
   titleSpan.className = "mobile-session-title";
   titleSpan.appendChild(document.createTextNode(s.title || "New Session"));
   el.appendChild(titleSpan);
+  appendGithubWork(el, s, titleSpan);
 
   if (itemOptions.worker) {
     var generation = document.createElement("span");

package/lib/public/modules/sidebar-sessions.js

@@ -1,3 +1,4 @@
+import { appendGithubWork } from './session-github.js';
 // sidebar-sessions.js - Session list, search, presence, countdown, CLI picker
 // Extracted from sidebar.js (PR-35)
 
@@ -1367,6 +1368,7 @@ function renderSessionItem(s, options) {
   textHtml += highlightMatch(s.title || "New Session", searchQuery);
   textSpan.innerHTML = textHtml;
   el.appendChild(textSpan);
+  appendGithubWork(el, s, textSpan);
 
   if (itemOptions.worker) {
     var workerLabel = document.createElement("span");

package/lib/public/style.css

@@ -1,3 +1,4 @@
+@import url("css/session-github.css");
 @import url("css/issues.css");
 @import url("css/base.css?v=20260828-type1");
 @import url("css/icon-strip.css?v=20260828-surfaces4");

package/lib/sdk-bridge.js

@@ -567,6 +567,17 @@ function createSDKBridge(opts) {
       return { behavior: "allow", updatedInput: input };
     }
 
+    // Session search is read-only; its handler enforces project and session access.
+    if (toolName === "search_other_driver_sessions"
+        || toolName === "mcp__clay-handoff__search_other_driver_sessions") {
+      return { behavior: "allow", updatedInput: input };
+    }
+
+    // Local work associations verify GitHub data but never mutate GitHub.
+    if (["link_session_github", "get_session_github", "unlink_session_github"].some(function (name) {
+      return toolName === name || toolName === "mcp__clay-github__" + name;
+    })) return { behavior: "allow", updatedInput: input };
+
     // Auto-approve safe browser MCP tools.
     // Only watch/unwatch: user explicitly chose which tab to share.
     // Everything else (screenshot, read_page, list_tabs, etc.) can expose

package/lib/session-github.js

@@ -0,0 +1,48 @@
+// Verified GitHub references owned by a work session, never inferred from mentions.
+var execFile = require("child_process").execFile;
+var wrapSpawnAsUser = require("./os-users").wrapSpawnAsUser;
+
+function parseReference(value) {
+  var match = typeof value === "string" && value.match(/^https:\/\/github\.com\/([a-zA-Z0-9][a-zA-Z0-9-]{0,38})\/([a-zA-Z0-9][a-zA-Z0-9._-]{0,99})\/(issues|pull)\/([1-9][0-9]*)(?:[?#].*)?$/);
+  if (!match || !Number.isSafeInteger(Number(match[4]))) throw new Error("Use a GitHub issue or pull request URL.");
+  return { repository: match[1] + "/" + match[2], kind: match[3] === "pull" ? "pr" : "issue", number: Number(match[4]), url: "https://github.com/" + match[1] + "/" + match[2] + "/" + match[3] + "/" + match[4] };
+}
+function runGh(cwd, args, identity) {
+  return new Promise(function (resolve, reject) {
+    var env = Object.assign({}, identity ? require("./build-user-env").buildUserEnv(identity) : process.env, { GH_PROMPT_DISABLED: "1", GH_HOST: "github.com" });
+    if (identity) {
+      // Never let the daemon's GitHub credentials cross an OS-user boundary.
+      delete env.GH_TOKEN; delete env.GITHUB_TOKEN; delete env.GH_ENTERPRISE_TOKEN; delete env.GITHUB_ENTERPRISE_TOKEN;
+      delete env.GH_CONFIG_DIR; delete env.XDG_CONFIG_HOME;
+      env.HOME = identity.home; env.USER = identity.user; env.LOGNAME = identity.user;
+    }
+    var options = { cwd: cwd, env: env, timeout: 15000, maxBuffer: 512 * 1024, encoding: "utf8" };
+    if (identity) { options.uid = identity.uid; options.gid = identity.gid; }
+    var wrapped = wrapSpawnAsUser("gh", args, options);
+    execFile(wrapped.command, wrapped.args, wrapped.options, function (error, stdout) {
+      if (error) return reject(new Error("GitHub is unavailable. Check gh authentication and repository access."));
+      try { resolve(JSON.parse(stdout)); } catch (e) { reject(new Error("GitHub returned an invalid response.")); }
+    });
+  });
+}
+async function readReference(cwd, url, identity, run) {
+  var ref = parseReference(url);
+  var fields = "title,state,url" + (ref.kind === "pr" ? ",isDraft,headRefName,reviewDecision,statusCheckRollup" : "");
+  var data = await (run || runGh)(cwd, [ref.kind === "pr" ? "pr" : "issue", "view", String(ref.number), "--repo", ref.repository, "--json", fields], identity);
+  var verified = parseReference(data.url);
+  if (verified.url.toLowerCase() !== ref.url.toLowerCase()) throw new Error("GitHub returned a different reference.");
+  ref.title = String(data.title || "").slice(0, 200);
+  ref.state = data.state === "MERGED" ? "merged" : data.state === "CLOSED" ? "closed" : data.state === "OPEN" ? (data.isDraft ? "draft" : "open") : "unknown";
+  ref.checkedAt = Date.now();
+  if (ref.kind === "pr") {
+    ref.branch = String(data.headRefName || "").slice(0, 200);
+    ref.review = ["APPROVED", "CHANGES_REQUESTED", "REVIEW_REQUIRED"].indexOf(data.reviewDecision) >= 0 ? data.reviewDecision : "";
+    ref.checks = (data.statusCheckRollup || []).slice(0, 30).map(function (check) {
+      var target = check.detailsUrl || check.targetUrl || "";
+      if (!/^https:\/\//i.test(target)) target = "";
+      return { name: String(check.name || check.context || "Check").slice(0, 100), state: String(check.conclusion || check.state || check.status || "PENDING").slice(0, 40), url: target };
+    });
+  }
+  return ref;
+}
+module.exports = { parseReference: parseReference, readReference: readReference };

package/lib/sessions.js

@@ -176,6 +176,7 @@ function createSessionManager(opts) {
         titleManuallySet: session.titleManuallySet === true,
         createdAt: session.createdAt,
       };
+      if (session.githubLinks) metaObj.githubLinks = session.githubLinks;
       if (session.ownerId) metaObj.ownerId = session.ownerId;
       if (session.vendor) metaObj.vendor = session.vendor;
       if (session.codexDynamicToolCatalogVersion) metaObj.codexDynamicToolCatalogVersion = session.codexDynamicToolCatalogVersion;
@@ -343,6 +344,7 @@ function createSessionManager(opts) {
         title: m.title || "",
         titleProvisional: m.titleProvisional === true,
         titleAutoGenerated: m.titleAutoGenerated === true,
+        githubLinks: Array.isArray(m.githubLinks) ? m.githubLinks.slice(0, 8) : [],
         titleManuallySet: m.titleManuallySet === true || legacyTitleProtected,
         createdAt: m.createdAt || Date.now(),
         lastActivity: loaded[i].mtime || m.createdAt || Date.now(),
@@ -604,6 +606,7 @@ function createSessionManager(opts) {
       id: s.localId,
       cliSessionId: s.cliSessionId || null,
       title: s.title || "New Session",
+      githubLinks: s.githubLinks || [],
       active: isActive,
       isProcessing: s.isProcessing,
       // Sidebar badge: user work only. Ambient housekeeping is surfaced in the

package/package.json

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