fix: explain project access denials and add an authorized repair path (#17509)

## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Low-trust agents may read only the projects in their allowed scope. > - Workspace setup correctly stops a task outside that scope. > - The task previously showed a generic failure, and agent settings did not offer an additive repair. > - This pull request explains the denial and lets authorized operators add projects while preserving other restrictions. > - The saved task then offers an explicit retry. Saving access does not start work. ## Linked Issues or Issue Description **What happened?** A project access denial appeared as an ordinary failed attempt. Operators could not add a second allowed project from agent settings. **Expected behavior** The task should explain the denied access and link to a working permission editor. The editor should preserve existing scope and restrictions, enforce operator authority, and retain drafts after a failed save. **Steps to reproduce** 1. Assign a low-trust agent to a task whose project is outside its allowed projects. 2. Let workspace setup deny project access. 3. Open the task, follow Manage project access, add the project, save, reload, and return to the task. 4. Confirm that the saved message remains and Retry task is a separate action. ## What Changed - Record a typed, non-retryable project denial before provider dispatch. Project denials do not enter automatic continuation or provider comment policy. - Project current and historical setup denials into a safe task notice. Keep unrelated failures, prior assignees, and approval/pause/budget gates separate. Recheck current project authority, including standard trust and root-issue grants. Accepted retries keep their working state. - Add board-only project-access reads and additive saves under the agent row lock. Enforce company scope, agent-management authority, pending-approval restrictions, and an audit record for new additions. - Add the production notice and searchable multi-project editor, including read-only, saving, cancellation, and failed-save states. Preserve the return-to-task query through canonical agent redirects. - Register board-only project-access routes in OpenAPI with a strict request schema. - Add production Storybook examples and API/persistence/concurrency regressions. Retain the approved design snapshot and update the behavior maps and implementation contract. ## Verification - Passed: `pnpm -r typecheck`, `pnpm build`, `pnpm build-storybook`, `pnpm check:token-gates`, `node scripts/check-maps.mjs`, and `node scripts/storybook-catalog.mjs`. - Passed: 11 permission/projection tests and 30 run-completion tests against an isolated PostgreSQL database. These cover historical failures, concurrent additions, idempotent audit, preserved restrictions, foreign projects, read-only users, agent self-grants, and no automatic wakeup. - Passed: all 27 OpenAPI route tests, including route coverage and the new board-only request/response contract. - Browser: the real app displayed a historical denial; Manage project access opened the editor; saving retained the original project and survived reload; Return to task showed the ready notice. Saving created one audit event and zero runs. Explicit Retry returned 202 and reached the separate sandbox requirement, which remained enforced. No external provider was used. - All five production Storybook interaction checks pass: blocked task, save, cancellation, failed-save recovery, and read-only settings. These use fixture callbacks; durable authorization is covered separately above. - `pnpm test:run` was attempted locally but stopped after repeated embedded PostgreSQL startup failures caused by macOS semaphore exhaustion. Full-suite CI is required before merge. The separate UI suite passed all 9,095 tests. The 41 focused server regressions also passed after rebasing onto the latest master. A further 26 recovery-classification tests pass, including a red-to-green regression for automatic continuation after a project denial. ## Risks - No schema migration. The new endpoint only adds same-company project IDs and preserves the rest of the stored policy. - The historical notice recognizes one exact setup denial message. It does not display arbitrary run errors or disclose a different source project's identity. - The retry still passes all current admission and isolation checks. The notice does not promise that other execution requirements are satisfied. - Related open work: #13309 covers inherited secret restrictions; #11234 covers the broader repository catalog. This change does not replace either policy surface. ## Model Used OpenAI Codex (GPT-6), with code execution and browser tools. The precise runtime model ID and context-window size were not exposed in this session. ## 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 searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass (focused server and full UI suites; full-suite infrastructure limit above) - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-10-27 19:35:13 +01:00 · 2026-10-24 16:16:29 -07:00
1 parent a3675ddcdf
commit d0c8f0b090
@@ -0,0 +1,107 @@
+import { randomUUID } from "node:crypto";
+import express from "express";
+import request from "supertest";
+import { and, eq } from "drizzle-orm";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { agents, agentWakeupRequests, activityLog, authUsers, companies, companyMemberships, createDb,
+  heartbeatRuns, issues, projects, EMBEDDED_POSTGRES_TEST_TIMEOUT_MS } from "@paperclipai/db";
+import { registerAgentProjectAccessRoutes } from "../routes/agent-project-access.js";
+import { errorHandler } from "../middleware/error-handler.js";
+import { assertTaskWorkspaceSourceProjectAccess } from "../services/task-workspace-access.js";
+import { taskInterruptionPresentation } from "../services/task-interruption-presentation.js";
+import { ProjectAccessDeniedError } from "../services/project-access-denial.js";
+import { startEmbeddedPostgresTestDatabase } from "./helpers/embedded-postgres.js";
+
+describe("additive project access", () => {
+  let database: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | undefined;
+  let db: ReturnType<typeof createDb>;
+  beforeAll(async () => {
+    const external = process.env.PAPERCLIP_TEST_DATABASE_URL;
+    if (external) db = createDb(external);
+    else { database = await startEmbeddedPostgresTestDatabase("agent-project-access-"); db = createDb(database.connectionString); }
+  }, EMBEDDED_POSTGRES_TEST_TIMEOUT_MS);
+  afterAll(async () => { await db?.$client.end(); await database?.cleanup(); });
+
+  async function seed() {
+    const companyId = randomUUID(), agentId = randomUUID(), issueId = randomUUID(), runId = randomUUID();
+    await db.insert(companies).values({ id: companyId, name: "Project access", issuePrefix: `A${companyId.slice(0, 6)}` });
+    const selected = await db.insert(projects).values(["Existing", "Needed", "Third"].map(name => ({ companyId, name }))).returning();
+    const permissions = { canCreateAgents: false, canCreateSkills: false, trustPreset: "low_trust_review",
+      authorizationPolicy: { reviewPreset: { id: "low_trust_review", version: 1, rawOutputDisposition: "quarantine" },
+        customPolicy: { preserve: true }, trustBoundary: { mode: "low_trust_review", companyId,
+          projectIds: [selected[0]!.id], issueIds: [issueId], allowedToolClasses: ["git.read"], allowedSecretBindingIds: [] } } };
+    await db.insert(agents).values({ id: agentId, companyId, name: "Reviewer", adapterType: "process", status: "idle", permissions });
+    await db.insert(companyMemberships).values({ companyId, principalType: "agent", principalId: agentId, membershipRole: "member", status: "active" });
+    const [issue] = await db.insert(issues).values({ id: issueId, companyId, title: "Saved message", status: "blocked", assigneeAgentId: agentId, projectId: selected[1]!.id }).returning();
+    await db.insert(heartbeatRuns).values({ id: runId, companyId, agentId, issueId, status: "failed", errorCode: "setup_failed",
+      error: "Project is outside this low-trust boundary.", contextSnapshot: { issueId } });
+    return { companyId, agentId, issue: issue!, runId, selected, permissions };
+  }
+  function app(actor: express.Request["actor"]) {
+    const app = express(); app.use(express.json()); app.use((req, _res, next) => { req.actor = actor; next(); });
+    registerAgentProjectAccessRoutes(app, db); app.use(errorHandler); return app;
+  }
+  const board = { type: "board" as const, source: "local_implicit" as const };
+
+  it("preserves containment, audits concurrent additions, and changes the persisted denial into an explicit retry", async () => {
+    const f = await seed();
+    const actor = { type: "agent" as const, source: "agent_key" as const, agentId: f.agentId, companyId: f.companyId };
+    await expect(assertTaskWorkspaceSourceProjectAccess(db, actor, f.companyId, f.selected[1]!.id)).rejects.toBeInstanceOf(ProjectAccessDeniedError);
+    expect(await taskInterruptionPresentation(db, f.issue)).toMatchObject({ userAction: "project_access", canRetry: false });
+    const api = app(board);
+    const results = await Promise.all(f.selected.slice(1).map(project => request(api).post(`/agents/${f.agentId}/project-access`).send({ projectIds: [project.id] })));
+    expect(results.map(result => result.status)).toEqual([200, 200]);
+    const [saved] = await db.select().from(agents).where(eq(agents.id, f.agentId));
+    expect(saved!.permissions).toEqual({ ...f.permissions, authorizationPolicy: { ...f.permissions.authorizationPolicy,
+      trustBoundary: { ...f.permissions.authorizationPolicy.trustBoundary, projectIds: expect.arrayContaining(f.selected.map(project => project.id)) } } });
+    expect((saved!.permissions as typeof f.permissions).authorizationPolicy.trustBoundary.projectIds).toHaveLength(3);
+    await expect(assertTaskWorkspaceSourceProjectAccess(db, actor, f.companyId, f.selected[1]!.id)).resolves.toBeUndefined();
+    expect(await taskInterruptionPresentation(db, f.issue)).toMatchObject({ canRetry: true, projectAccess: { ready: true } });
+    const again = await request(api).post(`/agents/${f.agentId}/project-access`).send({ projectIds: [f.selected[1]!.id] });
+    expect(again.status).toBe(200);
+    expect(await db.select().from(activityLog).where(and(eq(activityLog.companyId, f.companyId), eq(activityLog.action, "agent.project_access_added")))).toHaveLength(2);
+    expect(await db.select().from(agentWakeupRequests).where(eq(agentWakeupRequests.companyId, f.companyId))).toHaveLength(0);
+    expect(await db.select().from(heartbeatRuns).where(eq(heartbeatRuns.companyId, f.companyId))).toHaveLength(1);
+  });
+
+  it("rejects foreign projects, agent self-grants, unknown policy fields, and pending-approval agents", async () => {
+    const f = await seed(), other = await seed(), api = app(board);
+    expect((await request(api).post(`/agents/${f.agentId}/project-access`).send({ projectIds: [other.selected[1]!.id] })).status).toBe(404);
+    expect((await request(api).post(`/agents/${f.agentId}/project-access`).send({ projectIds: [f.selected[1]!.id], trustPreset: "standard" })).status).toBe(400);
+    expect((await request(app({ type: "agent", agentId: f.agentId, companyId: f.companyId, source: "agent_key" }))
+      .post(`/agents/${f.agentId}/project-access`).send({ projectIds: [f.selected[1]!.id] })).status).toBe(403);
+    await db.update(agents).set({ status: "pending_approval" }).where(eq(agents.id, f.agentId));
+    expect((await request(api).post(`/agents/${f.agentId}/project-access`).send({ projectIds: [f.selected[1]!.id] })).status).toBe(409);
+    const [saved] = await db.select().from(agents).where(eq(agents.id, f.agentId)); expect(saved!.permissions).toEqual(f.permissions);
+  });
+
+  it.each(["standard", "root_issue"])("rechecks actual project authority after a %s repair and acknowledges an accepted retry", async repair => {
+    const f = await seed();
+    const permissions = repair === "standard" ? { canCreateAgents: false, trustPreset: "standard", authorizationPolicy: {} }
+      : { ...f.permissions, authorizationPolicy: { ...f.permissions.authorizationPolicy,
+        trustBoundary: { ...f.permissions.authorizationPolicy.trustBoundary, rootIssueId: f.issue.id } } };
+    await db.update(agents).set({ permissions }).where(eq(agents.id, f.agentId));
+    expect(await taskInterruptionPresentation(db, f.issue)).toMatchObject({ canRetry: true, projectAccess: { ready: true } });
+    await db.insert(agentWakeupRequests).values({ companyId: f.companyId, agentId: f.agentId,
+      source: "on_demand", status: "deferred_issue_execution", requestedByActorType: "user", payload: { issueId: f.issue.id } });
+    const accepted = await taskInterruptionPresentation(db, f.issue);
+    expect(accepted).toMatchObject({ state: "working", canRetry: false });
+    expect(accepted).not.toHaveProperty("projectAccess");
+    // Current project policy remains authoritative even after agent access changes.
+    await db.update(projects).set({ executionWorkspacePolicy: { trustPreset: "low_trust_review", authorizationPolicy: {
+      trustBoundary: { mode: "low_trust_review", companyId: f.companyId, projectIds: [f.selected[0]!.id] },
+    } } }).where(eq(projects.id, f.selected[1]!.id));
+    if (repair === "standard") expect(await taskInterruptionPresentation(db, f.issue))
+      .toMatchObject({ canRetry: false, userAction: "project_access" });
+  });
+
+  it("shows read-only access to viewers and denies their saves and cross-company reads", async () => {
+    const f = await seed(), other = await seed(), userId = randomUUID();
+    await db.insert(authUsers).values({ id: userId, name: "Viewer", email: `${userId}@example.test`, emailVerified: true, createdAt: new Date(), updatedAt: new Date() });
+    await db.insert(companyMemberships).values({ companyId: f.companyId, principalType: "user", principalId: userId, membershipRole: "viewer", status: "active" });
+    const api = app({ type: "board", source: "session", userId, companyIds: [f.companyId], memberships: [{ companyId: f.companyId, membershipRole: "viewer", status: "active" }] });
+    expect((await request(api).get(`/agents/${f.agentId}/project-access`)).body).toMatchObject({ canManage: false });
+    expect((await request(api).post(`/agents/${f.agentId}/project-access`).send({ projectIds: [f.selected[1]!.id] })).status).toBe(403);
+    expect((await request(api).get(`/agents/${other.agentId}/project-access`)).status).toBe(404);
+  });
+});
@@ -21,6 +21,7 @@ const apiPrefixes: Record<string, string> = {
  "activity.ts": "/api",
  "adapters.ts": "/api",
  "agents.ts": "/api",
+  "agent-project-access.ts": "/api",
  "agent-commentary.ts": "/api",
  "agent-avatars.ts": "/api",
  "agent-profile-avatar.ts": "/api",
@@ -987,6 +988,21 @@ describe("openapi routes", () => {
    });
  });

