[codex] Add agent permissions and controls plan (#6386)

## Thinking Path

> - Paperclip orchestrates AI agents for zero-human companies by keeping
task ownership, approvals, and operator control inside one control
plane.
> - Agent permissions and plugin-hosted company settings sit on the
boundary between autonomy and governance.
> - V1 needs scoped task assignment rules, plugin extension points, and
clearer company access surfaces without weakening company boundaries.
> - The branch builds the core authorization service, plugin SDK/host
APIs, and UI simplifications needed to support those controls.
> - Paperclip EE plugin surfaces were intentionally moved out of this
core PR per review direction, so this PR now carries only the public
core/plugin infrastructure work.
> - The latest updates preserve the PAP-9937 branch changes that belong
in this PR, remove the `design/` artifacts, and exclude the experimental
`plugin-briefs` package.
> - Greptile feedback was applied through the authorization/audit paths
and the final cleanup commit was re-reviewed at 5/5 with no unresolved
Greptile threads.
> - The benefit is safer assignment control with extension hooks for
richer permission products while preserving simple defaults for normal
operators.

## What Changed

- Added scoped task-assignment authorization decisions and routed
issue/agent assignment mutations through the authorization service.
- Added plugin SDK and host APIs for company settings slots,
authorization policy/grant management, assignment previews, and bridge
invocation scope propagation.
- Simplified core company access UI and moved advanced controls behind
plugin-provided settings surfaces.
- Added retry-now affordances for blocked issue next-step notices.
- Added protected-assignment enforcement for persisted
agent/project/issue policies, including explicit-grant fallback
behavior.
- Added incremental principal-access compatibility backfill for active
agent memberships and role-default human permission grants.
- Added the Markdown code block wrap action fix from the latest branch
changes.
- Removed `design/` artifacts from the PR and removed
`packages/plugins/plugin-briefs` from the final diff.
- Addressed Greptile feedback for plugin actor sanitization, legacy
membership handling, audit pagination, unknown grant-scope metadata, and
startup test mocks.

## Verification

- `pnpm exec vitest run server/src/__tests__/access-service.test.ts
server/src/__tests__/company-portability.test.ts` -> 2 files passed, 54
tests passed.
- `pnpm exec vitest run
server/src/__tests__/server-startup-feedback-export.test.ts
server/src/__tests__/access-service.test.ts
server/src/__tests__/company-portability.test.ts` -> 3 files passed, 62
tests passed.
- `pnpm exec vitest run
server/src/__tests__/authorization-service.test.ts
server/src/__tests__/plugin-access-authorization-host-services.test.ts
server/src/__tests__/server-startup-feedback-export.test.ts` -> 3 files
passed, 28 tests passed.
- `pnpm --filter @paperclipai/server typecheck` -> passed.
- `git diff --check` -> passed.
- `node ./scripts/check-docker-deps-stage.mjs` -> passed.
- `CI=true pnpm install --frozen-lockfile --ignore-scripts` -> passed
with no lockfile update.
- `pnpm exec vitest run
ui/src/components/MarkdownBody.interaction.test.tsx` -> 1 test passed.
- `git ls-files design packages/plugins/plugin-briefs | wc -l` -> 0.
- GitHub CI on `40cd83b53` -> all checks passed, merge state `CLEAN`.
- Greptile on `40cd83b53` -> 5/5, 102 files reviewed, 0
comments/annotations added, 0 unresolved review threads.
- Confirmed the PR diff contains no `design/`,
`packages/plugins/plugin-briefs`, `pnpm-lock.yaml`, or
`.github/workflows` changes.

## Risks

- Medium: task assignment authorization paths are behaviorally stricter
for protected/private policy data, so existing plugin-authored policies
may block assignment until explicit grants or approval flows are
configured.
- Medium: plugin-host authorization APIs expand the surface area
available to trusted plugins and need careful review for company
scoping.
- Low: startup now performs a principal-access compatibility backfill,
but the migration and runtime backfill use conflict-tolerant inserts.

> 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 Codex, GPT-5 coding agent, tool-enabled workflow with shell,
git, and GitHub CLI access.

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

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

server/src/__tests__/access-routes-permissions-upgrade.test.ts

@@ -0,0 +1,167 @@
+import { randomUUID } from "node:crypto";
+import express from "express";
+import request from "supertest";
+import { and, eq } from "drizzle-orm";
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import {
+  activityLog,
+  companies,
+  companyMemberships,
+  createDb,
+  principalPermissionGrants,
+} from "@paperclipai/db";
+import {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+} from "./helpers/embedded-postgres.js";
+
+vi.hoisted(() => {
+  process.env.PAPERCLIP_HOME = "/tmp/paperclip-test-home";
+  process.env.PAPERCLIP_INSTANCE_ID = "vitest";
+  process.env.PAPERCLIP_LOG_DIR = "/tmp/paperclip-test-home/logs";
+  process.env.PAPERCLIP_IN_WORKTREE = "false";
+});
+
+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
+
+type Db = ReturnType<typeof createDb>;
+
+async function createApp(db: Db, companyId: string, userId: string) {
+  process.env.PAPERCLIP_LOG_DIR = "/tmp/paperclip-test-home/logs";
+  process.env.PAPERCLIP_IN_WORKTREE = "false";
+  const { accessRoutes } = await import("../routes/access.js");
+  const app = express();
+  app.use(express.json());
+  app.use((req, _res, next) => {
+    req.actor = {
+      type: "board",
+      userId,
+      source: "local_implicit",
+      companyIds: [companyId],
+      memberships: [{ companyId, membershipRole: "owner", status: "active" }],
+      isInstanceAdmin: true,
+    };
+    next();
+  });
+  app.use("/api", accessRoutes(db, {
+    deploymentMode: "authenticated",
+    deploymentExposure: "private",
+    bindHost: "127.0.0.1",
+    allowedHostnames: [],
+  }));
+  app.use((err: any, _req: express.Request, res: express.Response, _next: express.NextFunction) => {
+    res.status(err.status ?? 500).json({ error: err.message ?? "Internal server error" });
+  });
+  return app;
+}
+
+async function createCompanyWithOwner(db: Db) {
+  const company = await db
+    .insert(companies)
+    .values({
+      name: `Access Routes ${randomUUID()}`,
+      issuePrefix: `AR${randomUUID().replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+    })
+    .returning()
+    .then((rows) => rows[0]!);
+  const owner = await db
+    .insert(companyMemberships)
+    .values({
+      companyId: company.id,
+      principalType: "user",
+      principalId: `owner-${randomUUID()}`,
+      status: "active",
+      membershipRole: "owner",
+    })
+    .returning()
+    .then((rows) => rows[0]!);
+  return { company, owner };
+}
+
+describeEmbeddedPostgres("access routes permissions upgrade compatibility", () => {
+  let db!: Db;
+  let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
+
+  beforeAll(async () => {
+    tempDb = await startEmbeddedPostgresTestDatabase("paperclip-access-routes-permissions-upgrade-");
+    db = createDb(tempDb.connectionString);
+  }, 20_000);
+
+  afterEach(async () => {
+    await db.delete(activityLog);
+    await db.delete(principalPermissionGrants);
+    await db.delete(companyMemberships);
+    await db.delete(companies);
+  });
+
+  afterAll(async () => {
+    await tempDb?.cleanup();
+  });
+
+  it("rejects owner self-lockout through the member route after the permissions upgrade", async () => {
+    const { company, owner } = await createCompanyWithOwner(db);
+
+    const res = await request(await createApp(db, company.id, owner.principalId))
+      .patch(`/api/companies/${company.id}/members/${owner.id}`)
+      .send({ membershipRole: "admin" });
+
+    expect(res.status, JSON.stringify(res.body)).toBe(403);
+    expect(res.body.error).toContain("You cannot remove yourself");
+
+    const unchanged = await db
+      .select()
+      .from(companyMemberships)
+      .where(eq(companyMemberships.id, owner.id))
+      .then((rows) => rows[0]!);
+    expect(unchanged.membershipRole).toBe("owner");
+  });
+
+  it("keeps custom grants when the role-only member route changes a member role", async () => {
+    const { company, owner } = await createCompanyWithOwner(db);
+    const member = await db
+      .insert(companyMemberships)
+      .values({
+        companyId: company.id,
+        principalType: "user",
+        principalId: `admin-${randomUUID()}`,
+        status: "active",
+        membershipRole: "admin",
+      })
+      .returning()
+      .then((rows) => rows[0]!);
+    const customScope = { projectIds: ["project-1"] };
+    await db.insert(principalPermissionGrants).values({
+      companyId: company.id,
+      principalType: "user",
+      principalId: member.principalId,
+      permissionKey: "tasks:assign_scope",
+      scope: customScope,
+      grantedByUserId: owner.principalId,
+    });
+
+    const res = await request(await createApp(db, company.id, owner.principalId))
+      .patch(`/api/companies/${company.id}/members/${member.id}`)
+      .send({ membershipRole: "operator" });
+
+    expect(res.status, JSON.stringify(res.body)).toBe(200);
+    expect(res.body.membershipRole).toBe("operator");
+
+    const grants = await db
+      .select()
+      .from(principalPermissionGrants)
+      .where(
+        and(
+          eq(principalPermissionGrants.companyId, company.id),
+          eq(principalPermissionGrants.principalType, "user"),
+          eq(principalPermissionGrants.principalId, member.principalId),
+        ),
+      );
+    expect(grants).toHaveLength(1);
+    expect(grants[0]).toMatchObject({
+      permissionKey: "tasks:assign_scope",
+      scope: customScope,
+      grantedByUserId: owner.principalId,
+    });
+  });
+});

server/src/__tests__/access-service.test.ts

@@ -1,7 +1,8 @@
 import { randomUUID } from "node:crypto";
-import { eq } from "drizzle-orm";
+import { and, eq, sql } from "drizzle-orm";
 import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
 import {
+  agents,
   companies,
   companyMemberships,
   createDb,
@@ -14,6 +15,8 @@ import {
   startEmbeddedPostgresTestDatabase,
 } from "./helpers/embedded-postgres.js";
 import { accessService } from "../services/access.js";
+import { grantsForHumanRole } from "../services/company-member-roles.js";
+import { backfillPrincipalAccessCompatibility } from "../services/principal-access-compatibility.js";
 
 const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
 const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
@@ -56,6 +59,7 @@ describeEmbeddedPostgres("access service", () => {
     await db.delete(issues);
     await db.delete(principalPermissionGrants);
     await db.delete(instanceUserRoles);
+    await db.delete(agents);
     await db.delete(companyMemberships);
     await db.delete(companies);
   });
@@ -221,4 +225,285 @@ describeEmbeddedPostgres("access service", () => {
       access.setUserCompanyAccess(operator.principalId, [], { actorUserId: owner.principalId }),
     ).rejects.toThrow("Instance admins cannot be removed from company access");
   });
+
+  it("allows owner and admin role-default grants to manage environments", async () => {
+    const { company, owner } = await createCompanyWithOwner(db);
+    const access = accessService(db);
+    const roles = ["admin", "operator", "viewer"] as const;
+    const members = await db
+      .insert(companyMemberships)
+      .values(
+        roles.map((role) => ({
+          companyId: company.id,
+          principalType: "user" as const,
+          principalId: `${role}-${randomUUID()}`,
+          status: "active" as const,
+          membershipRole: role,
+        })),
+      )
+      .returning();
+
+    await access.setPrincipalGrants(
+      company.id,
+      "user",
+      owner.principalId,
+      grantsForHumanRole("owner"),
+      owner.principalId,
+    );
+    for (const member of members) {
+      await access.setPrincipalGrants(
+        company.id,
+        "user",
+        member.principalId,
+        grantsForHumanRole(member.membershipRole as "admin" | "operator" | "viewer"),
+        owner.principalId,
+      );
+    }
+
+    const admin = members.find((member) => member.membershipRole === "admin")!;
+    const operator = members.find((member) => member.membershipRole === "operator")!;
+    const viewer = members.find((member) => member.membershipRole === "viewer")!;
+
+    await expect(access.canUser(company.id, owner.principalId, "environments:manage")).resolves.toBe(true);
+    await expect(access.canUser(company.id, admin.principalId, "environments:manage")).resolves.toBe(true);
+    await expect(access.canUser(company.id, operator.principalId, "environments:manage")).resolves.toBe(false);
+    await expect(access.canUser(company.id, viewer.principalId, "environments:manage")).resolves.toBe(false);
+  });
+
+  it("backfills pre-upgrade human memberships with missing role grants without replacing custom grants", async () => {
+    const { company, owner } = await createCompanyWithOwner(db);
+    const scopedEnvironmentGrant = { environmentId: "env-1" };
+    const humanRows = await db
+      .insert(companyMemberships)
+      .values([
+        {
+          companyId: company.id,
+          principalType: "user",
+          principalId: `admin-${randomUUID()}`,
+          status: "active",
+          membershipRole: "admin",
+        },
+        {
+          companyId: company.id,
+          principalType: "user",
+          principalId: `operator-${randomUUID()}`,
+          status: "active",
+          membershipRole: "operator",
+        },
+        {
+          companyId: company.id,
+          principalType: "user",
+          principalId: `viewer-${randomUUID()}`,
+          status: "active",
+          membershipRole: "viewer",
+        },
+        {
+          companyId: company.id,
+          principalType: "user",
+          principalId: `legacy-${randomUUID()}`,
+          status: "active",
+          membershipRole: null,
+        },
+      ])
+      .returning();
+    const admin = humanRows[0]!;
+    const operator = humanRows[1]!;
+    const viewer = humanRows[2]!;
+    const legacyMember = humanRows[3]!;
+
+    await db.insert(principalPermissionGrants).values({
+      companyId: company.id,
+      principalType: "user",
+      principalId: owner.principalId,
+      permissionKey: "environments:manage",
+      scope: scopedEnvironmentGrant,
+      grantedByUserId: "custom-author",
+    });
+
+    const first = await backfillPrincipalAccessCompatibility(db);
+    const second = await backfillPrincipalAccessCompatibility(db);
+
+    expect(first.humanGrantsInserted).toBeGreaterThan(0);
+    expect(second.humanGrantsInserted).toBe(0);
+    await expect(accessService(db).canUser(company.id, admin.principalId, "environments:manage")).resolves.toBe(true);
+    await expect(accessService(db).canUser(company.id, operator.principalId, "tasks:assign")).resolves.toBe(true);
+    await expect(accessService(db).canUser(company.id, legacyMember.principalId, "tasks:assign")).resolves.toBe(true);
+    await expect(accessService(db).canUser(company.id, viewer.principalId, "tasks:assign")).resolves.toBe(false);
+
+    const ownerEnvironmentGrants = await db
+      .select()
+      .from(principalPermissionGrants)
+      .where(
+        and(
+          eq(principalPermissionGrants.companyId, company.id),
+          eq(principalPermissionGrants.principalId, owner.principalId),
+          eq(principalPermissionGrants.permissionKey, "environments:manage"),
+        ),
+      );
+    expect(ownerEnvironmentGrants).toHaveLength(1);
+    expect(ownerEnvironmentGrants[0]?.scope).toEqual(scopedEnvironmentGrant);
+    expect(ownerEnvironmentGrants[0]?.grantedByUserId).toBe("custom-author");
+  });
+
+  it("backfills non-terminal agents as active company members without reviving pending or terminated agents", async () => {
+    const { company } = await createCompanyWithOwner(db);
+    const agentRows = await db
+      .insert(agents)
+      .values([
+        {
+          companyId: company.id,
+          name: `Idle ${randomUUID()}`,
+          role: "engineer",
+          status: "idle",
+          adapterType: "process",
+          adapterConfig: {},
+          runtimeConfig: {},
+        },
+        {
+          companyId: company.id,
+          name: `Running ${randomUUID()}`,
+          role: "engineer",
+          status: "running",
+          adapterType: "process",
+          adapterConfig: {},
+          runtimeConfig: {},
+        },
+        {
+          companyId: company.id,
+          name: `Pending ${randomUUID()}`,
+          role: "engineer",
+          status: "pending_approval",
+          adapterType: "process",
+          adapterConfig: {},
+          runtimeConfig: {},
+        },
+        {
+          companyId: company.id,
+          name: `Terminated ${randomUUID()}`,
+          role: "engineer",
+          status: "terminated",
+          adapterType: "process",
+          adapterConfig: {},
+          runtimeConfig: {},
+        },
+      ])
+      .returning();
+    const idleAgent = agentRows[0]!;
+    const runningAgent = agentRows[1]!;
+    const pendingAgent = agentRows[2]!;
+    const terminatedAgent = agentRows[3]!;
+
+    const first = await backfillPrincipalAccessCompatibility(db);
+    const second = await backfillPrincipalAccessCompatibility(db);
+
+    expect(first.agentMembershipsInserted).toBe(2);
+    expect(second.agentMembershipsInserted).toBe(0);
+    const memberships = await db
+      .select()
+      .from(companyMemberships)
+      .where(eq(companyMemberships.principalType, "agent"));
+    expect(memberships.map((membership) => membership.principalId).sort()).toEqual([
+      idleAgent.id,
+      runningAgent.id,
+    ].sort());
+    expect(memberships.every((membership) => membership.status === "active")).toBe(true);
+    expect(memberships.every((membership) => membership.membershipRole === "member")).toBe(true);
+    expect(memberships.some((membership) => membership.principalId === pendingAgent.id)).toBe(false);
+    expect(memberships.some((membership) => membership.principalId === terminatedAgent.id)).toBe(false);
+  });
+
+  it("copies active user memberships with role-default grants for safe company imports", async () => {
+    const source = await createCompanyWithOwner(db);
+    const target = await createCompanyWithOwner(db);
+    const admin = await db
+      .insert(companyMemberships)
+      .values({
+        companyId: source.company.id,
+        principalType: "user",
+        principalId: `admin-${randomUUID()}`,
+        status: "active",
+        membershipRole: "admin",
+      })
+      .returning()
+      .then((rows) => rows[0]!);
+
+    const access = accessService(db);
+    await access.copyActiveUserMemberships(source.company.id, target.company.id);
+
+    const copiedOwnerGrants = await access.listPrincipalGrants(
+      target.company.id,
+      "user",
+      source.owner.principalId,
+    );
+    const copiedAdminGrants = await access.listPrincipalGrants(
+      target.company.id,
+      "user",
+      admin.principalId,
+    );
+    expect(copiedOwnerGrants.map((grant) => grant.permissionKey)).toEqual(
+      grantsForHumanRole("owner").map((grant) => grant.permissionKey).sort(),
+    );
+    expect(copiedAdminGrants.map((grant) => grant.permissionKey)).toEqual(
+      grantsForHumanRole("admin").map((grant) => grant.permissionKey).sort(),
+    );
+  });
+
+  it("preserves explicit scoped environment grants when backfilling owner and admin defaults", async () => {
+    const { company, owner } = await createCompanyWithOwner(db);
+    const scopedGrant = { environmentId: "env-1" };
+    await db.insert(principalPermissionGrants).values({
+      companyId: company.id,
+      principalType: "user",
+      principalId: owner.principalId,
+      permissionKey: "environments:manage",
+      scope: scopedGrant,
+      grantedByUserId: "custom-grant-author",
+    });
+
+    await db.execute(sql.raw(`
+      INSERT INTO "principal_permission_grants" (
+        "company_id",
+        "principal_type",
+        "principal_id",
+        "permission_key",
+        "scope",
+        "granted_by_user_id",
+        "created_at",
+        "updated_at"
+      )
+      SELECT
+        "company_id",
+        'user',
+        "principal_id",
+        'environments:manage',
+        NULL,
+        NULL,
+        now(),
+        now()
+      FROM "company_memberships"
+      WHERE "principal_type" = 'user'
+        AND "status" = 'active'
+        AND "membership_role" IN ('owner', 'admin')
+      ON CONFLICT (
+        "company_id",
+        "principal_type",
+        "principal_id",
+        "permission_key"
+      ) DO NOTHING
+    `));
+
+    const grants = await db
+      .select()
+      .from(principalPermissionGrants)
+      .where(
+        and(
+          eq(principalPermissionGrants.companyId, company.id),
+          eq(principalPermissionGrants.principalId, owner.principalId),
+          eq(principalPermissionGrants.permissionKey, "environments:manage"),
+        ),
+      );
+    expect(grants).toHaveLength(1);
+    expect(grants[0]?.scope).toEqual(scopedGrant);
+    expect(grants[0]?.grantedByUserId).toBe("custom-grant-author");
+  });
 });

server/src/__tests__/agent-adapter-validation-routes.test.ts

@@ -10,6 +10,7 @@ const mockAgentService = vi.hoisted(() => ({
 
 const mockAccessService = vi.hoisted(() => ({
   canUser: vi.fn(),
+  decide: vi.fn(),
   hasPermission: vi.fn(),
   ensureMembership: vi.fn(),
   setPrincipalPermission: vi.fn(),
@@ -192,6 +193,11 @@ describe("agent routes adapter validation", () => {
     mockCompanySkillService.listRuntimeSkillEntries.mockResolvedValue([]);
     mockCompanySkillService.resolveRequestedSkillKeys.mockResolvedValue([]);
     mockAccessService.canUser.mockResolvedValue(true);
+    mockAccessService.decide.mockResolvedValue({
+      allowed: true,
+      reason: "allow_explicit_grant",
+      explanation: "Allowed by test grant",
+    });
     mockAccessService.hasPermission.mockResolvedValue(true);
     mockAccessService.ensureMembership.mockResolvedValue(undefined);
     mockAccessService.setPrincipalPermission.mockResolvedValue(undefined);

server/src/__tests__/agent-cross-tenant-authz-routes.test.ts

@@ -60,6 +60,7 @@ const mockAgentService = vi.hoisted(() => ({
 
 const mockAccessService = vi.hoisted(() => ({
   canUser: vi.fn(),
+  decide: vi.fn(),
   hasPermission: vi.fn(),
   getMembership: vi.fn(),
   ensureMembership: vi.fn(),
@@ -293,6 +294,17 @@ function resetMockDefaults() {
     revokedAt: new Date("2026-04-11T00:05:00.000Z"),
   }));
   mockAccessService.canUser.mockImplementation(async () => currentAccessCanUser);
+  mockAccessService.decide.mockImplementation(async (input: { actor?: { type?: string; source?: string }; action?: string }) => {
+    const allowed = input.actor?.type === "board" && input.actor.source === "local_implicit"
+      ? true
+      : currentAccessCanUser;
+    return {
+      allowed,
+      action: input.action,
+      reason: allowed ? "allow_explicit_grant" : "deny_missing_grant",
+      explanation: allowed ? "Allowed by test grant." : `Missing permission: ${input.action ?? "action"}`,
+    };
+  });
   mockAccessService.hasPermission.mockImplementation(async () => false);
   mockAccessService.getMembership.mockImplementation(async () => null);
   mockAccessService.listPrincipalGrants.mockImplementation(async () => []);

server/src/__tests__/agent-instructions-routes.test.ts

@@ -21,6 +21,7 @@ const mockAgentInstructionsService = vi.hoisted(() => ({
 
 const mockAccessService = vi.hoisted(() => ({
   canUser: vi.fn(),
+  decide: vi.fn(),
   hasPermission: vi.fn(),
 }));
 
@@ -175,6 +176,11 @@ describe("agent instructions bundle routes", () => {
     vi.clearAllMocks();
     mockSyncInstructionsBundleConfigFromFilePath.mockImplementation((_agent, config) => config);
     mockFindServerAdapter.mockImplementation((_type: string) => ({ type: _type }));
+    mockAccessService.decide.mockResolvedValue({
+      allowed: true,
+      reason: "allow_explicit_grant",
+      explanation: "Allowed by test grant",
+    });
     mockAgentService.getById.mockResolvedValue(makeAgent());
     mockAgentService.update.mockImplementation(async (_id: string, patch: Record<string, unknown>) => ({
       ...makeAgent(),

server/src/__tests__/agent-live-run-routes.test.ts

@@ -51,7 +51,16 @@ function registerModuleMocks() {
   vi.doMock("../services/index.js", () => ({
     agentService: () => mockAgentService,
     agentInstructionsService: () => ({}),
-    accessService: () => ({}),
+    accessService: () => ({
+      canUser: vi.fn(async () => true),
+      decide: vi.fn(async (input: { action?: string }) => ({
+        allowed: true,
+        action: input.action,
+        reason: "allow_explicit_grant",
+        explanation: "Allowed by test grant.",
+      })),
+      hasPermission: vi.fn(async () => true),
+    }),
     approvalService: () => ({}),
     companySkillService: () => ({ listRuntimeSkillEntries: vi.fn() }),
     budgetService: () => ({}),

server/src/__tests__/agent-permissions-routes.test.ts

@@ -51,6 +51,7 @@ const mockAgentService = vi.hoisted(() => ({
 
 const mockAccessService = vi.hoisted(() => ({
   canUser: vi.fn(),
+  decide: vi.fn(),
   hasPermission: vi.fn(),
   getMembership: vi.fn(),
   ensureMembership: vi.fn(),
@@ -302,6 +303,7 @@ describe.sequential("agent permission routes", () => {
     mockAgentService.getChainOfCommand.mockReset();
     mockAgentService.resolveByReference.mockReset();
     mockAccessService.canUser.mockReset();
+    mockAccessService.decide.mockReset();
     mockAccessService.hasPermission.mockReset();
     mockAccessService.getMembership.mockReset();
     mockAccessService.ensureMembership.mockReset();
@@ -342,6 +344,14 @@ describe.sequential("agent permission routes", () => {
     mockAgentService.update.mockResolvedValue(baseAgent);
     mockAgentService.updatePermissions.mockResolvedValue(baseAgent);
     mockAccessService.canUser.mockResolvedValue(true);
+    mockAccessService.decide.mockImplementation(async (input: { action?: string }) => {
+      const allowed = Boolean(await mockAccessService.canUser());
+      return {
+        allowed,
+        reason: allowed ? "allow_explicit_grant" : "deny_missing_grant",
+        explanation: allowed ? "Allowed by test grant" : `Missing test grant for ${input.action ?? "action"}`,
+      };
+    });
     mockAccessService.hasPermission.mockResolvedValue(false);
     mockAccessService.getMembership.mockResolvedValue({
       id: "membership-1",
@@ -1342,6 +1352,24 @@ describe.sequential("agent permission routes", () => {
     expect(res.body.access.taskAssignSource).toBe("explicit_grant");
   }, 15_000);
 
+  it("reports simple-mode task assignment as enabled for active company agent members", async () => {
+    mockAccessService.listPrincipalGrants.mockResolvedValue([]);
+
+    const app = await createApp({
+      type: "board",
+      userId: "board-user",
+      source: "local_implicit",
+      isInstanceAdmin: true,
+      companyIds: [companyId],
+    });
+
+    const res = await requestApp(app, (baseUrl) => request(baseUrl).get(`/api/agents/${agentId}`));
+
+    expect(res.status).toBe(200);
+    expect(res.body.access.canAssignTasks).toBe(true);
+    expect(res.body.access.taskAssignSource).toBe("simple_default");
+  }, 15_000);
+
   it("keeps task assignment enabled when agent creation privilege is enabled", async () => {
     mockAgentService.updatePermissions.mockResolvedValue({
       ...baseAgent,

server/src/__tests__/agent-skills-routes.test.ts

@@ -11,6 +11,7 @@ const mockAgentService = vi.hoisted(() => ({
 
 const mockAccessService = vi.hoisted(() => ({
   canUser: vi.fn(),
+  decide: vi.fn(),
   hasPermission: vi.fn(),
   getMembership: vi.fn(),
   listPrincipalGrants: vi.fn(),
@@ -315,6 +316,11 @@ describe.sequential("agent skill routes", () => {
     );
     mockLogActivity.mockResolvedValue(undefined);
     mockAccessService.canUser.mockResolvedValue(true);
+    mockAccessService.decide.mockResolvedValue({
+      allowed: true,
+      reason: "allow_explicit_grant",
+      explanation: "Allowed by test grant",
+    });
     mockAccessService.hasPermission.mockResolvedValue(true);
     mockAccessService.getMembership.mockResolvedValue(null);
     mockAccessService.listPrincipalGrants.mockResolvedValue([]);

server/src/__tests__/agent-test-environment-routes.test.ts

@@ -10,6 +10,7 @@ const mockAgentService = vi.hoisted(() => ({
 
 const mockAccessService = vi.hoisted(() => ({
   canUser: vi.fn(),
+  decide: vi.fn(),
   hasPermission: vi.fn(),
   getMembership: vi.fn(async () => null),
   listPrincipalGrants: vi.fn(async () => []),
@@ -120,6 +121,11 @@ describe("agent test-environment route", () => {
   beforeEach(async () => {
     vi.resetModules();
     vi.clearAllMocks();
+    mockAccessService.decide.mockResolvedValue({
+      allowed: true,
+      reason: "allow_explicit_grant",
+      explanation: "Allowed by test grant",
+    });
     mockEnvironmentService.getById.mockResolvedValue({
       id: "11111111-1111-4111-8111-111111111111",
       companyId: "company-1",

server/src/__tests__/app-hmr-port.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { resolveViteHmrPort } from "../app.ts";
+import { resolveViteHmrHost, resolveViteHmrPort } from "../app.ts";
 
 describe("resolveViteHmrPort", () => {
   it("uses serverPort + 10000 when the result stays in range", () => {
@@ -17,3 +17,15 @@ describe("resolveViteHmrPort", () => {
     expect(resolveViteHmrPort(9_000)).toBe(19_000);
   });
 });
+
+describe("resolveViteHmrHost", () => {
+  it("omits wildcard bind hosts so Vite uses the browser hostname", () => {
+    expect(resolveViteHmrHost("0.0.0.0")).toBeUndefined();
+    expect(resolveViteHmrHost("::")).toBeUndefined();
+  });
+
+  it("keeps concrete bind hosts", () => {
+    expect(resolveViteHmrHost("127.0.0.1")).toBe("127.0.0.1");
+    expect(resolveViteHmrHost("paperclip-dev")).toBe("paperclip-dev");
+  });
+});

server/src/__tests__/authorization-service.test.ts

@@ -0,0 +1,547 @@
+import { randomUUID } from "node:crypto";
+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
+import {
+  agents,
+  companies,
+  companyMemberships,
+  createDb,
+  instanceUserRoles,
+  principalPermissionGrants,
+  projects,
+} from "@paperclipai/db";
+import {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+} from "./helpers/embedded-postgres.js";
+import { authorizationService } from "../services/authorization.js";
+
+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
+
+async function createCompany(db: ReturnType<typeof createDb>, label: string) {
+  return db
+    .insert(companies)
+    .values({
+      name: `Authorization ${label} ${randomUUID()}`,
+      issuePrefix: `AZ${randomUUID().slice(0, 6).toUpperCase()}`,
+    })
+    .returning()
+    .then((rows) => rows[0]!);
+}
+
+async function createAgent(
+  db: ReturnType<typeof createDb>,
+  companyId: string,
+  input: { role?: string; reportsTo?: string | null; permissions?: Record<string, unknown> } = {},
+) {
+  return db
+    .insert(agents)
+    .values({
+      companyId,
+      name: `Agent ${randomUUID()}`,
+      role: input.role ?? "engineer",
+      reportsTo: input.reportsTo ?? null,
+      permissions: input.permissions ?? {},
+      adapterType: "process",
+      adapterConfig: {},
+      runtimeConfig: {},
+    })
+    .returning()
+    .then((rows) => rows[0]!);
+}
+
+async function createProject(db: ReturnType<typeof createDb>, companyId: string, label: string) {
+  return db
+    .insert(projects)
+    .values({
+      companyId,
+      name: `Project ${label} ${randomUUID()}`,
+    })
+    .returning()
+    .then((rows) => rows[0]!);
+}
+
+async function grantAgentPermission(
+  db: ReturnType<typeof createDb>,
+  companyId: string,
+  agentId: string,
+  permissionKey: "tasks:assign" | "tasks:assign_scope",
+  scope: Record<string, unknown> | null = null,
+) {
+  await db.insert(companyMemberships).values({
+    companyId,
+    principalType: "agent",
+    principalId: agentId,
+    status: "active",
+    membershipRole: "member",
+  });
+  await db.insert(principalPermissionGrants).values({
+    companyId,
+    principalType: "agent",
+    principalId: agentId,
+    permissionKey,
+    scope,
+    grantedByUserId: null,
+  });
+}
+
+describeEmbeddedPostgres("authorization service", () => {
+  let db!: ReturnType<typeof createDb>;
+  let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
+
+  beforeAll(async () => {
+    tempDb = await startEmbeddedPostgresTestDatabase("paperclip-authorization-service-");
+    db = createDb(tempDb.connectionString);
+  }, 20_000);
+
+  afterEach(async () => {
+    await db.delete(principalPermissionGrants);
+    await db.delete(companyMemberships);
+    await db.delete(instanceUserRoles);
+    await db.delete(agents);
+    await db.delete(projects);
+    await db.delete(companies);
+  });
+
+  afterAll(async () => {
+    await tempDb?.cleanup();
+  });
+
+  it("allows active user role grants and explains the grant source", async () => {
+    const company = await createCompany(db, "UserGrant");
+    const userId = `user-${randomUUID()}`;
+    await db.insert(companyMemberships).values({
+      companyId: company.id,
+      principalType: "user",
+      principalId: userId,
+      status: "active",
+      membershipRole: "operator",
+    });
+    await db.insert(principalPermissionGrants).values({
+      companyId: company.id,
+      principalType: "user",
+      principalId: userId,
+      permissionKey: "tasks:assign",
+      grantedByUserId: "owner",
+    });
+
+    const decision = await authorizationService(db).decidePrincipalGrant({
+      companyId: company.id,
+      principalType: "user",
+      principalId: userId,
+      action: "tasks:assign",
+      permissionKey: "tasks:assign",
+    });
+
+    expect(decision).toMatchObject({
+      allowed: true,
+      reason: "allow_explicit_grant",
+      grant: {
+        principalType: "user",
+        principalId: userId,
+        permissionKey: "tasks:assign",
+      },
+    });
+    expect(decision.explanation).toContain("Allowed by explicit grant tasks:assign");
+  });
+
+  it("allows agent grants for agent configuration decisions", async () => {
+    const company = await createCompany(db, "AgentGrant");
+    const actorAgent = await createAgent(db, company.id);
+    const targetAgent = await createAgent(db, company.id);
+    await db.insert(companyMemberships).values({
+      companyId: company.id,
+      principalType: "agent",
+      principalId: actorAgent.id,
+      status: "active",
+      membershipRole: "member",
+    });
+    await db.insert(principalPermissionGrants).values({
+      companyId: company.id,
+      principalType: "agent",
+      principalId: actorAgent.id,
+      permissionKey: "agents:create",
+      grantedByUserId: null,
+    });
+
+    const decision = await authorizationService(db).decide({
+      actor: { type: "agent", agentId: actorAgent.id, companyId: company.id, source: "agent_key" },
+      action: "agent_config:read",
+      resource: { type: "agent", companyId: company.id, agentId: targetAgent.id },
+    });
+
+    expect(decision.allowed).toBe(true);
+    expect(decision.grant?.permissionKey).toBe("agents:create");
+  });
+
+  it("denies cross-company agent decisions before grant evaluation", async () => {
+    const sourceCompany = await createCompany(db, "Source");
+    const targetCompany = await createCompany(db, "Target");
+    const actorAgent = await createAgent(db, sourceCompany.id);
+
+    const decision = await authorizationService(db).decide({
+      actor: { type: "agent", agentId: actorAgent.id, companyId: sourceCompany.id, source: "agent_jwt" },
+      action: "tasks:assign",
+      resource: { type: "company", companyId: targetCompany.id },
+    });
+
+    expect(decision).toMatchObject({
+      allowed: false,
+      reason: "deny_company_boundary",
+    });
+    expect(decision.explanation).toContain("Agent key cannot access another company");
+  });
+
+  it("allows simple-mode task assignment between same-company agents without explicit grants", async () => {
+    const company = await createCompany(db, "AssignmentDefault");
+    const actorAgent = await createAgent(db, company.id, { role: "engineer" });
+    const targetAgent = await createAgent(db, company.id, { role: "engineer" });
+    await db.insert(companyMemberships).values({
+      companyId: company.id,
+      principalType: "agent",
+      principalId: actorAgent.id,
+      status: "active",
+      membershipRole: "member",
+    });
+
+    const decision = await authorizationService(db).decide({
+      actor: { type: "agent", agentId: actorAgent.id, companyId: company.id, source: "agent_key" },
+      action: "tasks:assign",
+      resource: { type: "issue", companyId: company.id, assigneeAgentId: targetAgent.id },
+      scope: { assigneeAgentId: targetAgent.id },
+    });
+
+    expect(decision).toMatchObject({
+      allowed: true,
+      reason: "allow_simple_company_member",
+    });
+    expect(decision.explanation).toContain("simple mode");
+  });
+
+  it("denies simple-mode assignment when the target agent requires protected-assignment approval", async () => {
+    const company = await createCompany(db, "ProtectedAssignment");
+    const actorAgent = await createAgent(db, company.id, { role: "engineer" });
+    const targetAgent = await createAgent(db, company.id, {
+      role: "engineer",
+      permissions: {
+        authorizationPolicy: {
+          assignmentPolicy: {
+            mode: "protected",
+            protectedAgentRequiresApproval: true,
+          },
+          protectedAgent: {
+            requiresApproval: true,
+            approvalReason: "Production deployment authority",
+          },
+          managedBy: "permissions-extension",
+        },
+      },
+    });
+
+    const decision = await authorizationService(db).decide({
+      actor: { type: "agent", agentId: actorAgent.id, companyId: company.id, source: "agent_key" },
+      action: "tasks:assign",
+      resource: { type: "issue", companyId: company.id, assigneeAgentId: targetAgent.id },
+      scope: { assigneeAgentId: targetAgent.id },
+    });
+
+    expect(decision).toMatchObject({
+      allowed: false,
+      reason: "deny_policy_restricted",
+    });
+    expect(decision.explanation).toContain("requires approval");
+  });
+
+  it("requires an explicit grant before assigning to a private target agent", async () => {
+    const company = await createCompany(db, "PrivateAssignment");
+    const actorAgent = await createAgent(db, company.id, { role: "engineer" });
+    const targetAgent = await createAgent(db, company.id, {
+      role: "engineer",
+      permissions: {
+        authorizationPolicy: {
+          agentVisibility: {
+            mode: "private",
+            hiddenFromDefaultDirectory: true,
+          },
+          assignmentPolicy: {
+            mode: "company_default",
+            protectedAgentRequiresApproval: false,
+          },
+          protectedAgent: {
+            requiresApproval: false,
+          },
+          managedBy: "permissions-extension",
+        },
+      },
+    });
+
+    const denied = await authorizationService(db).decide({
+      actor: { type: "agent", agentId: actorAgent.id, companyId: company.id, source: "agent_key" },
+      action: "tasks:assign",
+      resource: { type: "issue", companyId: company.id, assigneeAgentId: targetAgent.id },
+      scope: { assigneeAgentId: targetAgent.id },
+    });
+
+    await grantAgentPermission(db, company.id, actorAgent.id, "tasks:assign_scope", {
+      assigneeAgentId: targetAgent.id,
+    });
+
+    const allowed = await authorizationService(db).decide({
+      actor: { type: "agent", agentId: actorAgent.id, companyId: company.id, source: "agent_key" },
+      action: "tasks:assign",
+      resource: { type: "issue", companyId: company.id, assigneeAgentId: targetAgent.id },
+      scope: { assigneeAgentId: targetAgent.id },
+    });
+
+    expect(denied).toMatchObject({
+      allowed: false,
+      reason: "deny_policy_restricted",
+    });
+    expect(denied.explanation).toContain("private");
+    expect(allowed).toMatchObject({
+      allowed: true,
+      reason: "allow_explicit_grant",
+      grant: { permissionKey: "tasks:assign_scope" },
+    });
+  });
+
+  it("allows simple-mode task assignment for active same-company board operators without explicit grants", async () => {
+    const company = await createCompany(db, "BoardAssignmentDefault");
+    const userId = `user-${randomUUID()}`;
+    const targetAgent = await createAgent(db, company.id, { role: "engineer" });
+    await db.insert(companyMemberships).values({
+      companyId: company.id,
+      principalType: "user",
+      principalId: userId,
+      status: "active",
+      membershipRole: "operator",
+    });
+
+    const decision = await authorizationService(db).decide({
+      actor: { type: "board", userId, source: "session" },
+      action: "tasks:assign",
+      resource: { type: "issue", companyId: company.id, assigneeAgentId: targetAgent.id },
+      scope: { assigneeAgentId: targetAgent.id },
+    });
+
+    expect(decision).toMatchObject({
+      allowed: true,
+      reason: "allow_simple_company_member",
+    });
+  });
+
+  it("denies legacy board assignment context for viewers", async () => {
+    const company = await createCompany(db, "BoardViewerAssignment");
+    const userId = `user-${randomUUID()}`;
+    const targetAgent = await createAgent(db, company.id, { role: "engineer" });
+    await db.insert(companyMemberships).values({
+      companyId: company.id,
+      principalType: "user",
+      principalId: userId,
+      status: "active",
+      membershipRole: "viewer",
+    });
+
+    const decision = await authorizationService(db).decide({
+      actor: { type: "board", userId, companyIds: [company.id], source: "session" },
+      action: "tasks:assign",
+      resource: { type: "issue", companyId: company.id, assigneeAgentId: targetAgent.id },
+      scope: { assigneeAgentId: targetAgent.id },
+    });
+
+    expect(decision).toMatchObject({
+      allowed: false,
+      reason: "deny_missing_grant",
+    });
+  });
+
+  it("denies simple-mode assignment to a target agent from another company", async () => {
+    const sourceCompany = await createCompany(db, "AssignmentSource");
+    const targetCompany = await createCompany(db, "AssignmentTarget");
+    const actorAgent = await createAgent(db, sourceCompany.id, { role: "engineer" });
+    const targetAgent = await createAgent(db, targetCompany.id, { role: "engineer" });
+    await db.insert(companyMemberships).values({
+      companyId: sourceCompany.id,
+      principalType: "agent",
+      principalId: actorAgent.id,
+      status: "active",
+      membershipRole: "member",
+    });
+
+    const decision = await authorizationService(db).decide({
+      actor: { type: "agent", agentId: actorAgent.id, companyId: sourceCompany.id, source: "agent_key" },
+      action: "tasks:assign",
+      resource: { type: "issue", companyId: sourceCompany.id, assigneeAgentId: targetAgent.id },
+      scope: { assigneeAgentId: targetAgent.id },
+    });
+
+    expect(decision).toMatchObject({
+      allowed: false,
+      reason: "deny_company_boundary",
+    });
+  });
+
+  it("preserves legacy CEO agent creator authority", async () => {
+    const company = await createCompany(db, "Legacy");
+    const actorAgent = await createAgent(db, company.id, { role: "ceo" });
+
+    const decision = await authorizationService(db).decide({
+      actor: { type: "agent", agentId: actorAgent.id, companyId: company.id, source: "agent_jwt" },
+      action: "agents:create",
+      resource: { type: "company", companyId: company.id },
+    });
+
+    expect(decision).toMatchObject({
+      allowed: true,
+      reason: "allow_legacy_agent_creator",
+    });
+  });
+
+  it("allows scoped assignment inside a granted project and denies other projects", async () => {
+    const company = await createCompany(db, "ProjectScope");
+    const project = await createProject(db, company.id, "Allowed");
+    const otherProject = await createProject(db, company.id, "Denied");
+    const actorAgent = await createAgent(db, company.id);
+    const targetAgent = await createAgent(db, company.id);
+    await grantAgentPermission(db, company.id, actorAgent.id, "tasks:assign_scope", {
+      projectIds: [project.id],
+    });
+
+    const allowed = await authorizationService(db).decidePrincipalGrant({
+      companyId: company.id,
+      principalType: "agent",
+      principalId: actorAgent.id,
+      action: "tasks:assign",
+      permissionKey: "tasks:assign_scope",
+      scope: { projectId: project.id, assigneeAgentId: targetAgent.id },
+    });
+    const denied = await authorizationService(db).decidePrincipalGrant({
+      companyId: company.id,
+      principalType: "agent",
+      principalId: actorAgent.id,
+      action: "tasks:assign",
+      permissionKey: "tasks:assign_scope",
+      scope: { projectId: otherProject.id, assigneeAgentId: targetAgent.id },
+    });
+
+    expect(allowed).toMatchObject({
+      allowed: true,
+      grant: { permissionKey: "tasks:assign_scope" },
+    });
+    expect(denied).toMatchObject({
+      allowed: false,
+      reason: "deny_scope",
+    });
+    expect(denied.explanation).toContain("does not cover the requested scope");
+  });
+
+  it("treats unknown grant scope metadata as unconstrained", async () => {
+    const company = await createCompany(db, "UnknownScopeMetadata");
+    const actorAgent = await createAgent(db, company.id);
+    const targetAgent = await createAgent(db, company.id);
+    await grantAgentPermission(db, company.id, actorAgent.id, "tasks:assign_scope", {
+      note: "CEO-approved",
+    });
+
+    const decision = await authorizationService(db).decidePrincipalGrant({
+      companyId: company.id,
+      principalType: "agent",
+      principalId: actorAgent.id,
+      action: "tasks:assign",
+      permissionKey: "tasks:assign_scope",
+      scope: { assigneeAgentId: targetAgent.id },
+    });
+
+    expect(decision).toMatchObject({
+      allowed: true,
+      grant: { permissionKey: "tasks:assign_scope" },
+    });
+  });
+
+  it("allows scoped assignment to agents inside a managed subtree only", async () => {
+    const company = await createCompany(db, "SubtreeScope");
+    const actorAgent = await createAgent(db, company.id);
+    const managerAgent = await createAgent(db, company.id);
+    const childAgent = await createAgent(db, company.id, { reportsTo: managerAgent.id });
+    const grandchildAgent = await createAgent(db, company.id, { reportsTo: childAgent.id });
+    const outsideAgent = await createAgent(db, company.id);
+    await grantAgentPermission(db, company.id, actorAgent.id, "tasks:assign_scope", {
+      managedSubtreeAgentIds: [managerAgent.id],
+    });
+
+    const allowed = await authorizationService(db).decidePrincipalGrant({
+      companyId: company.id,
+      principalType: "agent",
+      principalId: actorAgent.id,
+      action: "tasks:assign",
+      permissionKey: "tasks:assign_scope",
+      scope: { assigneeAgentId: grandchildAgent.id },
+    });
+    const denied = await authorizationService(db).decidePrincipalGrant({
+      companyId: company.id,
+      principalType: "agent",
+      principalId: actorAgent.id,
+      action: "tasks:assign",
+      permissionKey: "tasks:assign_scope",
+      scope: { assigneeAgentId: outsideAgent.id },
+    });
+
+    expect(allowed.allowed).toBe(true);
+    expect(allowed.grant?.permissionKey).toBe("tasks:assign_scope");
+    expect(denied).toMatchObject({
+      allowed: false,
+      reason: "deny_scope",
+    });
+  });
+
+  it("allows scoped assignment to an explicit target-agent allowlist only", async () => {
+    const company = await createCompany(db, "AllowlistScope");
+    const actorAgent = await createAgent(db, company.id);
+    const allowedTarget = await createAgent(db, company.id);
+    const deniedTarget = await createAgent(db, company.id);
+    await grantAgentPermission(db, company.id, actorAgent.id, "tasks:assign_scope", {
+      assigneeAgentIds: [allowedTarget.id],
+    });
+
+    const allowed = await authorizationService(db).decidePrincipalGrant({
+      companyId: company.id,
+      principalType: "agent",
+      principalId: actorAgent.id,
+      action: "tasks:assign",
+      permissionKey: "tasks:assign_scope",
+      scope: { assigneeAgentId: allowedTarget.id },
+    });
+    const denied = await authorizationService(db).decidePrincipalGrant({
+      companyId: company.id,
+      principalType: "agent",
+      principalId: actorAgent.id,
+      action: "tasks:assign",
+      permissionKey: "tasks:assign_scope",
+      scope: { assigneeAgentId: deniedTarget.id },
+    });
+
+    expect(allowed.allowed).toBe(true);
+    expect(denied.allowed).toBe(false);
+  });
+
+  it("preserves unscoped tasks:assign compatibility for assignment decisions", async () => {
+    const company = await createCompany(db, "BroadAssign");
+    const actorAgent = await createAgent(db, company.id);
+    const targetAgent = await createAgent(db, company.id);
+    await grantAgentPermission(db, company.id, actorAgent.id, "tasks:assign");
+
+    const decision = await authorizationService(db).decidePrincipalGrant({
+      companyId: company.id,
+      principalType: "agent",
+      principalId: actorAgent.id,
+      action: "tasks:assign",
+      permissionKey: "tasks:assign",
+      scope: { assigneeAgentId: targetAgent.id },
+    });
+
+    expect(decision).toMatchObject({
+      allowed: true,
+      grant: { permissionKey: "tasks:assign" },
+    });
+  });
+});

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

@@ -5,13 +5,17 @@ import {
   buildBetterAuthAdvancedOptions,
   deriveAuthCookiePrefix,
   deriveAuthTrustedOrigins,
+  shouldDisableSecureAuthCookies,
 } from "../auth/better-auth.js";
 
 const ORIGINAL_INSTANCE_ID = process.env.PAPERCLIP_INSTANCE_ID;
+const ORIGINAL_PUBLIC_URL = process.env.PAPERCLIP_PUBLIC_URL;
 
 afterEach(() => {
   if (ORIGINAL_INSTANCE_ID === undefined) delete process.env.PAPERCLIP_INSTANCE_ID;
   else process.env.PAPERCLIP_INSTANCE_ID = ORIGINAL_INSTANCE_ID;
+  if (ORIGINAL_PUBLIC_URL === undefined) delete process.env.PAPERCLIP_PUBLIC_URL;
+  else process.env.PAPERCLIP_PUBLIC_URL = ORIGINAL_PUBLIC_URL;
 });
 
 describe("Better Auth cookie scoping", () => {
@@ -28,8 +32,8 @@ describe("Better Auth cookie scoping", () => {
     expect(advanced).toEqual({
       cookiePrefix: "paperclip-sat-worktree",
     });
-    expect(getCookies({ advanced } as BetterAuthOptions).sessionToken.name).toBe(
-      "paperclip-sat-worktree.session_token",
+    expect(getCookies({ advanced } as BetterAuthOptions).sessionToken.name).toMatch(
+      /paperclip-sat-worktree\.session_token$/,
     );
   });
 
@@ -42,6 +46,41 @@ describe("Better Auth cookie scoping", () => {
     });
   });
 
+  it("disables secure cookies when no canonical public auth URL is configured", () => {
+    delete process.env.PAPERCLIP_PUBLIC_URL;
+
+    expect(shouldDisableSecureAuthCookies({
+      deploymentMode: "authenticated",
+      authBaseUrlMode: "auto",
+      authPublicBaseUrl: undefined,
+    } as Parameters<typeof shouldDisableSecureAuthCookies>[0])).toBe(true);
+  });
+
+  it("derives secure cookie behavior from the configured public auth URL", () => {
+    delete process.env.PAPERCLIP_PUBLIC_URL;
+
+    expect(shouldDisableSecureAuthCookies({
+      deploymentMode: "authenticated",
+      authBaseUrlMode: "explicit",
+      authPublicBaseUrl: "http://paperclip-dev:46259",
+    } as Parameters<typeof shouldDisableSecureAuthCookies>[0])).toBe(true);
+    expect(shouldDisableSecureAuthCookies({
+      deploymentMode: "authenticated",
+      authBaseUrlMode: "explicit",
+      authPublicBaseUrl: "https://paperclip.example.test",
+    } as Parameters<typeof shouldDisableSecureAuthCookies>[0])).toBe(false);
+  });
+
+  it("lets PAPERCLIP_PUBLIC_URL override the auth base URL for cookie security", () => {
+    process.env.PAPERCLIP_PUBLIC_URL = "http://paperclip-dev:46259";
+
+    expect(shouldDisableSecureAuthCookies({
+      deploymentMode: "authenticated",
+      authBaseUrlMode: "explicit",
+      authPublicBaseUrl: "https://paperclip.example.test",
+    } as Parameters<typeof shouldDisableSecureAuthCookies>[0])).toBe(true);
+  });
+
   it("adds hostname port variants for authenticated mode on non-default ports", () => {
     const trustedOrigins = deriveAuthTrustedOrigins({
       deploymentMode: "authenticated",

server/src/__tests__/company-portability.test.ts

@@ -20,6 +20,7 @@ const agentSvc = {
 
 const accessSvc = {
   ensureMembership: vi.fn(),
+  ensureRoleDefaultGrants: vi.fn(),
   listActiveUserMemberships: vi.fn(),
   copyActiveUserMemberships: vi.fn(),
   setPrincipalPermission: vi.fn(),

server/src/__tests__/fixtures/plugin-worker-invocation-scope.cjs

@@ -0,0 +1,100 @@
+const readline = require("node:readline");
+
+let nextRequestId = 1;
+const pendingNested = new Map();
+
+function send(message) {
+  process.stdout.write(`${JSON.stringify(message)}\n`);
+}
+
+function sendNestedHostRequest(originalRequest, invocationId) {
+  const nestedId = `nested-${nextRequestId++}`;
+  const params = originalRequest.params?.params ?? {};
+  const mode = params.mode;
+  const requestedCompanyId = params.requestedCompanyId;
+  const nestedRequest = {
+    jsonrpc: "2.0",
+    id: nestedId,
+    method: "companies.get",
+    params: {
+      companyId: requestedCompanyId,
+    },
+  };
+
+  if (mode === "echo") {
+    nestedRequest.paperclipInvocationId = invocationId;
+  } else if (mode === "unknown") {
+    nestedRequest.paperclipInvocationId = "unknown-invocation";
+  }
+
+  pendingNested.set(nestedId, originalRequest.id);
+  send(nestedRequest);
+}
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  crlfDelay: Infinity,
+});
+
+rl.on("line", (line) => {
+  if (!line.trim()) return;
+  const message = JSON.parse(line);
+
+  if (message.id && pendingNested.has(message.id)) {
+    const originalId = pendingNested.get(message.id);
+    pendingNested.delete(message.id);
+    if (message.error) {
+      send({
+        jsonrpc: "2.0",
+        id: originalId,
+        error: message.error,
+      });
+      return;
+    }
+
+    send({
+      jsonrpc: "2.0",
+      id: originalId,
+      result: message.result,
+    });
+    return;
+  }
+
+  const method = message && typeof message.method === "string" ? message.method : null;
+
+  if (method === "initialize") {
+    send({
+      jsonrpc: "2.0",
+      id: message.id,
+      result: {
+        ok: true,
+        supportedMethods: ["getData"],
+      },
+    });
+    return;
+  }
+
+  if (method === "getData") {
+    sendNestedHostRequest(message, message.paperclipInvocation?.id);
+    return;
+  }
+
+  if (method === "shutdown") {
+    send({
+      jsonrpc: "2.0",
+      id: message.id,
+      result: {},
+    });
+    setImmediate(() => process.exit(0));
+    return;
+  }
+
+  send({
+    jsonrpc: "2.0",
+    id: message.id,
+    error: {
+      code: -32601,
+      message: `Unhandled method: ${method}`,
+    },
+  });
+});

server/src/__tests__/invite-join-grants.test.ts

@@ -68,6 +68,7 @@ describe("human invite roles", () => {
   it("maps owner to the full management grant set", () => {
     expect(grantsForHumanRole("owner")).toEqual([
       { permissionKey: "agents:create", scope: null },
+      { permissionKey: "environments:manage", scope: null },
       { permissionKey: "users:invite", scope: null },
       { permissionKey: "users:manage_permissions", scope: null },
       { permissionKey: "tasks:assign", scope: null },
@@ -75,6 +76,16 @@ describe("human invite roles", () => {
     ]);
   });
 
+  it("maps admin to management grants including environment management", () => {
+    expect(grantsForHumanRole("admin")).toEqual([
+      { permissionKey: "agents:create", scope: null },
+      { permissionKey: "environments:manage", scope: null },
+      { permissionKey: "users:invite", scope: null },
+      { permissionKey: "tasks:assign", scope: null },
+      { permissionKey: "joins:approve", scope: null },
+    ]);
+  });
+
   it("defaults legacy or missing roles to operator", () => {
     expect(normalizeHumanRole("member")).toBe("operator");
     expect(resolveHumanInviteRole(null)).toBe("operator");

server/src/__tests__/issue-agent-mutation-ownership-routes.test.ts

@@ -30,6 +30,7 @@ const mockIssueService = vi.hoisted(() => ({
 
 const mockAccessService = vi.hoisted(() => ({
   canUser: vi.fn(),
+  decide: vi.fn(),
   hasPermission: vi.fn(),
 }));
 
@@ -275,6 +276,13 @@ describe("agent issue mutation checkout ownership", () => {
     registerRouteMocks();
     vi.clearAllMocks();
     mockAccessService.canUser.mockReset();
+    mockAccessService.decide.mockReset();
+    mockAccessService.decide.mockImplementation(async (input: { action: string }) => ({
+      allowed: input.action === "tasks:assign",
+      action: input.action,
+      reason: input.action === "tasks:assign" ? "allow_explicit_grant" : "deny_missing_grant",
+      explanation: input.action === "tasks:assign" ? "Allowed by test assignment default." : "Missing permission.",
+    }));
     mockAccessService.hasPermission.mockReset();
     mockAgentService.getById.mockReset();
     mockAgentService.list.mockReset();
@@ -682,12 +690,12 @@ describe("agent issue mutation checkout ownership", () => {
   });
 
   it("allows agents with the active-checkout management grant to mutate active checkouts", async () => {
-    mockAccessService.hasPermission.mockImplementation(async (
-      _companyId: string,
-      _principalType: string,
-      principalId: string,
-      permissionKey: string,
-    ) => principalId === peerAgentId && permissionKey === "tasks:manage_active_checkouts");
+    mockAccessService.decide.mockImplementation(async (input: { action: string }) => ({
+      allowed: input.action === "tasks:manage_active_checkouts",
+      action: input.action,
+      reason: input.action === "tasks:manage_active_checkouts" ? "allow_explicit_grant" : "deny_missing_grant",
+      explanation: input.action === "tasks:manage_active_checkouts" ? "Allowed by checkout management grant." : "Missing permission.",
+    }));
 
     const res = await request(await createApp(peerActor())).patch(`/api/issues/${issueId}`).send({ title: "Managed update" });
 
@@ -828,4 +836,37 @@ describe("agent issue mutation checkout ownership", () => {
       }),
     );
   });
+
+  it("uses the authorization decision path for assignment changes", async () => {
+    const decide = vi.fn(async () => ({
+      allowed: false,
+      action: "tasks:assign",
+      reason: "deny_policy_restricted",
+      explanation: "Target agent requires approval before task assignment.",
+    }));
+    (mockAccessService as any).decide = decide;
+    mockIssueService.getById.mockResolvedValue(makeIssue({ assigneeAgentId: ownerAgentId }));
+    mockAgentService.resolveByReference.mockResolvedValue({
+      ambiguous: false,
+      agent: makeAgent(peerAgentId),
+    });
+
+    const app = await createApp(ownerActor());
+    const res = await request(app)
+      .patch(`/api/issues/${issueId}`)
+      .send({ assigneeAgentId: peerAgentId });
+
+    expect(res.status).toBe(403);
+    expect(res.body.error).toContain("requires approval");
+    expect(decide).toHaveBeenCalledWith(expect.objectContaining({
+      action: "tasks:assign",
+      resource: expect.objectContaining({
+        type: "issue",
+        companyId,
+        issueId,
+        assigneeAgentId: peerAgentId,
+      }),
+    }));
+    expect(mockIssueService.update).not.toHaveBeenCalled();
+  });
 });

server/src/__tests__/issue-assigned-backlog-contract-routes.test.ts

@@ -22,6 +22,12 @@ const mockIssueService = vi.hoisted(() => ({
 vi.mock("../services/index.js", () => ({
   accessService: () => ({
     canUser: vi.fn(async () => true),
+    decide: vi.fn(async (input: { action?: string }) => ({
+      allowed: true,
+      action: input.action,
+      reason: "allow_explicit_grant",
+      explanation: "Allowed by test grant.",
+    })),
     hasPermission: vi.fn(async () => true),
   }),
   agentService: () => ({

server/src/__tests__/issue-comment-reopen-routes.test.ts

@@ -16,6 +16,7 @@ const mockIssueService = vi.hoisted(() => ({
 
 const mockAccessService = vi.hoisted(() => ({
   canUser: vi.fn(),
+  decide: vi.fn(),
   hasPermission: vi.fn(),
 }));
 
@@ -229,6 +230,7 @@ describe.sequential("issue comment reopen routes", () => {
     mockIssueService.listWakeableBlockedDependents.mockReset();
     mockIssueService.getWakeableParentAfterChildCompletion.mockReset();
     mockAccessService.canUser.mockReset();
+    mockAccessService.decide.mockReset();
     mockAccessService.hasPermission.mockReset();
     mockHeartbeatService.wakeup.mockReset();
     mockHeartbeatService.reportRunActivity.mockReset();
@@ -307,6 +309,15 @@ describe.sequential("issue comment reopen routes", () => {
     mockIssueService.getWakeableParentAfterChildCompletion.mockResolvedValue(null);
     mockIssueService.assertCheckoutOwner.mockResolvedValue({ adoptedFromRunId: null });
     mockAccessService.canUser.mockResolvedValue(false);
+    mockAccessService.decide.mockImplementation(async (input: { action?: string }) => {
+      const allowed = input.action !== "tasks:manage_active_checkouts";
+      return {
+        allowed,
+        action: input.action,
+        reason: allowed ? "allow_explicit_grant" : "deny_missing_grant",
+        explanation: allowed ? "Allowed by test grant." : "Missing active checkout override.",
+      };
+    });
     mockAccessService.hasPermission.mockResolvedValue(false);
     mockAgentService.getById.mockResolvedValue(null);
     mockAgentService.list.mockResolvedValue([

server/src/__tests__/issue-execution-policy-routes.test.ts

@@ -26,6 +26,7 @@ const mockHeartbeatService = vi.hoisted(() => ({
 
 const mockAccessService = vi.hoisted(() => ({
   canUser: vi.fn(async () => false),
+  decide: vi.fn(),
   hasPermission: vi.fn(async () => false),
 }));
 
@@ -160,6 +161,17 @@ describe("issue execution policy routes", () => {
       parentBlockerAdded: false,
     });
     mockAccessService.canUser.mockResolvedValue(false);
+    mockAccessService.decide.mockImplementation(async (input: { actor?: { type?: string; source?: string }; action?: string }) => {
+      const allowed = input.actor?.type === "board" && input.actor.source === "local_implicit"
+        ? true
+        : Boolean(await mockAccessService.canUser() || await mockAccessService.hasPermission());
+      return {
+        allowed,
+        action: input.action,
+        reason: allowed ? "allow_explicit_grant" : "deny_missing_grant",
+        explanation: allowed ? "Allowed by test grant." : `Missing permission: ${input.action ?? "action"}`,
+      };
+    });
     mockAccessService.hasPermission.mockResolvedValue(false);
   });
 

server/src/__tests__/issue-thread-interaction-routes.test.ts

@@ -43,6 +43,12 @@ function registerModuleMocks() {
     }),
     accessService: () => ({
       canUser: vi.fn(async () => true),
+      decide: vi.fn(async (input: { action?: string }) => ({
+        allowed: true,
+        action: input.action,
+        reason: "allow_explicit_grant",
+        explanation: "Allowed by test grant.",
+      })),
       hasPermission: vi.fn(async () => true),
     }),
     agentService: () => ({

server/src/__tests__/issue-update-comment-wakeup-routes.test.ts

@@ -33,6 +33,12 @@ vi.mock("../services/index.js", () => ({
   }),
   accessService: () => ({
     canUser: vi.fn(async () => true),
+    decide: vi.fn(async (input: { action?: string }) => ({
+      allowed: true,
+      action: input.action,
+      reason: "allow_explicit_grant",
+      explanation: "Allowed by test grant.",
+    })),
     hasPermission: vi.fn(async () => true),
   }),
   agentService: () => ({
@@ -95,6 +101,12 @@ function registerModuleMocks() {
     }),
     accessService: () => ({
       canUser: vi.fn(async () => true),
+      decide: vi.fn(async (input: { action?: string }) => ({
+        allowed: true,
+        action: input.action,
+        reason: "allow_explicit_grant",
+        explanation: "Allowed by test grant.",
+      })),
       hasPermission: vi.fn(async () => true),
     }),
     agentService: () => ({

server/src/__tests__/permissions-upgrade-boundary-routes.test.ts

@@ -0,0 +1,348 @@
+import { randomUUID } from "node:crypto";
+import express from "express";
+import request from "supertest";
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import {
+  activityLog,
+  agents,
+  assets,
+  companies,
+  companyMemberships,
+  createDb,
+  documents,
+  heartbeatRuns,
+  issueAttachments,
+  issueComments,
+  issueDocuments,
+  issues,
+  issueWorkProducts,
+  principalPermissionGrants,
+} from "@paperclipai/db";
+import {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+} from "./helpers/embedded-postgres.js";
+
+vi.hoisted(() => {
+  process.env.PAPERCLIP_HOME = "/tmp/paperclip-test-home";
+  process.env.PAPERCLIP_INSTANCE_ID = "vitest";
+  process.env.PAPERCLIP_LOG_DIR = "/tmp/paperclip-test-home/logs";
+  process.env.PAPERCLIP_IN_WORKTREE = "false";
+});
+
+vi.mock("../services/issue-assignment-wakeup.js", () => ({
+  queueIssueAssignmentWakeup: vi.fn(),
+}));
+
+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
+
+type Db = ReturnType<typeof createDb>;
+
+function agentActor(companyId: string, agentId: string): Express.Request["actor"] {
+  return {
+    type: "agent",
+    agentId,
+    companyId,
+    runId: null,
+    source: "agent_jwt",
+  };
+}
+
+async function createApp(db: Db, actor: Express.Request["actor"]) {
+  process.env.PAPERCLIP_LOG_DIR = "/tmp/paperclip-test-home/logs";
+  process.env.PAPERCLIP_IN_WORKTREE = "false";
+  const [{ activityRoutes }, { issueRoutes }] = await Promise.all([
+    import("../routes/activity.js"),
+    import("../routes/issues.js"),
+  ]);
+  const app = express();
+  app.use(express.json());
+  app.use((req, _res, next) => {
+    req.actor = actor;
+    next();
+  });
+  app.use("/api", issueRoutes(db, {} as any));
+  app.use("/api", activityRoutes(db));
+  app.use((err: any, _req: express.Request, res: express.Response, _next: express.NextFunction) => {
+    res.status(err.status ?? 500).json({ error: err.message ?? "Internal server error" });
+  });
+  return app;
+}
+
+async function seedCompany(db: Db, label: string) {
+  return db
+    .insert(companies)
+    .values({
+      name: `Permissions Boundary ${label}`,
+      issuePrefix: `PB${randomUUID().replace(/-/g, "").slice(0, 6).toUpperCase()}`,
+    })
+    .returning()
+    .then((rows) => rows[0]!);
+}
+
+async function seedAgent(
+  db: Db,
+  companyId: string,
+  input: { role?: string; permissions?: Record<string, unknown>; status?: "active" | "idle" } = {},
+) {
+  return db
+    .insert(agents)
+    .values({
+      companyId,
+      name: `Agent ${randomUUID()}`,
+      role: input.role ?? "engineer",
+      status: input.status ?? "active",
+      adapterType: "process",
+      adapterConfig: {},
+      runtimeConfig: {},
+      permissions: input.permissions ?? {},
+    })
+    .returning()
+    .then((rows) => rows[0]!);
+}
+
+describeEmbeddedPostgres("permissions upgrade visibility and route boundaries", () => {
+  let db!: Db;
+  let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
+
+  beforeAll(async () => {
+    tempDb = await startEmbeddedPostgresTestDatabase("paperclip-permissions-boundary-routes-");
+    db = createDb(tempDb.connectionString);
+  }, 20_000);
+
+  afterEach(async () => {
+    await db.delete(issueAttachments);
+    await db.delete(assets);
+    await db.delete(issueDocuments);
+    await db.delete(documents);
+    await db.delete(issueWorkProducts);
+    await db.delete(issueComments);
+    await db.delete(activityLog);
+    await db.delete(principalPermissionGrants);
+    await db.delete(companyMemberships);
+    await db.delete(heartbeatRuns);
+    await db.delete(issues);
+    await db.delete(agents);
+    await db.delete(companies);
+  });
+
+  afterAll(async () => {
+    await tempDb?.cleanup();
+  });
+
+  it("keeps V1 private agent visibility from becoming issue, comment, document, attachment, activity, or work product privacy", async () => {
+    const company = await seedCompany(db, "Visibility");
+    const readerAgent = await seedAgent(db, company.id);
+    const privateTargetAgent = await seedAgent(db, company.id, {
+      permissions: {
+        authorizationPolicy: {
+          agentVisibility: {
+            mode: "private",
+            hiddenFromDefaultDirectory: true,
+          },
+          assignmentPolicy: { mode: "protected" },
+          protectedAgent: { requiresApproval: false },
+          managedBy: "permissions-extension",
+        },
+      },
+    });
+    const issue = await db
+      .insert(issues)
+      .values({
+        companyId: company.id,
+        identifier: `${company.issuePrefix}-1`,
+        title: "Visible work for a private target agent",
+        status: "todo",
+        priority: "medium",
+        assigneeAgentId: privateTargetAgent.id,
+      })
+      .returning()
+      .then((rows) => rows[0]!);
+    const comment = await db
+      .insert(issueComments)
+      .values({
+        companyId: company.id,
+        issueId: issue.id,
+        authorAgentId: privateTargetAgent.id,
+        body: "Private target agent status is still company-visible.",
+      })
+      .returning()
+      .then((rows) => rows[0]!);
+    const doc = await db
+      .insert(documents)
+      .values({
+        companyId: company.id,
+        title: "Plan",
+        latestBody: "Shared plan body",
+        createdByAgentId: privateTargetAgent.id,
+        updatedByAgentId: privateTargetAgent.id,
+      })
+      .returning()
+      .then((rows) => rows[0]!);
+    await db.insert(issueDocuments).values({
+      companyId: company.id,
+      issueId: issue.id,
+      documentId: doc.id,
+      key: "plan",
+    });
+    const asset = await db
+      .insert(assets)
+      .values({
+        companyId: company.id,
+        provider: "local_disk",
+        objectKey: `attachments/${randomUUID()}.txt`,
+        contentType: "text/plain",
+        byteSize: 12,
+        sha256: "abc123",
+        originalFilename: "note.txt",
+        createdByAgentId: privateTargetAgent.id,
+      })
+      .returning()
+      .then((rows) => rows[0]!);
+    await db.insert(issueAttachments).values({
+      companyId: company.id,
+      issueId: issue.id,
+      issueCommentId: comment.id,
+      assetId: asset.id,
+    });
+    await db.insert(issueWorkProducts).values({
+      companyId: company.id,
+      issueId: issue.id,
+      type: "url",
+      provider: "test",
+      title: "Preview",
+      url: "https://example.test/preview",
+      status: "ready",
+    });
+    await db.insert(activityLog).values({
+      companyId: company.id,
+      actorType: "agent",
+      actorId: privateTargetAgent.id,
+      agentId: privateTargetAgent.id,
+      action: "issue.updated",
+      entityType: "issue",
+      entityId: issue.id,
+      details: { source: "test" },
+    });
+
+    const app = await createApp(db, agentActor(company.id, readerAgent.id));
+
+    const [issueList, comments, docs, docDetail, attachments, activity, workProducts] = await Promise.all([
+      request(app).get(`/api/companies/${company.id}/issues`),
+      request(app).get(`/api/issues/${issue.id}/comments`),
+      request(app).get(`/api/issues/${issue.id}/documents`),
+      request(app).get(`/api/issues/${issue.id}/documents/plan`),
+      request(app).get(`/api/issues/${issue.id}/attachments`),
+      request(app).get(`/api/issues/${issue.id}/activity`),
+      request(app).get(`/api/issues/${issue.id}/work-products`),
+    ]);
+
+    expect(issueList.status, JSON.stringify(issueList.body)).toBe(200);
+    expect(issueList.body.items ?? issueList.body).toEqual(
+      expect.arrayContaining([expect.objectContaining({ id: issue.id })]),
+    );
+    expect(comments.status, JSON.stringify(comments.body)).toBe(200);
+    expect(comments.body).toEqual(expect.arrayContaining([expect.objectContaining({ id: comment.id })]));
+    expect(docs.status, JSON.stringify(docs.body)).toBe(200);
+    expect(docs.body).toEqual(expect.arrayContaining([expect.objectContaining({ key: "plan" })]));
+    expect(docDetail.status, JSON.stringify(docDetail.body)).toBe(200);
+    expect(docDetail.body.body ?? docDetail.body.latestBody).toContain("Shared plan body");
+    expect(attachments.status, JSON.stringify(attachments.body)).toBe(200);
+    expect(attachments.body).toEqual(expect.arrayContaining([expect.objectContaining({ id: expect.any(String) })]));
+    expect(activity.status, JSON.stringify(activity.body)).toBe(200);
+    expect(activity.body).toEqual(expect.arrayContaining([expect.objectContaining({ action: "issue.updated" })]));
+    expect(workProducts.status, JSON.stringify(workProducts.body)).toBe(200);
+    expect(workProducts.body).toEqual(expect.arrayContaining([expect.objectContaining({ title: "Preview" })]));
+  });
+
+  it("denies cross-company issue reads before private-agent grant evaluation can matter", async () => {
+    const sourceCompany = await seedCompany(db, "Source");
+    const targetCompany = await seedCompany(db, "Target");
+    const sourceAgent = await seedAgent(db, sourceCompany.id);
+    const privateTargetAgent = await seedAgent(db, targetCompany.id, {
+      permissions: {
+        authorizationPolicy: {
+          agentVisibility: { mode: "private", hiddenFromDefaultDirectory: true },
+          assignmentPolicy: { mode: "company_default" },
+          protectedAgent: { requiresApproval: false },
+        },
+      },
+    });
+    const issue = await db
+      .insert(issues)
+      .values({
+        companyId: targetCompany.id,
+        title: "Other company work",
+        status: "todo",
+        priority: "medium",
+        assigneeAgentId: privateTargetAgent.id,
+      })
+      .returning()
+      .then((rows) => rows[0]!);
+
+    const res = await request(await createApp(db, agentActor(sourceCompany.id, sourceAgent.id)))
+      .get(`/api/issues/${issue.id}`);
+
+    expect(res.status).toBe(403);
+    expect(res.body.error).toContain("Agent key cannot access another company");
+  });
+
+  it("allows same-company route assignment after upgrade but keeps private target assignment grant constrained", async () => {
+    const company = await seedCompany(db, "Assignment");
+    const actorAgent = await seedAgent(db, company.id);
+    const openTargetAgent = await seedAgent(db, company.id);
+    const privateTargetAgent = await seedAgent(db, company.id, {
+      permissions: {
+        authorizationPolicy: {
+          agentVisibility: { mode: "private", hiddenFromDefaultDirectory: true },
+          assignmentPolicy: { mode: "company_default" },
+          protectedAgent: { requiresApproval: false },
+          managedBy: "permissions-extension",
+        },
+      },
+    });
+    const app = await createApp(db, agentActor(company.id, actorAgent.id));
+
+    const openAssignment = await request(app)
+      .post(`/api/companies/${company.id}/issues`)
+      .send({ title: "Assignable after upgrade", assigneeAgentId: openTargetAgent.id });
+    expect(openAssignment.status, JSON.stringify(openAssignment.body)).toBe(201);
+
+    const deniedPrivateAssignment = await request(app)
+      .post(`/api/companies/${company.id}/issues`)
+      .send({ title: "Private target needs scope", assigneeAgentId: privateTargetAgent.id });
+    expect(deniedPrivateAssignment.status).toBe(403);
+    expect(deniedPrivateAssignment.body.error).toContain("private");
+
+    await db.insert(companyMemberships).values({
+      companyId: company.id,
+      principalType: "agent",
+      principalId: actorAgent.id,
+      status: "active",
+      membershipRole: "member",
+    });
+    await db.insert(principalPermissionGrants).values({
+      companyId: company.id,
+      principalType: "agent",
+      principalId: actorAgent.id,
+      permissionKey: "tasks:assign_scope",
+      scope: { assigneeAgentIds: [privateTargetAgent.id] },
+      grantedByUserId: null,
+    });
+
+    const allowedPrivateAssignment = await request(app)
+      .post(`/api/companies/${company.id}/issues`)
+      .send({ title: "Private target has explicit scope", assigneeAgentId: privateTargetAgent.id });
+    expect(allowedPrivateAssignment.status, JSON.stringify(allowedPrivateAssignment.body)).toBe(201);
+
+    const otherPrivateTargetAgent = await seedAgent(db, company.id, {
+      permissions: privateTargetAgent.permissions as Record<string, unknown>,
+    });
+    const deniedOutsideScope = await request(app)
+      .post(`/api/companies/${company.id}/issues`)
+      .send({ title: "Different private target stays denied", assigneeAgentId: otherPrivateTargetAgent.id });
+    expect(deniedOutsideScope.status).toBe(403);
+    expect(deniedOutsideScope.body.error).toContain("private");
+  });
+});

server/src/__tests__/plugin-access-authorization-host-services.test.ts

@@ -0,0 +1,322 @@
+import { randomUUID } from "node:crypto";
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import {
+  activityLog,
+  agents,
+  companies,
+  companyMemberships,
+  createDb,
+  invites,
+  principalPermissionGrants,
+} from "@paperclipai/db";
+import { buildHostServices } from "../services/plugin-host-services.js";
+import {
+  getEmbeddedPostgresTestSupport,
+  startEmbeddedPostgresTestDatabase,
+} from "./helpers/embedded-postgres.js";
+
+const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
+const pluginId = "plugin-record-id";
+
+function createEventBusStub() {
+  return {
+    forPlugin() {
+      return {
+        emit: vi.fn(),
+        subscribe: vi.fn(),
+        clear: vi.fn(),
+      };
+    },
+  } as any;
+}
+
+async function createCompany(db: ReturnType<typeof createDb>, prefix: string) {
+  return db
+    .insert(companies)
+    .values({
+      name: `${prefix} ${randomUUID()}`,
+      issuePrefix: `${prefix}${randomUUID().slice(0, 6).toUpperCase()}`,
+    })
+    .returning()
+    .then((rows) => rows[0]!);
+}
+
+describeEmbeddedPostgres("plugin access and authorization host services", () => {
+  let db!: ReturnType<typeof createDb>;
+  let tempDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | null = null;
+
+  beforeAll(async () => {
+    tempDb = await startEmbeddedPostgresTestDatabase("paperclip-plugin-access-authz-");
+    db = createDb(tempDb.connectionString);
+  }, 20_000);
+
+  afterEach(async () => {
+    await db.delete(activityLog);
+    await db.delete(principalPermissionGrants);
+    await db.delete(invites);
+    await db.delete(agents);
+    await db.delete(companyMemberships);
+    await db.delete(companies);
+  });
+
+  afterAll(async () => {
+    await tempDb?.cleanup();
+  });
+
+  it("rejects grant writes for principals outside the requested company", async () => {
+    const targetCompany = await createCompany(db, "PAX");
+    const otherCompany = await createCompany(db, "PAY");
+    const otherAgent = await db
+      .insert(agents)
+      .values({
+        companyId: otherCompany.id,
+        name: "Other agent",
+        role: "engineer",
+        adapterType: "process",
+        adapterConfig: {},
+        permissions: {},
+      })
+      .returning()
+      .then((rows) => rows[0]!);
+    const services = buildHostServices(db, pluginId, "permissions-extension", createEventBusStub());
+
+    await expect(
+      services.authorization.setGrants({
+        companyId: targetCompany.id,
+        principalType: "agent",
+        principalId: otherAgent.id,
+        grants: [{ permissionKey: "tasks:assign" }],
+      }),
+    ).rejects.toThrow("Agent not found");
+
+    const rows = await db.select().from(principalPermissionGrants);
+    expect(rows).toEqual([]);
+    services.dispose();
+  });
+
+  it("redacts invite token hashes and sensitive defaults from plugin invite reads", async () => {
+    const company = await createCompany(db, "PAZ");
+    const services = buildHostServices(db, pluginId, "permissions-extension", createEventBusStub());
+
+    const created = await services.access.createInvite({
+      companyId: company.id,
+      allowedJoinTypes: "human",
+      defaultsPayload: {
+        human: { role: "operator", apiKey: "secret-value" },
+        secret: "top-secret",
+      },
+    });
+
+    expect(created.token).toMatch(/^pcp_invite_/);
+    expect("tokenHash" in created).toBe(false);
+    expect(created.defaultsPayload).toMatchObject({
+      human: { role: "operator", apiKey: "***REDACTED***" },
+      secret: "***REDACTED***",
+    });
+
+    const listed = await services.access.listInvites({ companyId: company.id });
+    expect(listed.invites).toHaveLength(1);
+    expect("token" in listed.invites[0]!).toBe(false);
+    expect("tokenHash" in listed.invites[0]!).toBe(false);
+    services.dispose();
+  });
+
+  it("filters authorization audit entries by allow or deny decision details", async () => {
+    const company = await createCompany(db, "PAU");
+    const services = buildHostServices(db, pluginId, "permissions-extension", createEventBusStub());
+    await db.insert(activityLog).values([
+      {
+        companyId: company.id,
+        actorType: "agent",
+        actorId: "agent-1",
+        action: "authorization.assignment_preview",
+        entityType: "issue",
+        entityId: "issue-1",
+        details: { decision: "allow", secret: "do-not-leak" },
+        createdAt: new Date("2026-01-02T00:00:00Z"),
+      },
+      {
+        companyId: company.id,
+        actorType: "agent",
+        actorId: "agent-1",
+        action: "authorization.assignment_preview",
+        entityType: "issue",
+        entityId: "issue-2",
+        details: { reason: "deny_scope" },
+        createdAt: new Date("2026-01-03T00:00:00Z"),
+      },
+    ]);
+
+    const [allowed, denied] = await Promise.all([
+      services.authorization.searchAudit({
+        companyId: company.id,
+        action: "authorization.assignment_preview",
+        decision: "allow",
+        limit: 1,
+      }),
+      services.authorization.searchAudit({
+        companyId: company.id,
+        action: "authorization.assignment_preview",
+        decision: "deny",
+      }),
+    ]);
+
+    expect(allowed).toHaveLength(1);
+    expect(allowed[0]!.entityId).toBe("issue-1");
+    expect(allowed[0]!.details).toMatchObject({ decision: "allow", secret: "***REDACTED***" });
+    expect(denied).toHaveLength(1);
+    expect(denied[0]!.entityId).toBe("issue-2");
+    services.dispose();
+  });
+
+  it("uses persisted agent policy for plugin assignment preview and explanation", async () => {
+    const company = await createCompany(db, "PAP");
+    const [actorAgent, targetAgent] = await db
+      .insert(agents)
+      .values([
+        {
+          companyId: company.id,
+          name: "Actor agent",
+          role: "engineer",
+          adapterType: "process",
+          adapterConfig: {},
+          permissions: {},
+        },
+        {
+          companyId: company.id,
+          name: "Protected target",
+          role: "engineer",
+          adapterType: "process",
+          adapterConfig: {},
+          permissions: {},
+        },
+      ])
+      .returning();
+    await db.insert(companyMemberships).values({
+      companyId: company.id,
+      principalType: "agent",
+      principalId: actorAgent!.id,
+      status: "active",
+      membershipRole: "member",
+    });
+
+    const services = buildHostServices(db, pluginId, "permissions-extension", createEventBusStub());
+    const updatedPolicy = await services.authorization.updatePolicy({
+      companyId: company.id,
+      resourceType: "agent",
+      resourceId: targetAgent!.id,
+      policy: {
+        assignmentPolicy: {
+          mode: "protected",
+          protectedAgentRequiresApproval: true,
+        },
+        protectedAgent: {
+          requiresApproval: true,
+          approvalReason: "Needs board approval",
+        },
+        managedBy: "permissions-extension",
+      },
+    });
+    const input = {
+      companyId: company.id,
+      actor: {
+        type: "agent" as const,
+        agentId: actorAgent!.id,
+        companyId: company.id,
+        source: "agent_key" as const,
+      },
+      target: { assigneeAgentId: targetAgent!.id },
+    };
+    const [policy, preview, explanation] = await Promise.all([
+      Promise.resolve(updatedPolicy),
+      services.authorization.previewAssignment(input),
+      services.authorization.explainAssignment(input),
+    ]);
+
+    expect(policy.policy).toMatchObject({
+      protectedAgent: { requiresApproval: true },
+    });
+    expect(preview).toMatchObject({
+      allowed: false,
+      reason: "deny_policy_restricted",
+    });
+    expect(explanation).toMatchObject(preview);
+
+    const injectedBoardPreview = await services.authorization.previewAssignment({
+      companyId: company.id,
+      actor: {
+        type: "board",
+        userId: "operator",
+        companyIds: [company.id],
+        source: "local_implicit",
+        isInstanceAdmin: true,
+      } as any,
+      target: { assigneeAgentId: targetAgent!.id },
+    });
+    expect(injectedBoardPreview).toMatchObject({
+      allowed: false,
+      reason: "deny_policy_restricted",
+    });
+    services.dispose();
+  });
+
+  it("sanitizes plugin authorization policy updates and records audit activity", async () => {
+    const company = await createCompany(db, "PAS");
+    const targetAgent = await db
+      .insert(agents)
+      .values({
+        companyId: company.id,
+        name: "Policy target",
+        role: "engineer",
+        adapterType: "process",
+        adapterConfig: {},
+        permissions: {},
+      })
+      .returning()
+      .then((rows) => rows[0]!);
+    const services = buildHostServices(db, pluginId, "permissions-extension", createEventBusStub());
+
+    const updatedPolicy = await services.authorization.updatePolicy({
+      companyId: company.id,
+      resourceType: "agent",
+      resourceId: targetAgent.id,
+      policy: {
+        assignmentPolicy: { mode: "protected" },
+        apiKey: "sk-test-secret",
+        nested: {
+          authorization: "Bearer should-not-persist",
+          safeLabel: "kept",
+        },
+      },
+    });
+
+    expect(updatedPolicy.policy).toMatchObject({
+      assignmentPolicy: { mode: "protected" },
+      apiKey: "***REDACTED***",
+      nested: {
+        authorization: "***REDACTED***",
+        safeLabel: "kept",
+      },
+    });
+
+    const rows = await db.select().from(activityLog);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]).toMatchObject({
+      companyId: company.id,
+      actorType: "plugin",
+      actorId: pluginId,
+      action: "authorization.policy_updated_by_plugin",
+      entityType: "agent",
+      entityId: targetAgent.id,
+    });
+    expect(rows[0]!.details).toMatchObject({
+      hasPolicy: true,
+      sourcePluginId: pluginId,
+      sourcePluginKey: "permissions-extension",
+    });
+    expect(JSON.stringify(rows[0]!.details)).not.toContain("sk-test-secret");
+    expect(JSON.stringify(rows[0]!.details)).not.toContain("should-not-persist");
+    services.dispose();
+  });
+});

server/src/__tests__/plugin-routes-authz.test.ts

@@ -613,6 +613,28 @@ describe.sequential("plugin tool and bridge authz", () => {
     expect(call).not.toHaveBeenCalled();
   });
 
+  it("forwards authorized bridge company scope to the plugin worker", async () => {
+    readyPlugin();
+    const call = vi.fn().mockResolvedValue({ ok: true });
+    const { app } = await createApp(boardActor(), {}, {
+      bridgeDeps: {
+        workerManager: { call },
+      },
+    });
+
+    const res = await request(app)
+      .post(`/api/plugins/${pluginId}/data/health`)
+      .send({ companyId: companyA, params: { view: "compact" } });
+
+    expect(res.status).toBe(200);
+    expect(call).toHaveBeenCalledWith(pluginId, "getData", {
+      key: "health",
+      companyId: companyA,
+      params: { view: "compact" },
+      renderEnvironment: null,
+    });
+  });
+
   it("allows omitted-company bridge calls for instance admins as global plugin actions", async () => {
     readyPlugin();
     const call = vi.fn().mockResolvedValue({ ok: true });

server/src/__tests__/plugin-sdk-testing.test.ts

@@ -82,4 +82,29 @@ describe("plugin SDK test harness", () => {
       "missing required capability 'skills.managed'",
     );
   });
+
+  it("requires access and authorization capabilities for permission SDK calls", async () => {
+    const manifest: PaperclipPluginManifestV1 = {
+      id: "paperclip.test-missing-access-authz-capability",
+      apiVersion: 1,
+      version: "0.1.0",
+      displayName: "Missing Access Capability",
+      description: "Test plugin",
+      author: "Paperclip",
+      categories: ["automation"],
+      capabilities: [],
+      entrypoints: { worker: "./dist/worker.js" },
+    };
+    const harness = createTestHarness({ manifest });
+
+    await expect(harness.ctx.access.members.list({ companyId: "company-1" })).rejects.toThrow(
+      "missing required capability 'access.members.read'",
+    );
+    await expect(harness.ctx.authorization.grants.list({ companyId: "company-1" })).rejects.toThrow(
+      "missing required capability 'authorization.grants.read'",
+    );
+    await expect(harness.ctx.authorization.audit.search({ companyId: "company-1" })).rejects.toThrow(
+      "missing required capability 'authorization.audit.read'",
+    );
+  });
 });

server/src/__tests__/plugin-worker-manager.test.ts

@@ -3,7 +3,10 @@ import { fileURLToPath } from "node:url";
 import { describe, expect, it, vi } from "vitest";
 import type { PaperclipPluginManifestV1 } from "@paperclipai/shared";
 import {
+  createHostClientHandlers,
   JsonRpcCallError,
+  PLUGIN_RPC_ERROR_CODES,
+  type HostServices,
   type HostToWorkerMethods,
 } from "@paperclipai/plugin-sdk";
 import {
@@ -14,6 +17,10 @@ import {
 
 const FIXTURES_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), "fixtures");
 const DELAYED_WORKER_ENTRYPOINT = path.join(FIXTURES_DIR, "plugin-worker-delayed.cjs");
+const INVOCATION_SCOPE_WORKER_ENTRYPOINT = path.join(
+  FIXTURES_DIR,
+  "plugin-worker-invocation-scope.cjs",
+);
 const TERMINATED_WORKER_ENTRYPOINT = path.join(FIXTURES_DIR, "plugin-worker-terminated.cjs");
 
 const TEST_MANIFEST: PaperclipPluginManifestV1 = {
@@ -178,4 +185,86 @@ describe("plugin-worker-manager stderr failure context", () => {
       await handle.stop().catch(() => undefined);
     }
   });
+
+  it("passes echoed invocation scope to worker-to-host handlers", async () => {
+    const companiesGet = vi.fn(async () => ({ id: "company-1" }));
+    const handle = createPluginWorkerHandle("test.plugin", {
+      entrypointPath: INVOCATION_SCOPE_WORKER_ENTRYPOINT,
+      manifest: TEST_MANIFEST,
+      config: {},
+      instanceInfo: {
+        instanceId: "instance-1",
+        hostVersion: "1.0.0",
+      },
+      apiVersion: 1,
+      hostHandlers: {
+        "companies.get": companiesGet,
+      },
+    });
+
+    try {
+      await handle.start();
+
+      await expect(handle.call("getData", {
+        key: "probe",
+        companyId: "company-1",
+        params: {
+          mode: "echo",
+          requestedCompanyId: "company-1",
+        },
+      } as HostToWorkerMethods["getData"][0])).resolves.toEqual({ id: "company-1" });
+
+      expect(companiesGet).toHaveBeenCalledWith(
+        { companyId: "company-1" },
+        { invocationScope: { companyId: "company-1" } },
+      );
+    } finally {
+      await handle.stop().catch(() => undefined);
+    }
+  });
+
+  it("rejects missing or unknown invocation ids while a company invocation is active", async () => {
+    const companiesGet = vi.fn(async () => ({ id: "company-2" }));
+    const hostHandlers = createHostClientHandlers({
+      pluginId: "test.plugin",
+      capabilities: ["companies.read"],
+      services: {
+        companies: {
+          get: companiesGet,
+        },
+      } as unknown as HostServices,
+    });
+    const handle = createPluginWorkerHandle("test.plugin", {
+      entrypointPath: INVOCATION_SCOPE_WORKER_ENTRYPOINT,
+      manifest: TEST_MANIFEST,
+      config: {},
+      instanceInfo: {
+        instanceId: "instance-1",
+        hostVersion: "1.0.0",
+      },
+      apiVersion: 1,
+      hostHandlers,
+    });
+
+    try {
+      await handle.start();
+
+      for (const mode of ["omit", "unknown"]) {
+        await expect(handle.call("getData", {
+          key: "probe",
+          companyId: "company-1",
+          params: {
+            mode,
+            requestedCompanyId: "company-2",
+          },
+        } as HostToWorkerMethods["getData"][0])).rejects.toMatchObject({
+          code: PLUGIN_RPC_ERROR_CODES.CAPABILITY_DENIED,
+        });
+      }
+
+      expect(companiesGet).not.toHaveBeenCalled();
+    } finally {
+      await handle.stop().catch(() => undefined);
+    }
+  });
 });

server/src/__tests__/server-startup-feedback-export.test.ts

@@ -138,6 +138,10 @@ vi.mock("../realtime/live-events-ws.js", () => ({
 }));
 
 vi.mock("../services/index.js", () => ({
+  backfillPrincipalAccessCompatibility: vi.fn(async () => ({
+    agentMembershipsInserted: 0,
+    humanGrantsInserted: 0,
+  })),
   feedbackService: feedbackServiceFactoryMock,
   heartbeatService: vi.fn(() => ({
     reapOrphanedRuns: vi.fn(async () => undefined),

server/src/app.ts

@@ -96,6 +96,12 @@ export function resolveViteHmrPort(serverPort: number): number {
   return Math.max(1_024, serverPort - 10_000);
 }
 
+export function resolveViteHmrHost(bindHost: string): string | undefined {
+  const normalized = bindHost.trim().toLowerCase();
+  if (normalized === "0.0.0.0" || normalized === "::") return undefined;
+  return bindHost;
+}
+
 export function shouldServeViteDevHtml(req: ExpressRequest): boolean {
   const pathname = req.path;
   if (VITE_DEV_STATIC_PATHS.has(pathname)) return false;
@@ -373,6 +379,7 @@ export async function createApp(
     const uiRoot = path.resolve(__dirname, "../../ui");
     const publicUiRoot = path.resolve(uiRoot, "public");
     const hmrPort = resolveViteHmrPort(opts.serverPort);
+    const hmrHost = resolveViteHmrHost(opts.bindHost);
     const { createServer: createViteServer } = await import("vite");
     const vite = await createViteServer({
       root: uiRoot,
@@ -380,7 +387,7 @@ export async function createApp(
       server: {
         middlewareMode: true,
         hmr: {
-          host: opts.bindHost,
+          ...(hmrHost ? { host: hmrHost } : {}),
           port: hmrPort,
           clientPort: hmrPort,
         },

server/src/auth/better-auth.ts

@@ -44,6 +44,15 @@ export function buildBetterAuthAdvancedOptions(input: { disableSecureCookies: bo
   };
 }
 
+export function shouldDisableSecureAuthCookies(config: Config): boolean {
+  const configuredPublicUrl = (
+    process.env.PAPERCLIP_PUBLIC_URL?.trim() ||
+    (config.authBaseUrlMode === "explicit" ? config.authPublicBaseUrl?.trim() : "")
+  );
+  if (!configuredPublicUrl) return true;
+  return configuredPublicUrl.startsWith("http://");
+}
+
 function headersFromNodeHeaders(rawHeaders: IncomingHttpHeaders): Headers {
   const headers = new Headers();
   for (const [key, raw] of Object.entries(rawHeaders)) {
@@ -99,8 +108,7 @@ export function createBetterAuthInstance(db: Db, config: Config, trustedOrigins:
       "For local development, set BETTER_AUTH_SECRET=paperclip-dev-secret in your .env file.",
     );
   }
-  const publicUrl = process.env.PAPERCLIP_PUBLIC_URL ?? baseUrl;
-  const isHttpOnly = publicUrl ? publicUrl.startsWith("http://") : false;
+  const disableSecureCookies = shouldDisableSecureAuthCookies(config);
 
   const authConfig = {
     baseURL: baseUrl,
@@ -120,7 +128,7 @@ export function createBetterAuthInstance(db: Db, config: Config, trustedOrigins:
       requireEmailVerification: false,
       disableSignUp: config.authDisableSignUp,
     },
-    advanced: buildBetterAuthAdvancedOptions({ disableSecureCookies: isHttpOnly }),
+    advanced: buildBetterAuthAdvancedOptions({ disableSecureCookies }),
   };
 
   if (!baseUrl) {

server/src/board-claim.ts

@@ -3,6 +3,7 @@ import { and, eq } from "drizzle-orm";
 import type { Db } from "@paperclipai/db";
 import { companies, companyMemberships, instanceUserRoles } from "@paperclipai/db";
 import type { DeploymentMode } from "@paperclipai/shared";
+import { ensureHumanRoleDefaultGrants } from "./services/principal-access-compatibility.js";
 
 const LOCAL_BOARD_USER_ID = "local-board";
 const CLAIM_TTL_MS = 1000 * 60 * 60 * 24;
@@ -89,6 +90,7 @@ export async function claimBoardOwnership(
   const status = getChallengeStatus(opts.token, opts.code);
   if (status !== "available") return { status };
 
+  const claimedCompanyIds: string[] = [];
   await db.transaction(async (tx) => {
     const existingTargetAdmin = await tx
       .select({ id: instanceUserRoles.id })
@@ -108,6 +110,7 @@ export async function claimBoardOwnership(
 
     const allCompanies = await tx.select({ id: companies.id }).from(companies);
     for (const company of allCompanies) {
+      claimedCompanyIds.push(company.id);
       const existing = await tx
         .select({ id: companyMemberships.id, status: companyMemberships.status })
         .from(companyMemberships)
@@ -140,6 +143,15 @@ export async function claimBoardOwnership(
     }
   });
 
+  for (const companyId of claimedCompanyIds) {
+    await ensureHumanRoleDefaultGrants(db, {
+      companyId,
+      principalId: opts.userId,
+      membershipRole: "owner",
+      grantedByUserId: opts.userId,
+    });
+  }
+
   if (activeChallenge && activeChallenge.token === opts.token) {
     activeChallenge.claimedAt = new Date();
     activeChallenge.claimedByUserId = opts.userId;

server/src/index.ts

@@ -30,6 +30,7 @@ import { logger } from "./middleware/logger.js";
 import { setupLiveEventsWebSocketServer } from "./realtime/live-events-ws.js";
 import {
   feedbackService,
+  backfillPrincipalAccessCompatibility,
   heartbeatService,
   instanceSettingsService,
   reconcilePersistedRuntimeServicesOnStartup,
@@ -512,6 +513,10 @@ export async function startServer(): Promise<StartedServer> {
   if (config.deploymentMode === "local_trusted") {
     await ensureLocalTrustedBoardPrincipal(db as any);
   }
+  const accessBackfill = await backfillPrincipalAccessCompatibility(db as any);
+  if (accessBackfill.agentMembershipsInserted > 0 || accessBackfill.humanGrantsInserted > 0) {
+    logger.info(accessBackfill, "Backfilled principal access compatibility records");
+  }
   if (config.deploymentMode === "authenticated") {
     const {
       createBetterAuthHandler,

server/src/routes/agents.ts

@@ -501,6 +501,15 @@ export function agentRoutes(
       };
     }
 
+    if (membership?.status === "active") {
+      return {
+        canAssignTasks: true,
+        taskAssignSource: "simple_default" as const,
+        membership,
+        grants,
+      };
+    }
+
     return {
       canAssignTasks: false,
       taskAssignSource: "none" as const,
@@ -543,34 +552,32 @@ export function agentRoutes(
 
   async function assertCanCreateAgentsForCompany(req: Request, companyId: string) {
     assertCompanyAccess(req, companyId);
-    if (req.actor.type === "board") {
-      if (req.actor.source === "local_implicit" || req.actor.isInstanceAdmin) return null;
-      const allowed = await access.canUser(companyId, req.actor.userId, "agents:create");
-      if (!allowed) {
-        throw forbidden("Missing permission: agents:create");
-      }
-      return null;
+    const decision = await access.decide({
+      actor: req.actor,
+      action: "agents:create",
+      resource: { type: "company", companyId },
+    });
+    if (!decision.allowed) {
+      throw forbidden(decision.explanation);
     }
-    if (!req.actor.agentId) throw forbidden("Agent authentication required");
-    const actorAgent = await svc.getById(req.actor.agentId);
+    if (req.actor.type !== "agent") return null;
+    const actorAgent = req.actor.agentId ? await svc.getById(req.actor.agentId) : null;
     if (!actorAgent || actorAgent.companyId !== companyId) {
       throw forbidden("Agent key cannot access another company");
     }
-    const allowedByGrant = await access.hasPermission(companyId, "agent", actorAgent.id, "agents:create");
-    if (!allowedByGrant && !canCreateAgents(actorAgent)) {
-      throw forbidden("Missing permission: can create agents");
-    }
     return actorAgent;
   }
 
   async function assertBoardCanManageAgentsForCompany(req: Request, companyId: string) {
     assertBoard(req);
     assertCompanyAccess(req, companyId);
-    if (req.actor.source === "local_implicit" || req.actor.isInstanceAdmin) return;
-    const allowed = await access.canUser(companyId, req.actor.userId, "agents:create");
-    if (!allowed) {
-      throw forbidden("Missing permission: agents:create");
-    }
+    const decision = await access.decide({
+      actor: req.actor,
+      action: "agents:create",
+      resource: { type: "company", companyId },
+    });
+    if (decision.allowed) return;
+    throw forbidden(decision.explanation);
   }
 
   async function assertCanReadConfigurations(req: Request, companyId: string) {
@@ -592,15 +599,12 @@ export function agentRoutes(
 
   async function actorCanReadConfigurationsForCompany(req: Request, companyId: string) {
     assertCompanyAccess(req, companyId);
-    if (req.actor.type === "board") {
-      if (req.actor.source === "local_implicit" || req.actor.isInstanceAdmin) return true;
-      return access.canUser(companyId, req.actor.userId, "agents:create");
-    }
-    if (!req.actor.agentId) return false;
-    const actorAgent = await svc.getById(req.actor.agentId);
-    if (!actorAgent || actorAgent.companyId !== companyId) return false;
-    const allowedByGrant = await access.hasPermission(companyId, "agent", actorAgent.id, "agents:create");
-    return allowedByGrant || canCreateAgents(actorAgent);
+    const decision = await access.decide({
+      actor: req.actor,
+      action: "agent_config:read",
+      resource: { type: "company", companyId },
+    });
+    return decision.allowed;
   }
 
   async function buildSkippedWakeupResponse(
@@ -672,27 +676,13 @@ export function agentRoutes(
 
   async function assertCanUpdateAgent(req: Request, targetAgent: { id: string; companyId: string }) {
     assertCompanyAccess(req, targetAgent.companyId);
-    if (req.actor.type === "board") {
-      await assertBoardCanManageAgentsForCompany(req, targetAgent.companyId);
-      return;
-    }
-    if (!req.actor.agentId) throw forbidden("Agent authentication required");
-
-    const actorAgent = await svc.getById(req.actor.agentId);
-    if (!actorAgent || actorAgent.companyId !== targetAgent.companyId) {
-      throw forbidden("Agent key cannot access another company");
-    }
-
-    if (actorAgent.id === targetAgent.id) return;
-    if (actorAgent.role === "ceo") return;
-    const allowedByGrant = await access.hasPermission(
-      targetAgent.companyId,
-      "agent",
-      actorAgent.id,
-      "agents:create",
-    );
-    if (allowedByGrant || canCreateAgents(actorAgent)) return;
-    throw forbidden("Only CEO or agent creators can modify other agents");
+    const decision = await access.decide({
+      actor: req.actor,
+      action: "agent_config:update",
+      resource: { type: "agent", companyId: targetAgent.companyId, agentId: targetAgent.id },
+    });
+    if (decision.allowed) return;
+    throw forbidden(decision.explanation);
   }
 
   async function assertCanReadAgent(req: Request, targetAgent: { companyId: string }) {

server/src/routes/companies.ts

@@ -271,7 +271,14 @@ export function companyRoutes(db: Db, storage?: StorageService) {
       throw forbidden("Instance admin required");
     }
     const company = await svc.create(req.body);
-    await access.ensureMembership(company.id, "user", req.actor.userId ?? "local-board", "owner", "active");
+    const ownerPrincipalId = req.actor.userId ?? "local-board";
+    await access.ensureMembership(company.id, "user", ownerPrincipalId, "owner", "active");
+    await access.ensureRoleDefaultGrants(
+      company.id,
+      ownerPrincipalId,
+      "owner",
+      req.actor.userId ?? null,
+    );
     await logActivity(db, {
       companyId: company.id,
       actorType: "user",

server/src/routes/issues.ts

@@ -1246,29 +1246,48 @@ export function issueRoutes(
     return (req.actor.companyIds ?? []).includes(companyId);
   }
 
-  function canCreateAgentsLegacy(agent: { permissions: Record<string, unknown> | null | undefined; role: string }) {
-    if (agent.role === "ceo") return true;
-    if (!agent.permissions || typeof agent.permissions !== "object") return false;
-    return Boolean((agent.permissions as Record<string, unknown>).canCreateAgents);
+  type TaskAssignmentAuthorizationScope = {
+    issueId?: string | null;
+    projectId?: string | null;
+    parentIssueId?: string | null;
+    assigneeAgentId?: string | null;
+    assigneeUserId?: string | null;
+  };
+
+  async function resolveAssignmentProjectId(input: {
+    companyId: string;
+    projectId: string | null | undefined;
+    parentIssueId?: string | null;
+  }) {
+    if (input.projectId !== undefined) return input.projectId;
+    if (!input.parentIssueId) return null;
+    const parent = await svc.getById(input.parentIssueId);
+    if (!parent || parent.companyId !== input.companyId) return null;
+    return parent.projectId ?? null;
   }
 
-  async function assertCanAssignTasks(req: Request, companyId: string) {
+  async function assertCanAssignTasks(
+    req: Request,
+    companyId: string,
+    assignmentScope?: TaskAssignmentAuthorizationScope,
+  ) {
     assertCompanyAccess(req, companyId);
-    if (req.actor.type === "board") {
-      if (req.actor.source === "local_implicit" || req.actor.isInstanceAdmin) return;
-      const allowed = await access.canUser(companyId, req.actor.userId, "tasks:assign");
-      if (!allowed) throw forbidden("Missing permission: tasks:assign");
-      return;
-    }
-    if (req.actor.type === "agent") {
-      if (!req.actor.agentId) throw forbidden("Agent authentication required");
-      const allowedByGrant = await access.hasPermission(companyId, "agent", req.actor.agentId, "tasks:assign");
-      if (allowedByGrant) return;
-      const actorAgent = await agentsSvc.getById(req.actor.agentId);
-      if (actorAgent && actorAgent.companyId === companyId && canCreateAgentsLegacy(actorAgent)) return;
-      throw forbidden("Missing permission: tasks:assign");
-    }
-    throw unauthorized();
+    const decision = await access.decide({
+      actor: req.actor,
+      action: "tasks:assign",
+      resource: {
+        type: "issue",
+        companyId,
+        issueId: assignmentScope?.issueId ?? null,
+        projectId: assignmentScope?.projectId ?? null,
+        parentIssueId: assignmentScope?.parentIssueId ?? null,
+        assigneeAgentId: assignmentScope?.assigneeAgentId ?? null,
+        assigneeUserId: assignmentScope?.assigneeUserId ?? null,
+      },
+      scope: assignmentScope ?? null,
+    });
+    if (decision.allowed) return;
+    throw forbidden(decision.explanation);
   }
 
   function requireAgentRunId(req: Request, res: Response) {
@@ -1284,31 +1303,12 @@ export function issueRoutes(
     companyId: string,
     assigneeAgentId: string,
   ) {
-    const allowedByGrant = await access.hasPermission(
-      companyId,
-      "agent",
-      actorAgentId,
-      "tasks:manage_active_checkouts",
-    );
-    if (allowedByGrant) return true;
-
-    const companyAgents = await agentsSvc.list(companyId);
-    const agentsById = new Map(companyAgents.map((agent) => [agent.id, agent]));
-    const actorAgent = agentsById.get(actorAgentId);
-    if (!actorAgent) return false;
-    if (canCreateAgentsLegacy(actorAgent)) return true;
-
-    // Reporting-chain managers may intervene in an agent's active checkout
-    // without taking the task over. Peers must own the checkout/run first.
-    let cursor: string | null = assigneeAgentId;
-    for (let depth = 0; cursor && depth < 50; depth += 1) {
-      const assignee = agentsById.get(cursor);
-      if (!assignee) return false;
-      if (assignee.reportsTo === actorAgentId) return true;
-      cursor = assignee.reportsTo;
-    }
-
-    return false;
+    const decision = await access.decide({
+      actor: { type: "agent", agentId: actorAgentId, companyId },
+      action: "tasks:manage_active_checkouts",
+      resource: { type: "issue", companyId, assigneeAgentId },
+    });
+    return decision.allowed;
   }
 
   async function assertAgentIssueMutationAllowed(
@@ -3146,7 +3146,16 @@ export function issueRoutes(
     assertNoAgentHostWorkspaceCommandMutation(req, collectIssueWorkspaceCommandPaths(req.body));
     if (!(await assertCheapRecoveryIssueAssigneeProfileAllowed(req, res, { companyId }, req.body))) return;
     if (req.body.assigneeAgentId || req.body.assigneeUserId) {
-      await assertCanAssignTasks(req, companyId);
+      await assertCanAssignTasks(req, companyId, {
+        projectId: await resolveAssignmentProjectId({
+          companyId,
+          projectId: req.body.projectId,
+          parentIssueId: req.body.parentId,
+        }),
+        parentIssueId: req.body.parentId ?? null,
+        assigneeAgentId: req.body.assigneeAgentId ?? null,
+        assigneeUserId: req.body.assigneeUserId ?? null,
+      });
     }
     await assertIssueEnvironmentSelection(companyId, req.body.executionWorkspaceSettings?.environmentId);
 
@@ -3242,7 +3251,12 @@ export function issueRoutes(
     assertNoAgentHostWorkspaceCommandMutation(req, collectIssueWorkspaceCommandPaths(req.body));
     if (!(await assertCheapRecoveryIssueAssigneeProfileAllowed(req, res, parent, req.body))) return;
     if (req.body.assigneeAgentId || req.body.assigneeUserId) {
-      await assertCanAssignTasks(req, parent.companyId);
+      await assertCanAssignTasks(req, parent.companyId, {
+        projectId: req.body.projectId ?? parent.projectId ?? null,
+        parentIssueId: parent.id,
+        assigneeAgentId: req.body.assigneeAgentId ?? null,
+        assigneeUserId: req.body.assigneeUserId ?? null,
+      });
     }
     await assertIssueEnvironmentSelection(parent.companyId, req.body.executionWorkspaceSettings?.environmentId);
 
@@ -3631,7 +3645,23 @@ export function issueRoutes(
 
     if (assigneeWillChange && !transition.workflowControlledAssignment) {
       if (!isAgentReturningIssueToCreator) {
-        await assertCanAssignTasks(req, existing.companyId);
+        await assertCanAssignTasks(req, existing.companyId, {
+          issueId: existing.id,
+          projectId: await resolveAssignmentProjectId({
+            companyId: existing.companyId,
+            projectId: updateFields.projectId === undefined
+              ? existing.projectId
+              : updateFields.projectId as string | null | undefined,
+            parentIssueId: (updateFields.parentId === undefined
+              ? existing.parentId
+              : updateFields.parentId) as string | null | undefined,
+          }),
+          parentIssueId: (updateFields.parentId === undefined
+            ? existing.parentId
+            : updateFields.parentId) as string | null | undefined,
+          assigneeAgentId: nextAssigneeAgentId,
+          assigneeUserId: nextAssigneeUserId,
+        });
       }
     }
 
@@ -4401,6 +4431,16 @@ export function issueRoutes(
       return;
     }
 
+    if (issue.assigneeAgentId !== req.body.agentId) {
+      await assertCanAssignTasks(req, issue.companyId, {
+        issueId: issue.id,
+        projectId: issue.projectId ?? null,
+        parentIssueId: issue.parentId ?? null,
+        assigneeAgentId: req.body.agentId,
+        assigneeUserId: null,
+      });
+    }
+
     const closedExecutionWorkspace = await getClosedIssueExecutionWorkspace(issue);
     if (closedExecutionWorkspace) {
       respondClosedIssueExecutionWorkspace(res, closedExecutionWorkspace);

server/src/routes/plugins.ts

@@ -1116,7 +1116,7 @@ export function pluginRoutes(
       return;
     }
 
-    assertPluginBridgeScope(req, body.companyId);
+    const companyId = assertPluginBridgeScope(req, body.companyId);
 
     try {
       const result = await bridgeDeps.workerManager.call(
@@ -1124,6 +1124,7 @@ export function pluginRoutes(
         "getData",
         {
           key: body.key,
+          ...(companyId ? { companyId } : {}),
           params: body.params ?? {},
           renderEnvironment: body.renderEnvironment ?? null,
         },
@@ -1208,7 +1209,7 @@ export function pluginRoutes(
       return;
     }
 
-    assertPluginBridgeScope(req, body.companyId);
+    const companyId = assertPluginBridgeScope(req, body.companyId);
 
     try {
       const result = await bridgeDeps.workerManager.call(
@@ -1216,6 +1217,7 @@ export function pluginRoutes(
         "performAction",
         {
           key: body.key,
+          ...(companyId ? { companyId } : {}),
           params: body.params ?? {},
           renderEnvironment: body.renderEnvironment ?? null,
         },
@@ -1301,7 +1303,7 @@ export function pluginRoutes(
       renderEnvironment?: PluginLauncherRenderContextSnapshot | null;
     } | undefined;
 
-    assertPluginBridgeScope(req, body?.companyId);
+    const companyId = assertPluginBridgeScope(req, body?.companyId);
 
     try {
       const result = await bridgeDeps.workerManager.call(
@@ -1309,6 +1311,7 @@ export function pluginRoutes(
         "getData",
         {
           key,
+          ...(companyId ? { companyId } : {}),
           params: body?.params ?? {},
           renderEnvironment: body?.renderEnvironment ?? null,
         },
@@ -1390,7 +1393,7 @@ export function pluginRoutes(
       renderEnvironment?: PluginLauncherRenderContextSnapshot | null;
     } | undefined;
 
-    assertPluginBridgeScope(req, body?.companyId);
+    const companyId = assertPluginBridgeScope(req, body?.companyId);
 
     try {
       const result = await bridgeDeps.workerManager.call(
@@ -1398,6 +1401,7 @@ export function pluginRoutes(
         "performAction",
         {
           key,
+          ...(companyId ? { companyId } : {}),
           params: body?.params ?? {},
           renderEnvironment: body?.renderEnvironment ?? null,
         },

server/src/services/access.ts

@@ -9,6 +9,8 @@ import {
 } from "@paperclipai/db";
 import type { PermissionKey, PrincipalType } from "@paperclipai/shared";
 import { conflict } from "../errors.js";
+import { authorizationService, type AuthorizationActor, type AuthorizationResource } from "./authorization.js";
+import { ensureHumanRoleDefaultGrants } from "./principal-access-compatibility.js";
 
 type MembershipRow = typeof companyMemberships.$inferSelect;
 type GrantInput = {
@@ -24,6 +26,8 @@ type MemberArchiveInput = {
 };
 
 export function accessService(db: Db) {
+  const authorization = authorizationService(db);
+
   async function isInstanceAdmin(userId: string | null | undefined): Promise<boolean> {
     if (!userId) return false;
     const row = await db
@@ -58,21 +62,13 @@ export function accessService(db: Db) {
     principalId: string,
     permissionKey: PermissionKey,
   ): Promise<boolean> {
-    const membership = await getMembership(companyId, principalType, principalId);
-    if (!membership || membership.status !== "active") return false;
-    const grant = await db
-      .select({ id: principalPermissionGrants.id })
-      .from(principalPermissionGrants)
-      .where(
-        and(
-          eq(principalPermissionGrants.companyId, companyId),
-          eq(principalPermissionGrants.principalType, principalType),
-          eq(principalPermissionGrants.principalId, principalId),
-          eq(principalPermissionGrants.permissionKey, permissionKey),
-        ),
-      )
-      .then((rows) => rows[0] ?? null);
-    return Boolean(grant);
+    return authorization.decidePrincipalGrant({
+      companyId,
+      principalType,
+      principalId,
+      permissionKey,
+      action: permissionKey,
+    }).then((decision) => decision.allowed);
   }
 
   async function canUser(
@@ -80,9 +76,20 @@ export function accessService(db: Db) {
     userId: string | null | undefined,
     permissionKey: PermissionKey,
   ): Promise<boolean> {
-    if (!userId) return false;
-    if (await isInstanceAdmin(userId)) return true;
-    return hasPermission(companyId, "user", userId, permissionKey);
+    return authorization.decide({
+      actor: { type: "board", userId },
+      action: permissionKey,
+      resource: { type: "company", companyId },
+    }).then((decision) => decision.allowed);
+  }
+
+  async function decide(input: {
+    actor: AuthorizationActor;
+    action: Parameters<typeof authorization.decide>[0]["action"];
+    resource: AuthorizationResource;
+    scope?: Record<string, unknown> | null;
+  }) {
+    return authorization.decide(input);
   }
 
   async function listMembers(companyId: string) {
@@ -616,10 +623,30 @@ export function accessService(db: Db) {
         membership.membershipRole,
         "active",
       );
+      await ensureHumanRoleDefaultGrants(db, {
+        companyId: targetCompanyId,
+        principalId: membership.principalId,
+        membershipRole: membership.membershipRole,
+        grantedByUserId: null,
+      });
     }
     return sourceMemberships;
   }
 
+  async function ensureRoleDefaultGrants(
+    companyId: string,
+    principalId: string,
+    membershipRole: string | null | undefined,
+    grantedByUserId: string | null,
+  ) {
+    return ensureHumanRoleDefaultGrants(db, {
+      companyId,
+      principalId,
+      membershipRole,
+      grantedByUserId,
+    });
+  }
+
   async function listPrincipalGrants(
     companyId: string,
     principalType: PrincipalType,
@@ -768,6 +795,7 @@ export function accessService(db: Db) {
 
   return {
     isInstanceAdmin,
+    decide,
     canUser,
     hasPermission,
     getMembership,
@@ -776,6 +804,7 @@ export function accessService(db: Db) {
     listMembers,
     listActiveUserMemberships,
     copyActiveUserMemberships,
+    ensureRoleDefaultGrants,
     archiveMember,
     setMemberPermissions,
     updateMemberAndPermissions,

server/src/services/agent-permissions.ts

@@ -18,7 +18,9 @@ export function normalizeAgentPermissions(
   }
 
   const record = permissions as Record<string, unknown>;
+  const preserved = { ...record };
   return {
+    ...preserved,
     canCreateAgents:
       typeof record.canCreateAgents === "boolean"
         ? record.canCreateAgents

server/src/services/agents.ts

@@ -554,7 +554,7 @@ export function agentService(db: Db) {
       const updated = await db
         .update(agents)
         .set({
-          permissions: normalizeAgentPermissions(permissions, existing.role),
+          permissions: normalizeAgentPermissions({ ...existing.permissions, ...permissions }, existing.role),
           updatedAt: new Date(),
         })
         .where(eq(agents.id, id))

server/src/services/authorization.ts

@@ -0,0 +1,823 @@
+import { and, eq } from "drizzle-orm";
+import type { Db } from "@paperclipai/db";
+import {
+  agents,
+  companyMemberships,
+  instanceUserRoles,
+  issues,
+  principalPermissionGrants,
+  projects,
+} from "@paperclipai/db";
+import type { PermissionKey, PrincipalType } from "@paperclipai/shared";
+
+export type AuthorizationActor =
+  {
+    type: "board" | "agent" | "none";
+    userId?: string | null;
+    companyIds?: string[];
+    memberships?: Array<{ companyId: string; membershipRole?: string | null; status?: string }>;
+    isInstanceAdmin?: boolean;
+    agentId?: string | null;
+    companyId?: string | null;
+    source?:
+      | "local_implicit"
+      | "session"
+      | "board_key"
+      | "agent_key"
+      | "agent_jwt"
+      | "cloud_tenant"
+      | "none";
+  };
+
+export type AuthorizationAction =
+  | PermissionKey
+  | "agent_config:read"
+  | "agent_config:update"
+  | "issue:mutate";
+
+export type AuthorizationResource =
+  | { type: "company"; companyId: string }
+  | { type: "agent"; companyId: string; agentId?: string | null }
+  | {
+      type: "issue";
+      companyId: string;
+      issueId?: string | null;
+      projectId?: string | null;
+      parentIssueId?: string | null;
+      assigneeAgentId?: string | null;
+      assigneeUserId?: string | null;
+      status?: string | null;
+    };
+
+export type AuthorizationDecision = {
+  allowed: boolean;
+  action: AuthorizationAction;
+  explanation: string;
+  reason:
+    | "allow_local_board"
+    | "allow_instance_admin"
+    | "allow_explicit_grant"
+    | "allow_legacy_agent_creator"
+    | "allow_self"
+    | "allow_company_agent"
+    | "allow_simple_company_member"
+    | "allow_manager_chain"
+    | "deny_unauthenticated"
+    | "deny_company_boundary"
+    | "deny_missing_membership"
+    | "deny_missing_grant"
+    | "deny_policy_restricted"
+    | "deny_scope"
+    | "deny_unsupported_action";
+  grant?: {
+    principalType: PrincipalType;
+    principalId: string;
+    permissionKey: PermissionKey;
+    scope: Record<string, unknown> | null;
+  };
+};
+
+type PrincipalGrantDecision = AuthorizationDecision & {
+  grant?: NonNullable<AuthorizationDecision["grant"]>;
+};
+
+function companyIdForResource(resource: AuthorizationResource) {
+  return resource.companyId;
+}
+
+function permissionForAction(action: AuthorizationAction): PermissionKey | null {
+  if (action === "agent_config:read" || action === "agent_config:update") return "agents:create";
+  if (action === "issue:mutate") return null;
+  return action;
+}
+
+function canCreateAgentsLegacy(agent: { role: string; permissions: Record<string, unknown> | null | undefined }) {
+  if (agent.role === "ceo") return true;
+  if (!agent.permissions || typeof agent.permissions !== "object") return false;
+  return Boolean(agent.permissions.canCreateAgents);
+}
+
+function scopeValueList(value: unknown): string[] {
+  if (typeof value === "string" && value.trim()) return [value.trim()];
+  if (!Array.isArray(value)) return [];
+  return value
+    .filter((entry): entry is string => typeof entry === "string" && entry.trim().length > 0)
+    .map((entry) => entry.trim());
+}
+
+function prefixedScopeValues(grantScope: Record<string, unknown>, prefix: string) {
+  return scopeValueList(grantScope.allow)
+    .filter((rule) => rule.startsWith(prefix))
+    .map((rule) => rule.slice(prefix.length))
+    .filter((value) => value.length > 0);
+}
+
+function scopeValuesForKeys(grantScope: Record<string, unknown>, keys: string[]) {
+  return keys.flatMap((key) => scopeValueList(grantScope[key]));
+}
+
+function scopeIncludesId(ids: string[], id: string | null | undefined) {
+  return Boolean(id && ids.includes(id));
+}
+
+function isSimpleAssignableAgentStatus(status: string | null | undefined) {
+  return status !== "pending_approval" && status !== "terminated";
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function objectIsEmpty(value: Record<string, unknown>) {
+  return Object.keys(value).length === 0;
+}
+
+function readPolicyObject(container: unknown, key: string): Record<string, unknown> | null {
+  if (!isPlainRecord(container)) return null;
+  const value = container[key];
+  return isPlainRecord(value) ? value : null;
+}
+
+function readString(value: unknown): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+function readBoolean(value: unknown): boolean | null {
+  return typeof value === "boolean" ? value : null;
+}
+
+type AssignmentPolicyEffect =
+  | { kind: "none" }
+  | { kind: "restricted"; explanation: string }
+  | { kind: "requires_approval"; explanation: string }
+  | { kind: "unknown"; explanation: string };
+
+type AgentHierarchyRow = { id: string; reportsTo: string | null };
+
+function evaluateAuthorizationPolicyForAssignment(
+  policy: Record<string, unknown> | null | undefined,
+  label: string,
+): AssignmentPolicyEffect {
+  if (!policy || objectIsEmpty(policy)) return { kind: "none" };
+
+  const agentVisibility = readPolicyObject(policy, "agentVisibility");
+  const assignmentPolicy = readPolicyObject(policy, "assignmentPolicy");
+  const protectedAgent = readPolicyObject(policy, "protectedAgent");
+  const knownTopLevelKeys = new Set([
+    "agentVisibility",
+    "assignmentPolicy",
+    "protectedAgent",
+    "managedBy",
+  ]);
+  const hasUnknownTopLevelKey = Object.keys(policy).some((key) => !knownTopLevelKeys.has(key));
+  const hasKnownPolicySection = Boolean(agentVisibility || assignmentPolicy || protectedAgent);
+  if (hasUnknownTopLevelKey || !hasKnownPolicySection) {
+    return {
+      kind: "unknown",
+      explanation: `${label} has authorization policy data that core cannot evaluate for task assignment.`,
+    };
+  }
+
+  const visibilityMode = readString(agentVisibility?.mode);
+  if (visibilityMode && visibilityMode !== "discoverable" && visibilityMode !== "private") {
+    return {
+      kind: "unknown",
+      explanation: `${label} has an unsupported agent visibility policy mode.`,
+    };
+  }
+
+  const assignmentMode = readString(assignmentPolicy?.mode);
+  if (assignmentMode && assignmentMode !== "company_default" && assignmentMode !== "protected") {
+    return {
+      kind: "unknown",
+      explanation: `${label} has an unsupported assignment policy mode.`,
+    };
+  }
+
+  const requiresApproval =
+    readBoolean(protectedAgent?.requiresApproval) === true ||
+    readBoolean(assignmentPolicy?.protectedAgentRequiresApproval) === true;
+  if (requiresApproval) {
+    return {
+      kind: "requires_approval",
+      explanation: `${label} requires approval before task assignment.`,
+    };
+  }
+
+  if (
+    visibilityMode === "private" ||
+    readBoolean(agentVisibility?.hiddenFromDefaultDirectory) === true
+  ) {
+    return {
+      kind: "restricted",
+      explanation: `${label} is private and cannot use simple company-wide task assignment.`,
+    };
+  }
+
+  if (assignmentMode === "protected") {
+    return {
+      kind: "restricted",
+      explanation: `${label} is protected and requires an explicit assignment grant.`,
+    };
+  }
+
+  return { kind: "none" };
+}
+
+function agentIsInSubtree(
+  agentsById: Map<string, AgentHierarchyRow>,
+  rootAgentId: string,
+  targetAgentId: string,
+) {
+  if (rootAgentId === targetAgentId) return true;
+
+  let cursor: string | null = targetAgentId;
+  for (let depth = 0; cursor && depth < 50; depth += 1) {
+    const current = agentsById.get(cursor);
+    if (!current) return false;
+    if (current.reportsTo === rootAgentId) return true;
+    cursor = current.reportsTo;
+  }
+  return false;
+}
+
+async function loadCompanyAgentHierarchy(db: Db, companyId: string) {
+  const rows = await db
+    .select({ id: agents.id, reportsTo: agents.reportsTo })
+    .from(agents)
+    .where(eq(agents.companyId, companyId));
+  return new Map(rows.map((agent) => [agent.id, agent]));
+}
+
+async function isAgentInSubtree(db: Db, companyId: string, rootAgentId: string, targetAgentId: string) {
+  return agentIsInSubtree(
+    await loadCompanyAgentHierarchy(db, companyId),
+    rootAgentId,
+    targetAgentId,
+  );
+}
+
+async function scopeAllows(
+  db: Db,
+  companyId: string,
+  grantScope: Record<string, unknown> | null,
+  requestedScope: Record<string, unknown> | null | undefined,
+  options: { requireStructuredScope?: boolean } = {},
+) {
+  if (!grantScope || Object.keys(grantScope).length === 0) return !options.requireStructuredScope;
+  if (!requestedScope) return false;
+
+  const targetAssigneeAgentId =
+    typeof requestedScope.assigneeAgentId === "string"
+      ? requestedScope.assigneeAgentId
+      : typeof requestedScope.targetAgentId === "string"
+        ? requestedScope.targetAgentId
+        : null;
+  const requestedProjectId = typeof requestedScope.projectId === "string" ? requestedScope.projectId : null;
+  let constrained = false;
+
+  const projectIds = [
+    ...scopeValueList(grantScope.projectId),
+    ...scopeValueList(grantScope.projectIds),
+    ...prefixedScopeValues(grantScope, "project:"),
+  ];
+  if (projectIds.length > 0) {
+    constrained = true;
+    if (!scopeIncludesId(projectIds, requestedProjectId)) return false;
+  }
+
+  const targetAgentIds = [
+    ...scopeValuesForKeys(grantScope, [
+      "agentId",
+      "agentIds",
+      "assigneeAgentId",
+      "assigneeAgentIds",
+      "targetAgentId",
+      "targetAgentIds",
+    ]),
+    ...prefixedScopeValues(grantScope, "agent:"),
+  ];
+  if (targetAgentIds.length > 0) {
+    constrained = true;
+    if (!scopeIncludesId(targetAgentIds, targetAssigneeAgentId)) return false;
+  }
+
+  const subtreeRootAgentIds = [
+    ...scopeValuesForKeys(grantScope, [
+      "managerAgentId",
+      "managerAgentIds",
+      "managedSubtreeAgentId",
+      "managedSubtreeAgentIds",
+      "subtreeAgentId",
+      "subtreeAgentIds",
+      "subtreeRootAgentId",
+      "subtreeRootAgentIds",
+    ]),
+    ...prefixedScopeValues(grantScope, "subtree:"),
+  ];
+  if (subtreeRootAgentIds.length > 0) {
+    constrained = true;
+    if (!targetAssigneeAgentId) return false;
+    const agentsById = await loadCompanyAgentHierarchy(db, companyId);
+    let matchesSubtree = false;
+    for (const rootAgentId of subtreeRootAgentIds) {
+      if (agentIsInSubtree(agentsById, rootAgentId, targetAssigneeAgentId)) {
+        matchesSubtree = true;
+        break;
+      }
+    }
+    if (!matchesSubtree) return false;
+  }
+
+  // Unknown metadata keys do not constrain the grant. Recognized constraints
+  // return false above when they fail to match the requested assignment scope.
+  return !constrained ? true : constrained;
+}
+
+function allow(input: Omit<AuthorizationDecision, "allowed">): AuthorizationDecision {
+  return { ...input, allowed: true };
+}
+
+function deny(input: Omit<AuthorizationDecision, "allowed">): AuthorizationDecision {
+  return { ...input, allowed: false };
+}
+
+export function authorizationService(db: Db) {
+  async function isInstanceAdmin(userId: string | null | undefined): Promise<boolean> {
+    if (!userId) return false;
+    if (
+      await db
+        .select({ id: instanceUserRoles.id })
+        .from(instanceUserRoles)
+        .where(and(eq(instanceUserRoles.userId, userId), eq(instanceUserRoles.role, "instance_admin")))
+        .then((rows) => rows[0] ?? null)
+    ) {
+      return true;
+    }
+    return false;
+  }
+
+  async function getActiveMembership(
+    companyId: string,
+    principalType: PrincipalType,
+    principalId: string,
+  ) {
+    return db
+      .select()
+      .from(companyMemberships)
+      .where(
+        and(
+          eq(companyMemberships.companyId, companyId),
+          eq(companyMemberships.principalType, principalType),
+          eq(companyMemberships.principalId, principalId),
+          eq(companyMemberships.status, "active"),
+        ),
+      )
+      .then((rows) => rows[0] ?? null);
+  }
+
+  async function findGrant(
+    companyId: string,
+    principalType: PrincipalType,
+    principalId: string,
+    permissionKey: PermissionKey,
+  ) {
+    return db
+      .select()
+      .from(principalPermissionGrants)
+      .where(
+        and(
+          eq(principalPermissionGrants.companyId, companyId),
+          eq(principalPermissionGrants.principalType, principalType),
+          eq(principalPermissionGrants.principalId, principalId),
+          eq(principalPermissionGrants.permissionKey, permissionKey),
+        ),
+      )
+      .then((rows) => rows[0] ?? null);
+  }
+
+  async function decidePrincipalGrant(input: {
+    companyId: string;
+    principalType: PrincipalType;
+    principalId: string;
+    action: AuthorizationAction;
+    permissionKey: PermissionKey;
+    scope?: Record<string, unknown> | null;
+  }): Promise<PrincipalGrantDecision> {
+    const membership = await getActiveMembership(input.companyId, input.principalType, input.principalId);
+    if (!membership) {
+      return deny({
+        action: input.action,
+        reason: "deny_missing_membership",
+        explanation: `${input.principalType} principal ${input.principalId} is not an active member of company ${input.companyId}.`,
+      });
+    }
+
+    const grant = await findGrant(input.companyId, input.principalType, input.principalId, input.permissionKey);
+    if (!grant) {
+      return deny({
+        action: input.action,
+        reason: "deny_missing_grant",
+        explanation: `Missing permission: ${input.permissionKey}.`,
+      });
+    }
+
+    if (
+      !(await scopeAllows(db, input.companyId, grant.scope, input.scope, {
+        requireStructuredScope: input.permissionKey === "tasks:assign_scope",
+      }))
+    ) {
+      return deny({
+        action: input.action,
+        reason: "deny_scope",
+        explanation: `Permission ${input.permissionKey} does not cover the requested scope.`,
+        grant: {
+          principalType: input.principalType,
+          principalId: input.principalId,
+          permissionKey: input.permissionKey,
+          scope: grant.scope ?? null,
+        },
+      });
+    }
+
+    return allow({
+      action: input.action,
+      reason: "allow_explicit_grant",
+      explanation: `Allowed by explicit grant ${input.permissionKey}.`,
+      grant: {
+        principalType: input.principalType,
+        principalId: input.principalId,
+        permissionKey: input.permissionKey,
+        scope: grant.scope ?? null,
+      },
+    });
+  }
+
+  async function loadAgent(agentId: string) {
+    return db
+      .select({
+        id: agents.id,
+        companyId: agents.companyId,
+        role: agents.role,
+        status: agents.status,
+        reportsTo: agents.reportsTo,
+        permissions: agents.permissions,
+      })
+      .from(agents)
+      .where(eq(agents.id, agentId))
+      .then((rows) => rows[0] ?? null);
+  }
+
+  async function loadProjectAuthorizationPolicy(companyId: string, projectId: string) {
+    const row = await db
+      .select({ executionWorkspacePolicy: projects.executionWorkspacePolicy })
+      .from(projects)
+      .where(and(eq(projects.id, projectId), eq(projects.companyId, companyId)))
+      .then((rows) => rows[0] ?? null);
+    return readPolicyObject(row?.executionWorkspacePolicy, "authorizationPolicy");
+  }
+
+  async function loadIssueAuthorizationPolicy(companyId: string, issueId: string) {
+    const row = await db
+      .select({ executionPolicy: issues.executionPolicy })
+      .from(issues)
+      .where(and(eq(issues.id, issueId), eq(issues.companyId, companyId)))
+      .then((rows) => rows[0] ?? null);
+    return readPolicyObject(row?.executionPolicy, "authorizationPolicy");
+  }
+
+  async function assignmentTargetIsInCompany(resource: AuthorizationResource) {
+    if (resource.type !== "issue") return true;
+    if (resource.assigneeAgentId) {
+      const target = await loadAgent(resource.assigneeAgentId);
+      return Boolean(
+        target &&
+        target.companyId === resource.companyId &&
+        isSimpleAssignableAgentStatus(target.status),
+      );
+    }
+    if (resource.assigneeUserId) {
+      return Boolean(await getActiveMembership(resource.companyId, "user", resource.assigneeUserId));
+    }
+    return true;
+  }
+
+  async function assignmentPolicyEffect(resource: AuthorizationResource): Promise<AssignmentPolicyEffect> {
+    if (resource.type !== "issue") return { kind: "none" };
+
+    const checks: Array<Promise<AssignmentPolicyEffect>> = [];
+    if (resource.assigneeAgentId) {
+      checks.push(
+        loadAgent(resource.assigneeAgentId).then((agent) =>
+          evaluateAuthorizationPolicyForAssignment(
+            readPolicyObject(agent?.permissions, "authorizationPolicy"),
+            "Target agent",
+          ),
+        ),
+      );
+    }
+    if (resource.projectId) {
+      checks.push(
+        loadProjectAuthorizationPolicy(resource.companyId, resource.projectId).then((policy) =>
+          evaluateAuthorizationPolicyForAssignment(policy, "Target project"),
+        ),
+      );
+    }
+    if (resource.issueId) {
+      checks.push(
+        loadIssueAuthorizationPolicy(resource.companyId, resource.issueId).then((policy) =>
+          evaluateAuthorizationPolicyForAssignment(policy, "Target issue"),
+        ),
+      );
+    }
+    if (resource.parentIssueId && resource.parentIssueId !== resource.issueId) {
+      checks.push(
+        loadIssueAuthorizationPolicy(resource.companyId, resource.parentIssueId).then((policy) =>
+          evaluateAuthorizationPolicyForAssignment(policy, "Parent issue"),
+        ),
+      );
+    }
+    if (checks.length === 0) return { kind: "none" };
+
+    const effects = await Promise.all(checks);
+    return (
+      effects.find((effect) => effect.kind === "unknown") ??
+      effects.find((effect) => effect.kind === "requires_approval") ??
+      effects.find((effect) => effect.kind === "restricted") ??
+      { kind: "none" }
+    );
+  }
+
+  async function isManagerOf(companyId: string, managerAgentId: string, assigneeAgentId: string) {
+    return isAgentInSubtree(db, companyId, managerAgentId, assigneeAgentId);
+  }
+
+  async function decide(input: {
+    actor: AuthorizationActor;
+    action: AuthorizationAction;
+    resource: AuthorizationResource;
+    scope?: Record<string, unknown> | null;
+  }): Promise<AuthorizationDecision> {
+    const permissionKey = permissionForAction(input.action);
+    const companyId = companyIdForResource(input.resource);
+
+    async function decideWithTaskAssignmentGrants(
+      principalType: PrincipalType,
+      principalId: string,
+    ): Promise<AuthorizationDecision> {
+      const broadDecision = await decidePrincipalGrant({
+        companyId,
+        principalType,
+        principalId,
+        action: input.action,
+        permissionKey: "tasks:assign",
+        scope: input.scope,
+      });
+      if (broadDecision.allowed || broadDecision.reason === "deny_missing_membership") return broadDecision;
+      const scopedDecision = await decidePrincipalGrant({
+        companyId,
+        principalType,
+        principalId,
+        action: input.action,
+        permissionKey: "tasks:assign_scope",
+        scope: input.scope,
+      });
+      if (scopedDecision.allowed || broadDecision.reason === "deny_missing_grant") return scopedDecision;
+      return broadDecision;
+    }
+
+    async function denyForAssignmentPolicyIfNeeded(
+      policyEffect: AssignmentPolicyEffect,
+    ): Promise<AuthorizationDecision | null> {
+      if (policyEffect.kind === "none" || policyEffect.kind === "restricted") return null;
+      return deny({
+        action: input.action,
+        reason: "deny_policy_restricted",
+        explanation: policyEffect.explanation,
+      });
+    }
+
+    function denyRestrictedAssignmentPolicy(policyEffect: AssignmentPolicyEffect): AuthorizationDecision {
+      return deny({
+        action: input.action,
+        reason: "deny_policy_restricted",
+        explanation:
+          policyEffect.kind === "restricted"
+            ? policyEffect.explanation
+            : "Restrictive authorization policy blocks simple company-wide task assignment.",
+      });
+    }
+
+    if (input.actor.type === "none") {
+      return deny({
+        action: input.action,
+        reason: "deny_unauthenticated",
+        explanation: "Authentication required.",
+      });
+    }
+
+    if (input.actor.type === "board") {
+      let taskAssignmentPolicyEffect: AssignmentPolicyEffect | null = null;
+      if (input.actor.source === "local_implicit") {
+        return allow({
+          action: input.action,
+          reason: "allow_local_board",
+          explanation: "Allowed because the actor is the local implicit board.",
+        });
+      }
+      if (input.actor.isInstanceAdmin || await isInstanceAdmin(input.actor.userId)) {
+        return allow({
+          action: input.action,
+          reason: "allow_instance_admin",
+          explanation: "Allowed because the actor is an instance admin.",
+        });
+      }
+      if (!input.actor.userId) {
+        return deny({
+          action: input.action,
+          reason: "deny_unauthenticated",
+          explanation: "Board user id is required.",
+        });
+      }
+      if (input.action === "tasks:assign") {
+        if (!(await assignmentTargetIsInCompany(input.resource))) {
+          return deny({
+            action: input.action,
+            reason: "deny_company_boundary",
+            explanation: "Task assignment target agent is not active in the target company.",
+          });
+        }
+        const policyEffect = await assignmentPolicyEffect(input.resource);
+        taskAssignmentPolicyEffect = policyEffect;
+        const policyDeny = await denyForAssignmentPolicyIfNeeded(policyEffect);
+        if (policyDeny) return policyDeny;
+        const membership = await getActiveMembership(companyId, "user", input.actor.userId);
+        if (policyEffect.kind === "none" && membership && membership.membershipRole !== "viewer") {
+          return allow({
+            action: input.action,
+            reason: "allow_simple_company_member",
+            explanation: "Allowed by simple mode company-wide task assignment default.",
+          });
+        }
+      }
+      if (!permissionKey) {
+        return deny({
+          action: input.action,
+          reason: "deny_unsupported_action",
+          explanation: `No board permission mapping exists for ${input.action}.`,
+        });
+      }
+      if (input.action === "tasks:assign") {
+        const grantDecision = await decideWithTaskAssignmentGrants("user", input.actor.userId);
+        if (grantDecision.allowed) return grantDecision;
+        const policyEffect = taskAssignmentPolicyEffect ?? await assignmentPolicyEffect(input.resource);
+        if (policyEffect.kind === "restricted") return denyRestrictedAssignmentPolicy(policyEffect);
+        return grantDecision;
+      }
+      return decidePrincipalGrant({
+        companyId,
+        principalType: "user",
+        principalId: input.actor.userId,
+        action: input.action,
+        permissionKey,
+        scope: input.scope,
+      });
+    }
+
+    const actorAgentId = input.actor.agentId ?? null;
+    if (!actorAgentId) {
+      return deny({
+        action: input.action,
+        reason: "deny_unauthenticated",
+        explanation: "Agent authentication required.",
+      });
+    }
+    if (input.actor.companyId !== companyId) {
+      return deny({
+        action: input.action,
+        reason: "deny_company_boundary",
+        explanation: "Agent key cannot access another company.",
+      });
+    }
+
+    const actorAgent = await loadAgent(actorAgentId);
+    if (!actorAgent || actorAgent.companyId !== companyId) {
+      return deny({
+        action: input.action,
+        reason: "deny_company_boundary",
+        explanation: "Actor agent was not found in the target company.",
+      });
+    }
+
+    if (input.action === "tasks:assign") {
+      if (!isSimpleAssignableAgentStatus(actorAgent.status)) {
+        return deny({
+          action: input.action,
+          reason: "deny_missing_membership",
+          explanation: "Actor agent is not active for simple mode task assignment.",
+        });
+      }
+      if (!(await assignmentTargetIsInCompany(input.resource))) {
+        return deny({
+          action: input.action,
+          reason: "deny_company_boundary",
+          explanation: "Task assignment target agent is not active in the target company.",
+        });
+      }
+      const policyEffect = await assignmentPolicyEffect(input.resource);
+      const policyDeny = await denyForAssignmentPolicyIfNeeded(policyEffect);
+      if (policyDeny) return policyDeny;
+      if (policyEffect.kind === "restricted") {
+        const grantDecision = await decideWithTaskAssignmentGrants("agent", actorAgentId);
+        if (grantDecision.allowed) return grantDecision;
+        return denyRestrictedAssignmentPolicy(policyEffect);
+      }
+      return allow({
+        action: input.action,
+        reason: "allow_simple_company_member",
+        explanation: "Allowed by simple mode company-wide task assignment default.",
+      });
+    }
+
+    if (input.action === "issue:mutate") {
+      const resource = input.resource.type === "issue" ? input.resource : null;
+      if (resource?.assigneeAgentId === actorAgentId) {
+        return allow({
+          action: input.action,
+          reason: "allow_self",
+          explanation: "Allowed because the actor owns the assigned issue.",
+        });
+      }
+      if (!resource?.assigneeAgentId) {
+        return allow({
+          action: input.action,
+          reason: "allow_company_agent",
+          explanation: "Allowed because the issue has no agent assignee.",
+        });
+      }
+    }
+    if (
+      input.action === "agent_config:update" &&
+      input.resource.type === "agent" &&
+      input.resource.agentId === actorAgentId
+    ) {
+      return allow({
+        action: input.action,
+        reason: "allow_self",
+        explanation: "Allowed because the actor is updating its own agent configuration.",
+      });
+    }
+
+    if (permissionKey) {
+      const grantDecision = await decidePrincipalGrant({
+        companyId,
+        principalType: "agent",
+        principalId: actorAgentId,
+        action: input.action,
+        permissionKey,
+        scope: input.scope,
+      });
+      if (grantDecision.allowed) return grantDecision;
+    }
+
+    if (
+      (input.action === "agents:create" ||
+        input.action === "agent_config:read" ||
+        input.action === "agent_config:update" ||
+        input.action === "tasks:manage_active_checkouts") &&
+      canCreateAgentsLegacy(actorAgent)
+    ) {
+      return allow({
+        action: input.action,
+        reason: "allow_legacy_agent_creator",
+        explanation: "Allowed by legacy agent creator authority.",
+      });
+    }
+
+    if (
+      input.action === "tasks:manage_active_checkouts" &&
+      input.resource.type === "issue" &&
+      input.resource.assigneeAgentId &&
+      await isManagerOf(companyId, actorAgentId, input.resource.assigneeAgentId)
+    ) {
+      return allow({
+        action: input.action,
+        reason: "allow_manager_chain",
+        explanation: "Allowed because the actor manages the issue assignee in the reporting chain.",
+      });
+    }
+
+    return deny({
+      action: input.action,
+      reason: "deny_missing_grant",
+      explanation: permissionKey
+        ? `Missing permission: ${permissionKey}.`
+        : `No agent permission mapping exists for ${input.action}.`,
+    });
+  }
+
+  return {
+    decide,
+    decidePrincipalGrant,
+  };
+}

server/src/services/company-member-roles.ts

@@ -28,6 +28,7 @@ export function grantsForHumanRole(
     case "owner":
       return [
         { permissionKey: "agents:create", scope: null },
+        { permissionKey: "environments:manage", scope: null },
         { permissionKey: "users:invite", scope: null },
         { permissionKey: "users:manage_permissions", scope: null },
         { permissionKey: "tasks:assign", scope: null },
@@ -36,6 +37,7 @@ export function grantsForHumanRole(
     case "admin":
       return [
         { permissionKey: "agents:create", scope: null },
+        { permissionKey: "environments:manage", scope: null },
         { permissionKey: "users:invite", scope: null },
         { permissionKey: "tasks:assign", scope: null },
         { permissionKey: "joins:approve", scope: null },

server/src/services/company-portability.ts

@@ -4118,7 +4118,14 @@ export function companyPortabilityService(db: Db, storage?: StorageService) {
       if (mode === "agent_safe" && options?.sourceCompanyId) {
         await access.copyActiveUserMemberships(options.sourceCompanyId, created.id);
       } else {
-        await access.ensureMembership(created.id, "user", actorUserId ?? "board", "owner", "active");
+        const ownerPrincipalId = actorUserId ?? "board";
+        await access.ensureMembership(created.id, "user", ownerPrincipalId, "owner", "active");
+        await access.ensureRoleDefaultGrants(
+          created.id,
+          ownerPrincipalId,
+          "owner",
+          actorUserId ?? null,
+        );
       }
       targetCompany = created;
       companyAction = "created";

server/src/services/index.ts

@@ -44,6 +44,19 @@ export { sidebarBadgeService } from "./sidebar-badges.js";
 export { sidebarPreferenceService } from "./sidebar-preferences.js";
 export { inboxDismissalService } from "./inbox-dismissals.js";
 export { accessService } from "./access.js";
+export {
+  backfillPrincipalAccessCompatibility,
+  ensureHumanRoleDefaultGrants,
+  insertMissingPrincipalGrants,
+  type PrincipalAccessCompatibilityBackfillStats,
+} from "./principal-access-compatibility.js";
+export { authorizationService } from "./authorization.js";
+export type {
+  AuthorizationAction,
+  AuthorizationActor,
+  AuthorizationDecision,
+  AuthorizationResource,
+} from "./authorization.js";
 export { boardAuthService } from "./board-auth.js";
 export { instanceSettingsService } from "./instance-settings.js";
 export { companyPortabilityService } from "./company-portability.js";

server/src/services/plugin-capability-validator.ts

@@ -149,6 +149,7 @@ const UI_SLOT_CAPABILITIES: Record<PluginUiSlotType, PluginCapability> = {
   commentAnnotation: "ui.commentAnnotation.register",
   commentContextMenuItem: "ui.action.register",
   settingsPage: "instance.settings.register",
+  companySettingsPage: "instance.settings.register",
   routeSidebar: "ui.sidebar.register",
 };
 

server/src/services/plugin-host-services.ts

@@ -1,14 +1,18 @@
 import type { Db } from "@paperclipai/db";
 import {
+  activityLog,
   agentTaskSessions as agentTaskSessionsTable,
   agents as agentsTable,
   budgetIncidents,
   costEvents,
   heartbeatRuns,
+  invites,
   issues as issuesTable,
   pluginLogs,
+  principalPermissionGrants,
+  projects as projectsTable,
 } from "@paperclipai/db";
-import { eq, and, like, desc, inArray, sql } from "drizzle-orm";
+import { eq, and, like, desc, inArray, sql, isNull, isNotNull, gt, lte } from "drizzle-orm";
 import type {
   HostServices,
   Company,
@@ -22,7 +26,7 @@ import type {
   PluginIssueOrchestrationSummary,
   PluginExecutionWorkspaceMetadata,
 } from "@paperclipai/plugin-sdk";
-import type { CreateIssueThreadInteraction, IssueDocumentSummary } from "@paperclipai/shared";
+import type { CreateIssueThreadInteraction, InviteJoinType, IssueDocumentSummary, PermissionKey, PrincipalType } from "@paperclipai/shared";
 import { pluginOperationIssueOriginKind } from "@paperclipai/shared";
 import { companyService } from "./companies.js";
 import { agentService } from "./agents.js";
@@ -36,11 +40,8 @@ import { heartbeatService } from "./heartbeat.js";
 import { budgetService } from "./budgets.js";
 import { issueApprovalService } from "./issue-approvals.js";
 import { subscribeCompanyLiveEvents } from "./live-events.js";
-import { randomUUID } from "node:crypto";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
 import path from "node:path";
-import { activityService } from "./activity.js";
-import { costService } from "./costs.js";
-import { assetService } from "./assets.js";
 import { pluginRegistryService } from "./plugin-registry.js";
 import { pluginStateStore } from "./plugin-state-store.js";
 import { pluginDatabaseService } from "./plugin-database.js";
@@ -71,6 +72,9 @@ import { request as httpsRequest } from "node:https";
 import { isIP } from "node:net";
 import { logger } from "../middleware/logger.js";
 import { getTelemetryClient } from "../telemetry.js";
+import { accessService } from "./access.js";
+import { authorizationService, type AuthorizationActor } from "./authorization.js";
+import { sanitizeRecord } from "../redaction.js";
 
 // ---------------------------------------------------------------------------
 // SSRF protection for plugin HTTP fetch
@@ -526,11 +530,10 @@ export function buildHostServices(
   const issues = issueService(db);
   const documents = documentService(db);
   const goals = goalService(db);
-  const activity = activityService(db);
-  const costs = costService(db);
+  const access = accessService(db);
+  const authorization = authorizationService(db);
   const budgets = budgetService(db);
   const issueApprovals = issueApprovalService(db);
-  const assets = assetService(db);
   const scopedBus = eventBus.forPlugin(pluginKey);
 
   // Track active session event subscriptions for cleanup
@@ -562,6 +565,17 @@ export function buildHostServices(
     return rows.slice(offset, offset + limit);
   };
 
+  const authorizationAuditDecisionCondition = (decisionFilter: string) => {
+    const conditions = [
+      sql`lower(${activityLog.details}->>'decision') = ${decisionFilter}`,
+      decisionFilter === "allow" ? sql`left(coalesce(${activityLog.details}->>'reason', ''), 6) = 'allow_'` : undefined,
+      decisionFilter === "deny" ? sql`left(coalesce(${activityLog.details}->>'reason', ''), 5) = 'deny_'` : undefined,
+      decisionFilter === "allow" ? sql`${activityLog.details}->>'allowed' = 'true'` : undefined,
+      decisionFilter === "deny" ? sql`${activityLog.details}->>'allowed' = 'false'` : undefined,
+    ].filter((condition): condition is NonNullable<typeof condition> => Boolean(condition));
+    return sql`(${sql.join(conditions, sql` OR `)})`;
+  };
+
   /**
    * Plugins are instance-wide in the current runtime. Company IDs are still
    * required for company-scoped data access, but there is no per-company
@@ -841,6 +855,202 @@ export function buildHostServices(
     }));
   };
 
+  const INVITE_TOKEN_PREFIX = "pcp_invite_";
+  const INVITE_TOKEN_ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789";
+  const INVITE_TOKEN_SUFFIX_LENGTH = 8;
+  const INVITE_TOKEN_MAX_RETRIES = 5;
+  const COMPANY_INVITE_TTL_MS = 72 * 60 * 60 * 1000;
+
+  const hashToken = (token: string) => createHash("sha256").update(token).digest("hex");
+
+  const createInviteToken = () => {
+    const bytes = randomBytes(INVITE_TOKEN_SUFFIX_LENGTH);
+    let suffix = "";
+    for (let idx = 0; idx < INVITE_TOKEN_SUFFIX_LENGTH; idx += 1) {
+      suffix += INVITE_TOKEN_ALPHABET[bytes[idx]! % INVITE_TOKEN_ALPHABET.length];
+    }
+    return `${INVITE_TOKEN_PREFIX}${suffix}`;
+  };
+
+  const isInviteTokenHashCollisionError = (error: unknown) => {
+    const candidates = [
+      error,
+      (error as { cause?: unknown } | null)?.cause ?? null,
+    ];
+    for (const candidate of candidates) {
+      if (!candidate || typeof candidate !== "object") continue;
+      const code = "code" in candidate && typeof candidate.code === "string" ? candidate.code : null;
+      const message = "message" in candidate && typeof candidate.message === "string" ? candidate.message : "";
+      const constraint = "constraint" in candidate && typeof candidate.constraint === "string" ? candidate.constraint : null;
+      if (code !== "23505") continue;
+      if (constraint === "invites_token_hash_unique_idx") return true;
+      if (message.includes("invites_token_hash_unique_idx")) return true;
+    }
+    return false;
+  };
+
+  const inviteState = (invite: typeof invites.$inferSelect) => {
+    if (invite.revokedAt) return "revoked" as const;
+    if (invite.acceptedAt) return "accepted" as const;
+    if (invite.expiresAt <= new Date()) return "expired" as const;
+    return "active" as const;
+  };
+
+  const redactInvite = (invite: typeof invites.$inferSelect) => {
+    const { tokenHash: _tokenHash, defaultsPayload, ...safeInvite } = invite;
+    return {
+      ...safeInvite,
+      allowedJoinTypes: safeInvite.allowedJoinTypes as InviteJoinType,
+      defaultsPayload: defaultsPayload && typeof defaultsPayload === "object"
+        ? sanitizeRecord(defaultsPayload)
+        : defaultsPayload ?? null,
+      state: inviteState(invite),
+    };
+  };
+
+  const inviteStateWhereClause = (state: unknown) => {
+    const now = new Date();
+    switch (state) {
+      case "active":
+        return and(isNull(invites.revokedAt), isNull(invites.acceptedAt), gt(invites.expiresAt, now));
+      case "accepted":
+        return isNotNull(invites.acceptedAt);
+      case "expired":
+        return and(isNull(invites.revokedAt), isNull(invites.acceptedAt), lte(invites.expiresAt, now));
+      case "revoked":
+        return isNotNull(invites.revokedAt);
+      default:
+        return undefined;
+    }
+  };
+
+  const mergeInviteDefaults = (defaultsPayload: Record<string, unknown> | null | undefined, agentMessage: string | null, humanRole: string | null) => {
+    const defaults = defaultsPayload && typeof defaultsPayload === "object"
+      ? { ...defaultsPayload }
+      : {};
+    if (humanRole) {
+      defaults.human = {
+        ...(typeof defaults.human === "object" && defaults.human !== null ? defaults.human as Record<string, unknown> : {}),
+        role: humanRole,
+      };
+    }
+    if (agentMessage) {
+      defaults.agent = {
+        ...(typeof defaults.agent === "object" && defaults.agent !== null ? defaults.agent as Record<string, unknown> : {}),
+        message: agentMessage,
+      };
+    }
+    return sanitizeRecord(defaults);
+  };
+
+  const redactGrant = (grant: typeof principalPermissionGrants.$inferSelect) => ({
+    ...grant,
+    principalType: grant.principalType as PrincipalType,
+    permissionKey: grant.permissionKey as PermissionKey,
+    scope: grant.scope && typeof grant.scope === "object" ? sanitizeRecord(grant.scope) : grant.scope ?? null,
+  });
+
+  const loadPluginMember = async (companyId: string, memberId: string) => {
+    const member = await access.getMemberById(companyId, memberId);
+    if (!member) return null;
+    const grants = await access.listPrincipalGrants(
+      companyId,
+      member.principalType as PrincipalType,
+      member.principalId,
+    );
+    return {
+      ...member,
+      principalType: member.principalType as PrincipalType,
+      status: member.status as "pending" | "active" | "suspended" | "archived",
+      grants: grants.map(redactGrant),
+    };
+  };
+
+  const pluginAssignmentActor = (actor: {
+    type: "agent" | "board";
+    agentId?: string | null;
+    companyId?: string | null;
+    userId?: string | null;
+    companyIds?: string[];
+  }): AuthorizationActor => {
+    if (actor.type === "agent") {
+      return {
+        type: "agent",
+        agentId: actor.agentId ?? null,
+        companyId: actor.companyId ?? null,
+        source: "agent_key",
+      };
+    }
+    return {
+      type: "board",
+      userId: actor.userId ?? null,
+      companyIds: Array.isArray(actor.companyIds) ? actor.companyIds : [],
+      source: "session",
+    };
+  };
+
+  const policyPathForResource = (resourceType: "company" | "agent" | "project" | "issue") => {
+    switch (resourceType) {
+      case "agent":
+        return { table: "agent" as const };
+      case "project":
+        return { table: "project" as const };
+      case "issue":
+        return { table: "issue" as const };
+      case "company":
+        return { table: "company" as const };
+    }
+  };
+
+  const readAuthorizationPolicy = async (companyId: string, resourceType: "company" | "agent" | "project" | "issue", resourceId: string) => {
+    const pathInfo = policyPathForResource(resourceType);
+    if (pathInfo.table === "agent") {
+      const agent = await agents.getById(resourceId);
+      if (!inCompany(agent, companyId)) return null;
+      const permissions = agent.permissions && typeof agent.permissions === "object" ? agent.permissions as Record<string, unknown> : {};
+      return {
+        resourceType,
+        resourceId,
+        companyId,
+        policy: permissions.authorizationPolicy && typeof permissions.authorizationPolicy === "object"
+          ? sanitizeRecord(permissions.authorizationPolicy as Record<string, unknown>)
+          : null,
+        updatedAt: agent.updatedAt,
+      };
+    }
+    if (pathInfo.table === "project") {
+      const project = await projects.getById(resourceId);
+      if (!inCompany(project, companyId)) return null;
+      const policy = project.executionWorkspacePolicy && typeof project.executionWorkspacePolicy === "object"
+        ? (project.executionWorkspacePolicy as unknown as Record<string, unknown>).authorizationPolicy
+        : null;
+      return {
+        resourceType,
+        resourceId,
+        companyId,
+        policy: policy && typeof policy === "object" ? sanitizeRecord(policy as Record<string, unknown>) : null,
+        updatedAt: project.updatedAt,
+      };
+    }
+    if (pathInfo.table === "issue") {
+      const issue = await issues.getById(resourceId);
+      if (!inCompany(issue, companyId)) return null;
+      const policy = issue.executionPolicy && typeof issue.executionPolicy === "object"
+        ? (issue.executionPolicy as Record<string, unknown>).authorizationPolicy
+        : null;
+      return {
+        resourceType,
+        resourceId,
+        companyId,
+        policy: policy && typeof policy === "object" ? sanitizeRecord(policy as Record<string, unknown>) : null,
+        updatedAt: issue.updatedAt,
+      };
+    }
+    const company = await companies.getById(resourceId);
+    if (!company || company.id !== companyId) return null;
+    return { resourceType, resourceId, companyId, policy: null, updatedAt: company.updatedAt };
+  };
+
   return {
     config: {
       async get() {
@@ -1993,6 +2203,337 @@ export function buildHostServices(
       },
     },
 
+    access: {
+      async listMembers(params) {
+        const companyId = ensureCompanyId(params.companyId);
+        await ensurePluginAvailableForCompany(companyId);
+        const rows = await access.listMembers(companyId);
+        const visibleRows = params.includeArchived ? rows : rows.filter((row) => row.status !== "archived");
+        const grants = await db
+          .select()
+          .from(principalPermissionGrants)
+          .where(eq(principalPermissionGrants.companyId, companyId));
+        const grantsByPrincipal = new Map<string, typeof grants>();
+        for (const grant of grants) {
+          const key = `${grant.principalType}:${grant.principalId}`;
+          const existing = grantsByPrincipal.get(key) ?? [];
+          existing.push(grant);
+          grantsByPrincipal.set(key, existing);
+        }
+        return visibleRows.map((member) => ({
+          ...member,
+          principalType: member.principalType as PrincipalType,
+          status: member.status as "pending" | "active" | "suspended" | "archived",
+          grants: (grantsByPrincipal.get(`${member.principalType}:${member.principalId}`) ?? []).map(redactGrant),
+        }));
+      },
+      async getMember(params) {
+        const companyId = ensureCompanyId(params.companyId);
+        await ensurePluginAvailableForCompany(companyId);
+        return loadPluginMember(companyId, params.memberId);
+      },
+      async updateMember(params) {
+        const companyId = ensureCompanyId(params.companyId);
+        await ensurePluginAvailableForCompany(companyId);
+        const updated = await access.updateMember(companyId, params.memberId, params.patch);
+        if (!updated) throw new Error("Member not found");
+        await logPluginActivity({
+          companyId,
+          action: "company_member.updated_by_plugin",
+          entityType: "company_membership",
+          entityId: params.memberId,
+          details: {
+            patch: sanitizeRecord(params.patch as Record<string, unknown>),
+          },
+        });
+        return (await loadPluginMember(companyId, params.memberId))!;
+      },
+      async listInvites(params) {
+        const companyId = ensureCompanyId(params.companyId);
+        await ensurePluginAvailableForCompany(companyId);
+        const limit = Math.min(Math.max(Number(params.limit ?? 20), 1), 100);
+        const offset = Math.max(Number(params.offset ?? 0), 0);
+        const stateClause = inviteStateWhereClause(params.state);
+        const rows = await db
+          .select()
+          .from(invites)
+          .where(stateClause ? and(eq(invites.companyId, companyId), stateClause) : eq(invites.companyId, companyId))
+          .orderBy(desc(invites.createdAt))
+          .limit(limit + 1)
+          .offset(offset);
+        const hasMore = rows.length > limit;
+        return {
+          invites: rows.slice(0, limit).map(redactInvite),
+          nextOffset: hasMore ? offset + limit : null,
+        };
+      },
+      async createInvite(params) {
+        const companyId = ensureCompanyId(params.companyId);
+        await ensurePluginAvailableForCompany(companyId);
+        const normalizedAgentMessage = typeof params.agentMessage === "string"
+          ? params.agentMessage.trim() || null
+          : null;
+        const allowedJoinTypes = params.allowedJoinTypes ?? "both";
+        const humanRole = allowedJoinTypes === "agent" ? null : params.humanRole ?? "operator";
+        const insertValues = {
+          companyId,
+          inviteType: "company_join" as const,
+          allowedJoinTypes,
+          defaultsPayload: mergeInviteDefaults(params.defaultsPayload ?? null, normalizedAgentMessage, humanRole),
+          expiresAt: new Date(Date.now() + COMPANY_INVITE_TTL_MS),
+          invitedByUserId: null,
+        };
+        let token: string | null = null;
+        let created: typeof invites.$inferSelect | null = null;
+        for (let attempt = 0; attempt < INVITE_TOKEN_MAX_RETRIES; attempt += 1) {
+          const candidateToken = createInviteToken();
+          try {
+            created = await db
+              .insert(invites)
+              .values({
+                ...insertValues,
+                tokenHash: hashToken(candidateToken),
+              })
+              .returning()
+              .then((rows) => rows[0] ?? null);
+            token = candidateToken;
+            break;
+          } catch (error) {
+            if (!isInviteTokenHashCollisionError(error)) throw error;
+          }
+        }
+        if (!token || !created) throw new Error("Failed to generate a unique invite token");
+        await logPluginActivity({
+          companyId,
+          action: "invite.created_by_plugin",
+          entityType: "invite",
+          entityId: created.id,
+          details: {
+            allowedJoinTypes: created.allowedJoinTypes,
+            expiresAt: created.expiresAt.toISOString(),
+            hasAgentMessage: Boolean(normalizedAgentMessage),
+          },
+        });
+        return { ...redactInvite(created), token };
+      },
+      async revokeInvite(params) {
+        const companyId = ensureCompanyId(params.companyId);
+        await ensurePluginAvailableForCompany(companyId);
+        const invite = await db
+          .select()
+          .from(invites)
+          .where(and(eq(invites.id, params.inviteId), eq(invites.companyId, companyId)))
+          .then((rows) => rows[0] ?? null);
+        if (!invite) throw new Error("Invite not found");
+        if (invite.acceptedAt) throw new Error("Invite already consumed");
+        if (invite.revokedAt) return redactInvite(invite);
+        const revoked = await db
+          .update(invites)
+          .set({ revokedAt: new Date(), updatedAt: new Date() })
+          .where(eq(invites.id, invite.id))
+          .returning()
+          .then((rows) => rows[0] ?? invite);
+        await logPluginActivity({
+          companyId,
+          action: "invite.revoked_by_plugin",
+          entityType: "invite",
+          entityId: invite.id,
+        });
+        return redactInvite(revoked);
+      },
+    },
+
+    authorization: {
+      async listGrants(params) {
+        const companyId = ensureCompanyId(params.companyId);
+        await ensurePluginAvailableForCompany(companyId);
+        const conditions = [
+          eq(principalPermissionGrants.companyId, companyId),
+          params.principalType ? eq(principalPermissionGrants.principalType, params.principalType) : undefined,
+          params.principalId ? eq(principalPermissionGrants.principalId, params.principalId) : undefined,
+        ].filter((condition): condition is NonNullable<typeof condition> => Boolean(condition));
+        const rows = await db
+          .select()
+          .from(principalPermissionGrants)
+          .where(and(...conditions))
+          .orderBy(principalPermissionGrants.principalType, principalPermissionGrants.principalId, principalPermissionGrants.permissionKey);
+        return rows.map(redactGrant);
+      },
+      async setGrants(params) {
+        const companyId = ensureCompanyId(params.companyId);
+        await ensurePluginAvailableForCompany(companyId);
+        if (params.principalType !== "agent" && params.principalType !== "user") {
+          throw new Error("principalType must be 'agent' or 'user'");
+        }
+        if (params.principalType === "agent") {
+          requireInCompany("Agent", await agents.getById(params.principalId), companyId);
+        } else {
+          const membership = await access.getMembership(companyId, params.principalType as PrincipalType, params.principalId);
+          if (!membership) throw new Error("Principal is not a member of this company");
+        }
+        await access.setPrincipalGrants(
+          companyId,
+          params.principalType as PrincipalType,
+          params.principalId,
+          params.grants.map((grant) => ({
+            permissionKey: grant.permissionKey as PermissionKey,
+            scope: grant.scope ? sanitizeRecord(grant.scope) : null,
+          })),
+          params.grantedByUserId ?? null,
+        );
+        await logPluginActivity({
+          companyId,
+          action: "authorization.grants_updated_by_plugin",
+          entityType: "principal_permission_grants",
+          entityId: `${params.principalType}:${params.principalId}`,
+          details: { grantCount: params.grants.length },
+        });
+        return access
+          .listPrincipalGrants(companyId, params.principalType as PrincipalType, params.principalId)
+          .then((rows) => rows.map(redactGrant));
+      },
+      async policySummary(params) {
+        const companyId = ensureCompanyId(params.companyId);
+        await ensurePluginAvailableForCompany(companyId);
+        const [members, grants] = await Promise.all([
+          access.listMembers(companyId),
+          db
+            .select({ id: principalPermissionGrants.id })
+            .from(principalPermissionGrants)
+            .where(eq(principalPermissionGrants.companyId, companyId)),
+        ]);
+        return {
+          companyId,
+          permissionsMode: "simple" as const,
+          memberCount: members.length,
+          activeMemberCount: members.filter((member) => member.status === "active").length,
+          grantCount: grants.length,
+          advancedPolicyAvailable: false as const,
+        };
+      },
+      async getPolicy(params) {
+        const companyId = ensureCompanyId(params.companyId);
+        await ensurePluginAvailableForCompany(companyId);
+        return readAuthorizationPolicy(companyId, params.resourceType, params.resourceId);
+      },
+      async updatePolicy(params) {
+        const companyId = ensureCompanyId(params.companyId);
+        await ensurePluginAvailableForCompany(companyId);
+        const policy = params.policy ? sanitizeRecord(params.policy) : null;
+        if (params.resourceType === "agent") {
+          const agent = requireInCompany("Agent", await agents.getById(params.resourceId), companyId);
+          const permissions = agent.permissions && typeof agent.permissions === "object"
+            ? { ...(agent.permissions as Record<string, unknown>) }
+            : {};
+          if (policy) permissions.authorizationPolicy = policy;
+          else delete permissions.authorizationPolicy;
+          await db
+            .update(agentsTable)
+            .set({ permissions, updatedAt: new Date() })
+            .where(eq(agentsTable.id, agent.id));
+        } else if (params.resourceType === "project") {
+          const project = requireInCompany("Project", await projects.getById(params.resourceId), companyId);
+          const executionWorkspacePolicy = project.executionWorkspacePolicy && typeof project.executionWorkspacePolicy === "object"
+            ? { ...(project.executionWorkspacePolicy as unknown as Record<string, unknown>) }
+            : {};
+          if (policy) executionWorkspacePolicy.authorizationPolicy = policy;
+          else delete executionWorkspacePolicy.authorizationPolicy;
+          await db
+            .update(projectsTable)
+            .set({ executionWorkspacePolicy, updatedAt: new Date() })
+            .where(eq(projectsTable.id, project.id));
+        } else if (params.resourceType === "issue") {
+          const issue = requireInCompany("Issue", await issues.getById(params.resourceId), companyId);
+          const executionPolicy = issue.executionPolicy && typeof issue.executionPolicy === "object"
+            ? { ...(issue.executionPolicy as Record<string, unknown>) }
+            : {};
+          if (policy) executionPolicy.authorizationPolicy = policy;
+          else delete executionPolicy.authorizationPolicy;
+          await db
+            .update(issuesTable)
+            .set({ executionPolicy, updatedAt: new Date() })
+            .where(eq(issuesTable.id, issue.id));
+        } else {
+          const company = await companies.getById(params.resourceId);
+          if (!company || company.id !== companyId) throw new Error("Company not found");
+          throw new Error("Company authorization policy updates are not supported by the current core schema");
+        }
+        await logPluginActivity({
+          companyId,
+          action: "authorization.policy_updated_by_plugin",
+          entityType: params.resourceType,
+          entityId: params.resourceId,
+          details: { hasPolicy: Boolean(policy) },
+        });
+        const updated = await readAuthorizationPolicy(companyId, params.resourceType, params.resourceId);
+        if (!updated) throw new Error("Policy resource not found");
+        return updated;
+      },
+      async previewAssignment(params) {
+        const companyId = ensureCompanyId(params.companyId);
+        await ensurePluginAvailableForCompany(companyId);
+        return authorization.decide({
+          actor: pluginAssignmentActor(params.actor),
+          action: "tasks:assign",
+          resource: { type: "issue", companyId, ...params.target },
+          scope: {
+            issueId: params.target.issueId ?? null,
+            projectId: params.target.projectId ?? null,
+            parentIssueId: params.target.parentIssueId ?? null,
+            assigneeAgentId: params.target.assigneeAgentId ?? null,
+            assigneeUserId: params.target.assigneeUserId ?? null,
+          },
+        });
+      },
+      async explainAssignment(params) {
+        const companyId = ensureCompanyId(params.companyId);
+        await ensurePluginAvailableForCompany(companyId);
+        return authorization.decide({
+          actor: pluginAssignmentActor(params.actor),
+          action: "tasks:assign",
+          resource: { type: "issue", companyId, ...params.target },
+          scope: {
+            issueId: params.target.issueId ?? null,
+            projectId: params.target.projectId ?? null,
+            parentIssueId: params.target.parentIssueId ?? null,
+            assigneeAgentId: params.target.assigneeAgentId ?? null,
+            assigneeUserId: params.target.assigneeUserId ?? null,
+          },
+        });
+      },
+      async searchAudit(params) {
+        const companyId = ensureCompanyId(params.companyId);
+        await ensurePluginAvailableForCompany(companyId);
+        const limit = Math.min(Math.max(Number(params.limit ?? 50), 1), 100);
+        const offset = Math.max(Number(params.offset ?? 0), 0);
+        const decisionFilter = typeof params.decision === "string" && params.decision.trim()
+          ? params.decision.trim().toLowerCase()
+          : null;
+        const conditions = [
+          eq(activityLog.companyId, companyId),
+          params.action ? eq(activityLog.action, params.action) : undefined,
+          params.actorType ? eq(activityLog.actorType, params.actorType) : undefined,
+          params.actorId ? eq(activityLog.actorId, params.actorId) : undefined,
+          params.entityType ? eq(activityLog.entityType, params.entityType) : undefined,
+          params.entityId ? eq(activityLog.entityId, params.entityId) : undefined,
+          decisionFilter ? authorizationAuditDecisionCondition(decisionFilter) : undefined,
+        ].filter((condition): condition is NonNullable<typeof condition> => Boolean(condition));
+        const rows = await db
+          .select()
+          .from(activityLog)
+          .where(and(...conditions))
+          .orderBy(desc(activityLog.createdAt))
+          .limit(limit)
+          .offset(offset);
+        return rows.map((row) => ({
+          ...row,
+          details: row.details && typeof row.details === "object"
+            ? sanitizeRecord(row.details)
+            : row.details ?? null,
+        }));
+      },
+    },
+
     agentSessions: {
       async create(params) {
         const companyId = ensureCompanyId(params.companyId);

server/src/services/plugin-worker-manager.ts

@@ -19,6 +19,7 @@
  */
 
 import { fork, type ChildProcess } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import { EventEmitter } from "node:events";
 import { createInterface, type Interface as ReadlineInterface } from "node:readline";
 import type { PaperclipPluginManifestV1 } from "@paperclipai/shared";
@@ -39,9 +40,12 @@ import {
 } from "@paperclipai/plugin-sdk";
 import type {
   JsonRpcId,
+  PluginInvocationContext,
+  PluginInvocationScope,
   JsonRpcResponse,
   JsonRpcRequest,
   JsonRpcNotification,
+  WorkerHostCallContext,
   HostToWorkerMethodName,
   HostToWorkerMethods,
   WorkerToHostMethodName,
@@ -108,6 +112,7 @@ export type WorkerStatus =
  */
 export type WorkerToHostHandler<M extends WorkerToHostMethodName> = (
   params: WorkerToHostMethods[M][0],
+  context?: WorkerHostCallContext,
 ) => Promise<WorkerToHostMethods[M][1]>;
 
 /**
@@ -201,6 +206,11 @@ interface PendingRequest {
   sentAt: number;
 }
 
+interface ActiveInvocation {
+  scope: PluginInvocationScope;
+  timer?: ReturnType<typeof setTimeout>;
+}
+
 // ---------------------------------------------------------------------------
 // PluginWorkerHandle — manages a single worker process
 // ---------------------------------------------------------------------------
@@ -379,6 +389,7 @@ export function createPluginWorkerHandle(
   // Pending RPC requests awaiting a response
   const pendingRequests = new Map<string | number, PendingRequest>();
   let nextRequestId = 1;
+  const activeInvocations = new Map<string, ActiveInvocation>();
 
   // Optional methods reported by the worker during initialization
   let supportedMethods: string[] = [];
@@ -475,13 +486,78 @@ export function createPluginWorkerHandle(
     pending.resolve(response);
   }
 
+  function readNonEmptyString(value: unknown): string | null {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+  }
+
+  function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+  }
+
+  function deriveInvocationScope(
+    method: HostToWorkerMethodName | string,
+    params: unknown,
+  ): PluginInvocationScope | null {
+    if (!isRecord(params)) return null;
+
+    const directCompanyId = readNonEmptyString(params.companyId);
+    if (directCompanyId) return { companyId: directCompanyId };
+
+    if (method === "executeTool" && isRecord(params.runContext)) {
+      const companyId = readNonEmptyString(params.runContext.companyId);
+      return companyId ? { companyId } : null;
+    }
+
+    if (method === "onEvent" && isRecord(params.event)) {
+      const companyId = readNonEmptyString(params.event.companyId);
+      return companyId ? { companyId } : null;
+    }
+
+    return null;
+  }
+
+  function registerInvocation(scope: PluginInvocationScope, ttlMs?: number): PluginInvocationContext {
+    const invocation: PluginInvocationContext = {
+      id: randomUUID(),
+      scope,
+    };
+    const entry: ActiveInvocation = { scope };
+    if (ttlMs !== undefined) {
+      entry.timer = setTimeout(() => {
+        activeInvocations.delete(invocation.id);
+      }, ttlMs);
+      if (entry.timer.unref) entry.timer.unref();
+    }
+    activeInvocations.set(invocation.id, entry);
+    return invocation;
+  }
+
+  function clearInvocation(invocation: PluginInvocationContext | null): void {
+    if (!invocation) return;
+    const entry = activeInvocations.get(invocation.id);
+    if (entry?.timer) clearTimeout(entry.timer);
+    activeInvocations.delete(invocation.id);
+  }
+
+  function contextForWorkerMessage(message: JsonRpcRequest | JsonRpcNotification): WorkerHostCallContext {
+    const invocationId = readNonEmptyString(
+      (message as { paperclipInvocationId?: unknown }).paperclipInvocationId,
+    );
+    if (!invocationId) {
+      return activeInvocations.size > 0 ? { invalidInvocationScope: true } : {};
+    }
+    const entry = activeInvocations.get(invocationId);
+    if (!entry) return { invalidInvocationScope: true };
+    return { invocationScope: entry.scope };
+  }
+
   /**
    * Handle a JSON-RPC request from the worker (worker→host call).
    */
   async function handleWorkerRequest(request: JsonRpcRequest): Promise<void> {
     const method = request.method as WorkerToHostMethodName;
     const handler = options.hostHandlers[method] as
-      | ((params: unknown) => Promise<unknown>)
+      | ((params: unknown, context?: WorkerHostCallContext) => Promise<unknown>)
       | undefined;
 
     if (!handler) {
@@ -501,7 +577,7 @@ export function createPluginWorkerHandle(
     }
 
     try {
-      const result = await handler(request.params);
+      const result = await handler(request.params, contextForWorkerMessage(request));
       sendMessage({
         jsonrpc: JSONRPC_VERSION,
         id: request.id,
@@ -509,12 +585,15 @@ export function createPluginWorkerHandle(
       });
     } catch (err) {
       const errorMessage = err instanceof Error ? err.message : String(err);
+      const errorCode = typeof (err as { code?: unknown }).code === "number"
+        ? (err as { code: number }).code
+        : JSONRPC_ERROR_CODES.INTERNAL_ERROR;
       log.error({ method, err: errorMessage }, "host handler error");
       try {
         sendMessage(
           createErrorResponse(
             request.id,
-            JSONRPC_ERROR_CODES.INTERNAL_ERROR,
+            errorCode,
             errorMessage,
           ),
         );
@@ -572,12 +651,28 @@ export function createPluginWorkerHandle(
       notification.method === "streams.close"
     ) {
       const params = (notification.params ?? {}) as Record<string, unknown>;
+      const companyId = String(params.companyId ?? "");
+      const context = contextForWorkerMessage(notification);
+      if (context.invalidInvocationScope) {
+        log.warn(
+          { method: notification.method, companyId },
+          "dropping plugin stream notification with invalid invocation scope",
+        );
+        return;
+      }
+      const allowedCompanyId = context.invocationScope?.companyId;
+      if (allowedCompanyId && companyId !== allowedCompanyId) {
+        log.warn(
+          { method: notification.method, companyId, allowedCompanyId },
+          "dropping plugin stream notification outside invocation company scope",
+        );
+        return;
+      }
 
       // Track open channels so we can emit synthetic close on crash
       if (notification.method === "streams.open") {
         const ch = String(params.channel ?? "");
-        const co = String(params.companyId ?? "");
-        if (ch) openStreamChannels.set(ch, co);
+        if (ch) openStreamChannels.set(ch, companyId);
       } else if (notification.method === "streams.close") {
         openStreamChannels.delete(String(params.channel ?? ""));
       }
@@ -760,6 +855,10 @@ export function createPluginWorkerHandle(
       );
     }
     pendingRequests.clear();
+    for (const invocation of activeInvocations.values()) {
+      if (invocation.timer) clearTimeout(invocation.timer);
+    }
+    activeInvocations.clear();
   }
 
   // -----------------------------------------------------------------------
@@ -1020,6 +1119,8 @@ export function createPluginWorkerHandle(
 
       const id = nextRequestId++;
       const timeout = Math.min(timeoutMs ?? rpcTimeoutMs, MAX_RPC_TIMEOUT_MS);
+      const invocationScope = deriveInvocationScope(method, params);
+      const invocation = invocationScope ? registerInvocation(invocationScope) : null;
 
       // Guard against double-settlement. When a process exits all pending
       // requests are rejected via rejectAllPending(), but the timeout timer
@@ -1032,6 +1133,7 @@ export function createPluginWorkerHandle(
         settled = true;
         clearTimeout(timer);
         pendingRequests.delete(id);
+        clearInvocation(invocation);
         fn(value);
       };
 
@@ -1064,11 +1166,15 @@ export function createPluginWorkerHandle(
       pendingRequests.set(id, pending);
 
       try {
-        const request = createRequest(method, params, id);
+        const request = {
+          ...createRequest(method, params, id),
+          ...(invocation ? { paperclipInvocation: invocation } : {}),
+        };
         sendMessage(request);
       } catch (err) {
         clearTimeout(timer);
         pendingRequests.delete(id);
+        clearInvocation(invocation);
         reject(
           new Error(
             `Failed to send "${method}" to worker: ${
@@ -1135,13 +1241,17 @@ export function createPluginWorkerHandle(
 
     notify(method: string, params: unknown) {
       if (status !== "running") return;
+      const invocationScope = deriveInvocationScope(method, params);
+      const invocation = invocationScope ? registerInvocation(invocationScope, MAX_RPC_TIMEOUT_MS) : null;
       try {
         sendMessage({
           jsonrpc: JSONRPC_VERSION,
           method,
           params,
+          ...(invocation ? { paperclipInvocation: invocation } : {}),
         });
       } catch {
+        clearInvocation(invocation);
         log.warn({ method }, "failed to send notification to worker");
       }
     },

server/src/services/principal-access-compatibility.ts

@@ -0,0 +1,141 @@
+import { and, eq, notInArray } from "drizzle-orm";
+import type { Db } from "@paperclipai/db";
+import { agents, companyMemberships, principalPermissionGrants } from "@paperclipai/db";
+import type { PermissionKey, PrincipalType } from "@paperclipai/shared";
+import { grantsForHumanRole, normalizeHumanRole } from "./company-member-roles.js";
+
+type GrantInput = {
+  permissionKey: PermissionKey;
+  scope?: Record<string, unknown> | null;
+};
+
+export type PrincipalAccessCompatibilityBackfillStats = {
+  agentMembershipsInserted: number;
+  humanGrantsInserted: number;
+};
+
+export async function insertMissingPrincipalGrants(
+  db: Db,
+  input: {
+    companyId: string;
+    principalType: PrincipalType;
+    principalId: string;
+    grants: GrantInput[];
+    grantedByUserId: string | null;
+  },
+): Promise<number> {
+  if (input.grants.length === 0) return 0;
+
+  const now = new Date();
+  const inserted = await db
+    .insert(principalPermissionGrants)
+    .values(
+      input.grants.map((grant) => ({
+        companyId: input.companyId,
+        principalType: input.principalType,
+        principalId: input.principalId,
+        permissionKey: grant.permissionKey,
+        scope: grant.scope ?? null,
+        grantedByUserId: input.grantedByUserId,
+        createdAt: now,
+        updatedAt: now,
+      })),
+    )
+    .onConflictDoNothing({
+      target: [
+        principalPermissionGrants.companyId,
+        principalPermissionGrants.principalType,
+        principalPermissionGrants.principalId,
+        principalPermissionGrants.permissionKey,
+      ],
+    })
+    .returning({ id: principalPermissionGrants.id });
+
+  return inserted.length;
+}
+
+export async function ensureHumanRoleDefaultGrants(
+  db: Db,
+  input: {
+    companyId: string;
+    principalId: string;
+    membershipRole: string | null | undefined;
+    grantedByUserId: string | null;
+  },
+): Promise<number> {
+  const role = normalizeHumanRole(input.membershipRole, "operator");
+  return insertMissingPrincipalGrants(db, {
+    companyId: input.companyId,
+    principalType: "user",
+    principalId: input.principalId,
+    grants: grantsForHumanRole(role),
+    grantedByUserId: input.grantedByUserId,
+  });
+}
+
+export async function backfillPrincipalAccessCompatibility(
+  db: Db,
+): Promise<PrincipalAccessCompatibilityBackfillStats> {
+  const now = new Date();
+  const nonTerminalAgents = await db
+    .select({
+      companyId: agents.companyId,
+      principalId: agents.id,
+    })
+    .from(agents)
+    .where(notInArray(agents.status, ["pending_approval", "terminated"]));
+
+  const agentMembershipsInserted = nonTerminalAgents.length > 0
+    ? await db
+      .insert(companyMemberships)
+      .values(
+        nonTerminalAgents.map((agent) => ({
+          companyId: agent.companyId,
+          principalType: "agent",
+          principalId: agent.principalId,
+          status: "active",
+          membershipRole: "member",
+          createdAt: now,
+          updatedAt: now,
+        })),
+      )
+      .onConflictDoNothing({
+        target: [
+          companyMemberships.companyId,
+          companyMemberships.principalType,
+          companyMemberships.principalId,
+        ],
+      })
+      .returning({ id: companyMemberships.id })
+      .then((rows) => rows.length)
+    : 0;
+
+  const activeHumanMemberships = await db
+    .select({
+      companyId: companyMemberships.companyId,
+      principalId: companyMemberships.principalId,
+      membershipRole: companyMemberships.membershipRole,
+    })
+    .from(companyMemberships)
+    .where(
+      and(
+        eq(companyMemberships.principalType, "user"),
+        eq(companyMemberships.status, "active"),
+      ),
+    );
+
+  let humanGrantsInserted = 0;
+  for (const membership of activeHumanMemberships) {
+    humanGrantsInserted += await ensureHumanRoleDefaultGrants(db, {
+      companyId: membership.companyId,
+      principalId: membership.principalId,
+      membershipRole: membership.membershipRole,
+      grantedByUserId: null,
+    });
+  }
+
+  return {
+    agentMembershipsInserted,
+    humanGrantsInserted,
+  };
+}