[codex] Add resource membership controls (#6677)

## Thinking Path > - Paperclip orchestrates AI-agent companies through company-scoped issues, projects, agents, and board-visible workflows. > - The board sidebar and project list are the daily navigation surface for that control plane. > - Users need to keep all projects and agents accessible while hiding resources they have intentionally left from their own sidebar. > - That requires user-scoped resource membership state backed by company-scoped API and database contracts. > - The branch also needed to preserve HTTP worktree login sessions and keep the project list easier to scan after membership grouping. > - This pull request adds resource membership controls, sidebar leave actions, grouped/sortable project listings, and focused tests. > - The benefit is a cleaner personal workspace view without weakening company-scoped access to the underlying project or agent detail pages. ## What Changed - Added `project_memberships` and `agent_memberships` tables with API/shared/server contracts for current-user join/leave state. - Renumbered the membership migration to `0090_resource_memberships` after rebasing onto current `master`, and made it idempotent for anyone who had applied the old branch-local `0087` migration. - Added project and agent sidebar leave actions, plus list filtering that waits for membership state before hiding resources. - Added grouped project listing, project sorting controls, and reserved row subtitle height for cleaner scanning. - Fixed HTTP auth cookie security handling so HTTP worktree sessions can persist. - Updated focused server and UI tests for the new membership, sidebar, project list, and auth behavior. ## Verification - `pnpm exec vitest run server/src/__tests__/better-auth.test.ts server/src/__tests__/resource-memberships-routes.test.ts ui/src/pages/Projects.test.tsx ui/src/components/SidebarProjects.test.tsx ui/src/components/SidebarAgents.test.tsx ui/src/components/MembershipAction.test.tsx ui/src/components/EntityRow.test.tsx` - Confirmed the branch is rebased on current `origin/master`. - Confirmed the PR diff does not include `pnpm-lock.yaml` or `.github/workflows` changes. ## Risks - Migration safety: low to medium. The migration now uses `IF NOT EXISTS` / guarded constraints and is numbered after current master migrations, but it should still get CI coverage against fresh databases. - UI behavior: low. Left resources are hidden from sidebar only after membership state loads; direct detail access remains available. - Auth behavior: low. Cookie security is relaxed only for HTTP/private local-style origins where secure cookies would prevent login persistence. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - OpenAI GPT-5 Codex coding agent, tool-enabled shell/git workflow, context window not exposed by runtime. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] If this change affects the UI, I have included before/after screenshots - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge Screenshot note: no browser screenshots were captured in this heartbeat; the UI changes are covered by focused component tests above. --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-05-25 13:12:41 -05:00
parent 60efa38f86
commit 9aea3e3d35
42 changed files with 20241 additions and 201 deletions
@@ -143,6 +143,17 @@ The database mode is controlled by `DATABASE_URL`:

 Your Drizzle schema (`packages/db/src/schema/`) stays the same regardless of mode.

+## Resource membership tables
+
+Paperclip stores current-user sidebar membership state in:
+
+- `project_memberships`
+- `agent_memberships`
+
+These rows are company-scoped and user-scoped. A missing row means the user is joined, so existing users keep seeing projects and agents in the sidebar until they explicitly leave them. Rows only control sidebar visibility; they do not affect project/agent detail access, all-pages, selectors, assignment flows, or existing company permissions.
+
+Both tables use a unique key on `(company_id, user_id, resource_id)` and keep `state` as `joined` or `left`. Join/leave mutations are idempotent board-user `/me` operations and write activity entries when the effective state changes.
+
 ## Plugin database namespaces

 The plugin runtime tracks plugin-owned database namespaces and migrations in `plugin_database_namespaces` and `plugin_migrations`. Hosted deployments that separate runtime and migration connections should set `DATABASE_MIGRATION_URL`; plugin namespace migration work uses the migration connection when present.
@@ -311,7 +311,32 @@ Invariant: each event must attach to agent and company; rollups are aggregation,
 - `details` jsonb null
 - `created_at` timestamptz not null default now()

-## 7.12 `company_secrets` + `company_secret_versions`
+## 7.12 `project_memberships` + `agent_memberships`
+
+Per-user project/agent membership is personal visibility state for board users. It only controls whether a resource appears in the current user's sidebar; it must not grant or revoke access to all-pages, detail pages, selectors, assignment flows, search, or existing permissions.
+
+`project_memberships`:
+
+- `id` uuid pk
+- `company_id` uuid fk `companies.id` not null
+- `project_id` uuid fk `projects.id` not null
+- `user_id` text not null
+- `state` enum-like text: `joined | left`
+- `created_at` timestamptz not null default now()
+- `updated_at` timestamptz not null default now()
+- unique `(company_id, user_id, project_id)`
+
+`agent_memberships` mirrors the same shape with `agent_id` instead of `project_id` and unique `(company_id, user_id, agent_id)`.
+
+Invariants:
+
+- Missing membership rows mean `joined` for backward compatibility.
+- Mutations are board-user-only `/me` operations; agent API keys are rejected.
+- Viewer-role board users may update only their own membership rows through the narrow self-service helper.
+- Target project/agent ownership is checked against the path company before mutation.
+- Successful state changes write `resource_membership.joined` or `resource_membership.left` activity entries.
+
+## 7.13 `company_secrets` + `company_secret_versions`

 - Secret values are not stored inline in `agents.adapter_config.env`.
 - Agent env entries should use secret refs for sensitive values.
@@ -325,7 +350,7 @@ Operational policy:
 - Activity and approval payloads must not persist raw sensitive values.
 - Config revisions may include redacted placeholders; such revisions are non-restorable for redacted fields.

-## 7.13 Required Indexes
+## 7.14 Required Indexes

 - `agents(company_id, status)`
 - `agents(company_id, reports_to)`
@@ -343,8 +368,12 @@ Operational policy:
 - `issue_attachments(company_id, issue_id)`
 - `company_secrets(company_id, name)` unique
 - `company_secret_versions(secret_id, version)` unique
+- `project_memberships(company_id, user_id)`
+- `project_memberships(company_id, user_id, project_id)` unique
+- `agent_memberships(company_id, user_id)`
+- `agent_memberships(company_id, user_id, agent_id)` unique

-## 7.14 `assets` + `issue_attachments`
+## 7.15 `assets` + `issue_attachments`

 - `assets` stores provider-backed object metadata (not inline bytes):
  - `id` uuid pk
@@ -623,14 +652,28 @@ Server behavior:
 - `GET /projects/:projectId`
 - `PATCH /projects/:projectId`

-## 10.6 Approvals
+## 10.6 Current-user Resource Memberships
+
+- `GET /companies/:companyId/resource-memberships/me`
+- `PUT /companies/:companyId/resource-memberships/me/projects/:projectId`
+- `PUT /companies/:companyId/resource-memberships/me/agents/:agentId`
+
+Request payload:
+
+```json
+{ "state": "joined" }
+```
+
+Allowed states are `joined` and `left`. Endpoints require a concrete board user and active company membership, reject agent API keys, and only mutate the caller's own sidebar visibility state. Joining/leaving is idempotent; missing rows read as `joined`.
+
+## 10.7 Approvals

 - `GET /companies/:companyId/approvals?status=pending`
 - `POST /companies/:companyId/approvals`
 - `POST /approvals/:approvalId/approve`
 - `POST /approvals/:approvalId/reject`

-## 10.7 Cost and Budgets
+## 10.8 Cost and Budgets

 - `POST /companies/:companyId/cost-events`
 - `GET /companies/:companyId/costs/summary`
@@ -639,7 +682,7 @@ Server behavior:
 - `PATCH /companies/:companyId/budgets`
 - `PATCH /agents/:agentId/budgets`

-## 10.8 Activity and Dashboard
+## 10.9 Activity and Dashboard

 - `GET /companies/:companyId/activity`
 - `GET /companies/:companyId/dashboard`
@@ -651,7 +694,7 @@ Dashboard payload must include:
 - month-to-date spend and budget utilization
 - pending approvals count

-## 10.9 Error Semantics
+## 10.10 Error Semantics

 - `400` validation error
 - `401` unauthenticated
@@ -661,7 +704,7 @@ Dashboard payload must include:
 - `422` semantic rule violation
 - `500` server error

-## 10.10 Current Implementation API Addenda
+## 10.11 Current Implementation API Addenda

 The current app also exposes V1-supporting surfaces for:

@@ -0,0 +1,55 @@
+CREATE TABLE IF NOT EXISTS "agent_memberships" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"agent_id" uuid NOT NULL,
+	"user_id" text NOT NULL,
+	"state" text DEFAULT 'joined' NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "project_memberships" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"company_id" uuid NOT NULL,
+	"project_id" uuid NOT NULL,
+	"user_id" text NOT NULL,
+	"state" text DEFAULT 'joined' NOT NULL,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+DO $$ BEGIN
+	IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'agent_memberships_company_id_companies_id_fk') THEN
+		ALTER TABLE "agent_memberships" ADD CONSTRAINT "agent_memberships_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;
+	END IF;
+END $$;
+--> statement-breakpoint
+DO $$ BEGIN
+	IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'agent_memberships_agent_id_agents_id_fk') THEN
+		ALTER TABLE "agent_memberships" ADD CONSTRAINT "agent_memberships_agent_id_agents_id_fk" FOREIGN KEY ("agent_id") REFERENCES "public"."agents"("id") ON DELETE cascade ON UPDATE no action;
+	END IF;
+END $$;
+--> statement-breakpoint
+DO $$ BEGIN
+	IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'project_memberships_company_id_companies_id_fk') THEN
+		ALTER TABLE "project_memberships" ADD CONSTRAINT "project_memberships_company_id_companies_id_fk" FOREIGN KEY ("company_id") REFERENCES "public"."companies"("id") ON DELETE cascade ON UPDATE no action;
+	END IF;
+END $$;
+--> statement-breakpoint
+DO $$ BEGIN
+	IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'project_memberships_project_id_projects_id_fk') THEN
+		ALTER TABLE "project_memberships" ADD CONSTRAINT "project_memberships_project_id_projects_id_fk" FOREIGN KEY ("project_id") REFERENCES "public"."projects"("id") ON DELETE cascade ON UPDATE no action;
+	END IF;
+END $$;
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "agent_memberships_company_user_idx" ON "agent_memberships" USING btree ("company_id","user_id");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "agent_memberships_agent_idx" ON "agent_memberships" USING btree ("agent_id");
+--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "agent_memberships_company_user_agent_uq" ON "agent_memberships" USING btree ("company_id","user_id","agent_id");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "project_memberships_company_user_idx" ON "project_memberships" USING btree ("company_id","user_id");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "project_memberships_project_idx" ON "project_memberships" USING btree ("project_id");
+--> statement-breakpoint
+CREATE UNIQUE INDEX IF NOT EXISTS "project_memberships_company_user_project_uq" ON "project_memberships" USING btree ("company_id","user_id","project_id");
@@ -631,6 +631,13 @@
      "when": 1779129600000,
      "tag": "0089_cloud_upstreams",
      "breakpoints": true
+    },
+    {
+      "idx": 90,
+      "version": "7",
+      "when": 1779573019125,
+      "tag": "0090_resource_memberships",
+      "breakpoints": true
    }
  ]
 }
@@ -0,0 +1,25 @@
+import { pgTable, uuid, text, timestamp, uniqueIndex, index } from "drizzle-orm/pg-core";
+import { agents } from "./agents.js";
+import { companies } from "./companies.js";
+
+export const agentMemberships = pgTable(
+  "agent_memberships",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    companyId: uuid("company_id").notNull().references(() => companies.id, { onDelete: "cascade" }),
+    agentId: uuid("agent_id").notNull().references(() => agents.id, { onDelete: "cascade" }),
+    userId: text("user_id").notNull(),
+    state: text("state").notNull().default("joined"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    companyUserIdx: index("agent_memberships_company_user_idx").on(table.companyId, table.userId),
+    agentIdx: index("agent_memberships_agent_idx").on(table.agentId),
+    companyUserAgentUq: uniqueIndex("agent_memberships_company_user_agent_uq").on(
+      table.companyId,
+      table.userId,
+      table.agentId,
+    ),
+  }),
+);
@@ -6,6 +6,7 @@ export { cloudUpstreamConnections, cloudUpstreamRuns } from "./cloud_upstreams.j
 export { instanceUserRoles } from "./instance_user_roles.js";
 export { userSidebarPreferences } from "./user_sidebar_preferences.js";
 export { agents } from "./agents.js";
+export { agentMemberships } from "./agent_memberships.js";
 export { boardApiKeys } from "./board_api_keys.js";
 export { cliAuthChallenges } from "./cli_auth_challenges.js";
 export { companyMemberships } from "./company_memberships.js";
@@ -21,6 +22,7 @@ export { agentRuntimeState } from "./agent_runtime_state.js";
 export { agentTaskSessions } from "./agent_task_sessions.js";
 export { agentWakeupRequests } from "./agent_wakeup_requests.js";
 export { projects } from "./projects.js";
+export { projectMemberships } from "./project_memberships.js";
 export { projectWorkspaces } from "./project_workspaces.js";
 export { executionWorkspaces } from "./execution_workspaces.js";
 export { environments } from "./environments.js";