+  it("documents additive project access as board-only with a strict request", () => {
+    const { spec } = loadSpecRoutes();
+    const path = spec.paths["/api/agents/{id}/project-access"];
+    for (const operation of [path.get, path.post]) {
+      expect(operation["x-paperclip-authorization"]).toEqual({ actor: "board" });
+      expect(operation.security).toEqual([{ BoardSessionAuth: [] }, { BoardApiKeyAuth: [] }]);
+      expect(operation.responses["200"].content["application/json"].schema.required).toEqual(["projectIds", "canManage"]);
+    }
+    expect(path.post.requestBody.content["application/json"].schema).toMatchObject({
+      additionalProperties: false, required: ["projectIds"],
+      properties: { projectIds: { type: "array", items: { type: "string", format: "uuid" } } },
+    });
+    expect(path.post.responses["409"]).toBeDefined();
+  });
+
  it("documents the authenticated personal primary-agent contract", () => {
    const { spec } = loadSpecRoutes();
    const path = spec.paths["/api/companies/{companyId}/primary-agent/me"];
@@ -0,0 +1,25 @@
+import type { Router } from "express";
+import { agents, type Db } from "@paperclipai/db";
+import { eq } from "drizzle-orm";
+import { addAgentProjectAccessSchema } from "@paperclipai/shared";
+import { notFound } from "../errors.js";
+import { validate } from "../middleware/validate.js";
+import { addAgentProjectAccess, readAgentProjectAccess } from "../services/agent-project-access.js";
+import { assertBoard, assertCompanyAccess, hasCompanyAccess } from "./authz.js";
+
+export function registerAgentProjectAccessRoutes(router: Router, db: Db) {
+  router.get("/agents/:id/project-access", async (req, res) => {
+    assertBoard(req);
+    const [agent] = await db.select({ id: agents.id, companyId: agents.companyId }).from(agents).where(eq(agents.id, req.params.id as string));
+    if (!agent || !hasCompanyAccess(req, agent.companyId)) throw notFound("Agent not found");
+    assertCompanyAccess(req, agent.companyId);
+    res.json(await readAgentProjectAccess(db, req.actor, agent.companyId, agent.id));
+  });
+  router.post("/agents/:id/project-access", validate(addAgentProjectAccessSchema), async (req, res) => {
+    assertBoard(req);
+    const [agent] = await db.select({ id: agents.id, companyId: agents.companyId }).from(agents).where(eq(agents.id, req.params.id as string));
+    if (!agent || !hasCompanyAccess(req, agent.companyId)) throw notFound("Agent not found");
+    assertCompanyAccess(req, agent.companyId);
+    res.json(await addAgentProjectAccess(db, req.actor, agent.companyId, agent.id, req.body.projectIds));
+  });
+}
@@ -98,6 +98,7 @@ import {
 } from "@paperclipai/adapter-utils/server-utils";
 import { trackAgentCreated } from "@paperclipai/shared/telemetry";
 import { validate } from "../middleware/validate.js";
+import { registerAgentProjectAccessRoutes } from "./agent-project-access.js";
 import { inheritNativeRunnerAdapterConfig } from "../services/native-runtime/native-agent-runtime-inheritance.js";
 import { agentInstructionRevisionService } from "../services/agent-instruction-revisions.js";
 import { agentInstructionWorkingCopyService } from "../services/agent-instruction-working-copies.js";
@@ -4918,6 +4919,8 @@ export function agentRoutes(
    res.status(201).json({ ...redactAgentRowForResponse(agent), ...(configurationWarnings.length ? { configurationWarnings } : {}) });
  });

+  registerAgentProjectAccessRoutes(router, db);
+
  router.patch("/agents/:id/permissions", validate(updateAgentPermissionsSchema), async (req, res) => {
    const id = req.params.id as string;
    const existing = await getAccessibleResource(req, res, svc.getById(id), "Agent not found");
@@ -48,6 +48,7 @@ import {
  updateAgentSchema,
  updatePrimaryAgentSchema,
  updateAgentPermissionsSchema,
+  addAgentProjectAccessSchema,
  updateAgentInstructionsPathSchema,
  updateAgentInstructionsBundleSchema,
  upsertAgentInstructionsFileSchema,
@@ -1390,6 +1391,8 @@ const browserUseOperations = [
 ] as const;

 const BOARD_ONLY_OPERATIONS = new Set([
+  "GET /api/agents/{id}/project-access",
+  "POST /api/agents/{id}/project-access",
  "POST /api/issues/{id}/interactions/{interactionId}/dismiss",
  "POST /api/issues/{id}/retry",
  "GET /api/companies/{companyId}/prompt-injection-prevention",
@@ -3790,6 +3793,26 @@ registry.registerPath({
  responses: { 200: r.ok(), 400: r.badRequest, 401: r.unauthorized },
 });

+const agentProjectAccessResponse = z.object({ projectIds: z.array(z.string().uuid()), canManage: z.boolean() });
+registry.registerPath({
+  method: "get",
+  path: "/api/agents/{id}/project-access",
+  tags: ["agents"],
+  summary: "Read an agent's allowed projects and the current operator's management capability",
+  request: { params: z.object({ id: z.string() }) },
+  responses: { 200: r.ok(agentProjectAccessResponse), 401: r.unauthorized, 403: r.forbidden, 404: r.notFound },
+});
+registry.registerPath({
+  method: "post",
+  path: "/api/agents/{id}/project-access",
+  tags: ["agents"],
+  summary: "Add allowed projects without replacing an agent's other permissions",
+  description: "Requires board access and agents:create in the agent's company. Accepts 1 to 100 project IDs. Selected projects must be readable and in that company. Locks the low-trust agent, preserves existing containment, audits new additions, and rejects pending-approval agents or changed trust settings. Repeated additions are idempotent. Saving does not start or retry a task.",
+  request: { params: z.object({ id: z.string() }), body: jsonBody(addAgentProjectAccessSchema) },
+  responses: { 200: r.ok(agentProjectAccessResponse), 400: r.badRequest, 401: r.unauthorized,
+    403: r.forbidden, 404: r.notFound, 409: r.conflict },
+});
+
 registry.registerPath({
  method: "patch",
  path: "/api/agents/{id}/instructions-path",
@@ -0,0 +1,69 @@
+import { and, eq, inArray } from "drizzle-orm";
+import { agents, projects, type Db } from "@paperclipai/db";
+import { trustAuthorizationPolicySchema, type AgentProjectAccess } from "@paperclipai/shared";
+import { conflict, forbidden, notFound } from "../errors.js";
+import { normalizeAgentPermissions } from "../lib/agent-permissions.js";
+import { accessService } from "./access.js";
+import type { AuthorizationActor } from "./authorization.js";
+import { logActivity, publishActivity, type ActivityPublication } from "./activity-log.js";
+
+export async function readAgentProjectAccess(db: Db, actor: AuthorizationActor, companyId: string, agentId: string): Promise<AgentProjectAccess> {
+  const [agent] = await db.select({ permissions: agents.permissions, status: agents.status }).from(agents)
+    .where(and(eq(agents.companyId, companyId), eq(agents.id, agentId)));
+  if (!agent) throw notFound("Agent not found");
+  const decision = await accessService(db).decide({ actor, action: "agents:create", resource: { type: "company", companyId } });
+  const permissions = normalizeAgentPermissions(agent.permissions);
+  const policy = trustAuthorizationPolicySchema.safeParse(permissions.authorizationPolicy ?? {});
+  const boundary = policy.success ? policy.data.trustBoundary : undefined;
+  return { projectIds: policy.success ? policy.data.trustBoundary?.projectIds ?? [] : [],
+    canManage: actor.type === "board" && decision.allowed && agent.status !== "pending_approval"
+      && policy.success && permissions.trustPreset === "low_trust_review"
+      && (!boundary || (boundary.mode === "low_trust_review" && (!boundary.companyId || boundary.companyId === companyId))) };
+}
+
+/** An additive operation under the agent row lock, never a stale policy replacement. */
+export async function addAgentProjectAccess(db: Db, actor: AuthorizationActor, companyId: string, agentId: string, projectIds: string[]) {
+  if (actor.type !== "board") throw forbidden("Board access required");
+  const publications: ActivityPublication[] = [];
+  const result = await db.transaction(async tx => {
+    const [agent] = await tx.select().from(agents)
+      .where(and(eq(agents.companyId, companyId), eq(agents.id, agentId))).for("update");
+    if (!agent) throw notFound("Agent not found");
+    const transactionDb = tx as unknown as Db;
+    const access = accessService(transactionDb);
+    const decision = await access.decide({ actor, action: "agents:create", resource: { type: "company", companyId } });
+    if (!decision.allowed) throw forbidden(decision.explanation);
+    if (agent.status === "pending_approval") throw conflict("Pending approval agent permissions cannot be changed before board approval");
+    const permissions = normalizeAgentPermissions(agent.permissions);
+    const parsedPolicy = trustAuthorizationPolicySchema.safeParse(permissions.authorizationPolicy ?? {});
+    if (!parsedPolicy.success) throw conflict("The agent’s trust settings need review before adding project access.");
+    const policy = parsedPolicy.data;
+    const boundary = policy?.trustBoundary;
+    if (permissions.trustPreset !== "low_trust_review" || (boundary && (boundary.mode !== "low_trust_review"
+      || (boundary.companyId && boundary.companyId !== companyId)))) {
+      throw conflict("The agent’s trust settings changed. Refresh before adding project access.");
+    }
+    const requested = [...new Set(projectIds)];
+    const rows = await tx.select({ id: projects.id }).from(projects)
+      .where(and(eq(projects.companyId, companyId), inArray(projects.id, requested)));
+    if (rows.length !== requested.length) throw notFound("A selected project is unavailable");
+    for (const project of rows) {
+      const projectDecision = await access.decide({ actor, action: "project:read", resource: { type: "project", companyId, projectId: project.id } });
+      if (!projectDecision.allowed) throw forbidden("A selected project is unavailable");
+    }
+    const previous = boundary?.projectIds ?? [];
+    const added = requested.filter(id => !previous.includes(id));
+    const next = [...previous, ...added];
+    if (added.length) {
+      await tx.update(agents).set({ permissions: { ...agent.permissions, authorizationPolicy: {
+        ...policy, trustBoundary: { ...boundary, mode: "low_trust_review", companyId, projectIds: next },
+      } }, updatedAt: new Date() }).where(and(eq(agents.id, agentId), eq(agents.companyId, companyId)));
+      await logActivity(transactionDb, { companyId, actorType: "user", actorId: actor.userId ?? "local-board",
+        action: "agent.project_access_added", entityType: "agent", entityId: agentId,
+        details: { addedProjectIds: added, trustPreset: "low_trust_review" } }, publications);
+    }
+    return { projectIds: next, canManage: true } satisfies AgentProjectAccess;
+  });
+  for (const publication of publications) publishActivity(publication);
+  return result;
+}
@@ -9,6 +9,7 @@ import { createAgentIdentityRedactor } from "../agent-identity-redaction.js";
 import { UnresolvedWorkspaceBaseRefError } from "../workspace-runtime.js";
 import { LegacyControllerLeaseLostError } from "../legacy-controller-lease.js";
 import { requestedRunCancellation } from "../run-cancellation.js";
+import { ProjectAccessDeniedError } from "../project-access-denial.js";
 import { createHeartbeatLifecycle, type HeartbeatLifecycleDependencies } from "./run-lifecycle.js";
 import { createHeartbeatRunPreparation, ConfigurationIncompleteFailure } from "./run-preparation.js";
 import { createHeartbeatRunState, getAdapterSessionCodec } from "./run-state.js";
@@ -77,15 +78,19 @@ it("constructs completion handlers without querying or starting work", () => {
 });

 const support = await getEmbeddedPostgresTestSupport();
-describe.skipIf(!support.supported)("heartbeat run completion boundary", () => {
-  let database: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>>;
+describe.skipIf(!support.supported && !process.env.PAPERCLIP_TEST_DATABASE_URL)("heartbeat run completion boundary", () => {
+  let database: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>> | undefined;
  let db: Db;
  beforeAll(async () => {
    // Keep the accounting transaction real without reading provider receipt files.
    vi.spyOn(usageReceipts, "indexPendingUsageReceipts").mockResolvedValue(new Map());
    vi.spyOn(usageReceipts, "recoverPendingRunUsageReceipts").mockResolvedValue([]);
-    database = await startEmbeddedPostgresTestDatabase("paperclip-heartbeat-completion");
-    db = createDb(database.connectionString);
+    const external = process.env.PAPERCLIP_TEST_DATABASE_URL;
+    if (external) db = createDb(external);
+    else {
+      database = await startEmbeddedPostgresTestDatabase("paperclip-heartbeat-completion");
+      db = createDb(database.connectionString);
+    }
    await db.execute(sql`set client_min_messages = warning`);
  }, EMBEDDED_POSTGRES_TEST_TIMEOUT_MS);
  afterAll(async () => { await db?.$client.end(); await database?.cleanup(); vi.restoreAllMocks(); });
@@ -334,6 +339,18 @@ describe.skipIf(!support.supported)("heartbeat run completion boundary", () => {
    expect(f.deps.releaseIssueExecutionAndPromote).toHaveBeenCalledWith(expect.objectContaining({ id: f.run.id }), { suppressImmediateRecovery: true });
  });

+  it("persists a project denial without provider work or an automatic retry", async () => {
+    const f = await fixture();
+    const projectId = randomUUID();
+    await f.completion.failRunSetup(f.setup(new ProjectAccessDeniedError(projectId)));
+    expect(await read(f.run.id)).toMatchObject({ status: "failed", errorCode: "project_access_denied",
+      resultJson: { projectAccessDenied: { projectId }, executionRecovery: { kind: "bootstrap", providerWorkStarted: false } } });
+    expect(f.deps.scheduleBoundedRetryForRun).not.toHaveBeenCalled();
+    expect(f.deps.enqueueWakeup).not.toHaveBeenCalled();
+    expect(f.deps.scheduleInteractionContinuationInfrastructureRetryIfEligible).not.toHaveBeenCalled();
+    expect(f.deps.finalizeIssueCommentPolicy).not.toHaveBeenCalled();
+  });
+
  it("records a setup configuration gap without inventing provider work or applying comment policy", async () => {
    const f = await fixture();
    await f.completion.failRunSetup(f.setup(new ConfigurationIncompleteFailure("missing credential", { configurationIncomplete: { reason: "missing_binding" } })));
@@ -1,4 +1,5 @@
 import { measureRunPhase } from "../execution-preparation-timing.js";
+import { PROJECT_ACCESS_DENIED, ProjectAccessDeniedError } from "../project-access-denial.js";
 import { pendingCaseHandoffForRun } from "./case-handoff-lifecycle.js";
 import { NON_RETRYABLE_PREFLIGHT_FAILURE_CODES, isHeartbeatRunTerminalStatus } from "./run-lifecycle.js";
 import { ChatControlRecoveryUnresolvedError } from "./queue.js";
@@ -145,6 +146,7 @@ export interface FailHeartbeatRunSetupInput {
 }

 function nonRetryablePreflightFailureCode(error: unknown): string | null {
+  if (error instanceof ProjectAccessDeniedError) return PROJECT_ACCESS_DENIED;
  if (error instanceof ChatControlRecoveryUnresolvedError)
    return CHAT_CONTROL_RECOVERY_UNRESOLVED_CODE;
  if (
@@ -1344,6 +1346,8 @@ export function createHeartbeatRunCompletion(db: Db, dependencies: HeartbeatRunC
    // action, so it is persisted even when the agent lookup failed and the
    // agent-scoped stop metadata cannot be merged in.
    const setupFailureDetails =
+      (outerErr instanceof ProjectAccessDeniedError
+        ? { projectAccessDenied: { projectId: outerErr.projectId } } : null) ??
      (workspaceGitScanFailure ? {
        workspaceGitScan: {
          code: workspaceGitScanFailure.code,
@@ -1453,7 +1457,8 @@ export function createHeartbeatRunCompletion(db: Db, dependencies: HeartbeatRunC
        ).catch(() => undefined);
        if (
          !isWorkspaceValidationFailedRun(livenessRun) &&
-          !isConfigurationIncompleteFailedRun(livenessRun)
+          !isConfigurationIncompleteFailedRun(livenessRun) &&
+          livenessRun.errorCode !== PROJECT_ACCESS_DENIED
        ) {
          await finalizeIssueCommentPolicy(livenessRun, failedAgent).catch(
            () => undefined,
@@ -1462,15 +1467,17 @@ export function createHeartbeatRunCompletion(db: Db, dependencies: HeartbeatRunC
        // No provider work began. Retry temporary host scan failures with
        // the existing durable failure budget, before releasing execution.
        // Generic recovery must not grant a second budget on exhaustion.
-        await (isTransientWorkspaceGitScanCode(livenessRun.errorCode)
-          ? scheduleBoundedRetryForRun(livenessRun, failedAgent)
-          : scheduleInteractionContinuationInfrastructureRetryIfEligible(livenessRun, failedAgent)
-        ).catch((retryError) => {
-          logger.warn(
-            { err: retryError, runId: livenessRun.id },
-            "failed to schedule interaction continuation retry after setup failure",
-          );
-        });
+        if (livenessRun.errorCode !== PROJECT_ACCESS_DENIED) {
+          await (isTransientWorkspaceGitScanCode(livenessRun.errorCode)
+            ? scheduleBoundedRetryForRun(livenessRun, failedAgent)
+            : scheduleInteractionContinuationInfrastructureRetryIfEligible(livenessRun, failedAgent)
+          ).catch((retryError) => {
+            logger.warn(
+              { err: retryError, runId: livenessRun.id },
+              "failed to schedule interaction continuation retry after setup failure",
+            );
+          });
+        }
      }
      await releaseIssueExecutionAndPromote(livenessRun, {
        suppressImmediateRecovery:
@@ -244,6 +244,7 @@ const LIVENESS_BOOKKEEPING_EVENT_TYPES = [
 ];

 export const NON_RETRYABLE_PREFLIGHT_FAILURE_CODES = new Set<string>([
+  "project_access_denied",
  "low_trust_isolation_unavailable",
  "low_trust_requires_isolated_workspace",
  "low_trust_boundary_mismatch",
@@ -0,0 +1,10 @@
+import { HttpError } from "../errors.js";
+
+export const PROJECT_ACCESS_DENIED = "project_access_denied";
+
+/** Carries a safe, typed setup failure without changing the authorization decision. */
+export class ProjectAccessDeniedError extends HttpError {
+  constructor(readonly projectId: string) {
+    super(403, "Project is outside this low-trust boundary.");
+  }
+}
@@ -10,6 +10,10 @@ import { legacyExecutionNeedsReconciliation } from "../legacy-execution-recovery
 import { isConfigurationIncompleteFailedRun } from "../../modules/wake-queue/domain/values.js";

 describe("classifyAdapterFailureForRecovery", () => {
+  it("does not automatically replay a project access denial", () => {
+    expect(classifyContinuationFailure({ errorCode: "project_access_denied", resultJson: null } as never))
+      .toMatchObject({ kind: "non_retryable", maxAttempts: 0 });
+  });
  it("waits for model configuration changes instead of retrying a typed native model rejection", () => {
    const run = { errorCode: "native_provider_model_rejected", error: "Fixed model configuration message", resultJson: null };
    expect(classifyAdapterFailureForRecovery(run)).toEqual({ kind: "configuration_incomplete" });
@@ -516,6 +516,7 @@ const TRANSIENT_INFRA_CONTINUATION_ERROR_CODES = new Set<string>([
 ]);

 const NON_RETRYABLE_CONTINUATION_ERROR_CODES = new Set<string>([
+  "project_access_denied",
  "native_provider_model_rejected",
  "provider_tool_definition_invalid",
  "adapter_engine_unavailable",
@@ -0,0 +1,55 @@
+import { describe, expect, it } from "vitest";
+import { projectTaskInterruption } from "./task-interruption-presentation.js";
+
+const issue = { id: "task", companyId: "11111111-1111-4111-8111-111111111111", status: "blocked", assigneeAgentId: "agent", projectId: "22222222-2222-4222-8222-222222222222" };
+const run = { id: "run", agentId: "agent", status: "failed", scheduledRetryAt: null,
+  errorCode: "project_access_denied", error: null, livenessState: null,
+  resultJson: { projectAccessDenied: { projectId: "22222222-2222-4222-8222-222222222222" } } };
+const agent = { status: "idle", pauseReason: null };
+
+describe("task project-access interruption", () => {
+  it("explains a project denial without offering a futile retry", () => {
+    expect(projectTaskInterruption(issue, { run, agent, paused: false, approval: false })).toMatchObject({
+      state: "waiting_for_user", responsibility: "user", userAction: "project_access", canRetry: false,
+      projectAccess: { agentId: "agent", projectId: "22222222-2222-4222-8222-222222222222", ready: false },
+    });
+  });
+
+  it("projects the historical setup denial without requiring another failed run", () => {
+    expect(projectTaskInterruption(issue, { run: { ...run, errorCode: "setup_failed",
+      error: "Project is outside this low-trust boundary.", resultJson: null }, agent, paused: false, approval: false }))
+      .toMatchObject({ userAction: "project_access", canRetry: false });
+  });
+
+  it("offers an explicit retry after the project is added, without changing the failed run", () => {
+    expect(projectTaskInterruption(issue, { run, agent, projectAccessAllowed: true, paused: false, approval: false }))
+      .toMatchObject({ state: "failed", canRetry: true, projectAccess: { ready: true } });
+    expect(run.status).toBe("failed");
+  });
+
+  it("shows an accepted retry as working after access is repaired", () => {
+    const input = { run, agent, paused: false, approval: false, wait: { id: "request", requestedAt: new Date() } };
+    expect(projectTaskInterruption(issue, { ...input, projectAccessAllowed: true }))
+      .toMatchObject({ state: "working", canRetry: false });
+    expect(projectTaskInterruption(issue, { ...input, projectAccessAllowed: true })).not.toHaveProperty("projectAccess");
+    expect(projectTaskInterruption(issue, { ...input, projectAccessAllowed: false }))
+      .toMatchObject({ state: "waiting_for_user", userAction: "project_access", canRetry: false });
+  });
+
+  it("does not reinterpret unrelated failures or an old assignee's denial", () => {
+    for (const otherRun of [{ ...run, errorCode: "setup_failed", error: "Disk full", resultJson: null },
+      { ...run, agentId: "previous-agent" }]) {
+      expect(projectTaskInterruption(issue, { run: otherRun, agent, paused: false, approval: false }))
+        .not.toHaveProperty("projectAccess");
+    }
+  });
+
+  it("keeps approval, pause, running and completed states authoritative", () => {
+    expect(projectTaskInterruption(issue, { run, agent, paused: false, approval: true })).toMatchObject({ userAction: "approval" });
+    expect(projectTaskInterruption(issue, { run, agent, paused: true, approval: false })).toMatchObject({ userAction: "resume" });
+    expect(projectTaskInterruption(issue, { run: { ...run, status: "running" }, agent, paused: false, approval: false }))
+      .toMatchObject({ state: "working" });
+    expect(projectTaskInterruption({ ...issue, status: "done" }, { run, agent, paused: false, approval: false }))
+      .toMatchObject({ state: "resolved" });
+  });
+});
@@ -4,21 +4,35 @@ import { agents, agentWakeupRequests, approvals, companies, heartbeatRuns, issue
 import type { TaskInterruptionPresentation } from "@paperclipai/shared";
 import { isAiAuthenticationBlocked } from "./ai-auth-failure.js";
 import { readSystemRecovery } from "./system-recovery-state.js";
+import { PROJECT_ACCESS_DENIED } from "./project-access-denial.js";
+import { authorizationService } from "./authorization.js";

 type ProjectionIssue = Pick<typeof issues.$inferSelect, "id" | "companyId" | "status" | "assigneeAgentId" | "projectId">;
 type ProjectionRun = Pick<typeof heartbeatRuns.$inferSelect,
-  "id" | "status" | "scheduledRetryAt" | "errorCode" | "livenessState" | "resultJson">;
+  "id" | "status" | "scheduledRetryAt" | "errorCode" | "livenessState" | "resultJson"> &
+  Partial<Pick<typeof heartbeatRuns.$inferSelect, "agentId" | "error">>;
 type ProjectionState = {
  run?: ProjectionRun;
  action?: typeof issueRecoveryActions.$inferSelect;
  wait?: { id: string; requestedAt: Date };
  agent?: Pick<typeof agents.$inferSelect, "status" | "pauseReason">;
+  projectAccessAllowed?: boolean;
  project?: Pick<typeof projects.$inferSelect, "pausedAt" | "pauseReason">;
  company?: Pick<typeof companies.$inferSelect, "status" | "pauseReason">;
  paused: boolean;
  approval: boolean;
 };

+/** Recognize old persisted failures without displaying arbitrary run error text. */
+function deniedProjectId(issue: ProjectionIssue, run?: ProjectionRun): string | null | undefined {
+  const historical = run?.errorCode === "setup_failed" && run.error === "Project is outside this low-trust boundary.";
+  if (!run || run.status !== "failed" || run.agentId !== issue.assigneeAgentId
+      || (run.errorCode !== PROJECT_ACCESS_DENIED && !historical)) return undefined;
+  const detail = run.resultJson?.projectAccessDenied;
+  return detail && typeof detail === "object" && "projectId" in detail && typeof detail.projectId === "string"
+    ? detail.projectId : historical ? issue.projectId : null;
+}
+
 /** Presentation never grants authority. Dispatch repeats all gates under its
 * locks. The same projection is used in detail, lists and attention surfaces. */
 export function projectTaskInterruption(issue: ProjectionIssue, input: ProjectionState, now = Date.now()): TaskInterruptionPresentation | null {
@@ -36,6 +50,14 @@ export function projectTaskInterruption(issue: ProjectionIssue, input: Projectio
        ? "budget" : input.paused || project?.pausedAt || agent?.status === "paused" || company?.status === "paused" ? "resume" : null;
  if (userAction) return { ...base, responsibility: "user", state: "waiting_for_user", userAction };
  if (["running", "queued"].includes(run.status)) return { ...base, state: "working" };
+  const deniedProject = deniedProjectId(issue, run);
+  let projectAccess: TaskInterruptionPresentation["projectAccess"];
+  if (deniedProject !== undefined) {
+    const ready = input.projectAccessAllowed === true;
+    projectAccess = { agentId: run.agentId!, projectId: deniedProject === issue.projectId ? deniedProject : null, ready };
+    if (!ready) return { ...base, responsibility: "user", state: "waiting_for_user",
+      userAction: "project_access", projectAccess };
+  }
  const retryAt = system?.nextAttemptAt ?? run.scheduledRetryAt?.getTime();
  if (retryAt && retryAt > now) return { ...base, state: "retry_scheduled",
    nextRetryAt: new Date(retryAt).toISOString(), canRetry: true };
@@ -44,7 +66,7 @@ export function projectTaskInterruption(issue: ProjectionIssue, input: Projectio
      activeObservation > now - 45_000) return { ...base, state: "working" };
  if (wait && wait.requestedAt.getTime() > now - 10_000 && system?.state !== "exhausted")
    return { ...base, state: "working" };
-  return { ...base, state: "failed", canRetry: true };
+  return { ...base, state: "failed", canRetry: true, ...(projectAccess ? { projectAccess } : {}) };
 }

 /** Batch list reads rather than doing seven queries per row. Keep run logs and
@@ -61,8 +83,12 @@ export async function taskInterruptionPresentations(db: Db, companyId: string, i
  const projectIds = selected.flatMap(issue => issue.projectId ? [issue.projectId] : []);
  const [runs, waits, agentRows, projectRows, pauseRows, approvalRows, companyRows] = await Promise.all([
    db.selectDistinctOn([runIssue], { issueId: runIssue, id: heartbeatRuns.id, status: heartbeatRuns.status,
+      agentId: heartbeatRuns.agentId,
+      error: sql<string | null>`case when ${heartbeatRuns.errorCode} = 'setup_failed'
+        and ${heartbeatRuns.error} = 'Project is outside this low-trust boundary.' then ${heartbeatRuns.error} else null end`,
      errorCode: heartbeatRuns.errorCode, livenessState: heartbeatRuns.livenessState, scheduledRetryAt: heartbeatRuns.scheduledRetryAt,
-      resultJson: sql<Record<string, unknown>>`jsonb_build_object('configurationIncomplete', ${heartbeatRuns.resultJson}->'configurationIncomplete')`,
+      resultJson: sql<Record<string, unknown>>`jsonb_build_object('configurationIncomplete', ${heartbeatRuns.resultJson}->'configurationIncomplete',
+        'projectAccessDenied', ${heartbeatRuns.resultJson}->'projectAccessDenied')`,
    }).from(heartbeatRuns).where(and(eq(heartbeatRuns.companyId, companyId), inArray(runIssue, ids)))
      .orderBy(runIssue, desc(heartbeatRuns.createdAt), desc(heartbeatRuns.id)),
    db.selectDistinctOn([wakeIssue], { issueId: wakeIssue, id: agentWakeupRequests.id, requestedAt: agentWakeupRequests.requestedAt })
@@ -91,12 +117,32 @@ export async function taskInterruptionPresentations(db: Db, companyId: string, i
  )).orderBy(issueRecoveryActions.sourceIssueId, desc(issueRecoveryActions.createdAt)) : [];
  const byIssue = <T extends { issueId: string }>(rows: T[]) => new Map(rows.map(row => [row.issueId, row]));
  const runMap = byIssue(runs), waitMap = byIssue(waits);
+  // Recheck current authority, including standard trust, root-issue grants and
+  // project policy. Do not reuse the failed run's frozen policy for a new retry.
+  // Only denied tasks need these reads; deduplicate projects and batch per agent.
+  const deniedByAgent = new Map<string, Set<string>>();
+  for (const issue of selected) {
+    const projectId = deniedProjectId(issue, runMap.get(issue.id));
+    if (!projectId || !issue.assigneeAgentId || ["done", "cancelled"].includes(issue.status)) continue;
+    const ids = deniedByAgent.get(issue.assigneeAgentId) ?? new Set<string>();
+    ids.add(projectId);
+    deniedByAgent.set(issue.assigneeAgentId, ids);
+  }
+  const currentAccess = new Map<string, boolean>();
+  const authorization = authorizationService(db);
+  for (const [agentId, ids] of deniedByAgent) {
+    const projectIds = [...ids];
+    const decisions = await authorization.decideReads({ type: "agent", agentId, companyId, source: "agent_key" },
+      projectIds.map(projectId => ({ type: "project" as const, companyId, projectId })));
+    projectIds.forEach((projectId, index) => currentAccess.set(`${agentId}:${projectId}`, decisions[index]?.allowed === true));
+  }
  const actionMap = new Map(actions.map(action => [action.sourceIssueId, action]));
  const agentMap = new Map(agentRows.map(agent => [agent.id, agent]));
  const projectMap = new Map(projectRows.map(project => [project.id, project]));
  const pauses = new Set(pauseRows.map(row => row.issueId)), approvalsSet = new Set(approvalRows.map(row => row.issueId));
  for (const issue of selected) result.set(issue.id, projectTaskInterruption(issue, {
    run: runMap.get(issue.id), action: actionMap.get(issue.id), wait: waitMap.get(issue.id),
+    projectAccessAllowed: currentAccess.get(`${issue.assigneeAgentId}:${deniedProjectId(issue, runMap.get(issue.id))}`),
    agent: agentMap.get(issue.assigneeAgentId ?? ""), project: projectMap.get(issue.projectId ?? ""),
    company: companyRows[0], paused: pauses.has(issue.id), approval: approvalsSet.has(issue.id),
  }));
@@ -8,6 +8,7 @@ import { canonicalExecutionUuid } from "./execution-identity.js";
 import { assertSelectedWorkspaceTrust, runRetainsIssueIdentity, taskRepositoryRunColumns, taskRepositoryResponsibleUserMatches } from "./task-repository-acquisition.js";
 import { resolveCoreTrustPreset } from "./trust-preset-resolver.js";
 import { isDeepStrictEqual } from "node:util";
+import { ProjectAccessDeniedError } from "./project-access-denial.js";
 import { taskWorkspaceSelectionSchema, type TaskWorkspaceSelection } from "@paperclipai/shared";

 type DbTransaction = Parameters<Parameters<Db["transaction"]>[0]>[0];
@@ -19,7 +20,12 @@ export async function assertTaskWorkspaceSourceProjectAccess(
  const decision = await measureRunPhase("workspace.access.authorization", () => accessService(db as Db).decide({
    actor, action: "project:read", resource: { type: "project", companyId, projectId },
  }));
-  if (!decision.allowed) throw forbidden(decision.explanation);
+  if (!decision.allowed) {
+    if (actor.type === "agent" && decision.reason === "deny_low_trust_boundary") {
+      throw new ProjectAccessDeniedError(projectId);
+    }
+    throw forbidden(decision.explanation);
+  }
 }

 export async function assertExecutionWorkspaceRecordAccess(