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

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