@@ -0,0 +1,25 @@
+import { pgTable, uuid, text, timestamp, uniqueIndex, index } from "drizzle-orm/pg-core";
+import { companies } from "./companies.js";
+import { projects } from "./projects.js";
+
+export const projectMemberships = pgTable(
+  "project_memberships",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    companyId: uuid("company_id").notNull().references(() => companies.id, { onDelete: "cascade" }),
+    projectId: uuid("project_id").notNull().references(() => projects.id, { onDelete: "cascade" }),
+    userId: text("user_id").notNull(),
+    state: text("state").notNull().default("joined"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    companyUserIdx: index("project_memberships_company_user_idx").on(table.companyId, table.userId),
+    projectIdx: index("project_memberships_project_idx").on(table.projectId),
+    companyUserProjectUq: uniqueIndex("project_memberships_company_user_project_uq").on(
+      table.companyId,
+      table.userId,
+      table.projectId,
+    ),
+  }),
+);
@@ -18,6 +18,7 @@ export const API = {
  dashboard: `${API_PREFIX}/dashboard`,
  sidebarBadges: `${API_PREFIX}/sidebar-badges`,
  sidebarPreferences: `${API_PREFIX}/sidebar-preferences`,
+  resourceMemberships: `${API_PREFIX}/resource-memberships`,
  invites: `${API_PREFIX}/invites`,
  joinRequests: `${API_PREFIX}/join-requests`,
  members: `${API_PREFIX}/members`,
@@ -659,6 +659,18 @@ export {
  upsertSidebarOrderPreferenceSchema,
  type UpsertSidebarOrderPreference,
 } from "./validators/sidebar-preferences.js";
+export {
+  resourceMembershipStateSchema,
+  updateResourceMembershipSchema,
+  type UpdateResourceMembership,
+} from "./validators/resource-memberships.js";
+export {
+  RESOURCE_MEMBERSHIP_STATES,
+  type ResourceMembershipResourceType,
+  type ResourceMembershipState,
+  type ResourceMemberships,
+  type ResourceMembershipUpdateResult,
+} from "./types/resource-memberships.js";

 export { workspaceRuntimeControlTargetSchema } from "./validators/execution-workspace.js";
 export {
@@ -327,6 +327,14 @@ export type {
 } from "./user-profile.js";
 export type { SidebarBadges } from "./sidebar-badges.js";
 export type { SidebarOrderPreference } from "./sidebar-preferences.js";
+export type {
+  ResourceMembershipResourceType,
+  ResourceMembershipState,
+  ResourceMemberships,
+  ResourceMembershipUpdateResult,
+  UpdateResourceMembership,
+} from "./resource-memberships.js";
+export { RESOURCE_MEMBERSHIP_STATES } from "./resource-memberships.js";
 export type { InboxDismissal } from "./inbox-dismissal.js";
 export type {
  AccessUserProfile,
@@ -0,0 +1,21 @@
+export const RESOURCE_MEMBERSHIP_STATES = ["joined", "left"] as const;
+
+export type ResourceMembershipState = (typeof RESOURCE_MEMBERSHIP_STATES)[number];
+export type ResourceMembershipResourceType = "project" | "agent";
+
+export interface ResourceMemberships {
+  projectMemberships: Record<string, ResourceMembershipState>;
+  agentMemberships: Record<string, ResourceMembershipState>;
+  updatedAt: Date | null;
+}
+
+export interface UpdateResourceMembership {
+  state: ResourceMembershipState;
+}
+
+export interface ResourceMembershipUpdateResult {
+  resourceType: ResourceMembershipResourceType;
+  resourceId: string;
+  state: ResourceMembershipState;
+  updatedAt: Date;
+}
@@ -51,6 +51,11 @@ export {
  upsertSidebarOrderPreferenceSchema,
  type UpsertSidebarOrderPreference,
 } from "./sidebar-preferences.js";
+export {
+  resourceMembershipStateSchema,
+  updateResourceMembershipSchema,
+  type UpdateResourceMembership,
+} from "./resource-memberships.js";
 export {
  companySkillSourceTypeSchema,
  companySkillTrustLevelSchema,
@@ -0,0 +1,10 @@
+import { z } from "zod";
+import { RESOURCE_MEMBERSHIP_STATES } from "../types/resource-memberships.js";
+
+export const resourceMembershipStateSchema = z.enum(RESOURCE_MEMBERSHIP_STATES);
+
+export const updateResourceMembershipSchema = z.object({
+  state: resourceMembershipStateSchema,
+});
+
+export type UpdateResourceMembership = z.infer<typeof updateResourceMembershipSchema>;
@@ -123,6 +123,33 @@ describe("Better Auth cookie scoping", () => {
    } as Parameters<typeof shouldDisableSecureAuthCookies>[0])).toBe(true);
  });

+  it("disables secure cookies for private authenticated auto mode without a public URL", () => {
+    expect(shouldDisableSecureAuthCookies({
+      deploymentMode: "authenticated",
+      deploymentExposure: "private",
+      authBaseUrlMode: "auto",
+      authPublicBaseUrl: undefined,
+    })).toBe(true);
+  });
+
+  it("disables secure cookies for explicit HTTP public URLs", () => {
+    expect(shouldDisableSecureAuthCookies({
+      deploymentMode: "authenticated",
+      deploymentExposure: "private",
+      authBaseUrlMode: "explicit",
+      authPublicBaseUrl: "http://board.example.test:3101",
+    })).toBe(true);
+  });
+
+  it("keeps secure cookies for explicit HTTPS public URLs", () => {
+    expect(shouldDisableSecureAuthCookies({
+      deploymentMode: "authenticated",
+      deploymentExposure: "public",
+      authBaseUrlMode: "explicit",
+      authPublicBaseUrl: "https://board.example.test",
+    })).toBe(false);
+  });
+
  it("adds hostname port variants for authenticated mode on non-default ports", () => {
    const trustedOrigins = deriveAuthTrustedOrigins({
      deploymentMode: "authenticated",
@@ -0,0 +1,218 @@
+import { randomUUID } from "node:crypto";
+import express from "express";
+import request from "supertest";
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
+import {
+  activityLog,
+  agentMemberships,
+  agents,
+  companies,
+  createDb,
+  projectMemberships,
+  projects,
+} from "@paperclipai/db";
+import {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+} from "./helpers/embedded-postgres.js";
+import { resourceMembershipRoutes } from "../routes/resource-memberships.js";
+import { errorHandler } from "../middleware/index.js";
+import { resourceMembershipService } from "../services/resource-memberships.js";
+
+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
+
+if (!embeddedPostgresSupport.supported) {
+  console.warn(
+    `Skipping embedded Postgres resource membership tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,
+  );
+}
+
+function boardActor(companyId: string, role: "admin" | "operator" | "viewer" = "viewer") {
+  return {
+    type: "board" as const,
+    userId: "user-1",
+    source: "session" as const,
+    isInstanceAdmin: false,
+    companyIds: [companyId],
+    memberships: [{ companyId, membershipRole: role, status: "active" }],
+  };
+}
+
+function createApp(db: ReturnType<typeof createDb>, actor: Express.Request["actor"]) {
+  const app = express();
+  app.use(express.json());
+  app.use((req, _res, next) => {
+    req.actor = actor;
+    next();
+  });
+  app.use("/api", resourceMembershipRoutes(db));
+  app.use(errorHandler);
+  return app;
+}
+
+describeEmbeddedPostgres("resource membership routes", () => {
+  let db!: ReturnType<typeof createDb>;
+  let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
+
+  beforeAll(async () => {
+    tempDb = await startEmbeddedPostgresTestDatabase("paperclip-resource-memberships-");
+    db = createDb(tempDb.connectionString);
+  }, 20_000);
+
+  afterEach(async () => {
+    await db.delete(activityLog);
+    await db.delete(projectMemberships);
+    await db.delete(agentMemberships);
+    await db.delete(projects);
+    await db.delete(agents);
+    await db.delete(companies);
+  });
+
+  afterAll(async () => {
+    await tempDb?.cleanup();
+  });
+
+  async function seed() {
+    const companyId = randomUUID();
+    const otherCompanyId = randomUUID();
+    const projectId = randomUUID();
+    const otherProjectId = randomUUID();
+    const agentId = randomUUID();
+    const otherAgentId = randomUUID();
+    await db.insert(companies).values([
+      {
+        id: companyId,
+        name: "Paperclip",
+        issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+        requireBoardApprovalForNewAgents: false,
+      },
+      {
+        id: otherCompanyId,
+        name: "Other",
+        issuePrefix: `T${otherCompanyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+        requireBoardApprovalForNewAgents: false,
+      },
+    ]);
+    await db.insert(projects).values([
+      { id: projectId, companyId, name: "Growth", status: "in_progress" },
+      { id: otherProjectId, companyId: otherCompanyId, name: "Other", status: "in_progress" },
+    ]);
+    await db.insert(agents).values([
+      {
+        id: agentId,
+        companyId,
+        name: "CodexCoder",
+        role: "engineer",
+        status: "active",
+        adapterType: "codex_local",
+        adapterConfig: {},
+        runtimeConfig: {},
+        permissions: {},
+      },
+      {
+        id: otherAgentId,
+        companyId: otherCompanyId,
+        name: "OtherAgent",
+        role: "engineer",
+        status: "active",
+        adapterType: "codex_local",
+        adapterConfig: {},
+        runtimeConfig: {},
+        permissions: {},
+      },
+    ]);
+    return { companyId, otherAgentId, otherProjectId, projectId, agentId };
+  }
+
+  it("defaults missing membership rows to joined", async () => {
+    const { companyId } = await seed();
+    const app = createApp(db, boardActor(companyId));
+
+    const res = await request(app).get(`/api/companies/${companyId}/resource-memberships/me`);
+
+    expect(res.status).toBe(200);
+    expect(res.body).toEqual({
+      projectMemberships: {},
+      agentMemberships: {},
+      updatedAt: null,
+    });
+  });
+
+  it("allows viewer self-service mutations, logs changes, and keeps repeats idempotent", async () => {
+    const { companyId, projectId } = await seed();
+    const app = createApp(db, boardActor(companyId, "viewer"));
+
+    const first = await request(app)
+      .put(`/api/companies/${companyId}/resource-memberships/me/projects/${projectId}`)
+      .send({ state: "left" });
+    const second = await request(app)
+      .put(`/api/companies/${companyId}/resource-memberships/me/projects/${projectId}`)
+      .send({ state: "left" });
+
+    expect(first.status).toBe(200);
+    expect(first.body).toMatchObject({ resourceType: "project", resourceId: projectId, state: "left" });
+    expect(second.status).toBe(200);
+
+    const rows = await db.select().from(projectMemberships);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]).toMatchObject({ companyId, projectId, userId: "user-1", state: "left" });
+
+    const activity = await db.select().from(activityLog);
+    expect(activity).toHaveLength(1);
+    expect(activity[0]).toMatchObject({
+      companyId,
+      actorType: "user",
+      actorId: "user-1",
+      action: "resource_membership.left",
+      entityType: "project",
+      entityId: projectId,
+    });
+  });
+
+  it("rejects agent API key actors", async () => {
+    const { companyId, agentId } = await seed();
+    const app = createApp(db, {
+      type: "agent",
+      agentId,
+      companyId,
+      source: "agent_key",
+    });
+
+    const res = await request(app).get(`/api/companies/${companyId}/resource-memberships/me`);
+
+    expect(res.status).toBe(403);
+  });
+
+  it("rejects cross-company target resources", async () => {
+    const { companyId, otherAgentId, otherProjectId } = await seed();
+    const app = createApp(db, boardActor(companyId));
+
+    const projectRes = await request(app)
+      .put(`/api/companies/${companyId}/resource-memberships/me/projects/${otherProjectId}`)
+      .send({ state: "left" });
+    const agentRes = await request(app)
+      .put(`/api/companies/${companyId}/resource-memberships/me/agents/${otherAgentId}`)
+      .send({ state: "left" });
+
+    expect(projectRes.status).toBe(404);
+    expect(agentRes.status).toBe(404);
+    await expect(db.select().from(projectMemberships)).resolves.toHaveLength(0);
+    await expect(db.select().from(agentMemberships)).resolves.toHaveLength(0);
+  });
+
+  it("denies direct service calls that try to mutate another user's membership", async () => {
+    const { companyId, projectId } = await seed();
+    const svc = resourceMembershipService(db);
+
+    await expect(
+      svc.updateProject({
+        companyId,
+        projectId,
+        userId: "other-user",
+        state: "left",
+        actor: boardActor(companyId),
+      }),
+    ).rejects.toMatchObject({ status: 403 });
+  });
+});
@@ -28,6 +28,7 @@ import { dashboardRoutes } from "./routes/dashboard.js";
 import { userProfileRoutes } from "./routes/user-profiles.js";
 import { sidebarBadgeRoutes } from "./routes/sidebar-badges.js";
 import { sidebarPreferenceRoutes } from "./routes/sidebar-preferences.js";
