feat(server-mode): share one session; scope collaborators' pane tokens (sharing phase 3)

A workspace's owner (or an admin) can share ONE session from its right-click
menu (GET/PUT /api/lanes/:id/sessions/:sid/shares, table session_shares,
audited). The user sees the workspace (access: "session") with only that
session, joins the pane holding it, resumes it on their own account in a
free slot, and uses the workspace's git and Files reads and git writes;
everything else of the workspace answers 403 ESESSIONSHARE (scope.js
sessionShareAllows in scopeGuard). Hook/runtime broadcasts stay with full
collaborators.

A collaborator's pane token (readable by the owner's Linux account) now acts
as them inside that workspace only, and never starts or bills a session
(auth.js paneLaneAllows, 403 EPANESCOPE); a Terminal tab the owner or an
admin opens acts as the owner again. Docs say plainly that under S3 a
session share hands over the owner's account inside the terminal.

client/src/components/lanes/SessionMenu.tsx

@@ -31,6 +31,7 @@ export function SessionMenu({
   onArchive,
   onUnarchive,
   onPin,
+  onShare,
 }: MenuPoint & {
   laneId: number;
   session: Session | null;
@@ -42,6 +43,8 @@ export function SessionMenu({
   onUnarchive?: () => void;
   /** Pin or unpin (by `session.pinned_at`), where the list offers it. */
   onPin?: () => void;
+  /** Share this session on its own (server mode, the workspace's owner). */
+  onShare?: () => void;
 }) {
   const { t } = useTranslation("lanes");
   const navigate = useNavigate();
@@ -81,6 +84,11 @@ export function SessionMenu({
           {t(session.pinned_at ? "sessionMenu.unpin" : "sessionMenu.pin")}
         </MenuItem>
       )}
+      {onShare && session && (
+        <MenuItem testId="session-menu-share" onSelect={pick(onShare)}>
+          {t("sessionMenu.share")}
+        </MenuItem>
+      )}
       {session && (
         <>
           <MenuItem onSelect={pick(() => navigate(`/sessions/${session.id}`))}>

client/src/components/lanes/WorkspaceHome.tsx

@@ -278,10 +278,13 @@ function HomeBody({
   // own account and is billed to them (the server answers ENOCOLLABACCOUNT
   // when they have none).
   const collab = !ownsLane(lane);
+  // Only a session of it is shared with them (phase 3): no new session here —
+  // they open that session and send it messages (the server answers ESESSIONSHARE).
+  const sessionOnly = lane.access === "session";
   const start = async () => {
     // Enter reaches here past the disabled button: the same guards again.
     // A ref, not only the state: two Enters in one tick both read `starting` false.
-    if (startingRef.current || uploading || !text) return;
+    if (sessionOnly || startingRef.current || uploading || !text) return;
     startingRef.current = true;
     setStarting(true);
     setError(null);
@@ -537,7 +540,7 @@ function HomeBody({
                 type="button"
                 data-testid="workspace-home-start"
                 onClick={() => void start()}
-                disabled={starting || uploading || !text}
+                disabled={sessionOnly || starting || uploading || !text}
                 aria-label={t("home.start")}
                 title={t("home.start")}
                 className="flex h-8 w-8 items-center justify-center rounded-full bg-accent-solid text-white transition-opacity hover:opacity-90 disabled:opacity-40"
@@ -549,7 +552,7 @@ function HomeBody({
         </div>
         {collab && (
           <p data-testid="workspace-home-collab" className="mt-2 text-xs text-fg-muted">
-            {t("shared.ownAccount")}
+            {t(sessionOnly ? "shared.sessionOnly" : "shared.ownAccount")}
           </p>
         )}
         {/* The session's quieter choices, under the box like Claude Desktop's. */}

client/src/components/lanes/WorkspaceSessionList.tsx

@@ -31,7 +31,7 @@
  * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
  */
 
-import { useEffect, useState, type ReactNode } from "react";
+import { lazy, Suspense, useEffect, useState, type ReactNode } from "react";
 import { endRuns } from "../../lib/stopSession";
 import { isSubmitEnter } from "../../lib/keys";
 import { Archive, GitBranch, Pin, PinOff, SquareTerminal } from "lucide-react";
@@ -46,6 +46,11 @@ import { useAiTools } from "../../hooks/useAiTools";
 import { useThrottledValue } from "../../hooks/useThrottledValue";
 import { useContextMenu } from "../ContextMenu";
 import { SessionMenu } from "./SessionMenu";
+import { usePermissions } from "../AuthGate";
+
+const WorkspaceShareModal = lazy(() =>
+  import("./WorkspaceShareModal").then((m) => ({ default: m.WorkspaceShareModal }))
+);
 
 export const SESSION_LIMIT = 6;
 
@@ -256,6 +261,9 @@ export function WorkspaceSessionList({
   const [busy, setBusy] = useState(false);
   const ctx = useContextMenu<RunHandle>();
   const sessionCtx = useContextMenu<Session>();
+  // Share one session (server mode, the workspace's owner or an admin).
+  const { local, ownsLane } = usePermissions();
+  const [sharing, setSharing] = useState<Session | null>(null);
   // Rows shown; See all raises it to the whole list.
   const [limit, setLimit] = useState(SESSION_LIMIT);
 
@@ -637,8 +645,18 @@ export function WorkspaceSessionList({
           onPin={() =>
             void patch(sessionCtx.menu!.item, { pinned: !sessionCtx.menu!.item.pinned_at })
           }
+          onShare={!local && ownsLane(lane) ? () => setSharing(sessionCtx.menu!.item) : undefined}
         />
       )}
+      {sharing && (
+        <Suspense fallback={null}>
+          <WorkspaceShareModal
+            lane={lane}
+            session={{ id: sharing.id, name: sharing.name }}
+            onClose={() => setSharing(null)}
+          />
+        </Suspense>
+      )}
     </>
   );
 }

client/src/components/lanes/WorkspaceShareModal.tsx

@@ -1,8 +1,9 @@
 /**
- * @file WorkspaceShareModal — share a workspace with other users (server mode,
- * docs/plans/workspace-sharing/ phase 1). Ticks people from
- * `GET /api/artifacts/people` (names only) and saves the whole list through
- * `PUT /api/lanes/:id/shares`. It says plainly what sharing means on this
+ * @file WorkspaceShareModal — share a workspace, or one of its sessions
+ * (`session`), with other users (server mode, docs/plans/workspace-sharing/
+ * phases 1 and 3). Ticks people from `GET /api/artifacts/people` (names only)
+ * and saves the whole list through `PUT /api/lanes/:id/shares` or
+ * `PUT /api/lanes/:id/sessions/:sid/shares`. It says plainly what sharing means on this
  * server: the people it is shared with work as the owner's account and can
  * read everything in the owner's home. Only the owner or an admin opens it —
  * the server refuses anyone else (`ENOTOWNER`).
@@ -21,7 +22,16 @@ import { Checkbox } from "../Checkbox";
 
 type Person = { id: number; username: string; name: string; disabled?: boolean };
 
-export function WorkspaceShareModal({ lane, onClose }: { lane: Lane; onClose: () => void }) {
+export function WorkspaceShareModal({
+  lane,
+  session,
+  onClose,
+}: {
+  lane: Lane;
+  /** Share this one session instead of the whole workspace. */
+  session?: { id: string; name?: string | null };
+  onClose: () => void;
+}) {
   const { t } = useTranslation("lanes");
   const panelRef = useRef<HTMLDivElement>(null);
   useDialog(true, panelRef, onClose);
@@ -33,7 +43,11 @@ export function WorkspaceShareModal({ lane, onClose }: { lane: Lane; onClose: ()
 
   useEffect(() => {
     let alive = true;
-    Promise.all([api.artifacts.people(), api.lanes.shares(lane.id)])
+    const sid = session?.id;
+    Promise.all([
+      api.artifacts.people(),
+      sid ? api.lanes.sessionShares(lane.id, sid) : api.lanes.shares(lane.id),
+    ])
       .then(([p, s]) => {
         if (!alive) return;
         // Never the owner: a workspace is not shared with them. Someone it is
@@ -56,7 +70,7 @@ export function WorkspaceShareModal({ lane, onClose }: { lane: Lane; onClose: ()
     return () => {
       alive = false;
     };
-  }, [lane.id, lane.owner_id]);
+  }, [lane.id, lane.owner_id, session?.id]);
 
   const shown = useMemo(() => {
     const q = query.trim().toLowerCase();
@@ -66,7 +80,7 @@ export function WorkspaceShareModal({ lane, onClose }: { lane: Lane; onClose: ()
   }, [people, query]);
   const added = [...picked].filter((id) => !initial.has(id));
   const changed = added.length > 0 || [...initial].some((id) => !picked.has(id));
-  const name = lane.title || lane.cwd;
+  const name = session ? session.name || session.id : lane.title || lane.cwd;
 
   const save = async () => {
     if (added.length > 0) {
@@ -80,7 +94,9 @@ export function WorkspaceShareModal({ lane, onClose }: { lane: Lane; onClose: ()
     }
     setBusy(true);
     try {
-      const r = await api.lanes.setShares(lane.id, [...picked]);
+      const r = session
+        ? await api.lanes.setSessionShares(lane.id, session.id, [...picked])
+        : await api.lanes.setShares(lane.id, [...picked]);
       toast.success(
         r.shares.length ? t("share.saved", { count: r.shares.length }) : t("share.savedNone")
       );
@@ -116,7 +132,7 @@ export function WorkspaceShareModal({ lane, onClose }: { lane: Lane; onClose: ()
         <div className="flex items-start gap-3 border-b border-border px-5 py-4">
           <div className="min-w-0 flex-1">
             <h2 id="workspace-share-title" className="text-base font-semibold text-fg-primary">
-              {t("share.title")}
+              {t(session ? "share.sessionTitle" : "share.title")}
             </h2>
             <p className="mt-0.5 truncate text-xs text-fg-muted" title={lane.cwd}>
               {name}
@@ -133,7 +149,9 @@ export function WorkspaceShareModal({ lane, onClose }: { lane: Lane; onClose: ()
         </div>
 
         <div className="min-h-0 flex-1 space-y-3 overflow-y-auto px-5 py-4">
-          <p className="text-xs text-fg-secondary">{t("share.what")}</p>
+          <p className="text-xs text-fg-secondary">
+            {t(session ? "share.sessionWhat" : "share.what")}
+          </p>
           <div
             data-testid="workspace-share-warning"
             className="flex gap-2 rounded-lg border border-status-warning/30 bg-status-warning/10 px-3 py-2 text-xs text-status-warning"

client/src/components/lanes/__tests__/WorkspaceShareModal.test.tsx

@@ -3,7 +3,8 @@
  * on the current list, never offers the owner, warns what sharing means, asks
  * once before adding someone and saves the WHOLE list; WorkspaceRowMenu offers
  * Share (server mode) and the other owner-only items only to the workspace's
- * owner or an admin.
+ * owner or an admin; given a session, it lists and saves THAT session's
+ * shares instead.
  * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
  */
 
@@ -30,11 +31,18 @@ const m = vi.hoisted(() => ({
   people: vi.fn(),
   shares: vi.fn(),
   setShares: vi.fn(),
+  sessionShares: vi.fn(),
+  setSessionShares: vi.fn(),
 }));
 vi.mock("../../../lib/api", () => ({
   api: {
     artifacts: { people: m.people },
-    lanes: { shares: m.shares, setShares: m.setShares },
+    lanes: {
+      shares: m.shares,
+      setShares: m.setShares,
+      sessionShares: m.sessionShares,
+      setSessionShares: m.setSessionShares,
+    },
   },
 }));
 
@@ -159,3 +167,33 @@ describe("WorkspaceRowMenu on a shared workspace", () => {
     expect(screen.getByText("Rename")).toBeInTheDocument();
   });
 });
+
+describe("WorkspaceShareModal for one session", () => {
+  it("reads and saves that session's own list, never the workspace's", async () => {
+    m.shares.mockClear();
+    m.setShares.mockClear();
+    m.sessionShares.mockResolvedValue({ shares: [], canManage: true });
+    m.setSessionShares.mockResolvedValue({
+      shares: [{ id: 3, username: "carol", name: "Carol", sharedAt: "" }],
+    });
+    render(
+      <WorkspaceShareModal
+        lane={lane}
+        session={{ id: "s-1", name: "Fix cart" }}
+        onClose={() => {}}
+      />
+    );
+    await settle();
+    expect(m.sessionShares).toHaveBeenCalledWith(7, "s-1");
+    expect(m.shares).not.toHaveBeenCalled();
+    expect(screen.getByText("Share session")).toBeTruthy();
+    expect(screen.getByText("Fix cart")).toBeTruthy();
+    fireEvent.click(screen.getByRole("checkbox", { name: /Carol/ }));
+    fireEvent.click(screen.getByRole("button", { name: "Save" }));
+    await settle();
+    await act(async () => settleConfirm(true));
+    await settle();
+    expect(m.setSessionShares).toHaveBeenCalledWith(7, "s-1", [3]);
+    expect(m.setShares).not.toHaveBeenCalled();
+  });
+});

client/src/hooks/useLanes.ts

@@ -60,7 +60,9 @@ function onMessage(msg: WSMessage) {
   const lane = payload.lane;
   if (payload.removed !== undefined || !lane || !lanes) return void load();
   const i = lanes.findIndex((l) => l.id === lane.id);
-  if (i === -1) return void load();
+  // A broadcast carries no viewer's `access`: a lane seen through a shared
+  // session re-reads it (its access may have changed too).
+  if (i === -1 || lanes[i]?.access) return void load();
   const next = [...lanes];
   next[i] = lane;
   publish(next);

client/src/i18n/locales/en/lanes.json

@@ -405,6 +405,10 @@
   "share.disabled": "(disabled)",
   "share.savedNone": "No longer shared with anyone",
   "shared.ownAccount": "This workspace is shared with you: a session you start here runs on your own account — a pool account or an AI Proxy of yours — and is billed to you.",
+  "share.sessionTitle": "Share session",
+  "share.sessionWhat": "People you share it with see this session and the workspace's changes, join its open tab, type into it, send it messages (on their own account, billed to them) and commit — nothing else of the workspace. Only you share it. On this server they work as YOUR account inside its terminal, so they can still reach the rest of your home from there.",
+  "sessionMenu.share": "Share…",
+  "shared.sessionOnly": "Only a session of this workspace is shared with you: open it from the list to work in it.",
   "shared.badge": "Shared with you",
   "panel.changes": "Changes",
   "panel.analyst": "Analyst",

client/src/i18n/locales/vi/lanes.json

@@ -405,6 +405,10 @@
   "share.disabled": "(đã vô hiệu hoá)",
   "share.savedNone": "Không còn chia sẻ với ai",
   "shared.ownAccount": "Workspace này được chia sẻ với bạn: session bạn mở ở đây chạy bằng tài khoản của chính bạn — tài khoản pool hoặc AI Proxy của bạn — và tính tiền cho bạn.",
+  "share.sessionTitle": "Chia sẻ session",
+  "share.sessionWhat": "Người được chia sẻ thấy session này và các thay đổi của workspace, vào tab đang mở, gõ, gửi tin nhắn cho nó (bằng tài khoản của họ, tính tiền cho họ) và commit — không gì khác của workspace. Chỉ bạn chia sẻ được. Trên server này họ làm việc bằng TÀI KHOẢN CỦA BẠN trong terminal của nó, nên từ đó họ vẫn với tới được phần còn lại trong home của bạn.",
+  "sessionMenu.share": "Chia sẻ…",
+  "shared.sessionOnly": "Chỉ một session của workspace này được chia sẻ với bạn: mở nó từ danh sách để làm việc.",
   "shared.badge": "Được chia sẻ với bạn",
   "panel.changes": "Thay đổi",
   "panel.analyst": "Analyst",

client/src/lib/api.ts

@@ -5113,6 +5113,17 @@ export const api = {
         method: "PUT",
         body: JSON.stringify({ userIds }),
       }),
+    /** GET /api/lanes/:id/sessions/:sid/shares — the users one session is shared with. */
+    sessionShares: (id: number, sid: string) =>
+      request<{ shares: LaneShare[]; canManage: boolean }>(
+        `/workspaces/${id}/sessions/${encodeURIComponent(sid)}/shares`
+      ),
+    /** PUT /api/lanes/:id/sessions/:sid/shares — the WHOLE list (owner or admin). */
+    setSessionShares: (id: number, sid: string, userIds: number[]) =>
+      request<{ shares: LaneShare[] }>(
+        `/workspaces/${id}/sessions/${encodeURIComponent(sid)}/shares`,
+        { method: "PUT", body: JSON.stringify({ userIds }) }
+      ),
     removeSource: (id: number, sourceId: number) =>
       request<LaneSourcesView>(`/workspaces/${id}/sources/${sourceId}`, { method: "DELETE" }),
     /** GET /api/lanes/:id/memory — CLAUDE.md/AGENTS.md and Claude's auto memory, read-only. */

client/src/lib/types.ts

@@ -2708,6 +2708,8 @@ export interface Lane {
   owner_display_name?: string | null;
   /** When the owner's avatar was last set (`users.avatar_at`); null = none. */
   owner_avatar_at?: string | null;
+  /** Server mode: `"session"` when only sessions of it are shared with this viewer. */
+  access?: "session";
   branch: string | null;
   kind: "managed" | "adopted";
   /** The CLI this lane's runs spawn. Immutable once the lane exists. */