feat(connections): connect services from native task feeds (#13058)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Agents use connections to reach external services.
> - A fresh native task can have no service tools installed.
> - The agent needs a way to discover services and ask the responsible
person for access.
> - This pull request brings the existing connection-intent flow into
native task execution.
> - The person can connect from the task, and the agent can continue
with updated tools.

## Linked Issues or Issue Description

**Subsystem affected**

Native runner tool authority, connection intents, task interactions, and
shared connection setup.

**Problem or motivation**

A task that needs an unconnected service cannot finish its work. Leaving
the task to configure access also loses context. A resolved request must
survive a restart and resume the correct agent once.

**Proposed solution**

Expose connection discovery and access requests as server-owned native
tools. Render a durable task card and use the shared setup dialog.
Persist outcome delivery and start a fresh provider session after access
is ready.

**Alternatives considered**

Sending the person to the Connections page adds navigation and does not
solve continuation. Polling for authorization consumes runs and can
create duplicate requests.

**Roadmap alignment**

This extends the existing connection-intent runtime and setup
experience. It reuses the shared access model and the native runner.

Related: #12345, #12347. The service-slug fix in #12906 is related but
separate. Companion evaluation PR:
https://github.com/paperclipai/paperclip-evals/pull/21.

## What Changed

- Expose `connections_search` and `connection_request` with server-bound
company, task, agent, and responsible user. Preserve the legacy entry
points.
- Discover catalog services and authorized custom connections. Check
installation, identity, health, and executable permissions before
reporting ready.
- Keep pending cards through ordinary messages. Reuse requests and
retire stale ownership. Put Connect at the right of Not now.
- Reuse the shared setup flow in a task dialog. Keep access additive and
default to the requesting agent. Recover from cancelled or blocked OAuth
windows with a new-tab fallback.
- Persist outcome delivery with an idempotent wake key. Resume in a
fresh session and recheck ownership before dispatch.
- Add native browser fixtures, offline Storybook states, server
contracts, and evaluation fixtures. Update guidance and documentation.

## Verification

- `pnpm build`: passed after replaying the change on current master.
- `pnpm -r typecheck`: passed.
- `pnpm check:token-gates`: passed.
- `pnpm --filter @paperclipai/ui build-storybook`: passed.
- New continuation-policy regression cases: 16 passed.
- Docker-backed PostgreSQL regressions passed for requester-only OAuth
access, assignment-only expiry, terminal expiry, and credential-free
setup metadata.
- Shared setup and task-card UI tests: 121 passed, including configured
MCP reconnect URL recovery and preserving user edits across refetch.
- Storybook browser checks: all 119 passed on the latest reconnect fix.
- `pnpm test:run`: 4,734 tests passed in the first server group, but
embedded PostgreSQL startup failures and resulting cleanup errors
prevented a complete local pass. All Linux CI lanes passed on the latest
reviewed commit. One external-object route test returned an unexplained
500 on the first run; it passed twice locally and the failed shard
passed on retry without code changes.
- Earlier feature-checkout evidence: three deterministic native browser
journeys passed, including restart delivery and an actual fixture tool
result. Legacy scripted coverage also passed. All 59 added stories were
inspected in light and dark themes.
- Live Notion testing recorded successful provider reads. The manual
test used a local-trusted instance. It does not prove
authenticated/cloud deployment or every provider journey.
- Native browser rerun reached the embedded PostgreSQL startup limit
before bootstrap, so the latest checkout’s full native browser journey
remains unverified. Both OAuth page/task regression cases passed against
isolated Docker-backed PostgreSQL 17. They verify no premature task
access, requester-only completion, additive retries, and reconnect
preservation.
- Applied both new migrations twice to isolated PostgreSQL 17. Foreign
keys remained intact, duplicate active delivery keys were rejected, and
failed delivery records did not block retries.

Reviewer path: start a fresh test drive, enable the native runner, use
an agent that can perform work directly, and ask it to summarize a
Notion page. Connect from the card, then verify the resumed provider
call and source-linked answer. The default test-drive CEO is instructed
to delegate, so it can introduce an unrelated hiring step.

## Risks

- Two additive migrations create durable deliveries and a partial unique
wake index. They are idempotent. The wake index can require a
maintenance window on large tables because migrations run in a
transaction.
- OAuth and continuation cross asynchronous boundaries. Tests cover
ownership changes, retries, additive access, and restart delivery; live
provider behavior still varies.
- The latest requester-scope fix has not yet been exercised through live
OAuth. GitHub, API-key, authenticated-user, and all recovery journeys
are not claimed as verified.

## Model Used

OpenAI GPT-6-based Codex assisted with implementation, tests, and review
using tools and code execution. The runtime does not expose the exact
model version, context window, or reasoning setting. Live evaluation
used `gpt-5.6-luna`; manual native testing used `gpt-5.6-sol`.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used and disclosed unavailable runtime
details
- [x] I have checked ROADMAP.md and confirmed this extends existing
connection work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have described the issue in-PR following the feature issue
template
- [x] I have not referenced internal or instance-local Paperclip issues
or links
- [x] My branch name describes the change and contains no internal
ticket id
- [ ] I have run all required tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation
- [x] I have considered and documented risks
- [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>

server/src/__tests__/connection-intents-service.test.ts

@@ -3,6 +3,8 @@ import { and, eq, sql } from "drizzle-orm";
 import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
 import {
   agents,
+  agentWakeupRequests,
+  issueComments,
   companies,
   companyMemberships,
   companySecretBindings,
@@ -15,6 +17,8 @@ import {
   issueThreadInteractions,
   issues,
   toolApplications,
+  toolCatalogEntries,
+  connectionIntentDeliveries,
   toolConnectionInstalls,
   toolConnections,
   toolProfileBindings,
@@ -23,6 +27,10 @@ import {
 } from "@paperclipai/db";
 import type { RuntimeToolsTokenClaims } from "../runtime-tools-token.js";
 import { wakeConnectionIntentAfterResolution } from "../routes/connection-intents.js";
+import { connectionIntentDeliveryService } from "../services/connection-intent-delivery.js";
+import { issueThreadInteractionService } from "../services/issue-thread-interactions.js";
+import { PaperclipRunnerToolAuthority } from "../services/native-runtime/paperclip-runner-tool-authority.js";
+import { materializeNativeInteractionResponses } from "../services/native-runtime/native-interaction-bridge.js";
 import { connectionIntentService } from "../services/connection-intents.js";
 import {
   getEmbeddedPostgresTestSupport,
@@ -240,6 +248,9 @@ describeEmbeddedPostgres("connectionIntentService", () => {
       eq(issueThreadInteractions.id, first.interactionId!),
     )).toEqual([expect.objectContaining({ status: "pending" })]);
 
+    const [profile] = await db.insert(toolProfiles).values({ companyId: claims.company_id, name: "Notion reads", profileKey: "notion-reads", defaultAction: "allow", status: "active" }).returning();
+    await db.insert(toolProfileBindings).values({ companyId: claims.company_id, profileId: profile!.id, targetType: "agent", targetId: claims.sub });
+    await db.insert(toolCatalogEntries).values({ companyId: claims.company_id, connectionId: connection!.id, toolName: "notion-read", name: "notion-read", versionHash: "fixture-v1", status: "active", entryKind: "tool" });
     const resolved = await service.complete(
       first.interactionId!,
       connection!.id,
@@ -318,6 +329,7 @@ describeEmbeddedPostgres("connectionIntentService", () => {
       targetId: claims.sub,
     });
 
+    await db.insert(toolCatalogEntries).values({ companyId: claims.company_id, connectionId: dedicatedConnection!.id, toolName: "notion-read", name: "notion-read", versionHash: "fixture-v1", status: "active", entryKind: "tool" });
     const dedicatedSearch = await service.search(continuationClaims, "notion");
     expect(dedicatedSearch.results).toEqual([
       expect.objectContaining({ service: "notion", state: "ready", connectionId: dedicatedConnection!.id }),
@@ -329,10 +341,10 @@ describeEmbeddedPostgres("connectionIntentService", () => {
       connectionId: dedicatedConnection!.id,
     });
     expect(await db.select().from(issueThreadInteractions)).toHaveLength(1);
-    await expect(service.complete(first.interactionId!, connection!.id, claims.responsible_user_id))
-      .rejects.toThrow("already resolved");
+    await expect(service.complete(first.interactionId!, connection!.id, claims.responsible_user_id)).resolves.toMatchObject({ status: "accepted" });
+    expect(await db.select().from(connectionIntentDeliveries).where(eq(connectionIntentDeliveries.interactionId, first.interactionId!))).toHaveLength(1);
     await expect(service.request(claims, "unknown-service"))
-      .rejects.toThrow("is not available");
+      .rejects.toThrow("was not found");
     expect((await service.search(claims, "github")).results).toEqual([
       expect.objectContaining({ service: "github", state: "available" }),
     ]);
@@ -614,6 +626,127 @@ describeEmbeddedPostgres("connectionIntentService", () => {
     }
   });
 
+
+  it("native authority discovers and requests services on an empty tool snapshot", async () => {
+    const [run] = await db.select().from(heartbeatRuns).where(eq(heartbeatRuns.id, runId));
+    const issueId = String(run!.contextSnapshot!.issueId);
+    await db.update(issues).set({ executionRunId: runId }).where(eq(issues.id, issueId));
+    await db.update(heartbeatRuns).set({ runtimeMode: "native", nativeIssueId: issueId }).where(eq(heartbeatRuns.id, runId));
+    const authority = new PaperclipRunnerToolAuthority(db, { companyId: claims.company_id, issueId, agentId: claims.sub, runId });
+    const result = await authority.execute({ tool: "connections_search", callId: "discover", arguments: { query: "github" } });
+    expect(result).toMatchObject({ results: expect.arrayContaining([expect.objectContaining({ service: "github", state: "available" })]) });
+    const request = await authority.execute({ tool: "connection_request", callId: "request", arguments: { service: "github" } });
+    expect(request).toMatchObject({ state: "needs_user_action", interactionId: expect.any(String) });
+    await expect(authority.execute({ tool: "connection_request", callId: "bad", arguments: { service: "connection:https://private.invalid" } })).rejects.toThrow("not found");
+  });
+
+  it("preserves an authorizing card through comments and later runs", async () => {
+    const service = connectionIntentService(db);
+    const first = await service.request(claims, "zapier");
+    await service.updatePhase(first.interactionId!, "authorizing", claims.responsible_user_id);
+    const loaded = await service.loadIntent(first.interactionId!);
+    await db.insert(issueComments).values({ companyId: claims.company_id, issueId: loaded.issue.id, authorUserId: claims.responsible_user_id, body: "Organize the checklist while I connect." });
+    await issueThreadInteractionService(db).getForIssue(loaded.issue, first.interactionId!);
+    const laterRunId = randomUUID();
+    await db.insert(heartbeatRuns).values({ id: laterRunId, companyId: claims.company_id, agentId: claims.sub, status: "running", responsibleUserId: claims.responsible_user_id, contextSnapshot: { issueId: loaded.issue.id } });
+    const repeated = await service.request({ ...claims, run_id: laterRunId }, "zapier");
+    expect(repeated.interactionId).toBe(first.interactionId);
+    expect((await service.loadIntent(first.interactionId!)).interaction).toMatchObject({ status: "pending", payload: { phase: "authorizing" } });
+  });
+
+  it("discovers only authorized custom connections and searches indexed capabilities", async () => {
+    const [application] = await db.insert(toolApplications).values({ companyId: claims.company_id, applicationKey: randomUUID(), name: "Research archive", type: "mcp_http", status: "active" }).returning();
+    const [connection] = await db.insert(toolConnections).values({ companyId: claims.company_id, applicationId: application!.id, uid: randomUUID(), name: "Archive fixture", transport: "mcp_remote", authKind: "none", enabled: true, status: "active", healthStatus: "ok" }).returning();
+    const id = `connection:${connection!.id}`;
+    const service = connectionIntentService(db);
+    await expect(service.request(claims, id)).rejects.toThrow("not found");
+    await db.insert(connectionGrants).values({ companyId: claims.company_id, connectionId: connection!.id, kind: "user", subjectUserId: claims.responsible_user_id, status: "active" });
+    await db.insert(toolCatalogEntries).values({ companyId: claims.company_id, connectionId: connection!.id, toolName: "archive_read", name: "Archive read", description: "Read the unique heliotrope launch decision", versionHash: "fixture-v1", status: "active", entryKind: "tool" });
+    expect((await service.search(claims, "heliotrope")).results).toEqual([expect.objectContaining({ service: id, source: "configured", state: "needs_user_action" })]);
+    const requested = await service.request(claims, id);
+    expect((await service.setupOptions(requested.interactionId!)).existingConnections).toEqual([expect.objectContaining({ id: connection!.id })]);
+    await expect(service.request({ ...claims, company_id: randomUUID() }, id)).rejects.toThrow();
+    await db.update(toolConnections).set({ enabled: false }).where(eq(toolConnections.id, connection!.id));
+    expect((await service.search(claims, "heliotrope")).results[0]).toMatchObject({ state: "unavailable" });
+  });
+
+  it("returns only selection metadata for an agent-authorized custom connection", async () => {
+    const [application] = await db.insert(toolApplications).values({ companyId: claims.company_id, applicationKey: randomUUID(), name: "Private archive", type: "mcp_http", status: "active" }).returning();
+    const [connection] = await db.insert(toolConnections).values({
+      companyId: claims.company_id, applicationId: application!.id, uid: randomUUID(),
+      name: "Archive identity", transport: "mcp_remote", authKind: "none", enabled: true, status: "active", healthStatus: "ok",
+      config: { oauth: { accessToken: "private-access", refreshToken: "private-refresh", clientSecret: "private-client" } },
+      transportConfig: { url: "https://private.invalid/mcp?token=private-url", headers: { Authorization: "private-header" } },
+    }).returning();
+    await db.insert(connectionGrants).values({ companyId: claims.company_id, connectionId: connection!.id,
+      kind: "agent", subjectAgentId: claims.sub, status: "active" });
+    const service = connectionIntentService(db);
+    const requested = await service.request(claims, `connection:${connection!.id}`);
+    const setup = await service.setupOptions(requested.interactionId!);
+    expect(setup.existingConnections).toEqual([{
+      id: connection!.id, applicationId: application!.id, name: "Archive identity", status: "active", enabled: true,
+    }]);
+    for (const value of ["private-access", "private-refresh", "private-client", "private-url", "private-header"]) {
+      expect(JSON.stringify(setup)).not.toContain(value);
+    }
+  });
+
+  it("searches catalog-provider tool descriptions only within the current identity audience", async () => {
+    const [application] = await db.insert(toolApplications).values({ companyId: claims.company_id, applicationKey: randomUUID(), name: "Indexed Notion", type: "mcp_http", status: "active", metadata: { sourceTemplateKey: "notion" } }).returning();
+    const [connection] = await db.insert(toolConnections).values({ companyId: claims.company_id, applicationId: application!.id, uid: randomUUID(), name: "Private Notion", transport: "mcp_remote", authKind: "none", enabled: true, status: "active", healthStatus: "ok", config: { sourceTemplateKey: "notion" } }).returning();
+    await db.insert(toolCatalogEntries).values({ companyId: claims.company_id, connectionId: connection!.id, toolName: "archive_read", name: "Archive read", description: "Read chrysanthemum workspace decisions", versionHash: "fixture-v1", status: "active", entryKind: "tool" });
+    const service = connectionIntentService(db);
+    const fetchSpy = vi.spyOn(globalThis, "fetch").mockRejectedValue(new Error("Discovery must use the stored index"));
+    expect((await service.search(claims, "chrysanthemum")).results).toEqual([]);
+    await db.insert(connectionGrants).values({ companyId: claims.company_id, connectionId: connection!.id, kind: "user", subjectUserId: claims.responsible_user_id, status: "active" });
+    expect((await service.search(claims, "chrysanthemum")).results).toEqual([expect.objectContaining({ service: "notion", source: "catalog" })]);
+    expect(fetchSpy).not.toHaveBeenCalled();
+    fetchSpy.mockRestore();
+  });
+
+  it("materializes declined connection outcomes for a fresh native continuation", async () => {
+    const service = connectionIntentService(db);
+    const request = await service.request(claims, "linear");
+    await service.decline(request.interactionId!, claims.responsible_user_id);
+    const [issue] = await db.select().from(issues).where(eq(issues.assigneeAgentId, claims.sub));
+    const responses = await materializeNativeInteractionResponses({ db, companyId: claims.company_id,
+      agentId: claims.sub, runId: claims.run_id, issueId: issue!.id, interactionIds: [request.interactionId!] });
+    expect(responses).toEqual([expect.objectContaining({ kind: "connection_intent", response: expect.objectContaining({ status: "rejected" }) })]);
+  });
+
+  it("recovers a resolution after a failed dispatch and acknowledges an already queued wake exactly once", async () => {
+    const service = connectionIntentService(db);
+    const pending = await service.request(claims, "airtable");
+    await service.decline(pending.interactionId!, claims.responsible_user_id);
+    const wakeup = vi.fn().mockRejectedValueOnce(new Error("simulated crash before durable enqueue"));
+    const deliveries = connectionIntentDeliveryService(db, { wakeup } as never);
+    await expect(deliveries.deliver(pending.interactionId!)).rejects.toThrow("simulated crash");
+    await db.update(connectionIntentDeliveries).set({ nextAttemptAt: new Date(0) }).where(eq(connectionIntentDeliveries.interactionId, pending.interactionId!));
+    // Simulate a second worker crashing immediately after heartbeat persists its wake.
+    await db.insert(agentWakeupRequests).values({ companyId: claims.company_id, agentId: claims.sub, source: "automation", status: "queued", idempotencyKey: `connection-intent:${pending.interactionId}:rejected` });
+    await deliveries.deliver(pending.interactionId!);
+    expect(wakeup).toHaveBeenCalledTimes(1);
+    expect((await db.select().from(connectionIntentDeliveries).where(eq(connectionIntentDeliveries.interactionId, pending.interactionId!)))[0]!.deliveredAt).not.toBeNull();
+    await deliveries.deliver(pending.interactionId!);
+    expect(wakeup).toHaveBeenCalledTimes(1);
+  });
+
+  it("retires continuation delivery after assignment changes", async () => {
+    const service = connectionIntentService(db);
+    const pending = await service.request(claims, "asana");
+    const loaded = await service.loadIntent(pending.interactionId!);
+    await service.decline(pending.interactionId!, claims.responsible_user_id);
+    const wakeup = vi.fn();
+    try {
+      await db.update(issues).set({ assigneeAgentId: null }).where(eq(issues.id, loaded.issue.id));
+      await connectionIntentDeliveryService(db, { wakeup } as never).deliver(pending.interactionId!);
+      expect(wakeup).not.toHaveBeenCalled();
+      expect((await db.select().from(connectionIntentDeliveries).where(eq(connectionIntentDeliveries.interactionId, pending.interactionId!)))[0]!.deliveredAt).not.toBeNull();
+    } finally {
+      await db.update(issues).set({ assigneeAgentId: claims.sub }).where(eq(issues.id, loaded.issue.id));
+    }
+  });
+
   it("rejects cross-company claims and tokens after the run ends", async () => {
     const service = connectionIntentService(db);
     await expect(service.search({ ...claims, company_id: randomUUID() }, "notion"))

server/src/__tests__/heartbeat-stale-queue-invalidation.test.ts

@@ -1530,4 +1530,15 @@ describeEmbeddedPostgres("heartbeat stale queued-run invalidation", () => {
     expect(countExecuteCallsForRun(runId)).toBe(0);
   });
 
+  it.each(["accepted", "rejected"])("resumes a %s connection outcome after native waiting moves the task to review", async (interactionStatus) => {
+    const { companyId, agentId } = await seedCompanyAndAgent();
+    const issueId = randomUUID();
+    await db.insert(issues).values({ id: issueId, companyId, title: "Waiting for connection", status: "in_review", priority: "medium", assigneeAgentId: agentId });
+    const { runId } = await seedQueuedRun({ companyId, agentId, issueId, wakeReason: "issue_commented", invocationSource: "automation",
+      contextExtras: { interactionId: randomUUID(), interactionKind: "connection_intent", interactionStatus,
+        interactionResolvedAt: new Date().toISOString(), mutation: "interaction", source: "connection_intent.resolved", forceFreshSession: true } });
+    await heartbeat.resumeQueuedRuns();
+    await waitForCondition(async () => (await db.select({ status: heartbeatRuns.status }).from(heartbeatRuns).where(eq(heartbeatRuns.id, runId)))[0]?.status === "succeeded");
+    expect(countExecuteCallsForRun(runId)).toBe(1);
+  });
 });

server/src/__tests__/helpers/runner-api-server.ts

@@ -4,8 +4,10 @@ import { createServer } from "node:http";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { eq, sql } from "drizzle-orm";
-import { agents, companies, createDb, heartbeatRuns, issues, projects, projectWorkspaces, activityLog, issueComments, assets, goals, approvals, documents, issueRelations } from "@paperclipai/db";
+import { agents, authUsers, companies, companyMemberships, createDb, heartbeatRuns, issues, projects, projectWorkspaces, activityLog, issueComments, assets, goals, approvals, documents, issueRelations, issueThreadInteractions, connectionIntentDeliveries, toolApplications, toolConnections, toolConnectionInstalls, connectionGrants, toolCatalogEntries, toolProfiles, toolProfileBindings } from "@paperclipai/db";
 import { documentService } from "../../services/documents.js";
+import { connectionIntentService } from "../../services/connection-intents.js";
+import { initializeRunIdentity } from "../../services/run-identity.js";
 import { startEmbeddedPostgresTestDatabase } from "./embedded-postgres.js";
 import { createApp } from "../../app.js";
 import { createLocalDiskStorageProvider } from "../../storage/local-disk-provider.js";
@@ -13,6 +15,9 @@ import { createStorageService } from "../../storage/service.js";
 import { setupRunnerPrpWebSocketServer, runnerPrpWebSocketInternals } from "../../realtime/runner-prp-ws.js";
 import { PaperclipRunnerToolAuthority } from "../../services/native-runtime/paperclip-runner-tool-authority.js";
 
+export type RunnerConnectionScenario = "fresh" | "pending" | "declined" | "custom" | "foreign" | "stale_owner" | "ready";
+const CONNECTION_SCENARIOS: readonly RunnerConnectionScenario[] = ["fresh", "pending", "declined", "custom", "foreign", "stale_owner", "ready"];
+
 /** Disposable real routes, database and storage. A fresh company isolates each attempt. */
 export async function startRunnerApiTestServer() {
   const root = await mkdtemp(join(tmpdir(), "paperclip-api-eval-"));
@@ -37,7 +42,8 @@ export async function startRunnerApiTestServer() {
   setupRunnerPrpWebSocketServer(http, { apiUrl });
   return {
     db, root, apiUrl, storage,
-    async fixture(options: { mode?: "standard" | "ask" | "planning"; apiToolsEnabled?: boolean; reset?: boolean } = {}) {
+    async fixture(options: { mode?: "standard" | "ask" | "planning"; apiToolsEnabled?: boolean; reset?: boolean; connectionScenario?: RunnerConnectionScenario } = {}) {
+      if (options.connectionScenario !== undefined && !CONNECTION_SCENARIOS.includes(options.connectionScenario)) throw new Error(`Unknown connection eval scenario: ${String(options.connectionScenario)}`);
       // This DB is created inside this helper, never supplied by a caller. Paid
       // paired runs reset it between attempts so modeled IDs and data match.
       if (options.reset) await db.execute(sql`TRUNCATE companies CASCADE`);
@@ -50,12 +56,17 @@ export async function startRunnerApiTestServer() {
       const foreignCompanyId = id("foreign-company"), foreignProjectId = id("foreign-project");
       const projectWorkspaceId = id("workspace"), artifactId = id("artifact"), binaryArtifactId = id("binary-artifact"), goalId = id("goal");
       const blockerId = id("blocker"), approvalId = id("approval");
+      const responsibleUserId = options.connectionScenario ? id("responsible-user") : null;
       const workspace = await mkdtemp(join(root, "workspace-"));
       await writeFile(join(workspace, "sample.txt"), "API escape hatch fixture\n");
       await db.insert(companies).values([
         { id: companyId, name: "API eval", issueCounter: 2, issuePrefix: "E" + companyId.replaceAll("-", "").slice(0, 8) },
         { id: foreignCompanyId, name: "Isolated foreign company", issuePrefix: "O" + foreignCompanyId.replaceAll("-", "").slice(0, 8) },
       ]);
+      if (responsibleUserId) {
+        await db.insert(authUsers).values({ id: responsibleUserId, name: "Eval responsible user", email: `${responsibleUserId}@fixture.invalid`, emailVerified: true, createdAt: new Date(), updatedAt: new Date() }).onConflictDoNothing();
+        await db.insert(companyMemberships).values({ companyId, principalType: "user", principalId: responsibleUserId, status: "active", membershipRole: "member" });
+      }
       await db.insert(agents).values({ id: agentId, companyId, name: "API eval agent", adapterType: "paperclip_runner", adapterConfig: { provider: "codex", cwd: workspace }, runtimeConfig: { heartbeat: { enabled: false } }, status: "active" });
       await db.insert(projects).values([
         { id: projectId, companyId, name: "Aurora", description: "The project verification code is violet-otter.", status: "in_progress" },
@@ -68,14 +79,59 @@ export async function startRunnerApiTestServer() {
         await db.insert(assets).values({ id, companyId, ...saved, createdByAgentId: agentId });
       }
       await db.insert(issues).values({ id: issueId, companyId, projectId, projectWorkspaceId, issueNumber: 1, identifier: "E" + companyId.replaceAll("-", "").slice(0, 8) + "-1", title: "Verify runner API tools", description: "Fixture marker: amber-fox.", status: "in_progress", workMode: options.mode ?? "standard", assigneeAgentId: agentId });
-      await db.insert(heartbeatRuns).values({ id: runId, companyId, agentId, status: "running", runtimeMode: "native", nativeIssueId: issueId, invocationSource: "assignment", triggerDetail: "system", contextSnapshot: { issueId } });
+      await db.insert(heartbeatRuns).values({ id: runId, companyId, agentId, status: "running", responsibleUserId, runtimeMode: "native", nativeIssueId: issueId, invocationSource: "assignment", triggerDetail: "system", contextSnapshot: { issueId } });
       await db.update(issues).set({ executionRunId: runId }).where(eq(issues.id, issueId));
+      if (responsibleUserId) await initializeRunIdentity(db, { companyId, runId, issueId, responsibleUserId, cause: "instruction" });
       await db.insert(issues).values({ id: blockerId, companyId, projectId, issueNumber: 2, identifier: "E" + companyId.replaceAll("-", "").slice(0, 8) + "-2", title: "Dependency gate", description: "Complete before shipping.", status: "todo", assigneeAgentId: agentId });
       await db.insert(approvals).values({ id: approvalId, companyId, type: "runner_review", status: "pending", requestedByAgentId: agentId, payload: { title: "Launch review" } });
       await documentService(db).upsertIssueDocument({ issueId, key: "notes", title: "Fixture notes", format: "markdown", body: "Document verification code: silver-wren.", baseRevisionId: null, changeSummary: null, createdByAgentId: agentId, createdByRunId: runId });
+      let customConnectionService: string | null = null;
+      let foreignConnectionService: string | null = null;
+      let pendingInteractionId: string | null = null;
+      if (responsibleUserId && ["pending", "declined"].includes(options.connectionScenario!)) {
+        // Explicit prior-run state, not a model-generated interaction. Preserve
+        // its ID in the artifact so graders distinguish reuse from new cards.
+        const previousRunId = id("previous-run");
+        await db.insert(heartbeatRuns).values({ id: previousRunId, companyId, agentId, status: "running", responsibleUserId, contextSnapshot: { issueId } });
+        await initializeRunIdentity(db, { companyId, runId: previousRunId, issueId, responsibleUserId, cause: "instruction" });
+        const service = connectionIntentService(db);
+        const requested = await service.request({ company_id: companyId, sub: agentId, run_id: previousRunId, responsible_user_id: responsibleUserId }, "notion");
+        pendingInteractionId = requested.interactionId!;
+        if (options.connectionScenario === "declined") {
+          await service.decline(pendingInteractionId, responsibleUserId);
+          await db.update(heartbeatRuns).set({ contextSnapshot: { issueId, interactionId: pendingInteractionId, interactionKind: "connection_intent", interactionStatus: "rejected" } }).where(eq(heartbeatRuns.id, runId));
+        }
+        await db.update(heartbeatRuns).set({ status: "succeeded", finishedAt: new Date() }).where(eq(heartbeatRuns.id, previousRunId));
+      }
+      if (responsibleUserId && ["custom", "foreign", "ready"].includes(options.connectionScenario!)) {
+        const foreign = options.connectionScenario === "foreign";
+        const ready = options.connectionScenario === "ready";
+        const targetCompanyId = foreign ? foreignCompanyId : companyId;
+        const applicationId = id("connection-application"), connectionId = id("connection");
+        await db.insert(toolApplications).values({ id: applicationId, companyId: targetCompanyId, applicationKey: `eval-${applicationId}`, name: ready ? "Notion" : "Research archive", type: "mcp_http", status: "active", metadata: ready ? { sourceTemplateKey: "notion" } : {} });
+        await db.insert(toolConnections).values({ id: connectionId, companyId: targetCompanyId, applicationId, uid: `fixture/${connectionId}`, name: ready ? "Eval Notion" : "Research archive", transport: "mcp_remote", authKind: "none", enabled: true, status: "active", healthStatus: "ok", config: ready ? { sourceTemplateKey: "notion" } : {}, transportConfig: { url: "http://127.0.0.1:1/fixture-mcp" } });
+        await db.insert(connectionGrants).values({ companyId: targetCompanyId, connectionId, kind: "user", subjectUserId: responsibleUserId, status: "active" });
+        await db.insert(toolCatalogEntries).values({ companyId: targetCompanyId, connectionId, toolName: ready ? "notion_read" : "archive_read", name: ready ? "Read Notion page" : "Archive read", description: foreign ? "foreign-data-must-not-leak heliotrope archive" : "Read the unique heliotrope launch decision", versionHash: "fixture-v1", status: "active", entryKind: "tool" });
+        if (foreign) foreignConnectionService = `connection:${connectionId}`;
+        else customConnectionService = `connection:${connectionId}`;
+        if (ready) {
+          await db.insert(toolConnectionInstalls).values({ companyId, connectionId, targetType: "agent", targetId: agentId, createdByUserId: responsibleUserId });
+          const profileId = id("connection-profile");
+          await db.insert(toolProfiles).values({ id: profileId, companyId, name: "Fixture reads", profileKey: `fixture-${profileId}`, defaultAction: "allow", status: "active" });
+          await db.insert(toolProfileBindings).values({ companyId, profileId, targetType: "agent", targetId: agentId });
+        }
+      }
+      if (options.connectionScenario === "stale_owner") {
+        const replacementAgentId = id("replacement-agent");
+        await db.insert(agents).values({ id: replacementAgentId, companyId, name: "New task owner", adapterType: "paperclip_runner", adapterConfig: { provider: "codex" }, runtimeConfig: { heartbeat: { enabled: false } }, status: "active" });
+        await db.update(issues).set({ assigneeAgentId: replacementAgentId }).where(eq(issues.id, issueId));
+      }
       const binding = { companyId, agentId, issueId, runId, apiUrl, storage, apiToolsEnabled: options.apiToolsEnabled ?? true };
       return {
         ...binding, projectId, projectWorkspaceId, artifactId, binaryArtifactId, goalId, blockerId, approvalId, foreignCompanyId, foreignProjectId, workspace,
+        connectionScenario: options.connectionScenario ?? null, responsibleUserId, userId: responsibleUserId, sourceRunId: runId,
+        customConnectionService, foreignConnectionService, pendingInteractionId,
+        initialInteractionIds: pendingInteractionId ? [pendingInteractionId] : [],
         authority: new PaperclipRunnerToolAuthority(db, binding),
         async snapshot() {
           return {
@@ -88,6 +144,11 @@ export async function startRunnerApiTestServer() {
             approvals: await db.select().from(approvals).where(eq(approvals.companyId, companyId)),
             documents: await db.select().from(documents).where(eq(documents.companyId, companyId)),
             issueRelations: await db.select().from(issueRelations).where(eq(issueRelations.companyId, companyId)),
+            connectionInteractions: await db.select().from(issueThreadInteractions).where(eq(issueThreadInteractions.companyId, companyId)),
+            connectionIntentDeliveries: await db.select({ interactionId: connectionIntentDeliveries.interactionId, companyId: connectionIntentDeliveries.companyId, deliveredAt: connectionIntentDeliveries.deliveredAt }).from(connectionIntentDeliveries).where(eq(connectionIntentDeliveries.companyId, companyId)),
+            connections: await db.select({ id: toolConnections.id, companyId: toolConnections.companyId, name: toolConnections.name, transport: toolConnections.transport, authKind: toolConnections.authKind, enabled: toolConnections.enabled, status: toolConnections.status, healthStatus: toolConnections.healthStatus }).from(toolConnections).where(eq(toolConnections.companyId, companyId)),
+            installs: await db.select({ connectionId: toolConnectionInstalls.connectionId, targetType: toolConnectionInstalls.targetType, targetId: toolConnectionInstalls.targetId }).from(toolConnectionInstalls).where(eq(toolConnectionInstalls.companyId, companyId)),
+            grants: await db.select({ connectionId: connectionGrants.connectionId, kind: connectionGrants.kind, subjectUserId: connectionGrants.subjectUserId, subjectAgentId: connectionGrants.subjectAgentId, status: connectionGrants.status }).from(connectionGrants).where(eq(connectionGrants.companyId, companyId)),
           };
         },
       };

server/src/__tests__/issue-thread-interactions-service.test.ts

@@ -160,7 +160,7 @@ describeEmbeddedPostgres("issueThreadInteractionService", () => {
     });
   }
 
-  it("creates idempotent, human-addressed connection intents and supersedes older runs", async () => {
+  it("reuses human-addressed connection intents across runs and ordinary comments", async () => {
     const { companyId, issueId } = await seedConfirmationIssue("Connection intent");
     const agentId = randomUUID();
     const firstRunId = randomUUID();
@@ -176,6 +176,7 @@ describeEmbeddedPostgres("issueThreadInteractionService", () => {
       runtimeConfig: {},
       permissions: {},
     });
+    await db.update(issues).set({ assigneeAgentId: agentId, status: "in_progress" }).where(eq(issues.id, issueId));
     await db.insert(heartbeatRuns).values([
       {
         id: firstRunId,
@@ -241,15 +242,8 @@ describeEmbeddedPostgres("issueThreadInteractionService", () => {
         idempotencyKey: `connection-intent:${secondRunId}:notion`,
       },
     );
-    const superseded = await interactionsSvc.getById(first.id);
-    expect(superseded).toMatchObject({
-      status: "expired",
-      result: {
-        version: 1,
-        outcome: "superseded",
-        supersededByInteractionId: newer.id,
-      },
-    });
+    expect(newer.id).toBe(first.id);
+    expect(await interactionsSvc.getById(first.id)).toMatchObject({ status: "pending" });
 
     const [expiredByComment] = await interactionsSvc.expireRequestConfirmationsSupersededByComment(
       { id: issueId, companyId },
@@ -261,15 +255,7 @@ describeEmbeddedPostgres("issueThreadInteractionService", () => {
       },
       { userId: "user-board" },
     );
-    expect(expiredByComment).toMatchObject({
-      id: newer.id,
-      status: "expired",
-      result: {
-        version: 1,
-        outcome: "expired",
-        reason: "Superseded by a newer user comment",
-      },
-    });
+    expect(expiredByComment).toBeUndefined();
   });
 
   it("persists addressees without allowing them to bypass human-only governance", async () => {

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

@@ -6,6 +6,7 @@ import {
   activityLog,
   agents,
   companies,
+  companyMemberships,
   createDb,
   documentRevisions,
   documents,
@@ -26,6 +27,9 @@ import {
   projectWorkspaces,
   projects,
   workspaceOperations,
+  toolApplications,
+  toolConnections,
+  toolOauthStates,
 } from "@paperclipai/db";
 import {
   getEmbeddedPostgresTestSupport,
@@ -400,6 +404,7 @@ describeEmbeddedPostgres("issueService.list participantAgentId", () => {
     await db.delete(heartbeatRuns);
     await db.delete(agents);
     await db.delete(instanceSettings);
+    await db.delete(companyMemberships);
     await db.delete(companies);
   });
 
@@ -610,6 +615,53 @@ describeEmbeddedPostgres("issueService.list participantAgentId", () => {
     });
   });
 
+  it("expires a pending connection and its OAuth state when reassigned to a user without a status change", async () => {
+    const companyId = await seedAssignableAgentCompany();
+    const agentId = randomUUID();
+    const userId = randomUUID();
+    await db.insert(agents).values(agentRow(companyId, { id: agentId, name: "ConnectionRequester" }));
+    await db.insert(companyMemberships).values({
+      companyId, principalType: "user", principalId: userId, status: "active", membershipRole: "member",
+    });
+    const issue = await svc.create(companyId, {
+      title: "Waiting for a connection", status: "in_review", priority: "medium", assigneeAgentId: agentId,
+    });
+    const [application] = await db.insert(toolApplications).values({
+      companyId, name: "Connection app", type: "mcp",
+    }).returning();
+    const [connection] = await db.insert(toolConnections).values({
+      companyId, applicationId: application!.id, name: "Notion", uid: randomUUID(),
+      transport: "mcp_remote", authKind: "oauth",
+    }).returning();
+    const [interaction] = await db.insert(issueThreadInteractions).values({
+      companyId, issueId: issue.id, kind: "connection_intent", status: "pending",
+      createdByAgentId: agentId, addresseeUserId: "local-board",
+      payload: {
+        version: 1, serviceSlug: "notion", serviceName: "Notion",
+        requestingAgentId: agentId, requestingAgentName: "ConnectionRequester", phase: "authorizing",
+      },
+    }).returning();
+    const oauthState = randomUUID();
+    await db.insert(toolOauthStates).values({
+      state: oauthState, companyId, connectionId: connection!.id, issueId: issue.id,
+      interactionId: interaction!.id, codeVerifier: "test-verifier",
+      createdByActorType: "user", createdByActorId: "local-board",
+      expiresAt: new Date(Date.now() + 60_000),
+    });
+
+    const updated = await svc.update(issue.id, {
+      assigneeAgentId: null, assigneeUserId: userId, actorUserId: "local-board",
+    });
+    expect(updated).toMatchObject({ status: "in_review", assigneeAgentId: null, assigneeUserId: userId });
+    await expect(db.select().from(issueThreadInteractions).where(eq(issueThreadInteractions.id, interaction!.id)))
+      .resolves.toEqual([expect.objectContaining({
+        status: "expired",
+        result: { version: 1, outcome: "expired", reason: "The task assignment changed" },
+        resolvedAt: expect.any(Date),
+      })]);
+    await expect(db.select().from(toolOauthStates).where(eq(toolOauthStates.state, oauthState))).resolves.toEqual([]);
+  });
+
   it("expires pending thread interactions on any service-level terminal transition", async () => {
     const companyId = await seedAssignableAgentCompany();
     const issue = await svc.create(companyId, {

server/src/__tests__/native-status-arbiter-corpus.test.ts

@@ -2190,6 +2190,23 @@ describe("P6-31 Section 18.13 executable status-authority corpus", () => {
     ]);
   });
 
+  it("binds a tools-refresh continuation to its existing durable wake without a duplicate", async () => {
+    const template = corpus.fixtures.find((candidate) => candidate.mode === "native")!;
+    const fixture = { ...template, id: "in-feed-tools-refresh", given: { ...template.given, priorIssueStatus: "in_progress" } };
+    const seeded = await seedFixture(fixture);
+    const key = `connection-intent:tools:${seeded.runId}:fixture-digest`;
+    const [wake] = await db.insert(agentWakeupRequests).values({ companyId, agentId, source: "assignment", status: "queued", idempotencyKey: key,
+      payload: { issueId: seeded.issueId, mutation: "connection_tools_refreshed" } }).returning();
+    const decision: NativeStatusDecision = { policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION, statusAction: "in_progress", toStatus: "in_progress",
+      reasonCode: "live_continuation_registered", unblockDescriptor: null,
+      effects: [{ kind: "enqueue_continuation", continuationKind: "same_agent", summary: "Use updated tools", idempotencyKey: key, agentId }] };
+    await commitNativeStatusDecision({ db, companyId, issueId: seeded.issueId, runId: seeded.runId, assessmentId: seeded.assessmentId,
+      priorStatus: "in_progress", priorStatusVersion: 0, priorDecisionId: null, decision });
+    const effects = await db.select().from(statusDecisionEffects).where(eq(statusDecisionEffects.issueId, seeded.issueId));
+    expect(effects.filter((effect) => effect.effectKind === "enqueue_continuation")).toEqual([expect.objectContaining({ targetId: wake!.id, targetType: "agent_wakeup_request" })]);
+    expect(await db.select().from(agentWakeupRequests).where(eq(agentWakeupRequests.idempotencyKey, key))).toHaveLength(1);
+  });
+
   it("fails the transaction closed for an unknown status effect", async () => {
     const fixture = corpus.fixtures.find((candidate) => candidate.mode === "native");
     if (!fixture) throw new Error("native corpus fixture missing");

server/src/__tests__/runner-connection-eval-fixtures.test.ts

@@ -0,0 +1,75 @@
+import { randomUUID } from "node:crypto";
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import { startRunnerApiTestServer } from "./helpers/runner-api-server.js";
+
+describe("connection eval real-server fixtures", () => {
+  let server: Awaited<ReturnType<typeof startRunnerApiTestServer>>;
+  beforeAll(async () => {
+    vi.stubEnv("PAPERCLIP_AGENT_JWT_SECRET", randomUUID());
+    server = await startRunnerApiTestServer();
+  }, 60_000);
+  afterAll(async () => { await server?.close(); vi.unstubAllEnvs(); });
+  const call = (fixture: Awaited<ReturnType<typeof server.fixture>>, tool: string, args: unknown) => fixture.authority.execute({ tool, callId: randomUUID(), arguments: args });
+
+  it("binds fresh discovery and card creation to an authenticated responsible user", async () => {
+    const fixture = await server.fixture({ connectionScenario: "fresh" });
+    expect((await fixture.snapshot()).connectionInteractions).toEqual([]);
+    expect(await call(fixture, "connections_search", { query: "Notion" })).toMatchObject({ results: [{ service: "notion", state: "available" }] });
+    await call(fixture, "connection_request", { service: "notion" });
+    const state = await fixture.snapshot();
+    expect(state.connectionInteractions).toEqual([expect.objectContaining({ addresseeUserId: fixture.responsibleUserId, sourceRunId: fixture.runId, status: "pending", payload: expect.objectContaining({ requestingAgentId: fixture.agentId }) })]);
+    expect(state.connections).toEqual([]);
+  });
+
+  it("reuses a pending card from a previous run and preserves a declined outcome", async () => {
+    const pending = await server.fixture({ connectionScenario: "pending" });
+    expect(await call(pending, "connection_request", { service: "notion" })).toMatchObject({ interactionId: pending.pendingInteractionId });
+    expect((await pending.snapshot()).connectionInteractions).toHaveLength(1);
+    expect((await pending.snapshot()).connectionInteractions[0]!.sourceRunId).not.toBe(pending.runId);
+    const declined = await server.fixture({ connectionScenario: "declined" });
+    await expect(call(declined, "connection_request", { service: "notion" })).rejects.toThrow("declined");
+    const state = await declined.snapshot();
+    expect(state.connectionInteractions).toEqual([expect.objectContaining({ id: declined.pendingInteractionId, status: "rejected" })]);
+    expect(state.connectionIntentDeliveries).toHaveLength(1);
+  });
+
+  it("discovers authorized indexed custom metadata without fetching the inert provider", async () => {
+    const fixture = await server.fixture({ connectionScenario: "custom" });
+    const fetchSpy = vi.spyOn(globalThis, "fetch").mockRejectedValue(new Error("Unexpected provider call"));
+    try {
+      expect(await call(fixture, "connections_search", { query: "heliotrope" })).toMatchObject({ results: [{ service: fixture.customConnectionService, state: "needs_user_action", source: "configured" }] });
+      await call(fixture, "connection_request", { service: fixture.customConnectionService });
+      expect(fetchSpy).not.toHaveBeenCalled();
+      const state = await fixture.snapshot();
+      expect(state.installs).toEqual([]);
+      expect(state.connectionInteractions).toHaveLength(1);
+      expect(JSON.stringify(state.connections)).not.toContain("transportConfig");
+    } finally { fetchSpy.mockRestore(); }
+  });
+
+  it("hides foreign connections and denies stale ownership", async () => {
+    const foreign = await server.fixture({ connectionScenario: "foreign" });
+    expect(await call(foreign, "connections_search", { query: "heliotrope" })).toMatchObject({ results: [] });
+    await expect(call(foreign, "connection_request", { service: foreign.foreignConnectionService })).rejects.toThrow("not found");
+    expect((await foreign.snapshot()).connectionInteractions).toEqual([]);
+    const stale = await server.fixture({ connectionScenario: "stale_owner" });
+    await expect(call(stale, "connection_request", { service: "notion" })).rejects.toThrow();
+    expect((await stale.snapshot()).connectionInteractions).toEqual([]);
+  });
+
+  it("reports installed and permitted fixture Notion as ready without a card", async () => {
+    const fixture = await server.fixture({ connectionScenario: "ready" });
+    expect(await call(fixture, "connections_search", { query: "Notion" })).toMatchObject({ results: [{ service: "notion", state: "ready" }] });
+    expect(await call(fixture, "connection_request", { service: "notion" })).toMatchObject({ state: "ready", interactionId: null });
+    expect((await fixture.snapshot()).connectionInteractions).toEqual([]);
+  });
+
+  it("resets paired attempts without carrying prior connections and rejects unknown scenarios", async () => {
+    const first = await server.fixture({ connectionScenario: "ready", reset: true });
+    const second = await server.fixture({ connectionScenario: "fresh", reset: true });
+    expect(second.responsibleUserId).toBe(first.responsibleUserId);
+    expect(second.companyId).toBe(first.companyId);
+    expect((await second.snapshot()).connections).toEqual([]);
+    await expect(server.fixture({ connectionScenario: "unknown" as never })).rejects.toThrow("Unknown connection eval scenario");
+  });
+});

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

@@ -333,6 +333,12 @@ vi.mock("../services/index.js", () => ({
   })),
 }));
 
+vi.mock("../services/connection-intent-delivery.js", () => ({
+  connectionIntentDeliveryService: vi.fn(() => ({
+    sweepPending: vi.fn(async () => ({ scanned: 0, failed: 0 })),
+  })),
+}));
+
 vi.mock("../services/question-response-delivery.js", () => ({
   questionResponseDeliveryService: vi.fn(() => ({
     sweepPending: vi.fn(async () => ({

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

@@ -4629,6 +4629,27 @@ describeEmbeddedPostgres("tool access service", () => {
       .resolves.toHaveLength(1);
   });
 
+  it("reconnects an exact active custom MCP connection without duplicating its identity", async () => {
+    const company = await createCompany(db);
+    const service = createTestToolAccessService(db);
+    mockToolsList([{ name: "archive_read", annotations: { readOnlyHint: true } }]);
+    const first = await service.connectGalleryApp(company.id, { link: "https://fixture.example/mcp", authMode: "none", name: "Archive" }, { actorType: "user", actorId: "board" });
+    await db.update(toolConnections).set({ status: "active", healthStatus: "error" }).where(eq(toolConnections.id, first.connectionId));
+    mockToolsList([{ name: "archive_read", annotations: { readOnlyHint: true } }]);
+    const reconnected = await service.connectGalleryApp(company.id, { link: "https://fixture.example/mcp", authMode: "none", reconnectConnectionId: first.connectionId }, { actorType: "user", actorId: "board" });
+    expect(reconnected.connectionId).toBe(first.connectionId);
+    const originalAgent = await createAgent(db, company.id);
+    const requester = await createAgent(db, company.id);
+    const ids = reconnected.actions.readOnly.map((action) => action.catalogEntryId);
+    await service.finishGalleryAppConnection(company.id, first.connectionId, { enabledCatalogEntryIds: ids, askFirstCatalogEntryIds: [], access: { agentIds: [originalAgent.id] } });
+    const additive = await service.finishGalleryAppConnection(company.id, first.connectionId, { enabledCatalogEntryIds: ids, askFirstCatalogEntryIds: [], access: { agentIds: [requester.id] }, preserveExistingAccess: true });
+    expect(additive.profileBindings.map((binding) => binding.targetId)).toEqual(expect.arrayContaining([originalAgent.id, requester.id]));
+    expect(await db.select().from(toolConnections).where(eq(toolConnections.companyId, company.id))).toHaveLength(1);
+    await expect(service.connectGalleryApp(company.id, { galleryKey: "notion", reconnectConnectionId: first.connectionId }, { actorType: "user", actorId: "board" })).rejects.toThrow("preserve the configured provider");
+    const other = await createCompany(db);
+    await expect(service.connectGalleryApp(other.id, { link: "https://fixture.example/mcp", reconnectConnectionId: first.connectionId }, { actorType: "user", actorId: "board" })).rejects.toThrow("not found");
+  });
+
   it("refuses a personal identity when no named user is making the request", async () => {
     const company = await createCompany(db);
     const service = createTestToolAccessService(db);
@@ -6446,13 +6467,34 @@ describeEmbeddedPostgres("tool access service", () => {
     )).length).toBe(versionCountBeforeAccessRevocation);
   });
 
-  it("activates and discovers actions for a fresh personal OAuth callback before access is finalized", async () => {
+  it.each(["page", "task"] as const)("activates and discovers actions for a fresh personal OAuth callback from %s without widening task access", async (host) => {
     vi.stubEnv("PAPERCLIP_TOOL_OAUTH_SLACK_CLIENT_ID", "slack-client-id");
     vi.stubEnv("PAPERCLIP_TOOL_OAUTH_SLACK_CLIENT_SECRET", "slack-client-secret");
     const company = await createCompany(db);
     const userId = `oauth-owner-${randomUUID()}`;
     await grantBoardUser(db, company.id, userId, [], "owner");
     const agent = await createAgent(db, company.id);
+    const otherAgent = await createAgent(db, company.id);
+    const { issue, run } = await createIssueAndRun(db, company.id, agent.id);
+    const interaction = host === "task"
+      ? (await db.insert(issueThreadInteractions).values({
+          companyId: company.id,
+          issueId: issue.id,
+          sourceRunId: run.id,
+          kind: "connection_intent",
+          status: "pending",
+          createdByAgentId: agent.id,
+          addresseeUserId: userId,
+          payload: {
+            version: 1,
+            serviceSlug: "slack",
+            serviceName: "Slack",
+            requestingAgentId: agent.id,
+            requestingAgentName: agent.name,
+            phase: "authorizing",
+          },
+        }).returning())[0]
+      : undefined;
     const service = createTestToolAccessService(db);
     const connected = await service.connectGalleryApp(company.id, {
       galleryKey: "slack",
@@ -6463,6 +6505,7 @@ describeEmbeddedPostgres("tool access service", () => {
       redirectUri: "https://paperclip.example/api/tools/oauth/callback",
       actor: { actorType: "user", actorId: userId },
       subjectUserId: userId,
+      interactionId: interaction?.id,
     });
     vi.spyOn(globalThis, "fetch").mockImplementation(async (url, init) => {
       const href = String(url);
@@ -6526,9 +6569,9 @@ describeEmbeddedPostgres("tool access service", () => {
       eq(toolPolicies.enabled, true),
     ))).resolves.toEqual([]);
     const callbackPolicy = toolAccessPolicyService(db);
-    const decide = (entry: (typeof completed.catalog)[number]) => callbackPolicy.decide({
+    const decide = (entry: (typeof completed.catalog)[number], agentId = agent.id) => callbackPolicy.decide({
       companyId: company.id,
-      actor: { actorType: "agent", actorId: agent.id, agentId: agent.id },
+      actor: { actorType: "agent", actorId: agentId, agentId },
       request: {
         connectionId: connected.connectionId,
         catalogEntryId: entry.id,
@@ -6536,14 +6579,22 @@ describeEmbeddedPostgres("tool access service", () => {
         arguments: {},
       },
     });
-    await expect(decide(searchMessagesEntry)).resolves.toMatchObject({
-      decision: "allow",
-      reasonCode: "allow_profile",
-    });
-    await expect(decide(sendMessageEntry)).resolves.toMatchObject({
-      decision: "allow",
-      reasonCode: "allow_profile",
-    });
+    for (const entry of [searchMessagesEntry, sendMessageEntry]) {
+      await expect(decide(entry)).resolves.toMatchObject(host === "task"
+        ? { decision: "deny" }
+        : { decision: "allow", reasonCode: "allow_profile" });
+    }
+    if (host === "task") {
+      await expect(db.select().from(toolProfileBindings).where(eq(
+        toolProfileBindings.profileId, callbackProfile!.id,
+      ))).resolves.toEqual([]);
+      await expect(db.select().from(toolConnectionInstalls).where(eq(
+        toolConnectionInstalls.connectionId, connected.connectionId,
+      ))).resolves.toEqual([]);
+      await expect(db.select().from(issueThreadInteractions).where(eq(
+        issueThreadInteractions.id, interaction!.id,
+      ))).resolves.toEqual([expect.objectContaining({ status: "pending", result: null })]);
+    }
     const [personalGrant] = await db.select().from(connectionGrants).where(and(
       eq(connectionGrants.connectionId, connected.connectionId),
       eq(connectionGrants.subjectUserId, userId),
@@ -6556,15 +6607,41 @@ describeEmbeddedPostgres("tool access service", () => {
 
     const finished = await service.finalizeOAuthAccess(company.id, connected.connectionId, {
       grantKind: "user",
-    }, { actorType: "user", actorId: userId });
+    }, { actorType: "user", actorId: userId }, host === "task" ? agent.id : undefined);
     expect(finished.profileEntries).toHaveLength(2);
     expect(finished.profileBindings).toEqual([
-      expect.objectContaining({ targetType: "company", targetId: company.id }),
+      expect.objectContaining(host === "task"
+        ? { targetType: "agent", targetId: agent.id }
+        : { targetType: "company", targetId: company.id }),
     ]);
     await expect(db.select().from(toolConnectionInstalls).where(and(
       eq(toolConnectionInstalls.connectionId, connected.connectionId),
       eq(toolConnectionInstalls.targetType, "company"),
-    ))).resolves.toHaveLength(1);
+    ))).resolves.toHaveLength(host === "task" ? 0 : 1);
+    if (host === "task") {
+      await expect(decide(searchMessagesEntry)).resolves.toMatchObject({ decision: "allow" });
+      await expect(decide(searchMessagesEntry, otherAgent.id)).resolves.toMatchObject({ decision: "deny" });
+      // Granting a second requester and retrying the first must preserve both installs.
+      for (const requestingAgentId of [otherAgent.id, agent.id]) {
+        await service.finalizeOAuthAccess(company.id, connected.connectionId, {
+          grantKind: "user",
+        }, { actorType: "user", actorId: userId }, requestingAgentId);
+      }
+      const bindings = await db.select().from(toolProfileBindings).where(eq(
+        toolProfileBindings.profileId, callbackProfile!.id,
+      ));
+      expect(bindings.map(({ targetType, targetId }) => ({ targetType, targetId }))).toEqual(
+        expect.arrayContaining([agent.id, otherAgent.id].map((targetId) => ({ targetType: "agent", targetId }))),
+      );
+      expect(bindings).toHaveLength(2);
+      const installs = await db.select().from(toolConnectionInstalls).where(eq(
+        toolConnectionInstalls.connectionId, connected.connectionId,
+      ));
+      expect(installs.map(({ targetType, targetId }) => ({ targetType, targetId }))).toEqual(
+        expect.arrayContaining([agent.id, otherAgent.id].map((targetId) => ({ targetType: "agent", targetId }))),
+      );
+      expect(installs).toHaveLength(2);
+    }
     await expect(service.startOAuth(company.id, connected.connectionId, {
       redirectUri: "https://paperclip.example/api/tools/oauth/callback",
       actor: { actorType: "user", actorId: `different-user-${randomUUID()}` },
@@ -6586,6 +6663,7 @@ describeEmbeddedPostgres("tool access service", () => {
     const reconnect = await service.startOAuth(company.id, connected.connectionId, {
       redirectUri: "https://paperclip.example/api/tools/oauth/callback",
       actor: { actorType: "user", actorId: userId },
+      interactionId: interaction?.id,
     });
     await expect(service.peekOAuthState(new URL(reconnect.authorizationUrl).searchParams.get("state")!))
       .resolves.toMatchObject({ subjectUserId: userId });
@@ -6610,6 +6688,16 @@ describeEmbeddedPostgres("tool access service", () => {
     ));
     expect(revivedSecrets).toHaveLength(2);
     expect(revivedSecrets.every((secret) => secret.latestVersion === 2)).toBe(true);
+    if (host === "task") {
+      const installs = await db.select().from(toolConnectionInstalls).where(eq(
+        toolConnectionInstalls.connectionId, connected.connectionId,
+      ));
+      expect(installs).toHaveLength(2);
+      expect(installs.every((install) => install.targetType === "agent")).toBe(true);
+      for (const allowedAgentId of [agent.id, otherAgent.id]) {
+        await expect(decide(searchMessagesEntry, allowedAgentId)).resolves.toMatchObject({ decision: "allow" });
+      }
+    }
   });
 
   it("promotes a personal OAuth identity only after Everyone in the company is chosen", async () => {
@@ -6934,16 +7022,22 @@ describeEmbeddedPostgres("tool access service", () => {
     expect(location.searchParams.get("code")).toBe("oauth_authorization_denied");
   });
 
-  it("starts and completes OAuth app sign-in with PKCE state and secret-backed tokens", async () => {
+  it.each([
+    "https://paperclip-public.example",
+    "http://127.0.0.1:3200",
+    "http://localhost:3200",
+  ])("starts and completes OAuth with the same redirect URI at %s", async (origin) => {
     vi.stubEnv("PAPERCLIP_TOOL_OAUTH_SLACK_CLIENT_ID", "slack-client-id");
     vi.stubEnv("PAPERCLIP_TOOL_OAUTH_SLACK_CLIENT_SECRET", "slack-client-secret");
-    vi.stubEnv("PAPERCLIP_PUBLIC_URL", "https://paperclip-public.example");
+    vi.stubEnv("PAPERCLIP_PUBLIC_URL", origin.startsWith("https:") ? origin : "");
     const company = await createCompany(db);
     await grantBoardUser(db, company.id, "board-user", ["tools:manage_connections"]);
     const app = createRouteApp(db);
 
     const connectRes = await request(app)
       .post(`/api/companies/${company.id}/tools/apps/connect`)
+      .set("Host", new URL(origin).host)
+      .set("Origin", origin)
       .send({ galleryKey: "slack", name: "Slack workspace" });
 
     expect(connectRes.status).toBe(201);
@@ -6958,7 +7052,7 @@ describeEmbeddedPostgres("tool access service", () => {
     expect(startUrl.searchParams.get("client_id")).toBe("slack-client-id");
     expect(startUrl.searchParams.get("code_challenge_method")).toBe("S256");
     expect(startUrl.searchParams.get("code_challenge")).toMatch(/^[A-Za-z0-9_-]{43}$/);
-    expect(startUrl.searchParams.get("redirect_uri")).toBe("https://paperclip-public.example/api/tools/oauth/callback");
+    expect(startUrl.searchParams.get("redirect_uri")).toBe(`${origin}/api/tools/oauth/callback`);
     const state = startUrl.searchParams.get("state");
     expect(state).toBeTruthy();
     await expect(db.select().from(toolOauthStates)).resolves.toEqual([
@@ -6980,7 +7074,7 @@ describeEmbeddedPostgres("tool access service", () => {
         expect(body.get("code")).toBe("oauth-code");
         expect(body.get("client_secret")).toBe("slack-client-secret");
         expect(body.get("code_verifier")).toBeTruthy();
-        expect(body.get("redirect_uri")).toBe("https://paperclip-public.example/api/tools/oauth/callback");
+        expect(body.get("redirect_uri")).toBe(`${origin}/api/tools/oauth/callback`);
         return {
           ok: true,
           json: async () => ({
@@ -7011,6 +7105,7 @@ describeEmbeddedPostgres("tool access service", () => {
 
     const callbackRes = await request(app)
       .get("/api/tools/oauth/callback")
+      .set("Host", new URL(origin).host)
       .query({ state, code: "oauth-code" });
 
     expect(callbackRes.status).toBe(200);
@@ -7033,12 +7128,15 @@ describeEmbeddedPostgres("tool access service", () => {
 
     const redirectConnectRes = await request(app)
       .post(`/api/companies/${company.id}/tools/apps/connect`)
+      .set("Host", new URL(origin).host)
+      .set("Origin", origin)
       .send({ galleryKey: "slack", name: "Slack redirect" })
       .expect(201);
     const redirectState = new URL(redirectConnectRes.body.auth.startUrl).searchParams.get("state");
     expect(redirectState).toBeTruthy();
     const redirectCallbackRes = await request(app)
       .get("/api/tools/oauth/callback")
+      .set("Host", new URL(origin).host)
       .set("Accept", "text/html")
       .query({ state: redirectState, code: "oauth-code" });
 

server/src/index.ts

@@ -1,3 +1,4 @@
+import { connectionIntentDeliveryService } from "./services/connection-intent-delivery.js";
 /// <reference path="./types/express.d.ts" />
 // Kicks off the OTel bootstrap as early as possible (no-op unless
 // OTEL_EXPORTER_OTLP_ENDPOINT is set). startServer() awaits
@@ -1182,6 +1183,7 @@ async function startServerWithDatabaseTeardown(
   const ENVIRONMENT_LEASE_CLEANUP_SWEEP_BACKOFF_MS = 5 * 60 * 1000;
   const environmentLeaseCleanupHeartbeat =
     heartbeat ?? heartbeatService(db as any, { pluginWorkerManager });
+  const connectionDeliveries = connectionIntentDeliveryService(db as any, environmentLeaseCleanupHeartbeat);
   const questionResponseDeliveries = questionResponseDeliveryService(db as any, {
     heartbeat: environmentLeaseCleanupHeartbeat,
     resolveNativeQuestion: (interaction) => deliverNativeQuestionResponse(db as any, interaction),
@@ -1236,6 +1238,7 @@ async function startServerWithDatabaseTeardown(
       }));
   };
 
+  await connectionDeliveries.sweepPending();
   await questionResponseDeliveries.sweepPending().then((result) => {
     if (result.scanned > 0) {
       logger.info(result, "startup question-response delivery sweep completed");
@@ -1680,6 +1683,7 @@ async function startServerWithDatabaseTeardown(
             logger.error({ err }, "periodic secret proposal expiry sweep failed");
           }));
 
+        trackHeartbeatSchedulerWork(connectionDeliveries.sweepPending().catch((err) => logger.error({ err }, "connection continuation delivery failed")));
         trackHeartbeatSchedulerWork(questionResponseDeliveries.sweepPending()
           .then((result) => {
             if (result.scanned > 0) {

server/src/modules/run-dispatch/adapters/postgres.ts

@@ -527,6 +527,8 @@ export function createPostgresRunDispatchAdapter(
       issueAssigneeAgentId: issue?.assigneeAgentId ?? null,
       issueExecutionRunId: issue?.executionRunId ?? null,
       isResolvedInteractionContinuation,
+      isConnectionContinuation: (isResolvedInteractionContinuation && context.interactionKind === "connection_intent")
+        || context.source === "connection_tools.refreshed",
       isInteractionWake,
       isAuthorizedSourceScopedRecovery,
       isNonAssigneeWorkspaceBusyRetry: isNonAssigneeWorkspaceBusyRetry(retryReason, context),

server/src/modules/run-dispatch/domain/policy.test.ts

@@ -342,6 +342,40 @@ describe("decideQueuedRunStaleness", () => {
     expect(decision).toMatchObject({ errorCode });
   });
 
+  describe.each([
+    { name: "resolved connection", isResolvedInteractionContinuation: true, wakeReason: "issue_interaction_resolved" },
+    { name: "tool snapshot refresh", isResolvedInteractionContinuation: false, wakeReason: "connection_tools_updated" },
+  ])("$name continuation", ({ isResolvedInteractionContinuation, wakeReason }) => {
+    const connectionFacts = (): QueuedRunFacts => ({
+      ...baseStalenessFacts(),
+      isConnectionContinuation: true,
+      isResolvedInteractionContinuation,
+      wakeReason,
+      issueStatus: "in_review",
+      reviewParticipant: { ...NO_PARTICIPANT, isInReview: true },
+    });
+
+    it("continues an owned task waiting in review after connection access becomes ready", () => {
+      expect(decideQueuedRunStaleness(connectionFacts(), NOW)).toEqual({ stale: false });
+    });
+
+    it.each(["done", "cancelled", "todo", "backlog", "blocked"])("rejects a task in %s", (issueStatus) => {
+      expect(decideQueuedRunStaleness({ ...connectionFacts(), issueStatus }, NOW)).toMatchObject({
+        stale: true,
+        errorCode: "issue_not_in_progress",
+      });
+    });
+
+    it("rejects a reassigned task even when an interaction wake normally bypasses ownership", () => {
+      expect(decideQueuedRunStaleness({
+        ...connectionFacts(),
+        issueAssigneeAgentId: "agent-2",
+        isInteractionWake: true,
+        wakeCommentIdPresent: true,
+      }, NOW)).toMatchObject({ stale: true, errorCode: "issue_assignee_changed" });
+    });
+  });
+
   it("does not cancel a parked continuation summary when the classifier says it does not park the executor", () => {
     const facts: QueuedRunFacts = {
       ...baseStalenessFacts(),

server/src/modules/run-dispatch/domain/policy.ts

@@ -130,6 +130,8 @@ export type QueuedRunFacts = {
   issueExecutionRunId: string | null;
 
   isResolvedInteractionContinuation: boolean;
+  /** A connection resolution or tool refresh can resume an agent waiting in review. */
+  isConnectionContinuation?: boolean;
   isInteractionWake: boolean;
   isAuthorizedSourceScopedRecovery: boolean;
   isNonAssigneeWorkspaceBusyRetry: boolean;
@@ -458,10 +460,10 @@ export function decideQueuedRunStaleness(
     };
   }
 
-  if (facts.isResolvedInteractionContinuation) {
+  if (facts.isResolvedInteractionContinuation || facts.isConnectionContinuation) {
     const earlyStatus = decideIssueStatus({
       status: facts.issueStatus,
-      requiresInProgress: true,
+      requiresInProgress: !(facts.isConnectionContinuation && facts.issueStatus === "in_review"),
       terminalBypass: true,
     });
     if (earlyStatus === "not_in_progress") {

server/src/routes/connection-intents.test.ts

@@ -75,7 +75,7 @@ describe("connection intent continuation wake contract", () => {
       expect(wakeup).toHaveBeenCalledWith(
         "agent-123",
         expect.objectContaining({
-          idempotencyKey: `interaction:interaction-123:${status}`,
+          idempotencyKey: `connection-intent:interaction-123:${status}`,
           requestedByActorType: "user",
           requestedByActorId: "user-123",
           contextSnapshot: expect.objectContaining({
@@ -89,7 +89,7 @@ describe("connection intent continuation wake contract", () => {
     },
   );
 
-  it.each(["backlog", "todo", "in_review", "done", "blocked", "cancelled"])(
+  it.each(["backlog", "todo", "done", "blocked", "cancelled"])(
     "does not wake a parked or closed %s task",
     async (issueStatus) => {
       const wakeup = vi.fn().mockResolvedValue(undefined);

server/src/routes/connection-intents.ts

@@ -1,3 +1,4 @@
+import { connectionIntentDeliveryService } from "../services/connection-intent-delivery.js";
 import { Router, type Request } from "express";
 import type { Db } from "@paperclipai/db";
 import {
@@ -35,27 +36,8 @@ function resultContent(value: unknown) {
   };
 }
 
-export const RUNTIME_CONNECTION_TOOL_DEFINITIONS = [
-  {
-    name: "connections_search",
-    description: CONNECTIONS_SEARCH_TOOL_DESCRIPTION,
-    inputSchema: {
-      type: "object",
-      properties: { query: { type: "string" } },
-      additionalProperties: false,
-    },
-  },
-  {
-    name: "connection_request",
-    description: CONNECTION_REQUEST_TOOL_DESCRIPTION,
-    inputSchema: {
-      type: "object",
-      properties: { service: { type: "string" } },
-      required: ["service"],
-      additionalProperties: false,
-    },
-  },
-] as const;
+export { RUNTIME_CONNECTION_TOOL_DEFINITIONS } from "../services/connection-tool-definitions.js";
+import { RUNTIME_CONNECTION_TOOL_DEFINITIONS } from "../services/connection-tool-definitions.js";
 
 /** Public, token-authenticated routes mounted before the general actor middleware. */
 export function runtimeConnectionIntentRoutes(db: Db) {
@@ -158,56 +140,7 @@ export function runtimeConnectionIntentRoutes(db: Db) {
 
 type Heartbeat = ReturnType<typeof heartbeatService>;
 
-export async function wakeConnectionIntentAfterResolution(
-  heartbeat: Pick<Heartbeat, "wakeup">,
-  input: {
-    loaded: {
-      issue: { id: string; assigneeAgentId: string | null; status: string };
-      interaction: { id: string; resolvedAt?: string | Date | null };
-    };
-    status: string;
-    actorId: string;
-  },
-) {
-  const agentId = input.loaded.issue.assigneeAgentId;
-  if (!agentId || input.loaded.issue.status !== "in_progress") return;
-  const resolvedAt = input.loaded.interaction.resolvedAt;
-  const interactionResolvedAt = resolvedAt instanceof Date ? resolvedAt.toISOString() : resolvedAt;
-  await heartbeat.wakeup(agentId, {
-    source: "automation",
-    triggerDetail: "system",
-    reason: "issue_commented",
-    payload: {
-      issueId: input.loaded.issue.id,
-      interactionId: input.loaded.interaction.id,
-      interactionKind: "connection_intent",
-      interactionStatus: input.status,
-      mutation: "interaction",
-    },
-    idempotencyKey: `interaction:${input.loaded.interaction.id}:${input.status}`,
-    requestedByActorType: "user",
-    requestedByActorId: input.actorId,
-    contextSnapshot: {
-      issueId: input.loaded.issue.id,
-      taskId: input.loaded.issue.id,
-      interactionId: input.loaded.interaction.id,
-      interactionKind: "connection_intent",
-      interactionStatus: input.status,
-      mutation: "interaction",
-      wakeReason: "issue_commented",
-      source: "connection_intent.resolved",
-      ...(interactionResolvedAt
-        ? { interactionResolvedAt }
-        : {}),
-      forceFreshSession: true,
-    },
-    issueStateGuard: {
-      statuses: ["in_progress"],
-      assigneeAgentId: agentId,
-    },
-  });
-}
-
+export { wakeConnectionIntentAfterResolution } from "../services/connection-intent-delivery.js";
 export function connectionIntentBoardRoutes(db: Db, heartbeat: Heartbeat) {
   const router = Router();
   const service = connectionIntentService(db);
@@ -243,14 +176,7 @@ export function connectionIntentBoardRoutes(db: Db, heartbeat: Heartbeat) {
     status: string;
     actorId: string;
   }) {
-    // The operator may park or reassign the issue while the connection work
-    // and activity write are in flight. Re-read immediately before enqueueing
-    // so the wake decision is not made from addressedIntent's stale snapshot.
-    const current = await service.loadIntent(input.loaded.interaction.id);
-    await wakeConnectionIntentAfterResolution(heartbeat, {
-      ...input,
-      loaded: current,
-    });
+    await connectionIntentDeliveryService(db, heartbeat).tryDeliver(input.loaded.interaction.id);
   }
 
   router.get("/connection-intents/:interactionId/setup-options", async (req, res) => {

server/src/routes/tool-access.ts

@@ -77,7 +77,7 @@ import { isLoopbackHost } from "../url-utils.js";
 import { trustedBoardMutationOrigin } from "../middleware/board-mutation-guard.js";
 import { connectionIntentService } from "../services/connection-intents.js";
 import { redactRemoteUrlCredential } from "../services/remote-url-credentials.js";
-import { wakeConnectionIntentAfterResolution } from "./connection-intents.js";
+import { connectionIntentDeliveryService } from "../services/connection-intent-delivery.js";
 import type { heartbeatService } from "../services/heartbeat.js";
 
 const COMPANY_INSTALL_DENIAL_REASON =
@@ -268,22 +268,11 @@ export function toolAccessRoutes(
           canManageOrganizationGrant: input.canManageOrganizationGrant,
           bypassCurrentMembershipCheck: input.bypassCurrentMembershipCheck,
         })
-      : input.outcome === "declined"
-        ? await connectionIntents.decline(
-            input.interactionId,
-            input.userId,
-            "Authorization was declined in the provider window",
-            { bypassCurrentMembershipCheck: input.bypassCurrentMembershipCheck },
-          )
-        : await connectionIntents.updatePhase(input.interactionId, "needs_retry", input.userId, {
+      : await connectionIntents.updatePhase(input.interactionId, "needs_retry", input.userId, {
             bypassCurrentMembershipCheck: input.bypassCurrentMembershipCheck,
           });
-    if (input.outcome !== "failed" && options.connectionIntentHeartbeat) {
-      await wakeConnectionIntentAfterResolution(options.connectionIntentHeartbeat, {
-        loaded,
-        status: interaction.status,
-        actorId: input.userId,
-      });
+    if (interaction.status === "accepted" && options.connectionIntentHeartbeat) {
+      await connectionIntentDeliveryService(db, options.connectionIntentHeartbeat).tryDeliver(input.interactionId);
     }
     return interaction;
   }
@@ -338,12 +327,17 @@ export function toolAccessRoutes(
       // interoperable spelling and retain the browser's exact origin as OAuth
       // state for popup postMessage below.
       if (
-        (options.deploymentMode ?? "local_trusted") === "local_trusted"
+        req.method !== "GET"
+        && req.method !== "HEAD"
+        && (options.deploymentMode ?? "local_trusted") === "local_trusted"
         && parsed.protocol === "http:"
         && parsed.hostname !== "localhost"
       ) {
         parsed.hostname = "localhost";
       }
+      // A provider callback has no initiating browser Origin. Preserve its
+      // actual host: rewriting 127.0.0.1 here changes the redirect_uri used at
+      // authorization and causes the token endpoint to reject the code.
       return parsed.origin;
     } catch {
       return null;
@@ -862,8 +856,9 @@ function connectorEnrollmentPrincipal(req: Request): string {
     // On resume, the persisted connection identity is authoritative: accepting
     // a contradictory `grantKind: "user"` here could otherwise let a creator
     // replace the credential behind an existing organization grant.
-    const resumedConnection = req.body.resumeConnectionId
-      ? await svc.getConnection(req.body.resumeConnectionId, companyId)
+    const retainedConnectionId = req.body.resumeConnectionId ?? req.body.reconnectConnectionId;
+    const resumedConnection = retainedConnectionId
+      ? await svc.getConnection(retainedConnectionId, companyId)
       : null;
     const effectiveGrantKind = resumedConnection
       ? resumedConnection.credentialPolicy === "per_user"

server/src/services/connection-intent-delivery.ts

@@ -0,0 +1,120 @@
+import { connectionIntentService } from "./connection-intents.js";
+import { and, eq, isNull, lte, asc, notInArray } from "drizzle-orm";
+import { connectionIntentDeliveries, issueThreadInteractions, issues, agentWakeupRequests, companyMemberships, type Db } from "@paperclipai/db";
+import type { heartbeatService } from "./heartbeat.js";
+type Heartbeat = ReturnType<typeof heartbeatService>;
+
+export async function wakeConnectionIntentAfterResolution(
+  heartbeat: Pick<Heartbeat, "wakeup">,
+  input: {
+    loaded: {
+      issue: { id: string; assigneeAgentId: string | null; status: string };
+      interaction: { id: string; resolvedAt?: string | Date | null };
+    };
+    status: string;
+    actorId: string;
+  },
+) {
+  const agentId = input.loaded.issue.assigneeAgentId;
+  if (!agentId || !["in_progress", "in_review"].includes(input.loaded.issue.status)) return;
+  const resolvedAt = input.loaded.interaction.resolvedAt;
+  const interactionResolvedAt = resolvedAt instanceof Date ? resolvedAt.toISOString() : resolvedAt;
+  await heartbeat.wakeup(agentId, {
+    source: "automation",
+    triggerDetail: "system",
+    reason: "issue_commented",
+    payload: {
+      issueId: input.loaded.issue.id,
+      interactionId: input.loaded.interaction.id,
+      interactionKind: "connection_intent",
+      interactionStatus: input.status,
+      mutation: "interaction",
+    },
+    idempotencyKey: `connection-intent:${input.loaded.interaction.id}:${input.status}`,
+    requestedByActorType: "user",
+    requestedByActorId: input.actorId,
+    contextSnapshot: {
+      issueId: input.loaded.issue.id,
+      taskId: input.loaded.issue.id,
+      interactionId: input.loaded.interaction.id,
+      interactionKind: "connection_intent",
+      interactionStatus: input.status,
+      mutation: "interaction",
+      wakeReason: "issue_commented",
+      source: "connection_intent.resolved",
+      ...(interactionResolvedAt
+        ? { interactionResolvedAt }
+        : {}),
+      forceFreshSession: true,
+    },
+    issueStateGuard: {
+      statuses: ["in_progress", "in_review"],
+      assigneeAgentId: agentId,
+    },
+  });
+}
+
+
+export function connectionIntentDeliveryService(db: Db, heartbeat: Pick<Heartbeat, "wakeup">) {
+  async function deliver(interactionId: string) {
+    // Deterministic acceptance-test failpoint: preserve committed outcomes across a server restart.
+    if (process.env.NODE_ENV === "test" && process.env.PAPERCLIP_TEST_CONNECTION_DELIVERY_HOLD === "1") return;
+    const now = new Date();
+    // The retry deadline is also the worker lease. A crashed worker is reclaimed.
+    const [claimed] = await db.update(connectionIntentDeliveries)
+      .set({ nextAttemptAt: new Date(now.getTime() + 60_000) })
+      .where(and(eq(connectionIntentDeliveries.interactionId, interactionId), isNull(connectionIntentDeliveries.deliveredAt), lte(connectionIntentDeliveries.nextAttemptAt, now))).returning();
+    if (!claimed) return;
+    const [loaded] = await db.select({ interaction: issueThreadInteractions, issue: issues })
+      .from(issueThreadInteractions).innerJoin(issues, eq(issues.id, issueThreadInteractions.issueId))
+      .where(and(eq(issueThreadInteractions.id, interactionId), eq(issueThreadInteractions.companyId, claimed.companyId), eq(issues.companyId, claimed.companyId)));
+    const interaction = loaded?.interaction;
+    const payload = interaction?.payload as { requestingAgentId?: string; serviceSlug?: string } | undefined;
+    if (!loaded || !interaction || !["accepted", "rejected"].includes(interaction.status)
+      || ["done", "cancelled"].includes(loaded.issue.status) || loaded.issue.assigneeAgentId !== payload?.requestingAgentId) {
+      await db.update(connectionIntentDeliveries).set({ deliveredAt: new Date() }).where(eq(connectionIntentDeliveries.interactionId, interactionId));
+      return;
+    }
+    const userId = interaction.addresseeUserId;
+    if (userId !== "local-board") {
+      const [membership] = await db.select().from(companyMemberships).where(and(
+        eq(companyMemberships.companyId, claimed.companyId), eq(companyMemberships.principalType, "user"),
+        eq(companyMemberships.principalId, userId ?? ""), eq(companyMemberships.status, "active"),
+      )).limit(1);
+      if (!membership?.membershipRole || membership.membershipRole === "viewer") {
+        await db.update(connectionIntentDeliveries).set({ deliveredAt: new Date() }).where(eq(connectionIntentDeliveries.interactionId, interactionId));
+        return;
+      }
+    }
+    if (interaction.status === "accepted") {
+      const ready = await connectionIntentService(db).usableConnectionForAgent({ companyId: claimed.companyId,
+        agentId: payload!.requestingAgentId!, responsibleUserId: userId!, serviceSlug: payload!.serviceSlug! });
+      if (!ready) return;
+    }
+    if (!["in_progress", "in_review"].includes(loaded.issue.status)) return;
+    const durableWake = () => db.select({ id: agentWakeupRequests.id }).from(agentWakeupRequests).where(and(
+      eq(agentWakeupRequests.companyId, claimed.companyId),
+      eq(agentWakeupRequests.idempotencyKey, `connection-intent:${interactionId}:${interaction.status}`),
+      notInArray(agentWakeupRequests.status, ["skipped", "failed", "cancelled"]),
+    )).limit(1);
+    // Check before dispatch: the previous worker may have crashed after enqueueing.
+    if (!(await durableWake()).length) {
+      try {
+        await wakeConnectionIntentAfterResolution(heartbeat, { loaded, status: interaction.status, actorId: interaction.resolvedByUserId ?? interaction.addresseeUserId! });
+      } catch (error) {
+        // The unique wake key also protects overlapping leases. Other failures retry.
+        if (!(await durableWake()).length) throw error;
+      }
+    }
+    if ((await durableWake()).length) {
+      await db.update(connectionIntentDeliveries).set({ deliveredAt: new Date() }).where(eq(connectionIntentDeliveries.interactionId, interactionId));
+    }
+  }
+  return { deliver, tryDeliver: async (id: string) => { try { await deliver(id); } catch { /* Persisted delivery remains due after its lease. */ } }, sweepPending: async () => {
+    const rows = await db.select().from(connectionIntentDeliveries).where(and(isNull(connectionIntentDeliveries.deliveredAt), lte(connectionIntentDeliveries.nextAttemptAt, new Date())))
+      .orderBy(asc(connectionIntentDeliveries.nextAttemptAt)).limit(50);
+    let failed = 0;
+    for (const row of rows) { try { await deliver(row.interactionId); } catch { failed += 1; } }
+    return { scanned: rows.length, failed };
+  }};
+}

server/src/services/connection-intents.ts

@@ -2,6 +2,8 @@ import { and, eq } from "drizzle-orm";
 import type { Db } from "@paperclipai/db";
 import {
   agents,
+  toolConnections,
+  toolCatalogEntries,
   companyMemberships,
   heartbeatRuns,
   issueThreadInteractions,
@@ -12,8 +14,9 @@ import {
   CONNECTABLE_APP_DEFINITIONS,
   connectionIntentPayloadSchema,
   getAvailableConnectionMethods,
+  isToolConnectionAttentionHealth,
+  type ConnectionSearchResultItem,
   getAppStoreDefinition,
-  getConnectableAppDefinition,
   type ConnectionIntentInteraction,
   type ConnectionIntentSetupOptions,
   type ConnectionRequestResult,
@@ -25,8 +28,11 @@ import { conflict, forbidden, notFound, unprocessable } from "../errors.js";
 import type { RuntimeToolsTokenClaims } from "../runtime-tools-token.js";
 import { issueThreadInteractionService } from "./issue-thread-interactions.js";
 import { toolAccessService } from "./tool-access.js";
+import { captureRunIdentity } from "./run-identity.js";
 import { resolveManagedGitHubIdentitySelection } from "./git-credentials.js";
 
+type ConnectionRunClaims = Pick<RuntimeToolsTokenClaims, "sub" | "company_id" | "run_id" | "responsible_user_id">;
+
 type DbTransaction = Parameters<Parameters<Db["transaction"]>[0]>[0];
 
 function record(value: unknown): Record<string, unknown> | null {
@@ -47,14 +53,12 @@ function sourceSlugForConnection(
   connection: ToolConnection,
   applications: ReadonlyMap<string, ToolApplication>,
 ) {
-  return text(connection.config?.sourceTemplateKey)
+  const source = text(connection.config?.sourceTemplateKey)
     ?? text(connection.transportConfig?.sourceTemplateKey)
     ?? sourceSlugForApplication(applications.get(connection.applicationId));
+  return source && getAppStoreDefinition(source) ? source : `connection:${connection.id}`;
 }
 
-function displayDescription(app: (typeof CONNECTABLE_APP_DEFINITIONS)[number]) {
-  return text(app.description) ?? null;
-}
 
 export function connectionIntentService(db: Db) {
   const interactions = issueThreadInteractionService(db);
@@ -118,8 +122,8 @@ export function connectionIntentService(db: Db) {
     }
   }
 
-  async function loadRunContext(claims: RuntimeToolsTokenClaims) {
-    const run = await db
+  async function loadRunContext(claims: ConnectionRunClaims) {
+    let run = await db
       .select({
         id: heartbeatRuns.id,
         companyId: heartbeatRuns.companyId,
@@ -139,6 +143,11 @@ export function connectionIntentService(db: Db) {
       || (!run.activeIdentityContextId && run.responsibleUserId !== claims.responsible_user_id)
     ) throw forbidden("Runtime tool token does not match its heartbeat run");
     if (run.status !== "running") throw forbidden("Runtime tool token is no longer active");
+    if (run.activeIdentityContextId) {
+      const current = await captureRunIdentity(db, { companyId: run.companyId, agentId: run.agentId, runId: run.id });
+      run = { ...run, responsibleUserId: current.run.responsibleUserId };
+    }
+    if (!run.responsibleUserId) throw forbidden("This task needs a responsible user to connect a service");
     const snapshot = record(run.contextSnapshot);
     const issueId = text(snapshot?.issueId) ?? text(snapshot?.taskId);
     if (!issueId) throw unprocessable("Connection requests require a task-bound heartbeat run");
@@ -171,6 +180,7 @@ export function connectionIntentService(db: Db) {
     ) {
       throw forbidden("Responsible user is no longer authorized for company write access");
     }
+    if (issue.assigneeAgentId !== agent.id) throw conflict("The requesting agent no longer owns this task");
     if (issue.status === "done" || issue.status === "cancelled") {
       throw conflict("Connection requests cannot be created on a closed task");
     }
@@ -199,21 +209,23 @@ export function connectionIntentService(db: Db) {
     const inventory = input.inventory ?? await connectionInventory(input.companyId);
     const matching = inventory.connections.filter((connection) =>
       sourceSlugForConnection(connection, inventory.applicationsById) === input.serviceSlug
-      && connection.status === "active"
-      && connection.enabled
+      && connection.status !== "archived"
     );
     if (matching.length === 0) return null;
-    if (input.serviceSlug === "github") {
-      const selection = await resolveManagedGitHubIdentitySelection(db, input.companyId, {
-        agentId: input.agentId,
-        responsibleUserId: input.responsibleUserId,
-      });
-      return selection.grant
-        ? matching.find((connection) => connection.id === selection.grant!.connectionId) ?? null
-        : null;
-    }
     const effective = await access.getEffectiveProfilesForAgent(input.companyId, input.agentId);
     const installedIds = new Set(effective.installedConnections.map((connection) => connection.id));
+    const permittedIds = new Set(effective.allowedTools.map((tool) => tool.connectionId));
+    const usable = (connection: ToolConnection | undefined) => connection
+      && installedIds.has(connection.id) && permittedIds.has(connection.id)
+      && connection.status === "active" && connection.enabled
+      && ["mcp_remote", "local_stdio"].includes(connection.transport)
+      && !isToolConnectionAttentionHealth(connection.healthStatus) ? connection : null;
+    if (input.serviceSlug === "github") {
+      const selection = await resolveManagedGitHubIdentitySelection(db, input.companyId, {
+        agentId: input.agentId, responsibleUserId: input.responsibleUserId,
+      });
+      return usable(matching.find((connection) => connection.id === selection.grant?.connectionId));
+    }
     const installed = matching.filter((connection) => installedIds.has(connection.id));
     const grantsByConnection = await Promise.all(installed.map(async (connection) => ({
       connection,
@@ -228,7 +240,7 @@ export function connectionIntentService(db: Db) {
       .map((grant) => ({ connection, grant })));
     if (dedicated.length > 0) {
       const active = dedicated.filter(({ grant }) => grant.status === "active");
-      return active.length === 1 ? active[0]!.connection : null;
+      return active.length === 1 ? usable(active[0]!.connection) : null;
     }
 
     const personal = grantsByConnection.flatMap(({ connection, grants }) => grants
@@ -236,68 +248,121 @@ export function connectionIntentService(db: Db) {
       .map((grant) => ({ connection, grant })));
     if (personal.length > 0) {
       const active = personal.filter(({ grant }) => grant.status === "active");
-      return active.length === 1 ? active[0]!.connection : null;
+      return active.length === 1 ? usable(active[0]!.connection) : null;
     }
 
     const organization = grantsByConnection.flatMap(({ connection, grants }) => grants
       .filter((grant) => grant.kind === "organization")
       .map((grant) => ({ connection, grant })));
     const activeOrganization = organization.filter(({ grant }) => grant.status === "active");
-    return activeOrganization.length === 1 ? activeOrganization[0]!.connection : null;
+    return activeOrganization.length === 1 ? usable(activeOrganization[0]!.connection) : null;
   }
 
-  async function search(claims: RuntimeToolsTokenClaims, query: string): Promise<ConnectionsSearchResult> {
+  async function administrativeDenial(companyId: string, agentId: string, serviceSlug: string, inventory: Awaited<ReturnType<typeof connectionInventory>>) {
+    const effective = await access.getEffectiveProfilesForAgent(companyId, agentId);
+    const installed = effective.installedConnections.filter((connection) => sourceSlugForConnection(connection, inventory.applicationsById) === serviceSlug);
+    if (!installed.length || effective.allowedTools.some((tool) => installed.some((connection) => connection.id === tool.connectionId))) return false;
+    for (const connection of installed) {
+      if ((await indexedCatalog(connection.id, companyId)).some((tool) => tool.entryKind === "tool")) return true;
+    }
+    return false;
+  }
+
+  function indexedCatalog(connectionId: string, companyId: string) {
+    // Discovery must not contact providers or mutate their health/cache state.
+    return db.select().from(toolCatalogEntries).where(and(
+      eq(toolCatalogEntries.companyId, companyId), eq(toolCatalogEntries.connectionId, connectionId),
+      eq(toolCatalogEntries.status, "active"),
+    ));
+  }
+
+  async function resolveService(service: string, companyId: string, userId: string, agentId: string) {
+    if (!service.startsWith("connection:")) {
+      const app = getAppStoreDefinition(service);
+      if (!app) throw notFound("Connection service was not found");
+      return { ...app, available: app.availability?.available !== false,
+        searchCapabilities: getAvailableConnectionMethods(app).map((method) =>
+          `${method.whenToUse} ${method.capabilityProfile?.label ?? ""} ${method.capabilityProfile?.description ?? ""}`).join(" "),
+        methods: getAvailableConnectionMethods(app).map((method) => ({
+          key: method.key, label: method.label ?? method.key, auth: method.auth,
+        })), source: "catalog" as const };
+    }
+    const id = service.slice("connection:".length);
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id)) {
+      throw notFound("Configured connection was not found");
+    }
+    const connection = await access.getConnection(id, companyId);
+    const { grants } = await access.listConnectionGrants(id, companyId);
+    if (connection.status === "archived" || !grants.some((grant) => grant.status === "active" && (
+      grant.kind === "organization" || (grant.kind === "user" && grant.subjectUserId === userId)
+      || (grant.kind === "agent" && grant.subjectAgentId === agentId)
+    ))) throw notFound("Configured connection was not found");
+    const application = await access.getApplication(connection.applicationId, companyId);
+    return {
+      slug: service, name: connection.name, description: application.description, searchCapabilities: "",
+      branding: { logoUrl: undefined, darkLogoUrl: undefined },
+      available: connection.enabled,
+      methods: [{ key: "configured", label: "Use configured connection", auth:
+        connection.authKind === "oauth" ? "oauth" as const : connection.authKind === "none" ? "none" as const : "api_key" as const }],
+      source: "configured" as const,
+    };
+  }
+
+  async function search(claims: ConnectionRunClaims, query: string): Promise<ConnectionsSearchResult> {
     const { run, agent } = await loadRunContext(claims);
     const normalized = query.trim().toLocaleLowerCase();
+    const tokens = normalized.split(/[^\p{L}\p{N}]+/u).filter(Boolean);
     const inventory = await connectionInventory(run.companyId);
-    const results = await Promise.all(APP_STORE_DEFINITIONS
-      .filter((app) => !normalized
-        || app.slug.toLocaleLowerCase().includes(normalized)
-        || app.name.toLocaleLowerCase().includes(normalized)
-        || displayDescription(app)?.toLocaleLowerCase().includes(normalized))
-      .map(async (app) => {
-        const methods = getAvailableConnectionMethods(app);
-        const matching = inventory.connections.filter((connection) =>
-          sourceSlugForConnection(connection, inventory.applicationsById) === app.slug
-          && connection.status !== "archived"
-        );
-        const ready = await usableConnectionForAgent({
-          companyId: run.companyId,
-          agentId: agent.id,
-          responsibleUserId: run.responsibleUserId!,
-          serviceSlug: app.slug,
-          inventory,
-        });
-        return {
-          service: app.slug,
-          name: app.name,
-          description: displayDescription(app),
-          logoUrl: app.branding.logoUrl ?? null,
-          methods: methods.map((method) => ({
-            key: method.key,
-            label: method.label ?? method.key,
-            auth: method.auth,
-          })),
-          state: app.availability?.available === false || methods.length === 0
-            ? "unavailable" as const
-            : ready
-              ? "ready" as const
-              : matching.length > 0
-                ? "needs_user_action" as const
-                : "available" as const,
-          connectionId: ready?.id ?? null,
-        };
+    const candidates: Array<{ item: ConnectionSearchResultItem; score: number }> = [];
+    const services = [...APP_STORE_DEFINITIONS.map((app) => app.slug),
+      ...inventory.connections.filter((connection) =>
+        sourceSlugForConnection(connection, inventory.applicationsById)?.startsWith("connection:")
+        && connection.status !== "archived").map((connection) => `connection:${connection.id}`)];
+    for (const service of services) {
+      let app;
+      try { app = await resolveService(service, run.companyId, run.responsibleUserId!, agent.id); }
+      catch (error) { if (service.startsWith("connection:") && (error as { status?: number }).status === 404) continue; throw error; }
+      const matching = inventory.connections.filter((connection) =>
+        sourceSlugForConnection(connection, inventory.applicationsById) === service && connection.status !== "archived");
+      // Indexed descriptions can contain private workspace metadata, including
+      // for catalog providers. Check each configured connection's audience first.
+      const catalogs = await Promise.all(matching.map(async (connection) => {
+        const { grants } = await access.listConnectionGrants(connection.id, run.companyId);
+        const authorized = grants.some((grant) => grant.status === "active" && (
+          grant.kind === "organization" || (grant.kind === "user" && grant.subjectUserId === run.responsibleUserId)
+          || (grant.kind === "agent" && grant.subjectAgentId === agent.id)
+        ));
+        return authorized ? indexedCatalog(connection.id, run.companyId) : [];
       }));
-    return { version: 1, query, results };
+      const catalog = catalogs.flat().filter((entry) => entry.status === "active");
+      const haystack = `${app.slug} ${app.name} ${app.description ?? ""} ${app.searchCapabilities} ${catalog.map((tool) => `${tool.toolName} ${tool.description ?? ""}`).join(" ")}`.toLocaleLowerCase();
+      const score = !normalized ? 1 : app.slug === normalized || app.name.toLocaleLowerCase() === normalized
+        ? 1000 : tokens.reduce((sum, token) => sum + (haystack.includes(token) ? 1 : 0), 0);
+      if (!score) continue;
+      const ready = await usableConnectionForAgent({ companyId: run.companyId, agentId: agent.id,
+        responsibleUserId: run.responsibleUserId!, serviceSlug: service, inventory });
+      const denied = !ready && matching.length > 0 && await administrativeDenial(run.companyId, agent.id, service, inventory);
+      candidates.push({ score, item: {
+        service, name: app.name, description: app.description ?? null, logoUrl: app.branding.logoUrl ?? null,
+        methods: app.methods, source: app.source,
+        state: ready ? "ready" : denied ? "unavailable" : !app.available || !app.methods.length ? "unavailable"
+          : matching.length ? "needs_user_action" : "available",
+        reason: ready ? "Connection is installed and usable by this agent" : denied ? "An administrator has not permitted executable tools for this agent; reconnecting cannot grant that permission" : !app.available ? "Connection is disabled or unavailable"
+          : matching.some((connection) => isToolConnectionAttentionHealth(connection.healthStatus)) ? "Connection needs attention"
+          : matching.length ? "Review identity and access for this agent" : "Connect this service to continue",
+        connectionId: ready?.id ?? null,
+      }});
+    }
+    return { version: 1, query, results: candidates.sort((a, b) => b.score - a.score || a.item.name.localeCompare(b.item.name)).slice(0, 20).map(({ item }) => item) };
   }
 
   async function request(
-    claims: RuntimeToolsTokenClaims,
+    claims: ConnectionRunClaims,
     serviceSlug: string,
   ): Promise<ConnectionRequestResult> {
     const context = await loadRunContext(claims);
-    const app = getAppStoreDefinition(serviceSlug);
-    if (!app || app.availability?.available === false || getAvailableConnectionMethods(app).length === 0) {
+    const app = await resolveService(serviceSlug, context.run.companyId, context.run.responsibleUserId!, context.agent.id);
+    if (!app.available || app.methods.length === 0) {
       throw unprocessable(`Connection service ${serviceSlug} is not available`);
     }
     const ready = await usableConnectionForAgent({
@@ -313,9 +378,19 @@ export function connectionIntentService(db: Db) {
         state: "ready",
         connectionId: ready.id,
         interactionId: null,
-        instruction: `${app.name} is connected and available in this run.`,
+        instruction: `${app.name} is connected. Use its installed tools; a native continuation will refresh tools if needed.`,
       };
     }
+    if (await administrativeDenial(context.run.companyId, context.agent.id, app.slug, await connectionInventory(context.run.companyId))) {
+      throw forbidden("This agent has no permitted actions for this service. Ask an administrator to review tool permissions; reconnecting will not remove a denial.");
+    }
+    const outcomeId = context.run.contextSnapshot?.interactionId;
+    if (typeof outcomeId === "string") {
+      const [outcome] = await db.select().from(issueThreadInteractions).where(and(eq(issueThreadInteractions.id, outcomeId), eq(issueThreadInteractions.companyId, context.run.companyId), eq(issueThreadInteractions.issueId, context.issue.id)));
+      if (outcome?.kind === "connection_intent" && outcome.status === "rejected" && connectionIntentPayloadSchema.parse(outcome.payload).serviceSlug === app.slug) {
+        throw conflict("The user declined this connection. Pursue alternatives; do not request it again in this continuation.");
+      }
+    }
     const interaction = await interactions.createConnectionIntent(
       context.issue,
       {
@@ -330,17 +405,19 @@ export function connectionIntentService(db: Db) {
           phase: "requested",
         },
         sourceRunId: context.run.id,
+        sourceIdentityContextId: context.run.activeIdentityContextId,
         addresseeUserId: context.run.responsibleUserId!,
-        idempotencyKey: `connection-intent:${context.run.id}:${app.slug}`,
+        idempotencyKey: `connection-intent:${context.run.id}:${context.run.responsibleUserId}:${app.slug}`,
       },
     );
+    if (interaction.status !== "pending") throw conflict("This connection request has already been resolved. Follow its recorded outcome.");
     return {
       version: 1,
       service: app.slug,
       state: "needs_user_action",
       connectionId: null,
       interactionId: interaction.id,
-      instruction: `A connection card was sent to the responsible user. End this run and wait for continuation.`,
+      instruction: `A connection card was sent to the responsible user. Finish independent work, then yield and wait for continuation. Do not repeat this request.`,
     };
   }
 
@@ -359,8 +436,7 @@ export function connectionIntentService(db: Db) {
   async function setupOptions(interactionId: string): Promise<ConnectionIntentSetupOptions> {
     const loaded = await loadIntent(interactionId);
     const payload = connectionIntentPayloadSchema.parse(loaded.interaction.payload);
-    const app = getConnectableAppDefinition(payload.serviceSlug);
-    if (!app) throw notFound("Connection service is no longer available");
+    const app = await resolveService(payload.serviceSlug, loaded.issue.companyId, loaded.interaction.addresseeUserId!, payload.requestingAgentId);
     const inventory = await connectionInventory(loaded.issue.companyId);
     const matchingConnections = inventory.connections.filter((connection) =>
       sourceSlugForConnection(connection, inventory.applicationsById) === app.slug
@@ -371,7 +447,8 @@ export function connectionIntentService(db: Db) {
       const { grants } = await access.listConnectionGrants(connection.id, loaded.issue.companyId);
       const eligible = grants.some((grant) =>
         grant.status === "active"
-        && (grant.kind === "organization" || grant.subjectUserId === loaded.interaction.addresseeUserId)
+        && (grant.kind === "organization" || grant.subjectUserId === loaded.interaction.addresseeUserId
+          || (grant.kind === "agent" && grant.subjectAgentId === payload.requestingAgentId))
       );
       return eligible ? connection : null;
     }))).filter((connection): connection is ToolConnection => connection !== null);
@@ -381,17 +458,16 @@ export function connectionIntentService(db: Db) {
       service: {
         service: app.slug,
         name: app.name,
-        description: displayDescription(app),
+        description: app.description ?? null,
         logoUrl: app.branding.logoUrl ?? null,
-        methods: getAvailableConnectionMethods(app).map((method) => ({
-          key: method.key,
-          label: method.label ?? method.key,
-          auth: method.auth,
-        })),
+        methods: app.methods,
+        source: app.source,
         state: existingConnections.length > 0 ? "needs_user_action" : "available",
         connectionId: null,
       },
-      existingConnections,
+      existingConnections: existingConnections.map(({ id, applicationId, name, status, enabled }) => ({
+        id, applicationId, name, status, enabled,
+      })),
       requestedAgentId: payload.requestingAgentId,
     };
   }
@@ -406,7 +482,10 @@ export function connectionIntentService(db: Db) {
     } = {},
   ) {
     const loaded = await loadIntent(interactionId);
-    if (loaded.interaction.status !== "pending") throw conflict("Connection intent is already resolved");
+    if (loaded.interaction.status !== "pending") {
+      if (loaded.interaction.status === "accepted" && loaded.interaction.result?.connectionId === connectionId && loaded.interaction.addresseeUserId === userId) return loaded.interaction;
+      throw conflict("Connection intent is already resolved");
+    }
     if (loaded.interaction.addresseeUserId !== userId) throw forbidden("Only the addressed user can connect this service");
     await assertCurrentUserWriteAccess(
       loaded.issue.companyId,
@@ -415,6 +494,8 @@ export function connectionIntentService(db: Db) {
     );
     const payload = connectionIntentPayloadSchema.parse(loaded.interaction.payload);
     return db.transaction(async (tx) => {
+      const [task] = await tx.select().from(issues).where(and(eq(issues.id, loaded.issue.id), eq(issues.companyId, loaded.issue.companyId))).for("update");
+      if (!task || task.assigneeAgentId !== payload.requestingAgentId || ["done", "cancelled"].includes(task.status)) throw conflict("Connection request no longer belongs to an active task");
       // Membership downgrade/removal takes the same row lock. Whichever side
       // commits first is authoritative: a completed revocation makes this
       // revalidation fail, while completion holds authority through OAuth
@@ -428,6 +509,7 @@ export function connectionIntentService(db: Db) {
       const txDb = tx as unknown as Db;
       const txAccess = toolAccessService(txDb);
       const txInteractions = issueThreadInteractionService(txDb);
+      await tx.select({ id: toolConnections.id }).from(toolConnections).where(and(eq(toolConnections.id, connectionId), eq(toolConnections.companyId, loaded.issue.companyId))).for("update");
       let selectedConnection = await txAccess.getConnection(connectionId, loaded.issue.companyId);
       const selectedApplication = await txAccess.getApplication(
         selectedConnection.applicationId,
@@ -439,7 +521,7 @@ export function connectionIntentService(db: Db) {
       ) !== payload.serviceSlug) {
         throw notFound("Connection does not match this intent");
       }
-      if (selectedConnection.status !== "active" || !selectedConnection.enabled) {
+      if (selectedConnection.status !== "active" || !selectedConnection.enabled || isToolConnectionAttentionHealth(selectedConnection.healthStatus)) {
         throw conflict("Finish and test this connection before using it for the task");
       }
 
@@ -452,13 +534,14 @@ export function connectionIntentService(db: Db) {
       );
       if (selectedConnection.authKind === "oauth" && pendingPersonalGrant) {
         // txAccess is bound to the outer transaction. Its internal transactions
-        // become savepoints, so activation, credential bindings, the all-agents
-        // profile, and the company install roll back with any later failure.
+        // become savepoints, so activation, credential bindings, and the
+        // requesting agent's access roll back with any later failure.
         await txAccess.finalizeOAuthAccess(
           loaded.issue.companyId,
           selectedConnection.id,
           { grantKind: "user" },
           { actorType: "user", actorId: userId },
+          payload.requestingAgentId,
         );
         selectedConnection = await txAccess.getConnection(
           selectedConnection.id,
@@ -475,10 +558,11 @@ export function connectionIntentService(db: Db) {
       const organizationGrant = grants.find((grant) =>
         grant.kind === "organization" && grant.status === "active"
       );
-      if (!personalGrant && !organizationGrant) {
+      const dedicatedGrant = grants.find((grant) => grant.kind === "agent" && grant.status === "active" && grant.subjectAgentId === payload.requestingAgentId);
+      if (!personalGrant && !organizationGrant && !dedicatedGrant) {
         throw conflict("This connection has no usable identity grant");
       }
-      if (!personalGrant && !options.canManageOrganizationGrant) {
+      if (!personalGrant && !dedicatedGrant && !options.canManageOrganizationGrant) {
         throw forbidden("Sharing a company connection requires connection-management authority");
       }
 
@@ -504,6 +588,15 @@ export function connectionIntentService(db: Db) {
         actorId: userId,
       });
 
+      const effective = await txAccess.getEffectiveProfilesForAgent(loaded.issue.companyId, payload.requestingAgentId);
+      if (!effective.allowedTools.some((tool) => tool.connectionId === selectedConnection.id)) throw conflict("This connection has no permitted tools. Review its action permissions before continuing.");
+
+      const runtimeConnection = await connectionIntentService(txDb).usableConnectionForAgent({
+        companyId: loaded.issue.companyId, agentId: payload.requestingAgentId,
+        responsibleUserId: userId, serviceSlug: payload.serviceSlug,
+      });
+      if (runtimeConnection?.id !== selectedConnection.id) throw conflict("This identity is not the connection this agent can execute. Resolve conflicting identities before continuing.");
+
       return txInteractions.resolveConnectionIntent(
         loaded.issue,
         interactionId,
@@ -536,6 +629,7 @@ export function connectionIntentService(db: Db) {
 
   return {
     validate: loadRunContext,
+    usableConnectionForAgent,
     search,
     request,
     loadIntent,

server/src/services/connection-tool-definitions.ts

@@ -0,0 +1,24 @@
+import { CONNECTION_REQUEST_TOOL_DESCRIPTION, CONNECTIONS_SEARCH_TOOL_DESCRIPTION } from "@paperclipai/shared";
+
+export const RUNTIME_CONNECTION_TOOL_DEFINITIONS = [
+  {
+    name: "connections_search",
+    description: CONNECTIONS_SEARCH_TOOL_DESCRIPTION,
+    inputSchema: {
+      type: "object",
+      properties: { query: { type: "string" } },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "connection_request",
+    description: CONNECTION_REQUEST_TOOL_DESCRIPTION,
+    inputSchema: {
+      type: "object",
+      properties: { service: { type: "string" } },
+      required: ["service"],
+      additionalProperties: false,
+    },
+  },
+] as const;
+

server/src/services/heartbeat.ts

@@ -17462,11 +17462,12 @@ export function heartbeatService(
         isResolvedInteractionContinuationWakeContext(context)
       ) {
         try {
-          // Claim the issue under the same in_progress predicate used by the
+          // Claim the issue under the same active-status predicate used by the
           // queued-run staleness gate. This is the final atomic guard before
           // dispatch: an operator parking the issue after claim but before this
           // checkout must not be overwritten by the continuation.
-          await issuesSvc.checkout(issueId, agent.id, ["in_progress"], run.id);
+          await issuesSvc.checkout(issueId, agent.id, context.interactionKind === "connection_intent"
+            ? ["in_progress", "in_review"] : ["in_progress"], run.id);
           context[PAPERCLIP_HARNESS_CHECKOUT_KEY] = true;
         } catch (error) {
           if (!isCheckoutConflictError(error)) throw error;

server/src/services/issue-thread-interactions.ts

@@ -1,3 +1,4 @@
+import { connectionIntentDeliveries } from "@paperclipai/db";
 import { isDeepStrictEqual } from "node:util";
 import { and, asc, desc, eq, inArray, isNotNull, isNull, ne } from "drizzle-orm";
 import type { Db } from "@paperclipai/db";
@@ -656,7 +657,7 @@ function shouldReturnAcceptedConfirmationToCreatorAgent(args: {
 }
 
 function shouldSupersedeInteractionOnUserComment(interaction: UserCommentSupersedableInteraction) {
-  if (interaction.kind === "connection_intent") return true;
+  if (interaction.kind === "connection_intent") return false;
   return interaction.payload.supersedeOnUserComment === true;
 }
 
@@ -2034,6 +2035,7 @@ export function issueThreadInteractionService(db: Db, opts: IssueThreadInteracti
       input: {
         payload: ConnectionIntentInteraction["payload"];
         sourceRunId: string;
+        sourceIdentityContextId?: string | null;
         addresseeUserId: string;
         idempotencyKey: string;
       },
@@ -2049,7 +2051,9 @@ export function issueThreadInteractionService(db: Db, opts: IssueThreadInteracti
           existing.kind !== "connection_intent"
           || existing.sourceRunId !== input.sourceRunId
           || existing.addresseeUserId !== input.addresseeUserId
-          || !isDeepStrictEqual(existing.payload, payload)
+          || (existing.kind === "connection_intent"
+            ? connectionIntentPayloadSchema.parse(existing.payload).serviceSlug !== payload.serviceSlug
+            : !isDeepStrictEqual(existing.payload, payload))
         ) {
           throw conflict("Interaction idempotency key already exists for a different request", {
             idempotencyKey: input.idempotencyKey,
@@ -2058,17 +2062,31 @@ export function issueThreadInteractionService(db: Db, opts: IssueThreadInteracti
         return hydrateInteraction(existing) as ConnectionIntentInteraction;
       }
 
+      let inserted = false;
       const created = await db.transaction(async (tx) => {
         const issueRow = await tx
-          .select({ status: issues.status })
+          .select({ status: issues.status, assigneeAgentId: issues.assigneeAgentId })
           .from(issues)
           .where(and(eq(issues.id, issue.id), eq(issues.companyId, issue.companyId)))
           .for("update")
           .then((rows) => rows[0] ?? null);
-        if (!issueRow || isTerminalIssueStatus(issueRow.status)) {
+        if (!issueRow || isTerminalIssueStatus(issueRow.status) || issueRow.assigneeAgentId !== payload.requestingAgentId) {
           throw conflict("Cannot create an interaction on a closed issue");
         }
 
+        // Serialize on the task so retries and later runs share the same live card.
+        const pending = await tx.select().from(issueThreadInteractions).where(and(
+          eq(issueThreadInteractions.companyId, issue.companyId),
+          eq(issueThreadInteractions.issueId, issue.id),
+          eq(issueThreadInteractions.kind, "connection_intent"),
+          eq(issueThreadInteractions.status, "pending"),
+          eq(issueThreadInteractions.createdByAgentId, payload.requestingAgentId),
+          eq(issueThreadInteractions.addresseeUserId, input.addresseeUserId),
+        ));
+        const reusable = pending.find((candidate) =>
+          connectionIntentPayloadSchema.parse(candidate.payload).serviceSlug === payload.serviceSlug);
+        if (reusable) return reusable;
+
         const [row] = await tx
           .insert(issueThreadInteractions)
           .values({
@@ -2083,6 +2101,7 @@ export function issueThreadInteractionService(db: Db, opts: IssueThreadInteracti
             effectiveResolverPolicySource: "governed_action",
             idempotencyKey: input.idempotencyKey,
             sourceRunId: input.sourceRunId,
+            sourceIdentityContextId: input.sourceIdentityContextId ?? null,
             title: `Connect ${payload.serviceName}`,
             summary: `${payload.requestingAgentName} needs this connection to continue.`,
             createdByAgentId: payload.requestingAgentId,
@@ -2127,11 +2146,12 @@ export function issueThreadInteractionService(db: Db, opts: IssueThreadInteracti
             .where(inArray(issueThreadInteractions.id, supersededIds));
         }
         await touchIssue(tx, issue.id);
+        inserted = true;
         return row;
       });
 
       const interaction = hydrateInteraction(created) as ConnectionIntentInteraction;
-      emitInteractionCreatedTelemetry({
+      if (inserted) emitInteractionCreatedTelemetry({
         interactionKind: "connection_intent",
         usedDeprecatedResolverPolicyAlias: false,
       });
@@ -2182,7 +2202,8 @@ export function issueThreadInteractionService(db: Db, opts: IssueThreadInteracti
           ? "rejected"
           : "expired";
       const resolvedAt = now();
-      const [updated] = await db
+      const updated = await db.transaction(async (tx) => {
+        const [row] = await tx
         .update(issueThreadInteractions)
         .set({
           status,
@@ -2198,6 +2219,12 @@ export function issueThreadInteractionService(db: Db, opts: IssueThreadInteracti
           eq(issueThreadInteractions.status, "pending"),
         ))
         .returning();
+        if (!row) throw interactionAlreadyResolvedError();
+        if (status === "accepted" || status === "rejected") {
+          await tx.insert(connectionIntentDeliveries).values({ interactionId, companyId: issue.companyId }).onConflictDoNothing();
+        }
+        return row;
+      });
       if (!updated) throw interactionAlreadyResolvedError();
       await touchIssue(db, issue.id);
       const interaction = hydrateInteraction(updated) as ConnectionIntentInteraction;
@@ -3573,6 +3600,15 @@ export function issueThreadInteractionService(db: Db, opts: IssueThreadInteracti
       return expired;
     },
 
+    expireConnectionIntentsForOwnershipChange: async (issue: { id: string; companyId: string }) => {
+      const expired = await db.update(issueThreadInteractions).set({
+        status: "expired", result: { version: 1, outcome: "expired", reason: "The task assignment changed" },
+        resolvedAt: now(), updatedAt: now(),
+      }).where(and(eq(issueThreadInteractions.companyId, issue.companyId), eq(issueThreadInteractions.issueId, issue.id),
+        eq(issueThreadInteractions.kind, "connection_intent"), eq(issueThreadInteractions.status, "pending"))).returning();
+      if (expired.length) await db.delete(toolOauthStates).where(inArray(toolOauthStates.interactionId, expired.map((row) => row.id)));
+      return expired;
+    },
     expirePendingInteractionsForTerminalIssue: async (
       issue: { id: string; companyId: string; status: string },
       actor: InteractionActor = {},

server/src/services/issues.ts

@@ -7981,6 +7981,10 @@ export function issueService(db: Db) {
           .returning()
           .then((rows: Array<typeof issues.$inferSelect>) => rows[0] ?? null);
         if (!updated) return null;
+        if (updated.assigneeAgentId !== existing.assigneeAgentId || updated.assigneeUserId !== existing.assigneeUserId) {
+          const { issueThreadInteractionService } = await import("./issue-thread-interactions.js");
+          await issueThreadInteractionService(tx).expireConnectionIntentsForOwnershipChange(updated);
+        }
         if (existing.status !== updated.status) {
           if (
             (existing.status === "done" || existing.status === "cancelled")

server/src/services/native-runtime/native-interaction-bridge.ts

@@ -279,7 +279,7 @@ export async function materializeNativeInteractionResponses(input: {
       continue;
     }
 
-    if (interaction.kind === "suggest_tasks") {
+    if (interaction.kind === "suggest_tasks" || interaction.kind === "connection_intent") {
       if (
         (interaction.status !== "accepted" && interaction.status !== "rejected")
         || !interaction.result

server/src/services/native-runtime/native-session-executor.test.ts

@@ -180,6 +180,7 @@ import {
   nativeSessionFailureSourceCode,
   nativeSessionRecoveryProjection,
   nativeGovernedWaitResult,
+  nativeToolsRefreshWaitResult,
   parseRemoteExecutableCandidate,
   buildRemoteCodexLauncherCommand,
   mayUsePreinstalledRunnerArtifact,
@@ -2176,6 +2177,15 @@ describe("provider plan synchronization", () => {
 });
 
 describe("native governed waits", () => {
+  it("yields to an existing tools-refresh wake without claiming completion or a human interaction", () => {
+    const result = nativeToolsRefreshWaitResult({ wakeId: "wake-1", key: "connection-intent:tools:run-1:digest",
+      completionContract: { revision: "4", objective: "Read the archive", criteria: [{ id: "read", requirement: "Read the archive" }] } });
+    expect(result.completionClaim).toMatchObject({ contractRevision: "4", objectiveSatisfied: false });
+    expect(result.artifacts).toEqual([]);
+    expect(result.continuation).toMatchObject({ kind: "same_agent", idempotencyKey: "connection-intent:tools:run-1:digest" });
+    expect(result.evidence).toEqual([{ ref: "wakeup:wake-1" }]);
+  });
+
   it("turns a durable pending interaction into a response-wake result", () => {
     expect(
       nativeGovernedWaitResult({

server/src/services/native-runtime/native-session-executor.ts

@@ -56,8 +56,9 @@ import {
   type PaperclipRunnerTransport,
 } from "@paperclipai/adapter-utils/runner-connectivity";
 import type { Db } from "@paperclipai/db";
-import { and, desc, eq, gt, inArray, or, sql } from "drizzle-orm";
+import { and, desc, eq, gt, inArray, like, notInArray, or, sql } from "drizzle-orm";
 import {
+  agentWakeupRequests,
   documentRevisions,
   environmentLeases,
   heartbeatRunEvents,
@@ -885,6 +886,22 @@ export function createGovernedWaitEventObservation(
   };
 }
 
+export function nativeToolsRefreshWaitResult(input: {
+  wakeId: string; key: string;
+  completionContract: NativeExecutionInput["completionContract"]["contract"];
+}): PrpStructuredRunResult {
+  const ref = `wakeup:${input.wakeId}`;
+  return {
+    schema: "paperclip.run_result.v1", reportedWorkDisposition: "yielded",
+    summary: "Continuing with the newly installed connection tools.",
+    completionClaim: { contractRevision: input.completionContract.revision, objectiveSatisfied: false,
+      criteria: input.completionContract.criteria.map((criterion) => ({ criterionId: criterion.id, status: "unknown", evidenceRefs: [ref] })),
+      remainingWork: [{ description: "Continue in the queued session with updated tools.", blocksCompletion: true }] },
+    evidence: [{ ref }], verification: [], attentionRequests: [], artifacts: [],
+    continuation: { kind: "same_agent", summary: "Use the updated connection tools in a fresh session.", idempotencyKey: input.key },
+  };
+}
+
 /**
  * Partial item-verdict responses deliberately leave their original durable
  * interaction pending. They are already authority-checked before entering the
@@ -4343,6 +4360,10 @@ async function executePaperclipNativeSessionWithinScope(
               issueThreadInteractions.sourceRunId,
               input.execution.binding.runId,
             ),
+            and(
+              eq(issueThreadInteractions.kind, "connection_intent"),
+              eq(issueThreadInteractions.createdByAgentId, input.execution.binding.agentId),
+            ),
             ...(continuingInteractionIds.length > 0
               ? [inArray(issueThreadInteractions.id, continuingInteractionIds)]
               : []),
@@ -4356,12 +4377,20 @@ async function executePaperclipNativeSessionWithinScope(
       )
       .limit(1)
       .then((rows) => rows[0] ?? null);
-    return interaction
-      ? nativeGovernedWaitResult({
-          interaction,
-          completionContract: input.execution.completionContract.contract,
-        })
-      : null;
+    if (interaction) return nativeGovernedWaitResult({
+      interaction, completionContract: input.execution.completionContract.contract,
+    });
+    // A ready connection can become installed after the provider snapshot was
+    // pinned. Its already-durable wake is also a valid reason to end this turn.
+    const [refresh] = await input.db.select({ id: agentWakeupRequests.id, key: agentWakeupRequests.idempotencyKey })
+      .from(agentWakeupRequests).where(and(
+        eq(agentWakeupRequests.companyId, input.execution.binding.companyId),
+        eq(agentWakeupRequests.agentId, input.execution.binding.agentId),
+        like(agentWakeupRequests.idempotencyKey, `connection-intent:tools:${input.execution.binding.runId}:%`),
+        notInArray(agentWakeupRequests.status, ["skipped", "failed", "cancelled"]),
+      )).limit(1);
+    return refresh?.key ? nativeToolsRefreshWaitResult({ wakeId: refresh.id, key: refresh.key,
+      completionContract: input.execution.completionContract.contract }) : null;
   }
   const runnerExecution =
     input.useRunnerd && input.runnerExecutionTarget?.kind === "remote"
@@ -6203,6 +6232,7 @@ async function createRunnerdBackendWithinSessionClaim(
     runId: input.execution.binding.runId,
     agentId: input.execution.binding.agentId,
     normalizedSessionId: nativeSessionKey(input.execution),
+    pinnedMcpDigest: "runtimeContext" in input.execution ? input.execution.runtimeContext.mcp.digest : undefined,
     workMode: input.execution.task.workMode,
     enqueueWakeup: input.enqueueWakeup,
   });

server/src/services/native-runtime/paperclip-runner-tool-authority.test.ts

@@ -63,8 +63,9 @@ describe("PaperclipRunnerToolAuthority", () => {
 
   it("advertises only real bindings and reads the bound task", async () => {
     const authority = new PaperclipRunnerToolAuthority(db, { companyId, agentId, issueId, runId });
-    expect(authority.definitions()).toHaveLength(16);
+    expect(authority.definitions()).toHaveLength(18);
     expect(authority.definitions().map((tool) => tool.name)).toEqual(expect.arrayContaining([
+      "connections_search", "connection_request",
       "get_task_context", "get_task_history", "search_tasks", "report_progress",
       "request_human_input",
       "create_task", "set_dependencies",

server/src/services/native-runtime/paperclip-runner-tool-authority.ts

@@ -1,3 +1,7 @@
+import { resolveNativeRuntimeMcpSnapshot } from "./runtime-context.js";
+import { connectionIntentService } from "../connection-intents.js";
+import { RUNTIME_CONNECTION_TOOL_DEFINITIONS } from "../connection-tool-definitions.js";
+import { connectionsSearchInputSchema, connectionRequestInputSchema, CONNECTION_INTENT_AGENT_GUIDANCE } from "@paperclipai/shared";
 import { createHash } from "node:crypto";
 import { runnerApiToolsEnabled } from "./runner-api-rollout.js";
 import { openRunnerApiWorkspaceFile } from "./runner-api-files.js";
@@ -10,10 +14,11 @@ import { workspaceFileResourceService } from "../workspace-file-resources.js";
 import { badRequest, forbidden } from "../../errors.js";
 import { searchRunnerApi } from "./runner-api-catalog.js";
 import { executeRunnerApi, validateRunnerApiCall, RUNNER_API_MAX_BYTES, type RunnerApiFile } from "./runner-api-client.js";
-import { and, desc, eq, isNull } from "drizzle-orm";
+import { and, desc, eq, isNull, notInArray } from "drizzle-orm";
 import type { Db } from "@paperclipai/db";
 import {
   agents,
+  agentWakeupRequests,
   documentRevisions,
   heartbeatRuns,
   issueApprovals,
@@ -46,6 +51,7 @@ type Binding = {
   runId: string;
   agentId: string;
   normalizedSessionId?: string;
+  pinnedMcpDigest?: string;
   /** Server-owned API origin and storage; never obtained from tool input. */
   apiUrl?: string;
   storage?: StorageService;
@@ -61,6 +67,7 @@ type Binding = {
     requestedByActorType: "agent";
     requestedByActorId: string;
     contextSnapshot: Record<string, unknown>;
+    issueStateGuard?: { statuses: string[]; assigneeAgentId: string };
   }) => Promise<unknown>;
 };
 
@@ -90,7 +97,7 @@ export class PaperclipRunnerToolAuthority {
 
   definitions(): Array<Record<string, unknown>> {
     const workMode = this.binding.workMode ?? "standard";
-    return CAPABILITY_SEMANTIC_TOOL_CATALOG
+    return [...RUNTIME_CONNECTION_TOOL_DEFINITIONS, ...CAPABILITY_SEMANTIC_TOOL_CATALOG
       .filter((descriptor) =>
         IMPLEMENTED_OPERATIONS.has(descriptor.operationId)
         && (runnerApiToolsEnabled(this.binding.companyId, this.binding.apiToolsEnabled) || !["search_api", "call_api"].includes(descriptor.operationId))
@@ -100,10 +107,42 @@ export class PaperclipRunnerToolAuthority {
         name: descriptor.operationId,
         description: descriptor.description,
         inputSchema: descriptor.inputSchema,
-      }));
+      }))];
   }
 
   async execute(call: { tool: string; callId: string; arguments: unknown }): Promise<unknown> {
+    if (RUNTIME_CONNECTION_TOOL_DEFINITIONS.some((tool) => tool.name === call.tool)) {
+      await this.#boundContext();
+      const { run } = await captureRunIdentity(this.db, this.binding);
+      if (!run.responsibleUserId) throw forbidden("This task needs a responsible user before requesting a connection");
+      const claims = {
+        sub: this.binding.agentId, company_id: this.binding.companyId,
+        run_id: this.binding.runId, responsible_user_id: run.responsibleUserId,
+      };
+      const connections = connectionIntentService(this.db);
+      if (call.tool === "connections_search") return connections.search(claims, connectionsSearchInputSchema.parse(call.arguments).query);
+      const result = await connections.request(claims, connectionRequestInputSchema.parse(call.arguments).service);
+      if (result.state === "ready" && this.binding.pinnedMcpDigest && this.binding.enqueueWakeup) {
+        const current = await resolveNativeRuntimeMcpSnapshot({ db: this.db, agent: { id: this.binding.agentId, companyId: this.binding.companyId }, runId: this.binding.runId });
+        if (current.digest !== this.binding.pinnedMcpDigest) {
+          const idempotencyKey = `connection-intent:tools:${this.binding.runId}:${current.digest}`;
+          const delivered = () => this.db.select({ id: agentWakeupRequests.id }).from(agentWakeupRequests).where(and(
+            eq(agentWakeupRequests.companyId, this.binding.companyId), eq(agentWakeupRequests.idempotencyKey, idempotencyKey),
+            notInArray(agentWakeupRequests.status, ["skipped", "failed", "cancelled"]),
+          )).limit(1);
+          if (!(await delivered()).length) try { await this.binding.enqueueWakeup(this.binding.agentId, {
+            source: "assignment", triggerDetail: "system", reason: "issue_assigned",
+            payload: { issueId: this.binding.issueId, mutation: "connection_tools_refreshed" },
+            idempotencyKey,
+            issueStateGuard: { statuses: ["in_progress", "in_review"], assigneeAgentId: this.binding.agentId },
+            requestedByActorType: "agent", requestedByActorId: this.binding.agentId,
+            contextSnapshot: { issueId: this.binding.issueId, taskId: this.binding.issueId, forceFreshSession: true, wakeReason: "issue_assigned", source: "connection_tools.refreshed" },
+          }); } catch (error) { if (!(await delivered()).length) throw error; }
+          return { ...result, instruction: "Access is already authorized. A fresh continuation with updated tools is queued. Finish independent work, then yield. Do not request authorization again." };
+        }
+      }
+      return result;
+    }
     if (!IMPLEMENTED_OPERATIONS.has(call.tool)) throw new Error("paperclip_runner_tool_not_advertised");
     if (!runnerApiToolsEnabled(this.binding.companyId, this.binding.apiToolsEnabled) && ["search_api", "call_api"].includes(call.tool)) throw new Error("paperclip_runner_tool_not_advertised");
     const context = await this.#boundContext();
@@ -126,6 +165,7 @@ export class PaperclipRunnerToolAuthority {
           status: context.run.status,
           invocationSource: context.run.invocationSource,
         },
+        connectionGuidance: CONNECTION_INTENT_AGENT_GUIDANCE,
         acceptedPlan: await this.#acceptedPlan(context.run.contextSnapshot),
       };
       case "get_task_history": {

server/src/services/native-runtime/status-decision-committer.ts

@@ -1,4 +1,4 @@
-import { and, asc, desc, eq, inArray, sql } from "drizzle-orm";
+import { and, asc, desc, eq, inArray, notInArray, sql } from "drizzle-orm";
 import type { Db } from "@paperclipai/db";
 import type { CreateIssueThreadInteraction } from "@paperclipai/shared";
 import {
@@ -459,6 +459,15 @@ async function materializeDecisionEffect(input: {
   }
   if (effect.kind === "enqueue_continuation") {
     failAt("continuation_materialization", input.failpoint);
+    if (effect.idempotencyKey.startsWith(`connection-intent:tools:${input.runId}:`)) {
+      const [refresh] = await input.tx.select({ id: agentWakeupRequests.id }).from(agentWakeupRequests).where(and(
+        eq(agentWakeupRequests.companyId, input.companyId), eq(agentWakeupRequests.agentId, effect.agentId),
+        eq(agentWakeupRequests.idempotencyKey, effect.idempotencyKey),
+        notInArray(agentWakeupRequests.status, ["skipped", "failed", "cancelled"]),
+      )).limit(1);
+      if (refresh) return { effectKind: effect.kind, targetType: "agent_wakeup_request", targetId: refresh.id,
+        payload: { continuationKind: effect.continuationKind, summary: effect.summary } };
+    }
     const wakeId = await enqueueWake({
       tx: input.tx,
       companyId: input.companyId,

server/src/services/tool-access.ts

@@ -8789,13 +8789,14 @@ export function toolAccessService(db: Db, options: ToolAccessServiceOptions = {}
 
     let existingApplication: typeof toolApplications.$inferSelect | null = null;
     let requestedResumeConnection: typeof toolConnections.$inferSelect | null = null;
-    if (input.resumeConnectionId) {
+    const requestedConnectionId = input.resumeConnectionId ?? input.reconnectConnectionId;
+    if (requestedConnectionId) {
       const [connection] = await db.select().from(toolConnections).where(and(
-        eq(toolConnections.id, input.resumeConnectionId),
+        eq(toolConnections.id, requestedConnectionId),
         eq(toolConnections.companyId, companyId),
       ));
       if (!connection) throw notFound("Incomplete app connection not found");
-      if (connection.status !== "draft") {
+      if (input.resumeConnectionId && connection.status !== "draft") {
         throw conflict("Only an incomplete app connection can resume setup", {
           code: "connection_setup_not_incomplete",
         });
@@ -8808,6 +8809,10 @@ export function toolAccessService(db: Db, options: ToolAccessServiceOptions = {}
         eq(toolApplications.companyId, companyId),
       ));
       if (!application) throw notFound("App not found");
+      const source = asRecord(connection.config).sourceTemplateKey ?? asRecord(connection.transportConfig).sourceTemplateKey ?? asRecord(application.metadata).sourceTemplateKey ?? asRecord(application.metadata).source;
+      if (input.reconnectConnectionId && ((galleryEntry && source !== galleryEntry.slug) || (!galleryEntry && typeof source === "string" && getConnectableAppDefinition(source)))) {
+        throw badRequest("Reconnect must preserve the configured provider");
+      }
       requestedResumeConnection = connection;
       existingApplication = application;
     } else if (input.applicationId) {
@@ -9923,6 +9928,7 @@ export function toolAccessService(db: Db, options: ToolAccessServiceOptions = {}
           metadata: { source: "app_gallery_finish" },
         }));
     const transactionResult = await db.transaction(async (tx) => {
+      await tx.select({ id: toolConnections.id }).from(toolConnections).where(and(eq(toolConnections.id, connectionId), eq(toolConnections.companyId, companyId))).for("update");
       const [existingProfile] = await tx
         .select()
         .from(toolProfiles)
@@ -9930,6 +9936,12 @@ export function toolAccessService(db: Db, options: ToolAccessServiceOptions = {}
         .limit(1);
       let profileId: string;
       if (existingProfile) {
+        if (input.preserveExistingAccess) {
+          const priorBindings = await tx.select().from(toolProfileBindings).where(eq(toolProfileBindings.profileId, existingProfile.id));
+          for (const prior of priorBindings) if (!bindingInputs.some((binding) => binding.targetType === prior.targetType && binding.targetId === prior.targetId)) bindingInputs.push({ targetType: prior.targetType, targetId: prior.targetId, priority: prior.priority, metadata: prior.metadata });
+          const priorEntries = await tx.select().from(toolProfileEntries).where(eq(toolProfileEntries.profileId, existingProfile.id));
+          for (const prior of priorEntries) if (!entries.some((entry) => entry.catalogEntryId && entry.catalogEntryId === prior.catalogEntryId)) entries.push({ selectorType: prior.selectorType, effect: prior.effect, applicationId: prior.applicationId, connectionId: prior.connectionId, catalogEntryId: prior.catalogEntryId, toolName: prior.toolName, riskLevel: prior.riskLevel, conditions: prior.conditions });
+        }
         await tx
           .delete(toolProfileBindings)
           .where(and(eq(toolProfileBindings.companyId, companyId), eq(toolProfileBindings.profileId, existingProfile.id)));
@@ -10048,6 +10060,7 @@ export function toolAccessService(db: Db, options: ToolAccessServiceOptions = {}
         companyId,
         connection,
         askFirstEntries: askFirstRows,
+        disableStale: !input.preserveExistingAccess,
         actor,
       }, tx);
       const [updatedConnection] = await tx
@@ -10801,7 +10814,17 @@ export function toolAccessService(db: Db, options: ToolAccessServiceOptions = {}
     suggestedDefaults: ConnectToolAppResult["suggestedDefaults"];
     activateQuarantined?: boolean;
     actor?: ActorInfo;
+    interactionId?: string | null;
   }) {
+    const linkedInteraction = input.interactionId
+      ? await db.select({ kind: issueThreadInteractions.kind }).from(issueThreadInteractions).where(and(
+          eq(issueThreadInteractions.id, input.interactionId),
+          eq(issueThreadInteractions.companyId, input.connection.companyId),
+        )).limit(1).then((rows) => rows[0] ?? null)
+      : null;
+    // A task callback only prepares the catalog. The intent completion transaction
+    // validates current ownership and adds the requesting agent's access.
+    const deferTaskAccess = linkedInteraction?.kind === "connection_intent";
     const installs = await db.select().from(toolConnectionInstalls).where(and(
       eq(toolConnectionInstalls.companyId, input.connection.companyId),
       eq(toolConnectionInstalls.connectionId, input.connection.id),
@@ -10820,7 +10843,9 @@ export function toolAccessService(db: Db, options: ToolAccessServiceOptions = {}
       : suggestedAgentIds.length > 0
         ? { agentIds: suggestedAgentIds }
         : "all_agents";
-    const access: FinishToolApp["access"] = installs.length === 0
+    const access: FinishToolApp["access"] = deferTaskAccess
+      ? { agentIds: [] }
+      : installs.length === 0
       ? normalizedSuggestedAccess
       : companyInstall
         ? "all_agents"
@@ -10844,8 +10869,9 @@ export function toolAccessService(db: Db, options: ToolAccessServiceOptions = {}
         ? enabledCatalog.filter((entry) => entry.status === "quarantined").map((entry) => entry.id)
         : undefined,
       access,
+      preserveExistingAccess: deferTaskAccess,
     }, input.actor);
-    if (installs.length === 0) {
+    if (!deferTaskAccess && installs.length === 0) {
       const installTargets = access === "all_agents"
         ? [{ targetType: "company" as const, targetId: input.connection.companyId }]
         : [...new Set(access.agentIds)].map((agentId) => ({ targetType: "agent" as const, targetId: agentId }));
@@ -11137,6 +11163,7 @@ export function toolAccessService(db: Db, options: ToolAccessServiceOptions = {}
       : recommended;
     const finished = shouldFinalizeManagedDefaults
       ? await finishOAuthCatalogWithRecommendedDefaults({
+          interactionId: stateRow.interactionId,
           connection,
           catalog: refresh.catalog,
           suggestedDefaults,
@@ -11286,6 +11313,7 @@ export function toolAccessService(db: Db, options: ToolAccessServiceOptions = {}
     const method = connectionMethodForConnection(galleryEntry, connection);
     const refresh = await refreshCatalog(connection.id, input.actor, {
       enableAllByDefault: true,
+      skipDefaultProfileSync: true,
       credentialHeaders: {
         ...projectedConnectionHeaders(connection),
         [credential.headerName]: `${credential.headerPrefix ?? ""}${token.token}`,
@@ -11293,6 +11321,7 @@ export function toolAccessService(db: Db, options: ToolAccessServiceOptions = {}
     });
     const suggestedDefaults = recommendedDefaultsForApp(galleryEntry, method.key);
     const finished = await finishOAuthCatalogWithRecommendedDefaults({
+      interactionId: stateRow.interactionId,
       connection,
       catalog: refresh.catalog,
       suggestedDefaults,
@@ -11544,6 +11573,7 @@ export function toolAccessService(db: Db, options: ToolAccessServiceOptions = {}
       // Activate and discover with the just-issued token before returning.
       const refresh = await refreshCatalog(connection.id, input.actor, {
         enableAllByDefault: true,
+      skipDefaultProfileSync: true,
         credentialHeaders: { Authorization: `Bearer ${token.accessToken}` },
       });
       const [application] = await db.select().from(toolApplications).where(eq(toolApplications.id, connection.applicationId));
@@ -11552,6 +11582,7 @@ export function toolAccessService(db: Db, options: ToolAccessServiceOptions = {}
         ? recommendedDefaultsForApp(galleryEntry, connectionMethodForConnection(galleryEntry, connection).key)
         : { access: "all_agents" as const, askFirstRiskLevels: [] };
       const finished = await finishOAuthCatalogWithRecommendedDefaults({
+        interactionId: stateRow.interactionId,
         connection,
         catalog: refresh.catalog,
         suggestedDefaults,
@@ -11697,7 +11728,7 @@ export function toolAccessService(db: Db, options: ToolAccessServiceOptions = {}
     });
 
     await checkConnectionHealth(connection.id, input.actor);
-    const refresh = await refreshCatalog(connection.id, input.actor, { enableAllByDefault: true });
+    const refresh = await refreshCatalog(connection.id, input.actor, { enableAllByDefault: true, skipDefaultProfileSync: true });
     const [application] = await db.select().from(toolApplications).where(eq(toolApplications.id, connection.applicationId));
     const suggestedDefaults = galleryEntry ? recommendedDefaultsForApp(
       galleryEntry,
@@ -11707,6 +11738,7 @@ export function toolAccessService(db: Db, options: ToolAccessServiceOptions = {}
       askFirstRiskLevels: [],
     };
     const finished = await finishOAuthCatalogWithRecommendedDefaults({
+      interactionId: stateRow.interactionId,
       connection,
       catalog: refresh.catalog,
       suggestedDefaults,
@@ -11735,7 +11767,9 @@ export function toolAccessService(db: Db, options: ToolAccessServiceOptions = {}
     connectionId: string,
     input: FinalizeOAuthAccess,
     actor?: ActorInfo,
+    requestingAgentId?: string,
   ): Promise<FinishToolAppResult> {
+    if (requestingAgentId) await assertAgentsInCompany(companyId, [requestingAgentId]);
     let connection = await getConnectionRow(connectionId, companyId);
     if (connection.authKind !== "oauth") throw badRequest("This connection does not use browser sign-in");
     if (connection.status === "archived") throw conflict("Archived app connections cannot be finished");
@@ -11953,13 +11987,14 @@ export function toolAccessService(db: Db, options: ToolAccessServiceOptions = {}
       askFirstCatalogEntryIds: catalog
         .filter((entry) => askFirstRiskLevels.has(entry.riskLevel))
         .map((entry) => entry.id),
-      access: "all_agents",
+      access: requestingAgentId ? { agentIds: [requestingAgentId] } : "all_agents",
+      preserveExistingAccess: Boolean(requestingAgentId),
     }, actor);
     await db.insert(toolConnectionInstalls).values({
       companyId,
       connectionId: connection.id,
-      targetType: "company",
-      targetId: companyId,
+      targetType: requestingAgentId ? "agent" : "company",
+      targetId: requestingAgentId ?? companyId,
       createdByUserId: actorUserId,
     }).onConflictDoNothing();
     return finished;