+import { resourceMembershipRoutes } from "./routes/resource-memberships.js";
 import { inboxDismissalRoutes } from "./routes/inbox-dismissals.js";
 import { instanceSettingsRoutes } from "./routes/instance-settings.js";
 import {
@@ -228,6 +229,7 @@ export async function createApp(
  api.use(userProfileRoutes(db));
  api.use(sidebarBadgeRoutes(db));
  api.use(sidebarPreferenceRoutes(db));
+  api.use(resourceMembershipRoutes(db));
  api.use(inboxDismissalRoutes(db));
  api.use(instanceSettingsRoutes(db));
  if (opts.databaseBackupService) {
@@ -14,6 +14,7 @@ export { activityRoutes } from "./activity.js";
 export { dashboardRoutes } from "./dashboard.js";
 export { sidebarBadgeRoutes } from "./sidebar-badges.js";
 export { sidebarPreferenceRoutes } from "./sidebar-preferences.js";
+export { resourceMembershipRoutes } from "./resource-memberships.js";
 export { inboxDismissalRoutes } from "./inbox-dismissals.js";
 export { llmRoutes } from "./llms.js";
 export { accessRoutes } from "./access.js";
@@ -0,0 +1,120 @@
+import { Router, type Request, type Response } from "express";
+import type { Db } from "@paperclipai/db";
+import { updateResourceMembershipSchema } from "@paperclipai/shared";
+import { validate } from "../middleware/validate.js";
+import { getActorInfo } from "./authz.js";
+import { logActivity, resourceMembershipService } from "../services/index.js";
+
+function requireBoardUserId(req: Request, res: Response): string | null {
+  if (req.actor.type !== "board" || !req.actor.userId) {
+    res.status(403).json({ error: "Board user access required" });
+    return null;
+  }
+  return req.actor.userId;
+}
+
+async function logMembershipChange(
+  db: Db,
+  req: Request,
+  input: {
+    companyId: string;
+    userId: string;
+    resourceType: "project" | "agent";
+    resourceId: string;
+    state: "joined" | "left";
+    policySource: string;
+  },
+) {
+  const actor = getActorInfo(req);
+  await logActivity(db, {
+    companyId: input.companyId,
+    actorType: actor.actorType,
+    actorId: actor.actorId,
+    agentId: actor.agentId,
+    runId: actor.runId,
+    action: `resource_membership.${input.state}`,
+    entityType: input.resourceType,
+    entityId: input.resourceId,
+    details: {
+      userId: input.userId,
+      resourceType: input.resourceType,
+      resourceId: input.resourceId,
+      state: input.state,
+      policySource: input.policySource,
+    },
+  });
+}
+
+export function resourceMembershipRoutes(db: Db) {
+  const router = Router();
+  const svc = resourceMembershipService(db);
+
+  router.get("/companies/:companyId/resource-memberships/me", async (req, res) => {
+    const companyId = req.params.companyId as string;
+    const userId = requireBoardUserId(req, res);
+    if (!userId) return;
+    res.json(await svc.listForUser(companyId, userId, req.actor));
+  });
+
+  router.put(
+    "/companies/:companyId/resource-memberships/me/projects/:projectId",
+    validate(updateResourceMembershipSchema),
+    async (req, res) => {
+      const companyId = req.params.companyId as string;
+      const projectId = req.params.projectId as string;
+      const userId = requireBoardUserId(req, res);
+      if (!userId) return;
+      const result = await svc.updateProject({
+        companyId,
+        projectId,
+        userId,
+        state: req.body.state,
+        actor: req.actor,
+      });
+      if (result.changed) {
+        await logMembershipChange(db, req, {
+          companyId,
+          userId,
+          resourceType: "project",
+          resourceId: projectId,
+          state: result.state,
+          policySource: result.policySource,
+        });
+      }
+      const { changed: _changed, policySource: _policySource, ...response } = result;
+      res.json(response);
+    },
+  );
+
+  router.put(
+    "/companies/:companyId/resource-memberships/me/agents/:agentId",
+    validate(updateResourceMembershipSchema),
+    async (req, res) => {
+      const companyId = req.params.companyId as string;
+      const agentId = req.params.agentId as string;
+      const userId = requireBoardUserId(req, res);
+      if (!userId) return;
+      const result = await svc.updateAgent({
+        companyId,
+        agentId,
+        userId,
+        state: req.body.state,
+        actor: req.actor,
+      });
+      if (result.changed) {
+        await logMembershipChange(db, req, {
+          companyId,
+          userId,
+          resourceType: "agent",
+          resourceId: agentId,
+          state: result.state,
+          policySource: result.policySource,
+        });
+      }
+      const { changed: _changed, policySource: _policySource, ...response } = result;
+      res.json(response);
+    },
+  );
+
+  return router;
+}
@@ -42,6 +42,7 @@ export { classifyIssueGraphLiveness, type IssueLivenessFinding } from "./recover
 export { dashboardService } from "./dashboard.js";
 export { sidebarBadgeService } from "./sidebar-badges.js";
 export { sidebarPreferenceService } from "./sidebar-preferences.js";
+export { resourceMembershipService, type ResourceMembershipPolicyHook } from "./resource-memberships.js";
 export { inboxDismissalService } from "./inbox-dismissals.js";
 export { accessService } from "./access.js";
 export {
@@ -0,0 +1,318 @@
+import { and, eq } from "drizzle-orm";
+import type { Db } from "@paperclipai/db";
+import {
+  agentMemberships,
+  agents,
+  projectMemberships,
+  projects,
+} from "@paperclipai/db";
+import type {
+  ResourceMembershipResourceType,
+  ResourceMembershipState,
+  ResourceMemberships,
+  ResourceMembershipUpdateResult,
+} from "@paperclipai/shared";
+import { forbidden, notFound } from "../errors.js";
+import { logger } from "../middleware/logger.js";
+
+type BoardActor = {
+  type: "board" | "agent" | "none";
+  userId?: string;
+  companyIds?: string[];
+  memberships?: Array<{
+    companyId: string;
+    membershipRole?: string | null;
+    status?: string;
+  }>;
+  isInstanceAdmin?: boolean;
+  source?: string;
+};
+
+type PolicyDecision = {
+  allowed: boolean;
+  reason?: string | null;
+  source?: string | null;
+};
+
+export type ResourceMembershipPolicyHook = (input: {
+  actor: BoardActor;
+  companyId: string;
+  userId: string;
+  resourceType: ResourceMembershipResourceType;
+  resourceId: string;
+  state: ResourceMembershipState;
+}) => Promise<PolicyDecision> | PolicyDecision;
+
+type ResourceMembershipServiceOptions = {
+  policyHook?: ResourceMembershipPolicyHook | null;
+};
+
+function defaultJoinedMap<T extends { projectId?: string; agentId?: string; state: string }>(
+  rows: T[],
+  key: "projectId" | "agentId",
+): Record<string, ResourceMembershipState> {
+  const result: Record<string, ResourceMembershipState> = {};
+  for (const row of rows) {
+    const id = row[key];
+    if (typeof id !== "string") continue;
+    result[id] = row.state === "left" ? "left" : "joined";
+  }
+  return result;
+}
+
+function latestDate(...dates: Array<Date | null | undefined>): Date | null {
+  let latest: Date | null = null;
+  for (const date of dates) {
+    if (!date) continue;
+    if (!latest || date.getTime() > latest.getTime()) latest = date;
+  }
+  return latest;
+}
+
+function assertBoardSelfMembershipAccess(actor: BoardActor, companyId: string, userId: string) {
+  if (actor.type !== "board" || !actor.userId) {
+    throw forbidden("Board user access required");
+  }
+  if (actor.userId !== userId) {
+    throw forbidden("Users may only update their own resource memberships");
+  }
+  if (actor.source === "local_implicit" || actor.isInstanceAdmin) {
+    return;
+  }
+  const membership = actor.memberships?.find((item) => item.companyId === companyId);
+  if (!membership || membership.status !== "active") {
+    throw forbidden("User does not have active company access");
+  }
+}
+
+async function evaluatePolicy(
+  hook: ResourceMembershipPolicyHook | null | undefined,
+  input: Parameters<ResourceMembershipPolicyHook>[0],
+): Promise<PolicyDecision> {
+  if (!hook) return { allowed: true, source: "oss_default" };
+  try {
+    const decision = await hook(input);
+    return {
+      allowed: decision.allowed === true,
+      reason: decision.reason ?? null,
+      source: decision.source ?? "policy_hook",
+    };
+  } catch (err) {
+    logger.warn(
+      { err, companyId: input.companyId, resourceType: input.resourceType, resourceId: input.resourceId },
+      "resource membership policy hook failed closed",
+    );
+    return { allowed: false, reason: "policy_hook_failed", source: "policy_hook" };
+  }
+}
+
+export function resourceMembershipService(db: Db, options: ResourceMembershipServiceOptions = {}) {
+  const policyHook = options.policyHook ?? null;
+
+  async function assertMutationAllowed(input: {
+    actor: BoardActor;
+    companyId: string;
+    userId: string;
+    resourceType: ResourceMembershipResourceType;
+    resourceId: string;
+    state: ResourceMembershipState;
+  }): Promise<PolicyDecision> {
+    assertBoardSelfMembershipAccess(input.actor, input.companyId, input.userId);
+    const decision = await evaluatePolicy(policyHook, input);
+    if (!decision.allowed) {
+      logger.warn(
+        {
+          companyId: input.companyId,
+          userId: input.userId,
+          resourceType: input.resourceType,
+          resourceId: input.resourceId,
+          reason: decision.reason ?? "denied",
+          source: decision.source ?? "policy_hook",
+        },
+        "resource membership mutation denied",
+      );
+      throw forbidden("Resource membership policy denied this request");
+    }
+    return decision;
+  }
+
+  return {
+    async listForUser(companyId: string, userId: string, actor: BoardActor): Promise<ResourceMemberships> {
+      assertBoardSelfMembershipAccess(actor, companyId, userId);
+      const [projectRows, agentRows] = await Promise.all([
+        db
+          .select({
+            projectId: projectMemberships.projectId,
+            state: projectMemberships.state,
+            updatedAt: projectMemberships.updatedAt,
+          })
+          .from(projectMemberships)
+          .where(and(
+            eq(projectMemberships.companyId, companyId),
+            eq(projectMemberships.userId, userId),
+          )),
+        db
+          .select({
+            agentId: agentMemberships.agentId,
+            state: agentMemberships.state,
+            updatedAt: agentMemberships.updatedAt,
+          })
+          .from(agentMemberships)
+          .where(and(
+            eq(agentMemberships.companyId, companyId),
+            eq(agentMemberships.userId, userId),
+          )),
+      ]);
+      return {
+        projectMemberships: defaultJoinedMap(projectRows, "projectId"),
+        agentMemberships: defaultJoinedMap(agentRows, "agentId"),
+        updatedAt: latestDate(
+          ...projectRows.map((row) => row.updatedAt),
+          ...agentRows.map((row) => row.updatedAt),
+        ),
+      };
+    },
+
+    async updateProject(input: {
+      companyId: string;
+      userId: string;
+      projectId: string;
+      state: ResourceMembershipState;
+      actor: BoardActor;
+    }): Promise<ResourceMembershipUpdateResult & { changed: boolean; policySource: string }> {
+      const project = await db.query.projects.findFirst({
+        where: and(
+          eq(projects.id, input.projectId),
+          eq(projects.companyId, input.companyId),
+        ),
+      });
+      if (!project) throw notFound("Project not found");
+      const decision = await assertMutationAllowed({
+        actor: input.actor,
+        companyId: input.companyId,
+        userId: input.userId,
+        resourceType: "project",
+        resourceId: input.projectId,
+        state: input.state,
+      });
+
+      const existing = await db.query.projectMemberships.findFirst({
+        where: and(
+          eq(projectMemberships.companyId, input.companyId),
+          eq(projectMemberships.userId, input.userId),
+          eq(projectMemberships.projectId, input.projectId),
+        ),
+      });
+      const previousState: ResourceMembershipState = existing?.state === "left" ? "left" : "joined";
+      if (previousState === input.state) {
+        return {
+          resourceType: "project",
+          resourceId: input.projectId,
+          state: input.state,
+          updatedAt: existing?.updatedAt ?? new Date(),
+          changed: false,
+          policySource: decision.source ?? "oss_default",
+        };
+      }
+
+      const now = new Date();
+      const [row] = await db
+        .insert(projectMemberships)
+        .values({
+          companyId: input.companyId,
+          projectId: input.projectId,
+          userId: input.userId,
+          state: input.state,
+          updatedAt: now,
+        })
+        .onConflictDoUpdate({
+          target: [projectMemberships.companyId, projectMemberships.userId, projectMemberships.projectId],
+          set: {
+            state: input.state,
+            updatedAt: now,
+          },
+        })
+        .returning();
+
+      return {
+        resourceType: "project",
+        resourceId: input.projectId,
+        state: row?.state === "left" ? "left" : "joined",
+        updatedAt: row?.updatedAt ?? now,
+        changed: true,
+        policySource: decision.source ?? "oss_default",
+      };
+    },
+
+    async updateAgent(input: {
+      companyId: string;
+      userId: string;
+      agentId: string;
+      state: ResourceMembershipState;
+      actor: BoardActor;
+    }): Promise<ResourceMembershipUpdateResult & { changed: boolean; policySource: string }> {
+      const agent = await db.query.agents.findFirst({
+        where: and(
+          eq(agents.id, input.agentId),
+          eq(agents.companyId, input.companyId),
+        ),
+      });
+      if (!agent) throw notFound("Agent not found");
+      const decision = await assertMutationAllowed({
+        actor: input.actor,
+        companyId: input.companyId,
+        userId: input.userId,
+        resourceType: "agent",
+        resourceId: input.agentId,
+        state: input.state,
+      });
+
+      const existing = await db.query.agentMemberships.findFirst({
+        where: and(
+          eq(agentMemberships.companyId, input.companyId),
+          eq(agentMemberships.userId, input.userId),
+          eq(agentMemberships.agentId, input.agentId),
+        ),
+      });
+      const previousState: ResourceMembershipState = existing?.state === "left" ? "left" : "joined";
+      if (previousState === input.state) {
+        return {
+          resourceType: "agent",
+          resourceId: input.agentId,
+          state: input.state,
+          updatedAt: existing?.updatedAt ?? new Date(),
+          changed: false,
+          policySource: decision.source ?? "oss_default",
+        };
+      }
+
+      const now = new Date();
+      const [row] = await db
+        .insert(agentMemberships)
+        .values({
+          companyId: input.companyId,
+          agentId: input.agentId,
+          userId: input.userId,
+          state: input.state,
+          updatedAt: now,
+        })
+        .onConflictDoUpdate({
+          target: [agentMemberships.companyId, agentMemberships.userId, agentMemberships.agentId],
+          set: {
+            state: input.state,
+            updatedAt: now,
+          },
+        })
+        .returning();
+
+      return {
+        resourceType: "agent",
+        resourceId: input.agentId,
+        state: row?.state === "left" ? "left" : "joined",
+        updatedAt: row?.updatedAt ?? now,
+        changed: true,
+        policySource: decision.source ?? "oss_default",
+      };
+    },
+  };
+}
@@ -16,5 +16,6 @@ export { heartbeatsApi } from "./heartbeats";
 export { instanceSettingsApi } from "./instanceSettings";
 export { sidebarBadgesApi } from "./sidebarBadges";
 export { sidebarPreferencesApi } from "./sidebarPreferences";
+export { resourceMembershipsApi } from "./resourceMemberships";
 export { inboxDismissalsApi } from "./inboxDismissals";
 export { companySkillsApi } from "./companySkills";
@@ -0,0 +1,21 @@
+import type {
+  ResourceMemberships,
+  ResourceMembershipUpdateResult,
+  UpdateResourceMembership,
+} from "@paperclipai/shared";
+import { api } from "./client";
+
+export const resourceMembershipsApi = {
+  listMine: (companyId: string) =>
+    api.get<ResourceMemberships>(`/companies/${companyId}/resource-memberships/me`),
+  updateProject: (companyId: string, projectId: string, data: UpdateResourceMembership) =>
+    api.put<ResourceMembershipUpdateResult>(
+      `/companies/${companyId}/resource-memberships/me/projects/${projectId}`,
+      data,
+    ),
+  updateAgent: (companyId: string, agentId: string, data: UpdateResourceMembership) =>
+    api.put<ResourceMembershipUpdateResult>(
+      `/companies/${companyId}/resource-memberships/me/agents/${agentId}`,
+      data,
+    ),
+};
@@ -0,0 +1,26 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it, vi } from "vitest";
+import { EntityRow } from "./EntityRow";
+
+vi.mock("@/lib/router", () => ({
+  Link: ({ children, to, ...props }: React.ComponentProps<"a"> & { to: string }) => (
+    <a href={to} {...props}>
+      {children}
+    </a>
+  ),
+}));
+
+describe("EntityRow", () => {
+  it("keeps caller text color classes on linked rows", () => {
+    const markup = renderToStaticMarkup(
+      <EntityRow
+        title="Left project"
+        to="/projects/left-project"
+        className="group text-foreground/55"
+      />,
+    );
+
+    expect(markup).toContain("text-foreground/55");
+    expect(markup).not.toContain("text-inherit");
+  });
+});
@@ -62,7 +62,7 @@ export function EntityRow({

  if (to) {
    return (
-      <Link to={to} className={cn(classes, "no-underline text-inherit")} onClick={onClick}>
+      <Link to={to} className={cn("no-underline text-inherit", classes)} onClick={onClick}>
        {content}
      </Link>
    );
@@ -0,0 +1,121 @@
+// @vitest-environment jsdom
+
+import type { ReactNode } from "react";
+import { flushSync } from "react-dom";
+import { createRoot } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { MembershipAction } from "./MembershipAction";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+async function act(callback: () => void | Promise<void>) {
+  let result: void | Promise<void> = undefined;
+  flushSync(() => {
+    result = callback();
+  });
+  await result;
+}
+
+describe("MembershipAction", () => {
+  let container: HTMLDivElement;
+  let root: ReturnType<typeof createRoot> | null;
+
+  beforeEach(() => {
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = null;
+  });
+
+  afterEach(async () => {
+    const currentRoot = root;
+    if (currentRoot) {
+      await act(async () => {
+        currentRoot.unmount();
+      });
+    }
+    container.remove();
+    document.body.innerHTML = "";
+  });
+
+  async function renderAction(element: ReactNode) {
+    const currentRoot = createRoot(container);
+    root = currentRoot;
+    await act(async () => {
+      currentRoot.render(element);
+    });
+  }
+
+  function button() {
+    const element = container.querySelector("button");
+    expect(element).not.toBeNull();
+    return element as HTMLButtonElement;
+  }
+
+  it("renders a leave action for joined resources", async () => {
+    await renderAction(
+      <MembershipAction
+        state="joined"
+        resourceName="Growth"
+        onJoin={() => {}}
+        onLeave={() => {}}
+      />,
+    );
+
+    expect(button().getAttribute("aria-label")).toBe("Leave Growth");
+    expect(button().textContent).toContain("Leave");
+  });
+
+  it("renders a join action for left resources", async () => {
+    await renderAction(
+      <MembershipAction
+        state="left"
+        resourceName="Growth"
+        onJoin={() => {}}
+        onLeave={() => {}}
+      />,
+    );
+
+    expect(button().getAttribute("aria-label")).toBe("Join Growth");
+    expect(button().textContent).toContain("Join");
+  });
+
+  it("prevents row navigation when clicked", async () => {
+    const onLeave = vi.fn();
+    const parentClick = vi.fn();
+    await renderAction(
+      <a href="/projects/growth" onClick={parentClick}>
+        <MembershipAction
+          state="joined"
+          resourceName="Growth"
+          onJoin={() => {}}
+          onLeave={onLeave}
+        />
+      </a>,
+    );
+
+    await act(async () => {
+      button().dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }));
+    });
+
+    expect(onLeave).toHaveBeenCalledTimes(1);
+    expect(parentClick).not.toHaveBeenCalled();
+  });
+
+  it("marks pending actions busy and disabled", async () => {
+    await renderAction(
+      <MembershipAction
+        state="left"
+        pending
+        pendingState="joined"
+        resourceName="Growth"
+        onJoin={() => {}}
+        onLeave={() => {}}
+      />,
+    );
+
+    expect(button().getAttribute("aria-busy")).toBe("true");
+    expect(button().disabled).toBe(true);
+    expect(button().textContent).toContain("Joining...");
+  });
+});
@@ -0,0 +1,65 @@
+import type { MouseEvent } from "react";
+import { Loader2, LogIn, LogOut } from "lucide-react";
+import type { ResourceMembershipState } from "@paperclipai/shared";
+import { Button } from "@/components/ui/button";
+import { cn } from "../lib/utils";
+
+interface MembershipActionProps {
+  state: ResourceMembershipState;
+  resourceName: string;
+  pending?: boolean;
+  pendingState?: ResourceMembershipState | null;
+  compact?: boolean;
+  onJoin: () => void;
+  onLeave: () => void;
+}
+
+export function MembershipAction({
+  state,
+  resourceName,
+  pending = false,
+  pendingState = null,
+  compact = false,
+  onJoin,
+  onLeave,
+}: MembershipActionProps) {
+  const isLeft = state === "left";
+  const label = pending
+    ? pendingState === "left" ? "Leaving..." : "Joining..."
+    : isLeft ? "Join" : "Leave";
+  const ariaLabel = `${isLeft ? "Join" : "Leave"} ${resourceName}`;
+  const Icon = pending ? Loader2 : isLeft ? LogIn : LogOut;
+
+  function handleClick(event: MouseEvent<HTMLButtonElement>) {
+    event.preventDefault();
+    event.stopPropagation();
+    if (pending) return;
+    if (isLeft) onJoin();
+    else onLeave();
+  }
+
+  return (
+    <span
+      className={cn(
+        "flex w-[66px] shrink-0 justify-end",
+        !isLeft && !compact
+          ? "opacity-100 sm:opacity-0 sm:transition-opacity sm:group-hover:opacity-100 sm:group-focus-within:opacity-100"
+          : "opacity-100",
+      )}
+    >
+      <Button
+        type="button"
+        size="xs"
+        variant="ghost"
+        aria-label={ariaLabel}
+        aria-busy={pending ? "true" : undefined}
+        disabled={pending}
+        onClick={handleClick}
+        className="w-[66px]"
+      >
+        <Icon className={cn("h-3 w-3", pending && "motion-safe:animate-spin")} />
+        <span>{label}</span>
+      </Button>
+    </span>
+  );
+}
@@ -1,10 +1,10 @@
 // @vitest-environment jsdom

-import { act } from "react";
 import type { ReactNode } from "react";
+import { flushSync } from "react-dom";
 import { createRoot } from "react-dom/client";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
-import type { Agent } from "@paperclipai/shared";
+import type { Agent, ResourceMemberships } from "@paperclipai/shared";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { SidebarAgents } from "./SidebarAgents";

@@ -22,6 +22,11 @@ const mockHeartbeatsApi = vi.hoisted(() => ({
  liveRunsForCompany: vi.fn(),
 }));

+const mockResourceMembershipsApi = vi.hoisted(() => ({
+  listMine: vi.fn(),
+  updateAgent: vi.fn(),
+}));
+
 const mockOpenNewAgent = vi.hoisted(() => vi.fn());
 const mockPushToast = vi.hoisted(() => vi.fn());
 const mockSetSidebarOpen = vi.hoisted(() => vi.fn());
@@ -91,6 +96,10 @@ vi.mock("../api/heartbeats", () => ({
  heartbeatsApi: mockHeartbeatsApi,
 }));

+vi.mock("../api/resourceMemberships", () => ({
+  resourceMembershipsApi: mockResourceMembershipsApi,
+}));
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 (globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;

@@ -99,6 +108,14 @@ if (!globalThis.PointerEvent) {
  (globalThis as any).PointerEvent = MouseEvent;
 }

+async function act(callback: () => void | Promise<void>) {
+  let result: void | Promise<void> = undefined;
+  flushSync(() => {
+    result = callback();
+  });
+  await result;
+}
+
 function makeAgent(overrides: Partial<Agent>): Agent {
  return {
    id: "agent-1",
@@ -177,6 +194,7 @@ describe("SidebarAgents", () => {
  let container: HTMLDivElement;
  let root: ReturnType<typeof createRoot> | null;
  let queryClient: QueryClient;
+  let memberships: ResourceMemberships;

  beforeEach(() => {
    container = document.createElement("div");
@@ -193,6 +211,27 @@ describe("SidebarAgents", () => {
      user: { id: "user-1" },
    });
    mockHeartbeatsApi.liveRunsForCompany.mockResolvedValue([]);
+    memberships = {
+      projectMemberships: {},
+      agentMemberships: {},
+      updatedAt: null,
+    };
+    mockResourceMembershipsApi.listMine.mockImplementation(() => Promise.resolve(memberships));
+    mockResourceMembershipsApi.updateAgent.mockImplementation((_companyId, agentId, data) => {
+      memberships = {
+        ...memberships,
+        agentMemberships: {
+          ...memberships.agentMemberships,
+          [agentId]: data.state,
+        },
+        updatedAt: new Date(),
+      };
+      return Promise.resolve({
+        resourceType: "agent",
+        resourceId: agentId,
+        state: data.state,
+      });
+    });
    localStorage.clear();
  });

@@ -311,6 +350,31 @@ describe("SidebarAgents", () => {
    expect(agentLinkLabels(container)).toEqual(["Bravo", "Charlie", "Alpha"]);
  });

+  it("filters left agents only after membership state loads", async () => {
+    mockAgentsApi.list.mockResolvedValue([
+      makeAgent({ id: "agent-1", name: "Alpha", urlKey: "alpha" }),
+      makeAgent({ id: "agent-2", name: "Beta", urlKey: "beta" }),
+    ]);
+    let resolveMemberships!: (value: unknown) => void;
+    mockResourceMembershipsApi.listMine.mockReturnValue(new Promise((resolve) => {
+      resolveMemberships = resolve;
+    }));
+
+    await renderSidebarAgents();
+    expect(agentLinkLabels(container)).toEqual(["Alpha", "Beta"]);
+
+    await act(async () => {
+      resolveMemberships({
+        projectMemberships: {},
+        agentMemberships: { "agent-1": "left" },
+        updatedAt: null,
+      });
+    });
+    await flushReact();
+
+    expect(agentLinkLabels(container)).toEqual(["Beta"]);
+  });
+
  it("shows edit and pause actions for an active sidebar agent", async () => {
    await renderSidebarAgents();
    await openAgentMenu();
@@ -333,6 +397,27 @@ describe("SidebarAgents", () => {
    expect(mockPushToast).toHaveBeenCalledWith(expect.objectContaining({ title: "Agent paused" }));
  });

+  it("offers leave agent from each sidebar agent menu", async () => {
+    await renderSidebarAgents();
+    await openAgentMenu();
+
+    const leaveItem = Array.from(document.body.querySelectorAll('[data-slot="dropdown-menu-item"]'))
+      .find((element) => element.textContent?.includes("Leave agent"));
+    expect(leaveItem).toBeTruthy();
+
+    await act(async () => {
+      leaveItem?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    });
+    await flushReact();
+
+    expect(mockResourceMembershipsApi.updateAgent).toHaveBeenCalledWith(
+      "company-1",
+      "agent-1",
+      { state: "left" },
+    );
+    expect(agentLinkLabels(container)).toEqual([]);
+  });
+
  it("shows resume for paused sidebar agents", async () => {
    mockAgentsApi.list.mockResolvedValue([
      makeAgent({ status: "paused", pauseReason: "manual", pausedAt: new Date("2026-01-02T00:00:00Z") }),
@@ -3,6 +3,8 @@ import { Link, NavLink, useLocation } from "@/lib/router";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import {
  MoreHorizontal,
+  Loader2,
+  LogOut,
  PauseCircle,
  Pencil,
  PlayCircle,
@@ -20,6 +22,7 @@ import { SIDEBAR_SCROLL_RESET_STATE } from "../lib/navigation-scroll";
 import { queryKeys } from "../lib/queryKeys";
 import { cn, agentRouteRef, agentUrl } from "../lib/utils";
 import { useAgentOrder } from "../hooks/useAgentOrder";
+import { resourceMembershipState, useResourceMembershipMutation, useResourceMemberships } from "../hooks/useResourceMemberships";
 import {
  AGENT_SORT_MODE_UPDATED_EVENT,
  getAgentSortModeStorageKey,
@@ -82,6 +85,8 @@ function SidebarAgentItem({
  agent,
  disabled,
  isMobile,
+  leaving,
+  onLeaveAgent,
  onPauseResume,
  runCount,
  setSidebarOpen,
@@ -91,6 +96,8 @@ function SidebarAgentItem({
  agent: Agent;
  disabled: boolean;
  isMobile: boolean;
+  leaving: boolean;
+  onLeaveAgent: (agent: Agent) => void;
  onPauseResume: (agent: Agent, action: "pause" | "resume") => void;
  runCount: number;
  setSidebarOpen: (open: boolean) => void;
@@ -186,6 +193,17 @@ function SidebarAgentItem({
            {isPaused ? <PlayCircle className="size-4" /> : <PauseCircle className="size-4" />}
            <span>{pauseResumeDisabledLabel}</span>
          </DropdownMenuItem>
+          <DropdownMenuSeparator />
+          <DropdownMenuItem
+            onClick={() => {
+              if (leaving) return;
+              onLeaveAgent(agent);
+            }}
+            disabled={leaving}
+          >
+            {leaving ? <Loader2 className="size-4 motion-safe:animate-spin" /> : <LogOut className="size-4" />}
+            <span>{leaving ? "Leaving..." : "Leave agent"}</span>
+          </DropdownMenuItem>
        </DropdownMenuContent>
      </DropdownMenu>
    </div>
@@ -211,6 +229,8 @@ export function SidebarAgents() {
    queryKey: queryKeys.auth.session,
    queryFn: () => authApi.getSession(),
  });
+  const membershipsQuery = useResourceMemberships(selectedCompanyId);
+  const membershipMutation = useResourceMembershipMutation(selectedCompanyId);

  const { data: liveRuns } = useQuery({
    queryKey: queryKeys.liveRuns(selectedCompanyId!),
@@ -229,10 +249,15 @@ export function SidebarAgents() {

  const visibleAgents = useMemo(() => {
    const filtered = (agents ?? []).filter(
-      (a: Agent) => a.status !== "terminated"
+      (a: Agent) =>
+        a.status !== "terminated" &&
+        (
+          !membershipsQuery.isSuccess ||
+          resourceMembershipState(membershipsQuery.data, "agent", a.id) !== "left"
+        )
    );
    return filtered;
-  }, [agents]);
+  }, [agents, membershipsQuery.data, membershipsQuery.isSuccess]);
  const currentUserId = session?.user?.id ?? session?.session?.userId ?? null;
  const sortModeStorageKey = useMemo(() => {
    if (!selectedCompanyId) return null;
@@ -343,6 +368,23 @@ export function SidebarAgents() {
    },
  });

+  const leaveAgent = useCallback(
+    (agent: Agent) => membershipMutation.mutate({
+      resourceType: "agent",
+      resourceId: agent.id,
+      resourceName: agent.name,
+      state: "left",
+    }),
+    [membershipMutation],
+  );
+  const agentLeaving = useCallback(
+    (agent: Agent) =>
+      membershipMutation.isPending &&
+      membershipMutation.variables?.resourceType === "agent" &&
+      membershipMutation.variables.resourceId === agent.id,
+    [membershipMutation.isPending, membershipMutation.variables],
+  );
+
  return (
    <SidebarSection
      label="Agents"
@@ -374,6 +416,8 @@ export function SidebarAgents() {
            agent={agent}
            disabled={pendingAgentIds.has(agent.id)}
            isMobile={isMobile}
+            leaving={agentLeaving(agent)}
+            onLeaveAgent={leaveAgent}
            onPauseResume={(targetAgent, action) => pauseResumeAgent.mutate({ agent: targetAgent, action })}
            runCount={runCount}
            setSidebarOpen={setSidebarOpen}
@@ -1,10 +1,10 @@
 // @vitest-environment jsdom

-import { act } from "react";
 import type { ReactNode } from "react";
+import { flushSync } from "react-dom";
 import { createRoot } from "react-dom/client";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
-import type { Project } from "@paperclipai/shared";
+import type { Project, ResourceMemberships } from "@paperclipai/shared";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { SidebarProjects } from "./SidebarProjects";

@@ -16,7 +16,13 @@ const mockAuthApi = vi.hoisted(() => ({
  getSession: vi.fn(),
 }));

+const mockResourceMembershipsApi = vi.hoisted(() => ({
+  listMine: vi.fn(),
+  updateProject: vi.fn(),
+}));
+
 const mockOpenNewProject = vi.hoisted(() => vi.fn());
+const mockPushToast = vi.hoisted(() => vi.fn());
 const mockSetSidebarOpen = vi.hoisted(() => vi.fn());
 const mockPersistOrder = vi.hoisted(() => vi.fn());
 const mockSidebarState = vi.hoisted(() => ({ isMobile: false }));
@@ -70,6 +76,12 @@ vi.mock("../context/SidebarContext", () => ({
  }),
 }));

+vi.mock("../context/ToastContext", () => ({
+  useToastActions: () => ({
+    pushToast: mockPushToast,
+  }),
+}));
+
 vi.mock("../api/projects", () => ({
  projectsApi: mockProjectsApi,
 }));
@@ -78,6 +90,10 @@ vi.mock("../api/auth", () => ({
  authApi: mockAuthApi,
 }));

+vi.mock("../api/resourceMemberships", () => ({
+  resourceMembershipsApi: mockResourceMembershipsApi,
+}));
+
 vi.mock("../hooks/useProjectOrder", () => ({
  useProjectOrder: ({ projects }: { projects: Project[] }) => {
    const curatedOrder = ["project-b", "project-a", "project-c"];
@@ -107,6 +123,14 @@ if (!globalThis.PointerEvent) {
  (globalThis as any).PointerEvent = MouseEvent;
 }

+async function act(callback: () => void | Promise<void>) {
+  let result: void | Promise<void> = undefined;
+  flushSync(() => {
+    result = callback();
+  });
+  await result;
+}
+
 function makeProject(overrides: Partial<Project>): Project {
  return {
    id: "project-a",
@@ -170,6 +194,17 @@ async function openProjectsMenu(container: HTMLElement) {
  await flushReact();
 }

+async function openProjectMenu(label = "Open actions for Alpha") {
+  const trigger = document.body.querySelector(`button[aria-label="${label}"]`);
+  expect(trigger).not.toBeNull();
+
+  await act(async () => {
+    trigger?.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true, button: 0 }));
+    trigger?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+  });
+  await flushReact();
+}
+
 async function chooseSortMode(label: string) {
  const item = Array.from(document.body.querySelectorAll('[data-slot="dropdown-menu-radio-item"]'))
    .find((element) => element.textContent?.includes(label));
@@ -185,6 +220,7 @@ describe("SidebarProjects", () => {
  let container: HTMLDivElement;
  let root: ReturnType<typeof createRoot> | null;
  let queryClient: QueryClient;
+  let memberships: ResourceMemberships;

  beforeEach(() => {
    container = document.createElement("div");
@@ -238,6 +274,27 @@ describe("SidebarProjects", () => {
      session: { id: "session-1", userId: "user-1" },
      user: { id: "user-1" },
    });
+    memberships = {
+      projectMemberships: {},
+      agentMemberships: {},
+      updatedAt: null,
+    };
+    mockResourceMembershipsApi.listMine.mockImplementation(() => Promise.resolve(memberships));
+    mockResourceMembershipsApi.updateProject.mockImplementation((_companyId, projectId, data) => {
+      memberships = {
+        ...memberships,
+        projectMemberships: {
+          ...memberships.projectMemberships,
+          [projectId]: data.state,
+        },
+        updatedAt: new Date(),
+      };
+      return Promise.resolve({
+        resourceType: "project",
+        resourceId: projectId,
+        state: data.state,
+      });
+    });
  });

  afterEach(async () => {
@@ -334,4 +391,46 @@ describe("SidebarProjects", () => {

    expect(projectLinkLabels(container)).toEqual(["Charlie", "Bravo", "Alpha"]);
  });
+
+  it("filters left projects only after membership state loads", async () => {
+    let resolveMemberships!: (value: unknown) => void;
+    mockResourceMembershipsApi.listMine.mockReturnValue(new Promise((resolve) => {
+      resolveMemberships = resolve;
+    }));
+
+    await renderSidebarProjects();
+    expect(projectLinkLabels(container)).toEqual(["Bravo", "Alpha", "Charlie"]);
+
+    await act(async () => {
+      resolveMemberships({
+        projectMemberships: { "project-a": "left" },
+        agentMemberships: {},
+        updatedAt: null,
+      });
+    });
+    await flushReact();
+
+    expect(projectLinkLabels(container)).toEqual(["Bravo", "Charlie"]);
+  });
+
+  it("offers leave project from each sidebar project menu", async () => {
+    await renderSidebarProjects();
+    await openProjectMenu();
+
+    const leaveItem = Array.from(document.body.querySelectorAll('[data-slot="dropdown-menu-item"]'))
+      .find((element) => element.textContent?.includes("Leave project"));
+    expect(leaveItem).toBeTruthy();
+
+    await act(async () => {
+      leaveItem?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    });
+    await flushReact();
+
+    expect(mockResourceMembershipsApi.updateProject).toHaveBeenCalledWith(
+      "company-1",
+      "project-a",
+      { state: "left" },
+    );
+    expect(projectLinkLabels(container)).toEqual(["Bravo", "Charlie"]);
+  });
 });
@@ -1,7 +1,7 @@
 import { useCallback, useEffect, useMemo, useState } from "react";
 import { NavLink, useLocation } from "@/lib/router";
 import { useQuery } from "@tanstack/react-query";
-import { FolderOpen, Plus } from "lucide-react";
+import { FolderOpen, Loader2, LogOut, MoreHorizontal, Plus } from "lucide-react";
 import {
  DndContext,
  MouseSensor,
@@ -21,8 +21,16 @@ import { SIDEBAR_SCROLL_RESET_STATE } from "../lib/navigation-scroll";
 import { queryKeys } from "../lib/queryKeys";
 import { cn, projectRouteRef } from "../lib/utils";
 import { useProjectOrder } from "../hooks/useProjectOrder";
+import { resourceMembershipState, useResourceMembershipMutation, useResourceMemberships } from "../hooks/useResourceMemberships";
 import { BudgetSidebarMarker } from "./BudgetSidebarMarker";
 import { SidebarSection, type SidebarSectionRadioChoice } from "./SidebarSection";
+import { Button } from "@/components/ui/button";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
 import { PluginSlotMount, usePluginSlots } from "@/plugins/slots";
 import {
  getProjectSortModeStorageKey,
@@ -51,6 +59,8 @@ type ProjectItemProps = {
  project: Project;
  projectSidebarSlots: ProjectSidebarSlot[];
  setSidebarOpen: (open: boolean) => void;
+  onLeaveProject: (project: Project) => void;
+  leaving?: boolean;
  isDragging?: boolean;
 };

@@ -103,36 +113,70 @@ function ProjectItem({
  project,
  projectSidebarSlots,
  setSidebarOpen,
+  onLeaveProject,
+  leaving = false,
  isDragging = false,
 }: ProjectItemProps) {
  const routeRef = projectRouteRef(project);

  return (
    <div className="flex flex-col gap-0.5">
-      <NavLink
-        to={`/projects/${routeRef}/issues`}
-        state={SIDEBAR_SCROLL_RESET_STATE}
-        onClick={(e) => {
-          if (isDragging) {
-            e.preventDefault();
-            return;
-          }
-          if (isMobile) setSidebarOpen(false);
-        }}
-        className={cn(
-          "flex items-center gap-2.5 px-3 py-1.5 pointer-coarse:py-1 text-[13px] font-medium transition-colors",
-          activeProjectRef === routeRef || activeProjectRef === project.id
-            ? "bg-accent text-foreground"
-            : "text-foreground/80 hover:bg-accent/50 hover:text-foreground",
-        )}
-      >
-        <span
-          className="shrink-0 h-3.5 w-3.5 rounded-sm"
-          style={{ backgroundColor: project.color ?? "#6366f1" }}
-        />
-        <span className="flex-1 truncate">{project.name}</span>
-        {project.pauseReason === "budget" ? <BudgetSidebarMarker title="Project paused by budget" /> : null}
-      </NavLink>
+      <div className="group/project relative flex items-center">
+        <NavLink
+          to={`/projects/${routeRef}/issues`}
+          state={SIDEBAR_SCROLL_RESET_STATE}
+          onClick={(e) => {
+            if (isDragging) {
+              e.preventDefault();
+              return;
+            }
+            if (isMobile) setSidebarOpen(false);
+          }}
+          className={cn(
+            "flex min-w-0 flex-1 items-center gap-2.5 px-3 py-1.5 pr-8 pointer-coarse:py-1 text-[13px] font-medium transition-colors",
+            activeProjectRef === routeRef || activeProjectRef === project.id
+              ? "bg-accent text-foreground"
+              : "text-foreground/80 hover:bg-accent/50 hover:text-foreground",
+          )}
+        >
+          <span
+            className="shrink-0 h-3.5 w-3.5 rounded-sm"
+            style={{ backgroundColor: project.color ?? "#6366f1" }}
+          />
+          <span className="flex-1 truncate">{project.name}</span>
+          {project.pauseReason === "budget" ? <BudgetSidebarMarker title="Project paused by budget" /> : null}
+        </NavLink>
+
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <Button
+              variant="ghost"
+              size="icon-xs"
+              className={cn(
+                "absolute right-1 top-1/2 h-6 w-6 -translate-y-1/2 transition-opacity data-[state=open]:pointer-events-auto data-[state=open]:opacity-100",
+                isMobile
+                  ? "opacity-100"
+                  : "pointer-events-none opacity-0 group-hover/project:pointer-events-auto group-hover/project:opacity-100 group-focus-within/project:pointer-events-auto group-focus-within/project:opacity-100",
+              )}
+              aria-label={`Open actions for ${project.name}`}
+            >
+              <MoreHorizontal className="h-3.5 w-3.5" />
+            </Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end" className="w-44">
+            <DropdownMenuItem
+              onClick={() => {
+                if (leaving) return;
+                onLeaveProject(project);
+              }}
+              disabled={leaving}
+            >
+              {leaving ? <Loader2 className="size-4 motion-safe:animate-spin" /> : <LogOut className="size-4" />}
+              <span>{leaving ? "Leaving..." : "Leave project"}</span>
+            </DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+      </div>
      {projectSidebarSlots.length > 0 && (
        <div className="ml-5 flex flex-col gap-0.5">
          {projectSidebarSlots.map((slot) => (
@@ -196,6 +240,8 @@ export function SidebarProjects() {
    queryFn: () => projectsApi.list(selectedCompanyId!),
    enabled: !!selectedCompanyId,
  });
+  const membershipsQuery = useResourceMemberships(selectedCompanyId);
+  const membershipMutation = useResourceMembershipMutation(selectedCompanyId);
  const { data: session } = useQuery({
    queryKey: queryKeys.auth.session,
    queryFn: () => authApi.getSession(),
@@ -218,8 +264,12 @@ export function SidebarProjects() {
  });

  const visibleProjects = useMemo(
-    () => (projects ?? []).filter((project: Project) => !project.archivedAt),
-    [projects],
+    () => (projects ?? []).filter((project: Project) => {
+      if (project.archivedAt) return false;
+      if (!membershipsQuery.isSuccess) return true;
+      return resourceMembershipState(membershipsQuery.data, "project", project.id) !== "left";
+    }),
+    [membershipsQuery.data, membershipsQuery.isSuccess, projects],
  );
  const { orderedProjects, persistOrder } = useProjectOrder({
    projects: visibleProjects,
@@ -299,6 +349,23 @@ export function SidebarProjects() {
    [isTopMode, orderedProjects, persistOrder],
  );

+  const leaveProject = useCallback(
+    (project: Project) => membershipMutation.mutate({
+      resourceType: "project",
+      resourceId: project.id,
+      resourceName: project.name,
+      state: "left",
+    }),
+    [membershipMutation],
+  );
+  const projectLeaving = useCallback(
+    (project: Project) =>
+      membershipMutation.isPending &&
+      membershipMutation.variables?.resourceType === "project" &&
+      membershipMutation.variables.resourceId === project.id,
+    [membershipMutation.isPending, membershipMutation.variables],
+  );
+
  const renderProject = (project: Project) => (
    <ProjectItem
      key={project.id}
@@ -309,6 +376,8 @@ export function SidebarProjects() {
      project={project}
      projectSidebarSlots={projectSidebarSlots}
      setSidebarOpen={setSidebarOpen}
+      onLeaveProject={leaveProject}
+      leaving={projectLeaving(project)}
    />
  );

@@ -354,6 +423,8 @@ export function SidebarProjects() {
                  project={project}
                  projectSidebarSlots={projectSidebarSlots}
                  setSidebarOpen={setSidebarOpen}
+                  onLeaveProject={leaveProject}
+                  leaving={projectLeaving(project)}
                />
              ))}
            </div>
@@ -652,6 +652,14 @@ function invalidateActivityQueries(
  const action = readString(payload.action);
  const actorType = readString(payload.actorType);
  const actorId = readString(payload.actorId);
+  const details = readRecord(payload.details);
+
+  if (action?.startsWith("resource_membership.")) {
+    const targetUserId = readString(details?.userId);
+    if (!targetUserId || targetUserId === currentActor.userId) {
+      queryClient.invalidateQueries({ queryKey: queryKeys.resourceMemberships.mine(companyId) });
+    }
+  }

  if (entityType === "issue") {
    queryClient.invalidateQueries({ queryKey: queryKeys.issues.list(companyId) });
@@ -659,7 +667,6 @@ function invalidateActivityQueries(
    queryClient.invalidateQueries({ queryKey: queryKeys.issues.listTouchedByMe(companyId) });
    queryClient.invalidateQueries({ queryKey: queryKeys.issues.listUnreadTouchedByMe(companyId) });
    if (entityId) {
-      const details = readRecord(payload.details);
      const selfCommentActivity =
        ((action === "issue.comment_added") ||
          (action === "issue.updated" && readString(details?.source) === "comment")) &&
@@ -0,0 +1,114 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import type {
+  ResourceMembershipResourceType,
+  ResourceMembershipState,
+  ResourceMemberships,
+} from "@paperclipai/shared";
+import { resourceMembershipsApi } from "../api/resourceMemberships";
+import { useToastActions } from "../context/ToastContext";
+import { queryKeys } from "../lib/queryKeys";
+
+type MutationVariables = {
+  resourceType: ResourceMembershipResourceType;
+  resourceId: string;
+  resourceName: string;
+  state: ResourceMembershipState;
+};
+
+function emptyMemberships(): ResourceMemberships {
+  return {
+    projectMemberships: {},
+    agentMemberships: {},
+    updatedAt: null,
+  };
+}
+
+function applyMembershipState(
+  current: ResourceMemberships | undefined,
+  resourceType: ResourceMembershipResourceType,
+  resourceId: string,
+  state: ResourceMembershipState,
+): ResourceMemberships {
+  const base = current ?? emptyMemberships();
+  if (resourceType === "project") {
+    return {
+      ...base,
+      projectMemberships: {
+        ...base.projectMemberships,
+        [resourceId]: state,
+      },
+      updatedAt: new Date(),
+    };
+  }
+  return {
+    ...base,
+    agentMemberships: {
+      ...base.agentMemberships,
+      [resourceId]: state,
+    },
+    updatedAt: new Date(),
+  };
+}
+
+export function resourceMembershipState(
+  memberships: ResourceMemberships | undefined,
+  resourceType: ResourceMembershipResourceType,
+  resourceId: string,
+): ResourceMembershipState {
+  const state = resourceType === "project"
+    ? memberships?.projectMemberships[resourceId]
+    : memberships?.agentMemberships[resourceId];
+  return state === "left" ? "left" : "joined";
+}
+
+export function useResourceMemberships(companyId: string | null | undefined) {
+  return useQuery({
+    queryKey: queryKeys.resourceMemberships.mine(companyId ?? "__none__"),
+    queryFn: () => resourceMembershipsApi.listMine(companyId!),
+    enabled: !!companyId,
+  });
+}
+
+export function useResourceMembershipMutation(companyId: string | null | undefined) {
+  const queryClient = useQueryClient();
+  const { pushToast } = useToastActions();
+  const queryKey = queryKeys.resourceMemberships.mine(companyId ?? "__none__");
+
+  return useMutation({
+    mutationFn: (variables: MutationVariables) => {
+      if (!companyId) throw new Error("Select a company first.");
+      return variables.resourceType === "project"
+        ? resourceMembershipsApi.updateProject(companyId, variables.resourceId, { state: variables.state })
+        : resourceMembershipsApi.updateAgent(companyId, variables.resourceId, { state: variables.state });
+    },
+    onMutate: async (variables) => {
+      await queryClient.cancelQueries({ queryKey });
+      const previous = queryClient.getQueryData<ResourceMemberships>(queryKey);
+      queryClient.setQueryData<ResourceMemberships>(
+        queryKey,
+        applyMembershipState(previous, variables.resourceType, variables.resourceId, variables.state),
+      );
+      return { previous };
+    },
+    onError: (error, variables, context) => {
+      if (context?.previous) {
+        queryClient.setQueryData(queryKey, context.previous);
+      }
+      const verb = variables.state === "left" ? "leave" : "join";
+      pushToast({
+        title: `Couldn't ${verb} ${variables.resourceName}.`,
+        body: error instanceof Error ? error.message : "Try again.",
+        tone: "error",
+      });
+    },
+    onSuccess: (result, variables) => {
+      queryClient.setQueryData<ResourceMemberships>(
+        queryKey,
+        (current) => applyMembershipState(current, variables.resourceType, result.resourceId, result.state),
+      );
+    },
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey });
+    },
+  });
+}
@@ -128,6 +128,9 @@ export const queryKeys = {
    projectOrder: (companyId: string, userId: string) =>
      ["sidebar-preferences", "project-order", companyId, userId] as const,
  },
+  resourceMemberships: {
+    mine: (companyId: string) => ["resource-memberships", companyId, "me"] as const,
+  },
  instance: {
    generalSettings: ["instance", "general-settings"] as const,
    schedulerHeartbeats: ["instance", "scheduler-heartbeats"] as const,
@@ -36,6 +36,7 @@ import { agentStatusDot, agentStatusDotDefault } from "../lib/status-colors";
 import { MarkdownBody } from "../components/MarkdownBody";
 import { CopyText } from "../components/CopyText";
 import { EntityRow } from "../components/EntityRow";
+import { MembershipAction } from "../components/MembershipAction";
 import { Identity } from "../components/Identity";
 import { PageSkeleton } from "../components/PageSkeleton";
 import { RunButton, PauseResumeButton } from "../components/AgentActionButtons";
@@ -102,6 +103,11 @@ import {
 } from "@paperclipai/shared";
 import { redactHomePathUserSegments, redactHomePathUserSegmentsInValue } from "@paperclipai/adapter-utils";
 import { agentRouteRef } from "../lib/utils";
+import {
+  resourceMembershipState,
+  useResourceMembershipMutation,
+  useResourceMemberships,
+} from "../hooks/useResourceMemberships";
 import {
  applyAgentSkillSnapshot,
  arraysEqual,
@@ -675,6 +681,7 @@ export function AgentDetail() {
  const queryClient = useQueryClient();
  const navigate = useNavigate();
  const [actionError, setActionError] = useState<string | null>(null);
+  const [dismissedLeftAgentIds, setDismissedLeftAgentIds] = useState<Set<string>>(() => new Set());
  const [moreOpen, setMoreOpen] = useState(false);
  const activeView = urlRunId ? "runs" as AgentDetailView : parseAgentDetailView(urlTab ?? null);
  const needsDashboardData = activeView === "dashboard";
@@ -705,6 +712,11 @@ export function AgentDetail() {
  const canonicalAgentRef = agent ? agentRouteRef(agent) : routeAgentRef;
  const agentLookupRef = agent?.id ?? routeAgentRef;
  const resolvedAgentId = agent?.id ?? null;
+  const membershipsQuery = useResourceMemberships(resolvedCompanyId);
+  const membershipMutation = useResourceMembershipMutation(resolvedCompanyId);
+  const agentMembershipState = resolvedAgentId
+    ? resourceMembershipState(membershipsQuery.data, "agent", resolvedAgentId)
+    : "joined";

  const { data: runtimeState } = useQuery({
    queryKey: queryKeys.agents.runtimeState(resolvedAgentId ?? routeAgentRef),
@@ -984,6 +996,16 @@ export function AgentDetail() {
    return () => closePanel();
  }, [closePanel]);

+  useEffect(() => {
+    if (!resolvedAgentId || agentMembershipState !== "joined") return;
+    setDismissedLeftAgentIds((current) => {
+      if (!current.has(resolvedAgentId)) return current;
+      const next = new Set(current);
+      next.delete(resolvedAgentId);
+      return next;
+    });
+  }, [resolvedAgentId, agentMembershipState]);
+
  useBeforeUnload(
    useCallback((event) => {
      if (!configDirty) return;
@@ -1000,9 +1022,48 @@ export function AgentDetail() {
  }
  const isPendingApproval = agent.status === "pending_approval";
  const showConfigActionBar = (activeView === "configuration" || activeView === "instructions") && (configDirty || configSaving);
+  const showLeftAgentNotice = agentMembershipState === "left" && !dismissedLeftAgentIds.has(agent.id);
+  const agentMembershipPending =
+    membershipMutation.isPending &&
+    membershipMutation.variables?.resourceType === "agent" &&
+    membershipMutation.variables.resourceId === agent.id;

  return (
    <div className={cn("space-y-6", isMobile && showConfigActionBar && "pb-24")}>
+      {showLeftAgentNotice ? (
+        <div className="flex items-center gap-3 border border-yellow-300/35 bg-yellow-300/10 px-3 py-2 text-sm text-yellow-100">
+          <p className="min-w-0 flex-1">
+            You left this agent. It no longer appears in your sidebar.
+          </p>
+          <MembershipAction
+            compact
+            state="left"
+            pending={agentMembershipPending}
+            pendingState={agentMembershipPending ? membershipMutation.variables?.state : null}
+            resourceName={agent.name}
+            onJoin={() => membershipMutation.mutate({
+              resourceType: "agent",
+              resourceId: agent.id,
+              resourceName: agent.name,
+              state: "joined",
+            })}
+            onLeave={() => membershipMutation.mutate({
+              resourceType: "agent",
+              resourceId: agent.id,
+              resourceName: agent.name,
+              state: "left",
+            })}
+          />
+          <button
+            type="button"
+            className="h-6 w-6 shrink-0 text-yellow-100/70 hover:text-yellow-100"
+            aria-label="Dismiss agent membership notice"
+            onClick={() => setDismissedLeftAgentIds((current) => new Set(current).add(agent.id))}
+          >
+            ×
+          </button>
+        </div>
+      ) : null}
      {/* Header */}
      <div className="flex items-center justify-between gap-2">
        <div className="flex items-center gap-3 min-w-0">
@@ -1,11 +1,12 @@
 // @vitest-environment jsdom

-import { act } from "react";
 import type { ReactNode } from "react";
+import { flushSync } from "react-dom";
 import { createRoot } from "react-dom/client";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import type { Agent } from "@paperclipai/shared";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { ToastProvider } from "../context/ToastContext";
 import { Agents } from "./Agents";

 const mockAgentsApi = vi.hoisted(() => ({
@@ -17,6 +18,11 @@ const mockHeartbeatsApi = vi.hoisted(() => ({
  liveRunsForCompany: vi.fn(),
 }));

+const mockResourceMembershipsApi = vi.hoisted(() => ({
+  listMine: vi.fn(),
+  updateAgent: vi.fn(),
+}));
+
 const mockOpenNewAgent = vi.hoisted(() => vi.fn());
 const mockSetBreadcrumbs = vi.hoisted(() => vi.fn());

@@ -52,6 +58,10 @@ vi.mock("../api/heartbeats", () => ({
  heartbeatsApi: mockHeartbeatsApi,
 }));

+vi.mock("../api/resourceMemberships", () => ({
+  resourceMembershipsApi: mockResourceMembershipsApi,
+}));
+
 vi.mock("../adapters/adapter-display-registry", () => ({
  getAdapterLabel: (type: string) => type,
 }));
@@ -59,6 +69,14 @@ vi.mock("../adapters/adapter-display-registry", () => ({
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 (globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;

+async function act(callback: () => void | Promise<void>) {
+  let result: void | Promise<void> = undefined;
+  flushSync(() => {
+    result = callback();
+  });
+  await result;
+}
+
 function makeAgent(overrides: Partial<Agent>): Agent {
  return {
    id: "agent-1",
@@ -120,6 +138,17 @@ describe("Agents", () => {
      },
    ]);
    mockHeartbeatsApi.liveRunsForCompany.mockResolvedValue([]);
+    mockResourceMembershipsApi.listMine.mockResolvedValue({
+      projectMemberships: {},
+      agentMemberships: {},
+      updatedAt: null,
+    });
+    mockResourceMembershipsApi.updateAgent.mockResolvedValue({
+      resourceType: "agent",
+      resourceId: "agent-1",
+      state: "left",
+      updatedAt: new Date("2026-01-02T00:00:00Z"),
+    });
  });

  afterEach(async () => {
@@ -140,7 +169,9 @@ describe("Agents", () => {
    await act(async () => {
      root!.render(
        <QueryClientProvider client={queryClient}>
-          <Agents />
+          <ToastProvider>
+            <Agents />
+          </ToastProvider>
        </QueryClientProvider>,
      );
    });
@@ -9,6 +9,7 @@ import { useBreadcrumbs } from "../context/BreadcrumbContext";
 import { useSidebar } from "../context/SidebarContext";
 import { queryKeys } from "../lib/queryKeys";
 import { StatusBadge } from "../components/StatusBadge";
+import { MembershipAction } from "../components/MembershipAction";
 import { agentStatusDot, agentStatusDotDefault } from "../lib/status-colors";
 import { EntityRow } from "../components/EntityRow";
 import { EmptyState } from "../components/EmptyState";
@@ -19,6 +20,11 @@ import { Tabs } from "@/components/ui/tabs";
 import { Button } from "@/components/ui/button";
 import { Bot, Plus, List, GitBranch, SlidersHorizontal } from "lucide-react";
 import { AGENT_ROLE_LABELS, type Agent } from "@paperclipai/shared";
+import {
+  resourceMembershipState,
+  useResourceMembershipMutation,
+  useResourceMemberships,
+} from "../hooks/useResourceMemberships";

 import { getAdapterLabel } from "../adapters/adapter-display-registry";

@@ -93,6 +99,8 @@ export function Agents() {
    enabled: !!selectedCompanyId,
    refetchInterval: 15_000,
  });
+  const membershipsQuery = useResourceMemberships(selectedCompanyId);
+  const membershipMutation = useResourceMembershipMutation(selectedCompanyId);

  // Map agentId -> first live run + live run count
  const liveRunByAgent = useMemo(() => {
@@ -231,7 +239,11 @@ export function Agents() {
                title={agent.name}
                subtitle={`${roleLabels[agent.role] ?? agent.role}${agent.title ? ` - ${agent.title}` : ""}`}
                to={agentUrl(agent)}
-                className={agent.pausedAt && tab !== "paused" ? "opacity-50" : ""}
+                className={cn(
+                  "group",
+                  agent.pausedAt && tab !== "paused" ? "opacity-50" : "",
+                  resourceMembershipState(membershipsQuery.data, "agent", agent.id) === "left" ? "text-foreground/55" : "",
+                )}
                leading={
                  <span className="relative flex h-2.5 w-2.5">
                    <span
@@ -276,6 +288,34 @@ export function Agents() {
                        <StatusBadge status={agent.status} />
                      </span>
                    </div>
+                    <MembershipAction
+                      state={resourceMembershipState(membershipsQuery.data, "agent", agent.id)}
+                      pending={
+                        membershipMutation.isPending &&
+                        membershipMutation.variables?.resourceType === "agent" &&
+                        membershipMutation.variables.resourceId === agent.id
+                      }
+                      pendingState={
+                        membershipMutation.isPending &&
+                        membershipMutation.variables?.resourceType === "agent" &&
+                        membershipMutation.variables.resourceId === agent.id
+                          ? membershipMutation.variables.state
+                          : null
+                      }
+                      resourceName={agent.name}
+                      onJoin={() => membershipMutation.mutate({
+                        resourceType: "agent",
+                        resourceId: agent.id,
+                        resourceName: agent.name,
+                        state: "joined",
+                      })}
+                      onLeave={() => membershipMutation.mutate({
+                        resourceType: "agent",
+                        resourceId: agent.id,
+                        resourceName: agent.name,
+                        state: "left",
+                      })}
+                    />
                  </div>
                }
              />
@@ -294,7 +334,16 @@ export function Agents() {
      {effectiveView === "org" && filteredOrg.length > 0 && (
        <div className="border border-border py-1">
          {filteredOrg.map((node) => (
-            <OrgTreeNode key={node.id} node={node} depth={0} agentMap={agentMap} liveRunByAgent={liveRunByAgent} tab={tab} />
+            <OrgTreeNode
+              key={node.id}
+              node={node}
+              depth={0}
+              agentMap={agentMap}
+              liveRunByAgent={liveRunByAgent}
+              tab={tab}
+              memberships={membershipsQuery.data}
+              membershipMutation={membershipMutation}
+            />
          ))}
        </div>
      )}
@@ -320,14 +369,22 @@ function OrgTreeNode({
  agentMap,
  liveRunByAgent,
  tab,
+  memberships,
+  membershipMutation,
 }: {
  node: OrgNode;
  depth: number;
  agentMap: Map<string, Agent>;
  liveRunByAgent: Map<string, { runId: string; liveCount: number }>;
  tab: FilterTab;
+  memberships: ReturnType<typeof useResourceMemberships>["data"];
+  membershipMutation: ReturnType<typeof useResourceMembershipMutation>;
 }) {
  const agent = agentMap.get(node.id);
+  const membershipState = resourceMembershipState(memberships, "agent", node.id);
+  const pending = membershipMutation.isPending &&
+    membershipMutation.variables?.resourceType === "agent" &&
+    membershipMutation.variables.resourceId === node.id;

  const statusColor = agentStatusDot[node.status] ?? agentStatusDotDefault;

@@ -335,7 +392,11 @@ function OrgTreeNode({
    <div style={{ paddingLeft: depth * 24 }}>
      <Link
        to={agent ? agentUrl(agent) : `/agents/${node.id}`}
-        className={cn("flex items-center gap-3 px-3 py-2 hover:bg-accent/30 transition-colors w-full text-left no-underline text-inherit", agent?.pausedAt && tab !== "paused" && "opacity-50")}
+        className={cn(
+          "group flex items-center gap-3 px-3 py-2 hover:bg-accent/30 transition-colors w-full text-left no-underline text-inherit",
+          agent?.pausedAt && tab !== "paused" && "opacity-50",
+          membershipState === "left" && "text-foreground/55",
+        )}
      >
        <span className="relative flex h-2.5 w-2.5 shrink-0">
          <span className={`absolute inline-flex h-full w-full rounded-full ${statusColor}`} />
@@ -387,12 +448,39 @@ function OrgTreeNode({
              <StatusBadge status={node.status} />
            </span>
          </div>
+          <MembershipAction
+            state={membershipState}
+            pending={pending}
+            pendingState={pending ? membershipMutation.variables?.state : null}
+            resourceName={node.name}
+            onJoin={() => membershipMutation.mutate({
+              resourceType: "agent",
+              resourceId: node.id,
+              resourceName: node.name,
+              state: "joined",
+            })}
+            onLeave={() => membershipMutation.mutate({
+              resourceType: "agent",
+              resourceId: node.id,
+              resourceName: node.name,
+              state: "left",
+            })}
+          />
        </div>
      </Link>
      {node.reports && node.reports.length > 0 && (
        <div className="border-l border-border/50 ml-4">
          {node.reports.map((child) => (
-            <OrgTreeNode key={child.id} node={child} depth={depth + 1} agentMap={agentMap} liveRunByAgent={liveRunByAgent} tab={tab} />
+            <OrgTreeNode
+              key={child.id}
+              node={child}
+              depth={depth + 1}
+              agentMap={agentMap}
+              liveRunByAgent={liveRunByAgent}
+              tab={tab}
+              memberships={memberships}
+              membershipMutation={membershipMutation}
+            />
          ))}
        </div>
      )}
@@ -124,6 +124,7 @@ import { InlineEditor } from "@/components/InlineEditor";
 import { PageSkeleton } from "@/components/PageSkeleton";
 import { Identity } from "@/components/Identity";
 import { IssueReferencePill } from "@/components/IssueReferencePill";
+import { MembershipAction } from "@/components/MembershipAction";

 /* ------------------------------------------------------------------ */
 /*  Section wrapper                                                    */
@@ -896,6 +897,66 @@ export function DesignGuide() {
            selected
          />
        </div>
+        <SubSection title="Membership action">
+          <div className="border border-border rounded-md">
+            <EntityRow
+              title="Joined resource"
+              subtitle="Hover or focus the row to reveal the reserved action slot."
+              className="group"
+              trailing={
+                <MembershipAction
+                  state="joined"
+                  resourceName="Joined resource"
+                  onJoin={() => {}}
+                  onLeave={() => {}}
+                />
+              }
+            />
+            <EntityRow
+              title="Left resource"
+              subtitle="Persistent action with dimmed row content."
+              className="group text-foreground/55"
+              trailing={
+                <MembershipAction
+                  state="left"
+                  resourceName="Left resource"
+                  onJoin={() => {}}
+                  onLeave={() => {}}
+                />
+              }
+            />
+            <EntityRow
+              title="Leaving resource"
+              subtitle="Disabled while the optimistic mutation is pending."
+              className="group text-foreground/55"
+              trailing={
+                <MembershipAction
+                  state="left"
+                  pending
+                  pendingState="left"
+                  resourceName="Leaving resource"
+                  onJoin={() => {}}
+                  onLeave={() => {}}
+                />
+              }
+            />
+            <EntityRow
+              title="Joining resource"
+              subtitle="The target state is visible immediately while the server confirms."
+              className="group"
+              trailing={
+                <MembershipAction
+                  state="joined"
+                  pending
+                  pendingState="joined"
+                  resourceName="Joining resource"
+                  onJoin={() => {}}
+                  onLeave={() => {}}
+                />
+              }
+            />
+          </div>
+        </SubSection>
      </Section>

      {/* ============================================================ */}
@@ -2,7 +2,8 @@

 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import type { Project } from "@paperclipai/shared";
-import { act, type ReactNode } from "react";
+import type { ReactNode } from "react";
+import { flushSync } from "react-dom";
 import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { ProjectDetail } from "./ProjectDetail";
@@ -24,6 +25,10 @@ const mockBudgetsApi = vi.hoisted(() => ({ overview: vi.fn(), upsertPolicy: vi.f
 const mockExecutionWorkspacesApi = vi.hoisted(() => ({ list: vi.fn() }));
 const mockInstanceSettingsApi = vi.hoisted(() => ({ getExperimental: vi.fn() }));
 const mockAssetsApi = vi.hoisted(() => ({ uploadImage: vi.fn() }));
+const mockResourceMembershipsApi = vi.hoisted(() => ({
+  listMine: vi.fn(),
+  updateProject: vi.fn(),
+}));
 const mockNavigate = vi.hoisted(() => vi.fn());
 const mockSetBreadcrumbs = vi.hoisted(() => vi.fn());
 const mockIssuesList = vi.hoisted(() => vi.fn());
@@ -36,6 +41,7 @@ vi.mock("../api/budgets", () => ({ budgetsApi: mockBudgetsApi }));
 vi.mock("../api/execution-workspaces", () => ({ executionWorkspacesApi: mockExecutionWorkspacesApi }));
 vi.mock("../api/instanceSettings", () => ({ instanceSettingsApi: mockInstanceSettingsApi }));
 vi.mock("../api/assets", () => ({ assetsApi: mockAssetsApi }));
+vi.mock("../api/resourceMemberships", () => ({ resourceMembershipsApi: mockResourceMembershipsApi }));

 vi.mock("@/lib/router", () => ({
  Link: ({ children, to }: { children?: ReactNode; to: string }) => <a href={to}>{children}</a>,
@@ -87,6 +93,14 @@ vi.mock("../components/IssuesList", () => ({
  },
 }));

+async function act(callback: () => void | Promise<void>) {
+  let result: void | Promise<void> = undefined;
+  flushSync(() => {
+    result = callback();
+  });
+  await result;
+}
+
 function project(overrides: Partial<Project> = {}): Project {
  const now = new Date("2026-05-01T00:00:00Z");
  return {
@@ -152,10 +166,21 @@ describe("ProjectDetail", () => {
    mockBudgetsApi.overview.mockResolvedValue({ policies: [] });
    mockInstanceSettingsApi.getExperimental.mockResolvedValue({ enableIsolatedWorkspaces: false });
    mockExecutionWorkspacesApi.list.mockResolvedValue([]);
+    mockResourceMembershipsApi.listMine.mockResolvedValue({
+      projectMemberships: {},
+      agentMemberships: {},
+      updatedAt: null,
+    });
+    mockResourceMembershipsApi.updateProject.mockResolvedValue({
+      resourceType: "project",
+      resourceId: "project-1",
+      state: "left",
+      updatedAt: new Date("2026-05-01T00:00:00Z"),
+    });
  });

-  afterEach(() => {
-    act(() => root?.unmount());
+  afterEach(async () => {
+    await act(() => root?.unmount());
    root = null;
    container.remove();
    vi.clearAllMocks();
@@ -23,6 +23,7 @@ import { IssuesList } from "../components/IssuesList";
 import { PageSkeleton } from "../components/PageSkeleton";
 import { PageTabBar } from "../components/PageTabBar";
 import { ProjectWorkspacesContent } from "../components/ProjectWorkspacesContent";
+import { MembershipAction } from "../components/MembershipAction";
 import { buildProjectWorkspaceSummaries } from "../lib/project-workspaces-tab";
 import { collectLiveIssueIds } from "../lib/liveIssueIds";
 import { projectRouteRef } from "../lib/utils";
@@ -30,6 +31,11 @@ import { Button } from "@/components/ui/button";
 import { Tabs } from "@/components/ui/tabs";
 import { PluginLauncherOutlet } from "@/plugins/launchers";
 import { PluginSlotMount, PluginSlotOutlet, usePluginSlots } from "@/plugins/slots";
+import {
+  resourceMembershipState,
+  useResourceMembershipMutation,
+  useResourceMemberships,
+} from "../hooks/useResourceMemberships";

 /* ── Top-level tab types ── */

@@ -286,6 +292,7 @@ export function ProjectDetail() {
  const navigate = useNavigate();
  const location = useLocation();
  const [fieldSaveStates, setFieldSaveStates] = useState<Partial<Record<ProjectConfigFieldKey, ProjectFieldSaveState>>>({});
+  const [dismissedLeftProjectIds, setDismissedLeftProjectIds] = useState<Set<string>>(() => new Set());
  const fieldSaveRequestIds = useRef<Partial<Record<ProjectConfigFieldKey, number>>>({});
  const fieldSaveTimers = useRef<Partial<Record<ProjectConfigFieldKey, ReturnType<typeof setTimeout>>>>({});
  const routeProjectRef = projectId ?? "";
@@ -311,6 +318,11 @@ export function ProjectDetail() {
  const canonicalProjectRef = project ? projectRouteRef(project) : routeProjectRef;
  const projectLookupRef = project?.id ?? routeProjectRef;
  const resolvedCompanyId = project?.companyId ?? selectedCompanyId;
+  const membershipsQuery = useResourceMemberships(resolvedCompanyId);
+  const membershipMutation = useResourceMembershipMutation(resolvedCompanyId);
+  const projectMembershipState = project?.id
+    ? resourceMembershipState(membershipsQuery.data, "project", project.id)
+    : "joined";
  const experimentalSettingsQuery = useQuery({
    queryKey: queryKeys.instance.experimentalSettings,
    queryFn: () => instanceSettingsApi.getExperimental(),
@@ -476,6 +488,16 @@ export function ProjectDetail() {
    return () => closePanel();
  }, [closePanel]);

+  useEffect(() => {
+    if (!project?.id || projectMembershipState !== "joined") return;
+    setDismissedLeftProjectIds((current) => {
+      if (!current.has(project.id)) return current;
+      const next = new Set(current);
+      next.delete(project.id);
+      return next;
+    });
+  }, [project?.id, projectMembershipState]);
+
  useEffect(() => {
    return () => {
      Object.values(fieldSaveTimers.current).forEach((timer) => {
@@ -607,6 +629,12 @@ export function ProjectDetail() {
  if (isLoading) return <PageSkeleton variant="detail" />;
  if (error) return <p className="text-sm text-destructive">{error.message}</p>;
  if (!project) return null;
+  const showLeftProjectNotice =
+    projectMembershipState === "left" && !dismissedLeftProjectIds.has(project.id);
+  const projectMembershipPending =
+    membershipMutation.isPending &&
+    membershipMutation.variables?.resourceType === "project" &&
+    membershipMutation.variables.resourceId === project.id;

  const handleTabChange = (tab: ProjectTab) => {
    // Cache the active tab per project
@@ -634,6 +662,40 @@ export function ProjectDetail() {

  return (
    <div className="space-y-6">
+      {showLeftProjectNotice ? (
+        <div className="flex items-center gap-3 border border-yellow-300/35 bg-yellow-300/10 px-3 py-2 text-sm text-yellow-100">
+          <p className="min-w-0 flex-1">
+            You left this project. It no longer appears in your sidebar.
+          </p>
+          <MembershipAction
+            compact
+            state="left"
+            pending={projectMembershipPending}
+            pendingState={projectMembershipPending ? membershipMutation.variables?.state : null}
+            resourceName={project.name}
+            onJoin={() => membershipMutation.mutate({
+              resourceType: "project",
+              resourceId: project.id,
+              resourceName: project.name,
+              state: "joined",
+            })}
+            onLeave={() => membershipMutation.mutate({
+              resourceType: "project",
+              resourceId: project.id,
+              resourceName: project.name,
+              state: "left",
+            })}
+          />
+          <button
+            type="button"
+            className="h-6 w-6 shrink-0 text-yellow-100/70 hover:text-yellow-100"
+            aria-label="Dismiss project membership notice"
+            onClick={() => setDismissedLeftProjectIds((current) => new Set(current).add(project.id))}
+          >
+            ×
+          </button>
+        </div>
+      ) : null}
      <div className="flex items-start gap-3">
        <div className="h-7 flex items-center">
          <ColorPicker
@@ -1,49 +1,81 @@
 // @vitest-environment jsdom

+import type { ReactNode } from "react";
+import { flushSync } from "react-dom";
+import { createRoot } from "react-dom/client";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import type { Project } from "@paperclipai/shared";
-import { act, type ReactNode } from "react";
-import { createRoot, type Root } from "react-dom/client";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { ToastProvider } from "../context/ToastContext";
 import { Projects } from "./Projects";

-(globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
-
 const mockProjectsApi = vi.hoisted(() => ({
  list: vi.fn(),
 }));
+
+const mockResourceMembershipsApi = vi.hoisted(() => ({
+  listMine: vi.fn(),
+  updateProject: vi.fn(),
+}));
+
 const mockOpenNewProject = vi.hoisted(() => vi.fn());
 const mockSetBreadcrumbs = vi.hoisted(() => vi.fn());

-vi.mock("../api/projects", () => ({ projectsApi: mockProjectsApi }));
 vi.mock("@/lib/router", () => ({
-  Link: ({ children, to }: { children?: ReactNode; to: string }) => <a href={to}>{children}</a>,
+  Link: ({ children, to, ...props }: { children?: ReactNode; to: string }) => (
+    <a href={to} {...props}>{children}</a>
+  ),
 }));
+
 vi.mock("../context/CompanyContext", () => ({
  useCompany: () => ({ selectedCompanyId: "company-1" }),
 }));
+
 vi.mock("../context/DialogContext", () => ({
  useDialogActions: () => ({ openNewProject: mockOpenNewProject }),
 }));
+
 vi.mock("../context/BreadcrumbContext", () => ({
  useBreadcrumbs: () => ({ setBreadcrumbs: mockSetBreadcrumbs }),
 }));

-function project(overrides: Partial<Project>): Project {
-  const now = new Date("2026-05-01T00:00:00Z");
+vi.mock("../api/projects", () => ({
+  projectsApi: mockProjectsApi,
+}));
+
+vi.mock("../api/resourceMemberships", () => ({
+  resourceMembershipsApi: mockResourceMembershipsApi,
+}));
+
+(globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+if (!globalThis.PointerEvent) {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  (globalThis as any).PointerEvent = MouseEvent;
+}
+
+async function act(callback: () => void | Promise<void>) {
+  let result: void | Promise<void> = undefined;
+  flushSync(() => {
+    result = callback();
+  });
+  await result;
+}
+
+function makeProject(overrides: Partial<Project>): Project {
  return {
-    id: "project-1",
+    id: "project-a",
    companyId: "company-1",
-    urlKey: "project-1",
+    urlKey: "alpha",
    goalId: null,
    goalIds: [],
    goals: [],
-    name: "Project",
+    name: "Alpha",
    description: null,
    status: "in_progress",
    leadAgentId: null,
    targetDate: null,
-    color: "#14b8a6",
+    color: "#ef4444",
    env: null,
    pauseReason: null,
    pausedAt: null,
@@ -55,103 +87,150 @@ function project(overrides: Partial<Project>): Project {
      defaultRef: null,
      repoName: null,
      localFolder: null,
-      managedFolder: "/tmp/project-1",
-      effectiveLocalFolder: "/tmp/project-1",
-      origin: "managed_checkout",
+      managedFolder: "/tmp/project-a",
+      effectiveLocalFolder: "/tmp/project-a",
+      origin: "local_folder",
    },
    workspaces: [],
    primaryWorkspace: null,
+    managedByPlugin: null,
    archivedAt: null,
-    createdAt: now,
-    updatedAt: now,
+    createdAt: new Date("2026-01-01T00:00:00Z"),
+    updatedAt: new Date("2026-01-01T00:00:00Z"),
    ...overrides,
  };
 }

-async function renderProjects(container: HTMLElement) {
-  const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
-  let root: Root | null = null;
-
+async function flushReact() {
  await act(async () => {
-    root = createRoot(container);
-    root.render(
-      <QueryClientProvider client={queryClient}>
-        <Projects />
-      </QueryClientProvider>,
-    );
-  });
-  await act(async () => {
-    await new Promise((resolve) => setTimeout(resolve, 0));
-    await new Promise((resolve) => setTimeout(resolve, 0));
-  });
-
-  return root;
-}
-
-function projectLinkNames(container: HTMLElement): string[] {
-  return Array.from(container.querySelectorAll<HTMLAnchorElement>("a[href^='/projects/']")).map((link) => {
-    const title = link.querySelector("span.truncate");
-    return title?.textContent ?? "";
+    await Promise.resolve();
+    await new Promise((resolve) => window.setTimeout(resolve, 0));
  });
 }

 describe("Projects", () => {
-  let root: Root | null = null;
  let container: HTMLDivElement;
+  let root: ReturnType<typeof createRoot> | null;
+  let queryClient: QueryClient;

  beforeEach(() => {
    container = document.createElement("div");
    document.body.appendChild(container);
+    root = null;
+    queryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
+    });
    mockProjectsApi.list.mockResolvedValue([
-      project({
-        id: "project-bravo",
+      makeProject({
+        id: "project-c",
+        urlKey: "charlie",
+        name: "Charlie",
+        updatedAt: new Date("2026-01-10T00:00:00Z"),
+      }),
+      makeProject({
+        id: "project-b",
        urlKey: "bravo",
        name: "Bravo",
-        description: null,
-        updatedAt: new Date("2026-05-02T00:00:00Z"),
+        updatedAt: new Date("2026-01-05T00:00:00Z"),
      }),
-      project({
-        id: "project-alpha",
+      makeProject({
+        id: "project-a",
        urlKey: "alpha",
        name: "Alpha",
        description: "First project",
-        updatedAt: new Date("2026-05-01T00:00:00Z"),
-      }),
-      project({
-        id: "project-charlie",
-        urlKey: "charlie",
-        name: "Charlie",
-        description: null,
-        updatedAt: new Date("2026-05-03T00:00:00Z"),
+        updatedAt: new Date("2026-01-01T00:00:00Z"),
      }),
    ]);
+    mockResourceMembershipsApi.listMine.mockResolvedValue({
+      projectMemberships: { "project-b": "left" },
+      agentMemberships: {},
+      updatedAt: null,
+    });
+    mockResourceMembershipsApi.updateProject.mockResolvedValue({
+      resourceType: "project",
+      resourceId: "project-b",
+      state: "joined",
+      updatedAt: new Date("2026-01-05T00:00:00Z"),
+    });
  });

-  afterEach(() => {
-    act(() => root?.unmount());
-    root = null;
+  afterEach(async () => {
+    const currentRoot = root;
+    if (currentRoot) {
+      await act(async () => {
+        currentRoot.unmount();
+      });
+    }
+    queryClient.clear();
    container.remove();
+    document.body.innerHTML = "";
    vi.clearAllMocks();
  });

-  it("sorts projects by name by default and can switch sort mode", async () => {
-    root = await renderProjects(container);
-
-    expect(projectLinkNames(container)).toEqual(["Alpha", "Bravo", "Charlie"]);
-
-    const select = container.querySelector("select");
-    expect(select).not.toBeNull();
+  async function renderProjects() {
+    const currentRoot = createRoot(container);
+    root = currentRoot;

    await act(async () => {
-      select!.value = "updated";
-      select!.dispatchEvent(new Event("change", { bubbles: true }));
+      currentRoot.render(
+        <QueryClientProvider client={queryClient}>
+          <ToastProvider>
+            <Projects />
+          </ToastProvider>
+        </QueryClientProvider>,
+      );
    });
+    await flushReact();
+    await flushReact();
+  }

-    expect(projectLinkNames(container)).toEqual(["Charlie", "Bravo", "Alpha"]);
+  async function openSortMenu() {
+    const trigger = container.querySelector<HTMLButtonElement>('button[title="Sort"]');
+    expect(trigger).not.toBeNull();
+
+    await act(async () => {
+      trigger?.dispatchEvent(new PointerEvent("pointerdown", { bubbles: true, button: 0 }));
+      trigger?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    });
+    await flushReact();
+  }
+
+  async function chooseSortField(label: string) {
+    const item = Array.from(document.body.querySelectorAll("button"))
+      .find((element) => element.textContent?.includes(label));
+    expect(item).toBeTruthy();
+
+    await act(async () => {
+      item?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    });
+    await flushReact();
+  }
+
+  it("groups joined projects above left projects and defaults sorting by name", async () => {
+    await renderProjects();
+
+    const content = container.textContent ?? "";
+    expect(container.querySelector('button[title="Sort"]')?.textContent).toContain("Sort: Name");
+    expect(content.indexOf("My Projects")).toBeLessThan(content.indexOf("Alpha"));
+    expect(content.indexOf("Alpha")).toBeLessThan(content.indexOf("Charlie"));
+    expect(content.indexOf("Charlie")).toBeLessThan(content.indexOf("Other Projects"));
+    expect(content.indexOf("Other Projects")).toBeLessThan(content.indexOf("Bravo"));
+    expect(content).toContain("in progress");
+  });
+
+  it("sorts grouped projects by the selected field", async () => {
+    await renderProjects();
+    await openSortMenu();
+    await chooseSortField("Updated");
+
+    const content = container.textContent ?? "";
+    expect(content.indexOf("My Projects")).toBeLessThan(content.indexOf("Charlie"));
+    expect(content.indexOf("Charlie")).toBeLessThan(content.indexOf("Alpha"));
+    expect(content.indexOf("Alpha")).toBeLessThan(content.indexOf("Other Projects"));
  });

  it("reserves description line height for projects without descriptions", async () => {
-    root = await renderProjects(container);
+    await renderProjects();

    const bravoLink = Array.from(container.querySelectorAll<HTMLAnchorElement>("a")).find((link) =>
      link.textContent?.includes("Bravo"),
@@ -8,63 +8,67 @@ import { useBreadcrumbs } from "../context/BreadcrumbContext";
 import { queryKeys } from "../lib/queryKeys";
 import { EntityRow } from "../components/EntityRow";
 import { StatusBadge } from "../components/StatusBadge";
+import { MembershipAction } from "../components/MembershipAction";
 import { EmptyState } from "../components/EmptyState";
 import { PageSkeleton } from "../components/PageSkeleton";
 import { formatDate, projectUrl } from "../lib/utils";
+import {
+  resourceMembershipState,
+  useResourceMembershipMutation,
+  useResourceMemberships,
+} from "../hooks/useResourceMemberships";
 import { Button } from "@/components/ui/button";
-import { ArrowUpDown, Hexagon, Plus } from "lucide-react";
+import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover";
+import { ArrowUpDown, Check, Hexagon, Plus } from "lucide-react";

-type ProjectSortMode = "name" | "updated" | "targetDate" | "status";
+type ProjectSortField = "name" | "updated" | "created" | "targetDate";
+type ProjectSortDir = "asc" | "desc";

-const PROJECT_SORT_LABELS: Record<ProjectSortMode, string> = {
-  name: "Name",
-  updated: "Recently updated",
-  targetDate: "Target date",
-  status: "Status",
-};
+const PROJECT_SORT_OPTIONS: Array<{ field: ProjectSortField; label: string }> = [
+  { field: "name", label: "Name" },
+  { field: "updated", label: "Updated" },
+  { field: "created", label: "Created" },
+  { field: "targetDate", label: "Target date" },
+];

-const PROJECT_STATUS_RANK: Record<Project["status"], number> = {
-  in_progress: 0,
-  planned: 1,
-  backlog: 2,
-  completed: 3,
-  cancelled: 4,
-};
-
-function projectTime(project: Project, field: "createdAt" | "updatedAt"): number {
-  const value = project[field];
-  const time = value instanceof Date ? value.getTime() : new Date(value).getTime();
-  return Number.isFinite(time) ? time : 0;
-}
-
-function compareProjectNames(left: Project, right: Project): number {
+function compareProjectNames(left: Project, right: Project) {
  const nameDiff = left.name.localeCompare(right.name, undefined, { sensitivity: "base" });
  return nameDiff !== 0 ? nameDiff : left.id.localeCompare(right.id);
 }

-function compareTargetDates(left: Project, right: Project): number {
-  if (!left.targetDate && !right.targetDate) return compareProjectNames(left, right);
-  if (!left.targetDate) return 1;
-  if (!right.targetDate) return -1;
-
-  const dateDiff = left.targetDate.localeCompare(right.targetDate);
-  return dateDiff !== 0 ? dateDiff : compareProjectNames(left, right);
+function projectTime(value: Date | string | null | undefined): number | null {
+  if (!value) return null;
+  const time = new Date(value).getTime();
+  return Number.isFinite(time) ? time : null;
 }

-function sortProjects(projects: Project[], sortMode: ProjectSortMode): Project[] {
+function compareOptionalTime(
+  left: Date | string | null | undefined,
+  right: Date | string | null | undefined,
+  sortDir: ProjectSortDir,
+) {
+  const leftTime = projectTime(left);
+  const rightTime = projectTime(right);
+  if (leftTime === null && rightTime === null) return 0;
+  if (leftTime === null) return 1;
+  if (rightTime === null) return -1;
+  return sortDir === "asc" ? leftTime - rightTime : rightTime - leftTime;
+}
+
+function sortProjects(projects: Project[], sortField: ProjectSortField, sortDir: ProjectSortDir) {
  return [...projects].sort((left, right) => {
-    if (sortMode === "updated") {
-      const updatedDiff = projectTime(right, "updatedAt") - projectTime(left, "updatedAt");
-      return updatedDiff !== 0 ? updatedDiff : compareProjectNames(left, right);
+    let comparison = 0;
+    if (sortField === "name") {
+      comparison = compareProjectNames(left, right);
+      return sortDir === "asc" ? comparison : -comparison;
    }
-    if (sortMode === "targetDate") {
-      return compareTargetDates(left, right);
-    }
-    if (sortMode === "status") {
-      const statusDiff = PROJECT_STATUS_RANK[left.status] - PROJECT_STATUS_RANK[right.status];
-      return statusDiff !== 0 ? statusDiff : compareProjectNames(left, right);
-    }
-    return compareProjectNames(left, right);
+
+    if (sortField === "updated") comparison = compareOptionalTime(left.updatedAt, right.updatedAt, sortDir);
+    else if (sortField === "created") comparison = compareOptionalTime(left.createdAt, right.createdAt, sortDir);
+    else comparison = compareOptionalTime(left.targetDate, right.targetDate, sortDir);
+
+    if (comparison === 0) comparison = compareProjectNames(left, right);
+    return comparison;
  });
 }

@@ -72,7 +76,8 @@ export function Projects() {
  const { selectedCompanyId } = useCompany();
  const { openNewProject } = useDialogActions();
  const { setBreadcrumbs } = useBreadcrumbs();
-  const [sortMode, setSortMode] = useState<ProjectSortMode>("name");
+  const [sortField, setSortField] = useState<ProjectSortField>("name");
+  const [sortDir, setSortDir] = useState<ProjectSortDir>("asc");

  useEffect(() => {
    setBreadcrumbs([{ label: "Projects" }]);
@@ -83,14 +88,31 @@ export function Projects() {
    queryFn: () => projectsApi.list(selectedCompanyId!),
    enabled: !!selectedCompanyId,
  });
+  const membershipsQuery = useResourceMemberships(selectedCompanyId);
+  const membershipMutation = useResourceMembershipMutation(selectedCompanyId);
  const projects = useMemo(
    () => (allProjects ?? []).filter((p) => !p.archivedAt),
    [allProjects],
  );
  const sortedProjects = useMemo(
-    () => sortProjects(projects, sortMode),
-    [projects, sortMode],
+    () => sortProjects(projects, sortField, sortDir),
+    [projects, sortDir, sortField],
  );
+  const groupedProjects = useMemo(() => {
+    const groups = {
+      mine: [] as typeof sortedProjects,
+      other: [] as typeof sortedProjects,
+    };
+
+    for (const project of sortedProjects) {
+      const state = resourceMembershipState(membershipsQuery.data, "project", project.id);
+      if (state === "left") groups.other.push(project);
+      else groups.mine.push(project);
+    }
+
+    return groups;
+  }, [membershipsQuery.data, sortedProjects]);
+  const sortLabel = PROJECT_SORT_OPTIONS.find((option) => option.field === sortField)?.label ?? "Name";

  if (!selectedCompanyId) {
    return <EmptyState icon={Hexagon} message="Select a company to view projects." />;
@@ -102,22 +124,46 @@ export function Projects() {

  return (
    <div className="space-y-4">
-      <div className="flex flex-wrap items-center justify-between gap-3">
-        <label className="flex items-center gap-2 text-sm text-muted-foreground">
-          <ArrowUpDown className="h-4 w-4" />
-          <span>Sort</span>
-          <select
-            className="rounded-md border border-border bg-background px-2.5 py-1.5 text-sm text-foreground outline-none transition-colors hover:bg-accent/50 focus-visible:ring-2 focus-visible:ring-ring"
-            value={sortMode}
-            onChange={(event) => setSortMode(event.target.value as ProjectSortMode)}
-          >
-            {(Object.keys(PROJECT_SORT_LABELS) as ProjectSortMode[]).map((value) => (
-              <option key={value} value={value}>
-                {PROJECT_SORT_LABELS[value]}
-              </option>
-            ))}
-          </select>
-        </label>
+      <div className="flex flex-col gap-2 sm:flex-row sm:items-center sm:justify-between">
+        <Popover>
+          <PopoverTrigger asChild>
+            <Button variant="ghost" size="sm" className="w-fit text-xs" title="Sort">
+              <ArrowUpDown className="h-3.5 w-3.5 sm:h-3 sm:w-3 sm:mr-1" />
+              <span>Sort: {sortLabel}</span>
+            </Button>
+          </PopoverTrigger>
+          <PopoverContent align="start" className="w-44 p-0">
+            <div className="p-2 space-y-0.5">
+              {PROJECT_SORT_OPTIONS.map((option) => (
+                <button
+                  key={option.field}
+                  type="button"
+                  className={`flex w-full items-center justify-between rounded-sm px-2 py-1.5 text-sm ${
+                    sortField === option.field
+                      ? "bg-accent/50 text-foreground"
+                      : "text-muted-foreground hover:bg-accent/50"
+                  }`}
+                  onClick={() => {
+                    if (sortField === option.field) {
+                      setSortDir((current) => (current === "asc" ? "desc" : "asc"));
+                      return;
+                    }
+                    setSortField(option.field);
+                    setSortDir(option.field === "name" || option.field === "targetDate" ? "asc" : "desc");
+                  }}
+                >
+                  <span>{option.label}</span>
+                  {sortField === option.field ? (
+                    <span className="flex items-center gap-1 text-xs text-muted-foreground">
+                      <Check className="h-3 w-3" />
+                      {sortDir === "asc" ? "Asc" : "Desc"}
+                    </span>
+                  ) : null}
+                </button>
+              ))}
+            </div>
+          </PopoverContent>
+        </Popover>
        <Button size="sm" variant="outline" onClick={openNewProject}>
          <Plus className="h-4 w-4 mr-1" />
          Add Project
@@ -136,26 +182,70 @@ export function Projects() {
      )}

      {projects.length > 0 && (
-        <div className="border border-border">
-          {sortedProjects.map((project) => (
-            <EntityRow
-              key={project.id}
-              title={project.name}
-              subtitle={project.description ?? undefined}
-              reserveSubtitleSpace
-              to={projectUrl(project)}
-              trailing={
-                <div className="flex items-center gap-3">
-                  {project.targetDate && (
-                    <span className="text-xs text-muted-foreground">
-                      {formatDate(project.targetDate)}
-                    </span>
-                  )}
-                  <StatusBadge status={project.status} />
+        <div className="space-y-6">
+          {([
+            ["My Projects", groupedProjects.mine],
+            ["Other Projects", groupedProjects.other],
+          ] as const).map(([label, sectionProjects]) => {
+            if (sectionProjects.length === 0) return null;
+
+            return (
+              <section key={label} className="space-y-2">
+                <div className="flex items-center justify-between">
+                  <h2 className="text-sm font-medium">{label}</h2>
+                  <span className="text-xs text-muted-foreground">
+                    {sectionProjects.length} project{sectionProjects.length === 1 ? "" : "s"}
+                  </span>
                </div>
-              }
-            />
-          ))}
+                <div className="border border-border">
+                  {sectionProjects.map((project) => {
+                    const state = resourceMembershipState(membershipsQuery.data, "project", project.id);
+                    const pending = membershipMutation.isPending &&
+                      membershipMutation.variables?.resourceType === "project" &&
+                      membershipMutation.variables.resourceId === project.id;
+                    return (
+                      <EntityRow
+                        key={project.id}
+                        title={project.name}
+                        subtitle={project.description ?? undefined}
+                        reserveSubtitleSpace
+                        to={projectUrl(project)}
+                        className={state === "left" ? "group text-foreground/55" : "group"}
+                        trailing={
+                          <div className="flex items-center gap-3">
+                            {project.targetDate && (
+                              <span className="text-xs text-muted-foreground">
+                                {formatDate(project.targetDate)}
+                              </span>
+                            )}
+                            <StatusBadge status={project.status} />
+                            <MembershipAction
+                              state={state}
+                              pending={pending}
+                              pendingState={pending ? membershipMutation.variables?.state : null}
+                              resourceName={project.name}
+                              onJoin={() => membershipMutation.mutate({
+                                resourceType: "project",
+                                resourceId: project.id,
+                                resourceName: project.name,
+                                state: "joined",
+                              })}
+                              onLeave={() => membershipMutation.mutate({
+                                resourceType: "project",
+                                resourceId: project.id,
+                                resourceName: project.name,
+                                state: "left",
+                              })}
+                            />
+                          </div>
+                        }
+                      />
+                    );
+                  })}
+                </div>
+              </section>
+            );
+          })}
        </div>
      )}
    </div>