[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>

doc/DATABASE.md

@@ -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.

doc/SPEC-implementation.md

@@ -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:
 

packages/db/src/migrations/0090_resource_memberships.sql

@@ -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");

packages/db/src/migrations/meta/_journal.json

@@ -631,6 +631,13 @@
       "when": 1779129600000,
       "tag": "0089_cloud_upstreams",
       "breakpoints": true
+    },
+    {
+      "idx": 90,
+      "version": "7",
+      "when": 1779573019125,
+      "tag": "0090_resource_memberships",
+      "breakpoints": true
     }
   ]
 }

packages/db/src/schema/agent_memberships.ts

@@ -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,
+    ),
+  }),
+);

packages/db/src/schema/index.ts

@@ -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";

packages/db/src/schema/project_memberships.ts

@@ -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,
+    ),
+  }),
+);

packages/shared/src/api.ts

@@ -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`,

packages/shared/src/index.ts

@@ -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 {

packages/shared/src/types/index.ts

@@ -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,

packages/shared/src/types/resource-memberships.ts

@@ -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;
+}

packages/shared/src/validators/index.ts

@@ -51,6 +51,11 @@ export {
   upsertSidebarOrderPreferenceSchema,
   type UpsertSidebarOrderPreference,
 } from "./sidebar-preferences.js";
+export {
+  resourceMembershipStateSchema,
+  updateResourceMembershipSchema,
+  type UpdateResourceMembership,
+} from "./resource-memberships.js";
 export {
   companySkillSourceTypeSchema,
   companySkillTrustLevelSchema,

packages/shared/src/validators/resource-memberships.ts

@@ -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>;

server/src/__tests__/better-auth.test.ts

@@ -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",

server/src/__tests__/resource-memberships-routes.test.ts

@@ -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 });
+  });
+});

server/src/app.ts

@@ -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) {

server/src/routes/index.ts

@@ -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";

server/src/routes/resource-memberships.ts

@@ -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;
+}

server/src/services/index.ts

@@ -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 {

server/src/services/resource-memberships.ts

@@ -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",
+      };
+    },
+  };
+}

ui/src/api/index.ts

@@ -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";

ui/src/api/resourceMemberships.ts

@@ -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,
+    ),
+};

ui/src/components/EntityRow.test.tsx

@@ -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");
+  });
+});

ui/src/components/EntityRow.tsx

@@ -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>
     );

ui/src/components/MembershipAction.test.tsx

@@ -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...");
+  });
+});

ui/src/components/MembershipAction.tsx

@@ -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>
+  );
+}

ui/src/components/SidebarAgents.test.tsx

@@ -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") }),

ui/src/components/SidebarAgents.tsx

@@ -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}

ui/src/components/SidebarProjects.test.tsx

@@ -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"]);
+  });
 });

ui/src/components/SidebarProjects.tsx

@@ -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
+      <div className="group/project relative flex items-center">
-        to={`/projects/${routeRef}/issues`}
+        <NavLink
-        state={SIDEBAR_SCROLL_RESET_STATE}
+          to={`/projects/${routeRef}/issues`}
-        onClick={(e) => {
+          state={SIDEBAR_SCROLL_RESET_STATE}
-          if (isDragging) {
+          onClick={(e) => {
-            e.preventDefault();
+            if (isDragging) {
-            return;
+              e.preventDefault();
-          }
+              return;
-          if (isMobile) setSidebarOpen(false);
+            }
-        }}
+            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",
+          className={cn(
-          activeProjectRef === routeRef || activeProjectRef === project.id
+            "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",
-            ? "bg-accent text-foreground"
+            activeProjectRef === routeRef || activeProjectRef === project.id
-            : "text-foreground/80 hover:bg-accent/50 hover:text-foreground",
+              ? "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"
+          <span
-          style={{ backgroundColor: project.color ?? "#6366f1" }}
+            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}
+          <span className="flex-1 truncate">{project.name}</span>
-      </NavLink>
+          {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 ?? []).filter((project: Project) => {
-    [projects],
+      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>

ui/src/context/LiveUpdatesProvider.tsx

@@ -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")) &&

ui/src/hooks/useResourceMemberships.ts

@@ -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 });
+    },
+  });
+}

ui/src/lib/queryKeys.ts

@@ -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,

ui/src/pages/AgentDetail.tsx

@@ -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">

ui/src/pages/Agents.test.tsx

@@ -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>,
       );
     });

ui/src/pages/Agents.tsx

@@ -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>
       )}

ui/src/pages/DesignGuide.tsx

@@ -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>
 
       {/* ============================================================ */}

ui/src/pages/ProjectDetail.test.tsx

@@ -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(() => {
+  afterEach(async () => {
-    act(() => root?.unmount());
+    await act(() => root?.unmount());
     root = null;
     container.remove();
     vi.clearAllMocks();

ui/src/pages/ProjectDetail.tsx

@@ -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

ui/src/pages/Projects.test.tsx

@@ -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 {
+vi.mock("../api/projects", () => ({
-  const now = new Date("2026-05-01T00:00:00Z");
+  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",
+      managedFolder: "/tmp/project-a",
-      effectiveLocalFolder: "/tmp/project-1",
+      effectiveLocalFolder: "/tmp/project-a",
-      origin: "managed_checkout",
+      origin: "local_folder",
     },
     workspaces: [],
     primaryWorkspace: null,
+    managedByPlugin: null,
     archivedAt: null,
-    createdAt: now,
+    createdAt: new Date("2026-01-01T00:00:00Z"),
-    updatedAt: now,
+    updatedAt: new Date("2026-01-01T00:00:00Z"),
     ...overrides,
   };
 }
 
-async function renderProjects(container: HTMLElement) {
+async function flushReact() {
-  const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
-  let root: Root | null = null;
-
   await act(async () => {
-    root = createRoot(container);
+    await Promise.resolve();
-    root.render(
+    await new Promise((resolve) => window.setTimeout(resolve, 0));
-      <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 ?? "";
   });
 }
 
 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({
+      makeProject({
-        id: "project-bravo",
+        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-01-05T00:00:00Z"),
-        updatedAt: new Date("2026-05-02T00:00:00Z"),
       }),
-      project({
+      makeProject({
-        id: "project-alpha",
+        id: "project-a",
         urlKey: "alpha",
         name: "Alpha",
         description: "First project",
-        updatedAt: new Date("2026-05-01T00:00:00Z"),
+        updatedAt: new Date("2026-01-01T00:00:00Z"),
-      }),
-      project({
-        id: "project-charlie",
-        urlKey: "charlie",
-        name: "Charlie",
-        description: null,
-        updatedAt: new Date("2026-05-03T00: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(() => {
+  afterEach(async () => {
-    act(() => root?.unmount());
+    const currentRoot = root;
-    root = null;
+    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 () => {
+  async function renderProjects() {
-    root = await renderProjects(container);
+    const currentRoot = createRoot(container);
-
+    root = currentRoot;
-    expect(projectLinkNames(container)).toEqual(["Alpha", "Bravo", "Charlie"]);
-
-    const select = container.querySelector("select");
-    expect(select).not.toBeNull();
 
     await act(async () => {
-      select!.value = "updated";
+      currentRoot.render(
-      select!.dispatchEvent(new Event("change", { bubbles: true }));
+        <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"),

ui/src/pages/Projects.tsx

@@ -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> = {
+const PROJECT_SORT_OPTIONS: Array<{ field: ProjectSortField; label: string }> = [
-  name: "Name",
+  { field: "name", label: "Name" },
-  updated: "Recently updated",
+  { field: "updated", label: "Updated" },
-  targetDate: "Target date",
+  { field: "created", label: "Created" },
-  status: "Status",
+  { field: "targetDate", label: "Target date" },
-};
+];
 
-const PROJECT_STATUS_RANK: Record<Project["status"], number> = {
+function compareProjectNames(left: Project, right: Project) {
-  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 {
   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 {
+function projectTime(value: Date | string | null | undefined): number | null {
-  if (!left.targetDate && !right.targetDate) return compareProjectNames(left, right);
+  if (!value) return null;
-  if (!left.targetDate) return 1;
+  const time = new Date(value).getTime();
-  if (!right.targetDate) return -1;
+  return Number.isFinite(time) ? time : null;
-
-  const dateDiff = left.targetDate.localeCompare(right.targetDate);
-  return dateDiff !== 0 ? dateDiff : compareProjectNames(left, right);
 }
 
-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") {
+    let comparison = 0;
-      const updatedDiff = projectTime(right, "updatedAt") - projectTime(left, "updatedAt");
+    if (sortField === "name") {
-      return updatedDiff !== 0 ? updatedDiff : compareProjectNames(left, right);
+      comparison = compareProjectNames(left, right);
+      return sortDir === "asc" ? comparison : -comparison;
     }
-    if (sortMode === "targetDate") {
+
-      return compareTargetDates(left, right);
+    if (sortField === "updated") comparison = compareOptionalTime(left.updatedAt, right.updatedAt, sortDir);
-    }
+    else if (sortField === "created") comparison = compareOptionalTime(left.createdAt, right.createdAt, sortDir);
-    if (sortMode === "status") {
+    else comparison = compareOptionalTime(left.targetDate, right.targetDate, sortDir);
-      const statusDiff = PROJECT_STATUS_RANK[left.status] - PROJECT_STATUS_RANK[right.status];
+
-      return statusDiff !== 0 ? statusDiff : compareProjectNames(left, right);
+    if (comparison === 0) comparison = compareProjectNames(left, right);
-    }
+    return comparison;
-    return compareProjectNames(left, right);
   });
 }
 
@@ -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),
+    () => sortProjects(projects, sortField, sortDir),
-    [projects, sortMode],
+    [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">
+      <div className="flex flex-col gap-2 sm:flex-row sm:items-center sm:justify-between">
-        <label className="flex items-center gap-2 text-sm text-muted-foreground">
+        <Popover>
-          <ArrowUpDown className="h-4 w-4" />
+          <PopoverTrigger asChild>
-          <span>Sort</span>
+            <Button variant="ghost" size="sm" className="w-fit text-xs" title="Sort">
-          <select
+              <ArrowUpDown className="h-3.5 w-3.5 sm:h-3 sm:w-3 sm:mr-1" />
-            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"
+              <span>Sort: {sortLabel}</span>
-            value={sortMode}
+            </Button>
-            onChange={(event) => setSortMode(event.target.value as ProjectSortMode)}
+          </PopoverTrigger>
-          >
+          <PopoverContent align="start" className="w-44 p-0">
-            {(Object.keys(PROJECT_SORT_LABELS) as ProjectSortMode[]).map((value) => (
+            <div className="p-2 space-y-0.5">
-              <option key={value} value={value}>
+              {PROJECT_SORT_OPTIONS.map((option) => (
-                {PROJECT_SORT_LABELS[value]}
+                <button
-              </option>
+                  key={option.field}
-            ))}
+                  type="button"
-          </select>
+                  className={`flex w-full items-center justify-between rounded-sm px-2 py-1.5 text-sm ${
-        </label>
+                    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">
+        <div className="space-y-6">
-          {sortedProjects.map((project) => (
+          {([
-            <EntityRow
+            ["My Projects", groupedProjects.mine],
-              key={project.id}
+            ["Other Projects", groupedProjects.other],
-              title={project.name}
+          ] as const).map(([label, sectionProjects]) => {
-              subtitle={project.description ?? undefined}
+            if (sectionProjects.length === 0) return null;
-              reserveSubtitleSpace
+
-              to={projectUrl(project)}
+            return (
-              trailing={
+              <section key={label} className="space-y-2">
-                <div className="flex items-center gap-3">
+                <div className="flex items-center justify-between">
-                  {project.targetDate && (
+                  <h2 className="text-sm font-medium">{label}</h2>
-                    <span className="text-xs text-muted-foreground">
+                  <span className="text-xs text-muted-foreground">
-                      {formatDate(project.targetDate)}
+                    {sectionProjects.length} project{sectionProjects.length === 1 ? "" : "s"}
-                    </span>
+                  </span>
-                  )}
-                  <StatusBadge status={project.status} />
                 </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>