paperclip-github-plugin 0.8.7 → 0.8.8

package/README.md

@@ -72,6 +72,12 @@ Because GitHub alone cannot tell which pull requests came from a Paperclip compa
 
 That API route path matters on authenticated Paperclip deployments today because a current host bug blocks agents from calling plugin tools unless the instance runs in `local_trusted` mode. Those agents can still use `gh` with the propagated `GITHUB_TOKEN`, then call the agent-authenticated plugin API route from the shell after they create a PR. The Paperclip host authenticates `Authorization: Bearer <PAPERCLIP_API_KEY>`, scopes the request to the calling agent's company, and rejects anonymous or non-agent calls before dispatching to the worker.
 
+### Third-party issue links
+
+Sometimes a Paperclip issue is implemented through a GitHub issue or pull request in a repository that is not mapped to any Paperclip project. GitHub Sync can now track those targeted links without enrolling the whole repository in sync. The `link_github_item` agent tool records the durable link on local-trusted Paperclip instances, and authenticated agent runs can post the same link to `/api/plugins/paperclip-github-plugin/api/issue-link` with `PAPERCLIP_API_KEY` when plugin tools are blocked by host board-auth gates.
+
+Third-party links are company-scoped and sync only the linked GitHub issue or pull request. Future manual or scheduled company sync runs refresh those external records and update the Paperclip issue status from the same CI, mergeability, review, thread, and issue-state rules used for mapped repositories.
+
 ### Project pull request command center
 
 Each mapped project can expose a **Pull Requests** entry in the sidebar that opens a live GitHub queue page for that repository. The sidebar badge uses a lightweight total-count read, while the queue keeps the default view fast by loading only the current 10-row page, uses a repo-wide metrics read for the summary cards, reuses that cached metrics scan to keep filtered views fast by fetching only the visible filtered rows, keeps repo-scoped count, metrics, and per-PR review/check insight caches warm for repeat visits, lets operators explicitly bust those caches with Refresh when they want a live reread, shows total, mergeable, reviewable, and failing cards that filter the table, only treats a pull request as mergeable when it targets the current default branch with green checks, at least one approval, no outstanding change requests, and no unresolved review threads, includes an **Up to date** column that distinguishes current branches, clean update candidates, conflict cases, and unknown freshness when GitHub cannot confirm the comparison, shows the PR target branch with a highlighted default-branch badge, keeps the list sorted by most recently updated first, paginates larger repositories, keeps a compact bottom detail pane with markdown-and-HTML-rendered conversation plus an inline comment composer, supports deterministic **Update branch** actions for clean behind-base pull requests, adds Copilot quick actions that post `@copilot` requests for **Fix CI**, **Rebase**, and **Address review feedback**, requests Copilot through GitHub’s native reviewer flow for **Review**, keeps comment, review, quick approve/request-changes, re-run CI, merge, and close actions available, lets the review modal submit comment-only, approve, or request-changes reviews, hides any pull request action whose required GitHub permission is not verified for the saved token, and opens linked Paperclip issues in a plugin-provided right drawer so operators can stay on the queue page.
@@ -93,6 +99,7 @@ Linked Paperclip issues can also be unlinked from the GitHub detail surface. Unl
 ### Agent workflows built in
 
 Paperclip agents can search GitHub for duplicates, read and update issues, assign issues to the saved token owner, post comments, create pull requests, inspect changed files and CI, reply to review threads, resolve or unresolve threads, request reviewers, search org-level GitHub Projects, and associate pull requests with those projects without leaving the Paperclip plugin surface.
+They can also link a Paperclip issue to a GitHub issue or pull request in any accessible repository with `link_github_item`, including third-party repositories that are not mapped to a Paperclip project.
 
 ## Requirements
 
@@ -259,10 +266,33 @@ Current host caveat: on authenticated Paperclip deployments, the Paperclip host
 
 Because the KPI attribution endpoint is a native plugin JSON route rather than a plugin tool, authenticated agent runs can still call it directly with `PAPERCLIP_API_KEY` even while that host bug blocks the GitHub Sync tool surface.
 
+### Issue link API route
+
+Authenticated agent runs can link the current Paperclip issue to a GitHub issue or pull request by posting to `/api/plugins/paperclip-github-plugin/api/issue-link`. This is useful after creating a PR with `gh` in a repository that is not mapped to a Paperclip project.
+
+Supported payload fields:
+
+- `paperclipIssueId` required: the Paperclip issue id to link
+- `kind` optional: `issue` or `pull_request`; omitted values are inferred from full GitHub URLs when possible
+- `reference` optional: a GitHub issue or pull request number, or a full GitHub URL
+- `repository` optional: `owner/repo` or `https://github.com/owner/repo`, required for number-only references when the issue project is not mapped to that repository
+- `issueNumber`, `pullRequestNumber`, or `pullRequestUrl` optional alternatives to `reference`
+
+Example:
+
+```bash
+payload='{"paperclipIssueId":"iss_123","pullRequestUrl":"https://github.com/third-party/external/pull/77"}'
+
+curl -X POST "${PAPERCLIP_API_URL%/}/api/plugins/paperclip-github-plugin/api/issue-link" \
+  -H "content-type: application/json" \
+  -H "authorization: Bearer ${PAPERCLIP_API_KEY}" \
+  -d "${payload}"
+```
+
 ## Troubleshooting
 
 - If an older GitHub Sync build fails upgrade with `requires host version 2026.427.0 or newer, but this server is running 0.0.0`, upgrade to a build that removes the strict manifest host-version gate. The host is reporting a development-version sentinel, so the plugin now relies on declared capabilities and runtime fallbacks instead.
-- If setup is reported as incomplete, confirm that a GitHub token has been saved or that `${PAPERCLIP_HOME:-~/.paperclip}/plugins/github-sync/config.json` contains `githubToken`, and make sure at least one mapping has a created Paperclip project.
+- If setup is reported as incomplete, confirm that a GitHub token has been saved or that `${PAPERCLIP_HOME:-~/.paperclip}/plugins/github-sync/config.json` contains `githubToken`, and make sure at least one mapping has a created Paperclip project or at least one Paperclip issue has been linked to GitHub.
 - If Paperclip says board access is required, open plugin settings inside the affected company and complete the Paperclip board access flow before retrying sync.
 - If GitHub Sync agent tools fail with `403 {"error":"Board access required"}` on `/api/plugins/tools` or `/api/plugins/tools/execute`, the current Paperclip host rejected the request before the plugin worker ran. Re-run from a board-authenticated session or agent run that has board access to the target company.
 - If a KPI API route call is rejected, make sure the request includes `Authorization: Bearer ${PAPERCLIP_API_KEY}`, that the token is still valid for the current run, and that any `companyId` in the payload matches the calling agent's company.

package/dist/manifest.js

@@ -522,6 +522,55 @@ var GITHUB_AGENT_TOOLS = [
         projectNumber: projectNumberProperty
       }
     }
+  },
+  {
+    name: "link_github_item",
+    displayName: "Link GitHub Item",
+    description: "Link a Paperclip issue to a GitHub issue or pull request so GitHub Sync can monitor status even when the repository is not mapped to a Paperclip project.",
+    parametersSchema: {
+      type: "object",
+      additionalProperties: false,
+      required: ["kind", "paperclipIssueId"],
+      anyOf: [
+        {
+          required: ["reference"]
+        },
+        {
+          required: ["issueNumber"]
+        },
+        {
+          required: ["pullRequestNumber"]
+        },
+        {
+          required: ["pullRequestUrl"]
+        }
+      ],
+      properties: {
+        kind: {
+          type: "string",
+          enum: ["issue", "pull_request"],
+          description: "Whether to link a GitHub issue or pull request."
+        },
+        paperclipIssueId: {
+          type: "string",
+          description: "Paperclip issue id that should receive the GitHub link."
+        },
+        repository: {
+          type: "string",
+          description: "GitHub repository as owner/repo or https://github.com/owner/repo. Required when using a number instead of a full GitHub URL and the Paperclip issue project is not mapped to that repository."
+        },
+        reference: {
+          type: "string",
+          description: "GitHub issue or pull request number, or a full GitHub issue or pull request URL."
+        },
+        issueNumber: issueNumberProperty,
+        pullRequestNumber: pullRequestNumberProperty,
+        pullRequestUrl: {
+          type: "string",
+          description: "Full GitHub pull request URL."
+        }
+      }
+    }
   }
 ];
 
@@ -530,12 +579,15 @@ var GITHUB_SYNC_PLUGIN_ID = "paperclip-github-plugin";
 var COMPANY_METRIC_API_ROUTE_KEY = "record-company-metric-event";
 var COMPANY_METRIC_API_ROUTE_PATH = "/company-metrics/events";
 var COMPANY_METRIC_API_ROUTE_URL_PATH = `/api/plugins/${GITHUB_SYNC_PLUGIN_ID}/api${COMPANY_METRIC_API_ROUTE_PATH}`;
+var ISSUE_LINK_API_ROUTE_KEY = "link-github-item";
+var ISSUE_LINK_API_ROUTE_PATH = "/issue-link";
+var ISSUE_LINK_API_ROUTE_URL_PATH = `/api/plugins/${GITHUB_SYNC_PLUGIN_ID}/api${ISSUE_LINK_API_ROUTE_PATH}`;
 
 // src/manifest.ts
 var require2 = createRequire(import.meta.url);
 var packageJson = require2("../package.json");
 var SCHEDULE_TICK_CRON = "* * * * *";
-var MANIFEST_VERSION = "0.8.7"?.trim() || typeof packageJson.version === "string" && packageJson.version.trim() || process.env.npm_package_version?.trim() || "0.0.0-dev";
+var MANIFEST_VERSION = "0.8.8"?.trim() || typeof packageJson.version === "string" && packageJson.version.trim() || process.env.npm_package_version?.trim() || "0.0.0-dev";
 var manifest = {
   id: GITHUB_SYNC_PLUGIN_ID,
   apiVersion: 1,
@@ -607,6 +659,13 @@ var manifest = {
       path: COMPANY_METRIC_API_ROUTE_PATH,
       auth: "agent",
       capability: "api.routes.register"
+    },
+    {
+      routeKey: ISSUE_LINK_API_ROUTE_KEY,
+      method: "POST",
+      path: ISSUE_LINK_API_ROUTE_PATH,
+      auth: "agent",
+      capability: "api.routes.register"
     }
   ],
   tools: GITHUB_AGENT_TOOLS,

package/dist/worker.js

@@ -531,6 +531,55 @@ var GITHUB_AGENT_TOOLS = [
         projectNumber: projectNumberProperty
       }
     }
+  },
+  {
+    name: "link_github_item",
+    displayName: "Link GitHub Item",
+    description: "Link a Paperclip issue to a GitHub issue or pull request so GitHub Sync can monitor status even when the repository is not mapped to a Paperclip project.",
+    parametersSchema: {
+      type: "object",
+      additionalProperties: false,
+      required: ["kind", "paperclipIssueId"],
+      anyOf: [
+        {
+          required: ["reference"]
+        },
+        {
+          required: ["issueNumber"]
+        },
+        {
+          required: ["pullRequestNumber"]
+        },
+        {
+          required: ["pullRequestUrl"]
+        }
+      ],
+      properties: {
+        kind: {
+          type: "string",
+          enum: ["issue", "pull_request"],
+          description: "Whether to link a GitHub issue or pull request."
+        },
+        paperclipIssueId: {
+          type: "string",
+          description: "Paperclip issue id that should receive the GitHub link."
+        },
+        repository: {
+          type: "string",
+          description: "GitHub repository as owner/repo or https://github.com/owner/repo. Required when using a number instead of a full GitHub URL and the Paperclip issue project is not mapped to that repository."
+        },
+        reference: {
+          type: "string",
+          description: "GitHub issue or pull request number, or a full GitHub issue or pull request URL."
+        },
+        issueNumber: issueNumberProperty,
+        pullRequestNumber: pullRequestNumberProperty,
+        pullRequestUrl: {
+          type: "string",
+          description: "Full GitHub pull request URL."
+        }
+      }
+    }
   }
 ];
 function getGitHubAgentToolDeclaration(name) {
@@ -585,6 +634,9 @@ var GITHUB_SYNC_PLUGIN_ID = "paperclip-github-plugin";
 var COMPANY_METRIC_API_ROUTE_KEY = "record-company-metric-event";
 var COMPANY_METRIC_API_ROUTE_PATH = "/company-metrics/events";
 var COMPANY_METRIC_API_ROUTE_URL_PATH = `/api/plugins/${GITHUB_SYNC_PLUGIN_ID}/api${COMPANY_METRIC_API_ROUTE_PATH}`;
+var ISSUE_LINK_API_ROUTE_KEY = "link-github-item";
+var ISSUE_LINK_API_ROUTE_PATH = "/issue-link";
+var ISSUE_LINK_API_ROUTE_URL_PATH = `/api/plugins/${GITHUB_SYNC_PLUGIN_ID}/api${ISSUE_LINK_API_ROUTE_PATH}`;
 
 // src/paperclip-health.ts
 function normalizeOptionalString(value) {
@@ -636,6 +688,10 @@ var COMPANY_KPI_SCOPE = {
   scopeKind: "instance",
   stateKey: "paperclip-github-plugin-company-kpis"
 };
+var EXTERNAL_LINK_COMPANY_INDEX_SCOPE = {
+  scopeKind: "instance",
+  stateKey: "paperclip-github-plugin-external-link-companies"
+};
 var DEFAULT_SCHEDULE_FREQUENCY_MINUTES = 15;
 var DEFAULT_IMPORTED_ISSUE_STATUS = "backlog";
 var DEFAULT_IGNORED_GITHUB_ISSUE_USERNAMES = ["renovate"];
@@ -2544,19 +2600,6 @@ async function resolveManualSyncTarget(ctx, settings, input) {
       if (!pullRequestLink) {
         throw new Error("This Paperclip issue is not linked to a GitHub issue or pull request yet. Run a broader sync first.");
       }
-      const candidateMappings = getSyncableMappingsForTarget(settings.mappings, {
-        kind: "issue",
-        companyId: companyId2,
-        projectId: pullRequestLink.data.paperclipProjectId,
-        repositoryUrl: pullRequestLink.data.repositoryUrl,
-        issueId: input.issueId,
-        githubPullRequestNumber: pullRequestLink.data.githubPullRequestNumber,
-        githubPullRequestUrl: pullRequestLink.data.githubPullRequestUrl,
-        displayLabel: `pull request #${pullRequestLink.data.githubPullRequestNumber}`
-      });
-      if (candidateMappings.length === 0) {
-        throw new Error("No saved GitHub repository mapping matches this Paperclip issue.");
-      }
       return {
         kind: "issue",
         companyId: companyId2,
@@ -4481,6 +4524,58 @@ function normalizeImportRegistry(value) {
     };
   }).filter((entry) => entry !== null);
 }
+function normalizeExternalGitHubLinkCompanyIndex(value) {
+  const rawCompanyIds = Array.isArray(value) ? value : value && typeof value === "object" && Array.isArray(value.companyIds) ? value.companyIds : [];
+  const companyIds = [
+    ...new Set(
+      rawCompanyIds.map((entry) => normalizeCompanyId(entry)).filter((companyId) => Boolean(companyId))
+    )
+  ].sort();
+  const updatedAt = value && typeof value === "object" && typeof value.updatedAt === "string" ? value.updatedAt.trim() : void 0;
+  return {
+    companyIds,
+    ...updatedAt ? { updatedAt } : {}
+  };
+}
+async function getExternalGitHubLinkCompanyIds(ctx) {
+  return normalizeExternalGitHubLinkCompanyIndex(await ctx.state.get(EXTERNAL_LINK_COMPANY_INDEX_SCOPE)).companyIds;
+}
+async function rememberExternalGitHubLinkCompany(ctx, companyId) {
+  const normalizedCompanyId = normalizeCompanyId(companyId);
+  if (!normalizedCompanyId) {
+    return;
+  }
+  const index = normalizeExternalGitHubLinkCompanyIndex(await ctx.state.get(EXTERNAL_LINK_COMPANY_INDEX_SCOPE));
+  if (index.companyIds.includes(normalizedCompanyId)) {
+    return;
+  }
+  await ctx.state.set(EXTERNAL_LINK_COMPANY_INDEX_SCOPE, {
+    companyIds: [...index.companyIds, normalizedCompanyId].sort(),
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  });
+}
+async function forgetExternalGitHubLinkCompanyIfEmpty(ctx, companyId) {
+  const normalizedCompanyId = normalizeCompanyId(companyId);
+  if (!normalizedCompanyId) {
+    return;
+  }
+  const [issueLinks, pullRequestLinks] = await Promise.all([
+    listGitHubIssueLinkRecords(ctx),
+    listGitHubPullRequestLinkRecords(ctx)
+  ]);
+  const hasRemainingLinks = issueLinks.some((record) => record.data.companyId === normalizedCompanyId) || pullRequestLinks.some((record) => record.data.companyId === normalizedCompanyId);
+  if (hasRemainingLinks) {
+    return;
+  }
+  const index = normalizeExternalGitHubLinkCompanyIndex(await ctx.state.get(EXTERNAL_LINK_COMPANY_INDEX_SCOPE));
+  if (!index.companyIds.includes(normalizedCompanyId)) {
+    return;
+  }
+  await ctx.state.set(EXTERNAL_LINK_COMPANY_INDEX_SCOPE, {
+    companyIds: index.companyIds.filter((entry) => entry !== normalizedCompanyId),
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  });
+}
 function requireRepositoryReference(repositoryInput) {
   const parsed = parseRepositoryReference(repositoryInput);
   if (!parsed) {
@@ -6967,6 +7062,126 @@ async function listGitHubPullRequestIssueLinksForMapping(ctx, mapping, target) {
   }
   return [...recordsByKey.values()];
 }
+function doesGitHubIssueLinkRecordMatchMapping(record, mapping) {
+  if (record.data.repositoryUrl !== getNormalizedMappingRepositoryUrl(mapping)) {
+    return false;
+  }
+  if (record.data.companyId && record.data.companyId !== mapping.companyId) {
+    return false;
+  }
+  if (record.data.paperclipProjectId && record.data.paperclipProjectId !== mapping.paperclipProjectId) {
+    return false;
+  }
+  return Boolean(mapping.companyId && mapping.paperclipProjectId);
+}
+function doesGitHubIssueLinkRecordMatchTarget(record, target) {
+  if (!target) {
+    return true;
+  }
+  switch (target.kind) {
+    case "company":
+      return !record.data.companyId || record.data.companyId === target.companyId;
+    case "project":
+      return (!record.data.companyId || record.data.companyId === target.companyId) && (!record.data.paperclipProjectId || record.data.paperclipProjectId === target.projectId);
+    case "issue":
+      return Boolean(target.issueId && record.paperclipIssueId === target.issueId) && (!record.data.companyId || record.data.companyId === target.companyId);
+    default:
+      return true;
+  }
+}
+function isGitHubIssueLinkCoveredByMappings(record, mappings) {
+  return mappings.some((mapping) => doesGitHubIssueLinkRecordMatchMapping(record, mapping));
+}
+function isGitHubPullRequestLinkCoveredByMappings(record, mappings) {
+  return mappings.some((mapping) => doesGitHubPullRequestLinkRecordMatchMapping(record, mapping));
+}
+async function listExternalGitHubLinkSyncWork(ctx, mappings, target) {
+  const syncableMappings = getSyncableMappingsForTarget(mappings, target);
+  const issueLinksByKey = /* @__PURE__ */ new Map();
+  const pullRequestLinksByKey = /* @__PURE__ */ new Map();
+  const [issueLinks, pullRequestLinks] = await Promise.all([
+    listGitHubIssueLinkRecords(ctx, {
+      ...target?.kind === "issue" && target.issueId ? { paperclipIssueId: target.issueId } : {}
+    }),
+    listGitHubPullRequestLinkRecords(ctx, {
+      ...target?.kind === "issue" && target.issueId ? { paperclipIssueId: target.issueId } : {}
+    })
+  ]);
+  for (const record of issueLinks) {
+    if (!doesGitHubIssueLinkRecordMatchTarget(record, target) || isGitHubIssueLinkCoveredByMappings(record, syncableMappings)) {
+      continue;
+    }
+    issueLinksByKey.set(
+      `${record.paperclipIssueId}:${record.data.githubIssueUrl}`,
+      record
+    );
+  }
+  for (const record of pullRequestLinks) {
+    if (!doesGitHubPullRequestLinkRecordMatchTarget(record, target) || isGitHubPullRequestLinkCoveredByMappings(record, syncableMappings)) {
+      continue;
+    }
+    pullRequestLinksByKey.set(
+      `${record.paperclipIssueId}:${buildGitHubPullRequestReferenceKey({
+        number: record.data.githubPullRequestNumber,
+        repositoryUrl: record.data.repositoryUrl
+      })}`,
+      record
+    );
+  }
+  return {
+    issueLinks: [...issueLinksByKey.values()],
+    pullRequestLinks: [...pullRequestLinksByKey.values()]
+  };
+}
+function buildExternalLinkAuthMappings(work) {
+  const mappingsByKey = /* @__PURE__ */ new Map();
+  const addMapping = (params) => {
+    const companyId = normalizeCompanyId(params.companyId);
+    if (!companyId) {
+      return;
+    }
+    const repositoryUrl = getNormalizedMappingRepositoryUrl({
+      repositoryUrl: params.repositoryUrl
+    });
+    const key = `${companyId}:${params.projectId ?? ""}:${repositoryUrl}`;
+    mappingsByKey.set(key, {
+      id: `external-link:${key}`,
+      repositoryUrl,
+      paperclipProjectName: "",
+      ...params.projectId ? { paperclipProjectId: params.projectId } : {},
+      companyId
+    });
+  };
+  for (const link of work.issueLinks) {
+    addMapping({
+      companyId: link.data.companyId,
+      projectId: link.data.paperclipProjectId,
+      repositoryUrl: link.data.repositoryUrl
+    });
+  }
+  for (const link of work.pullRequestLinks) {
+    addMapping({
+      companyId: link.data.companyId,
+      projectId: link.data.paperclipProjectId,
+      repositoryUrl: link.data.repositoryUrl
+    });
+  }
+  return [...mappingsByKey.values()];
+}
+function countExternalLinkRepositories(work) {
+  const repositories = /* @__PURE__ */ new Set();
+  for (const link of work.issueLinks) {
+    if (link.data.companyId) {
+      repositories.add(`${link.data.companyId}:${link.data.repositoryUrl}`);
+    }
+  }
+  for (const link of work.pullRequestLinks) {
+    if (link.data.companyId) {
+      repositories.add(`${link.data.companyId}:${link.data.repositoryUrl}`);
+    }
+  }
+  return repositories.size;
+}
 async function findStoredStatusTransitionCommentAnnotation(ctx, params) {
   const issueId = params.issueId.trim();
   const commentId = params.commentId.trim();
@@ -7052,7 +7267,7 @@ async function upsertGitHubPullRequestLinkRecord(ctx, params) {
     status: params.pullRequestState,
     data: {
       companyId: params.companyId,
-      paperclipProjectId: params.projectId,
+      ...params.projectId ? { paperclipProjectId: params.projectId } : {},
       repositoryUrl: getNormalizedMappingRepositoryUrl({
         repositoryUrl: params.repositoryUrl
       }),
@@ -7091,6 +7306,56 @@ async function assertPaperclipIssueHasNoManualGitHubLink(ctx, params) {
     throw new Error("This Paperclip issue is already linked to a GitHub pull request.");
   }
 }
+async function resolveIssueGitHubLinkScope(ctx, params) {
+  if (!params.allowUnmapped) {
+    const mappedScope = await resolveIssueGitHubLinkMapping(ctx, params);
+    return {
+      issue: mappedScope.issue,
+      projectId: mappedScope.projectId,
+      mapping: mappedScope.mapping,
+      repository: mappedScope.repository
+    };
+  }
+  const issue = await ctx.issues.get(params.issueId, params.companyId);
+  if (!issue) {
+    throw new Error("Paperclip issue was not found.");
+  }
+  const projectId = typeof issue.projectId === "string" && issue.projectId.trim() ? issue.projectId.trim() : void 0;
+  const settings = normalizeSettings(await ctx.state.get(SETTINGS_SCOPE));
+  const requestedRepository = params.repositoryUrl ? parseRepositoryReference(params.repositoryUrl) : null;
+  if (params.repositoryUrl && !requestedRepository) {
+    throw new Error(`Invalid GitHub repository: ${params.repositoryUrl}. Use owner/repo or https://github.com/owner/repo.`);
+  }
+  const candidateMappings = projectId ? await resolveProjectScopedMappings(ctx, settings.mappings, {
+    companyId: params.companyId,
+    projectId
+  }) : [];
+  const matchingMappings = requestedRepository ? candidateMappings.filter(
+    (mapping) => areRepositoriesEqual(requireRepositoryReference(mapping.repositoryUrl), requestedRepository)
+  ) : candidateMappings;
+  if (matchingMappings.length === 1) {
+    const mapping = matchingMappings[0];
+    return {
+      issue,
+      projectId,
+      mapping,
+      repository: requestedRepository ?? requireRepositoryReference(mapping.repositoryUrl)
+    };
+  }
+  if (matchingMappings.length > 1 && !requestedRepository) {
+    throw new Error("This Paperclip issue project has multiple GitHub repositories. Enter the full GitHub URL.");
+  }
+  if (!requestedRepository) {
+    throw new Error(
+      "Enter a full GitHub URL or repository because this Paperclip issue project is not mapped to that repository."
+    );
+  }
+  return {
+    issue,
+    ...projectId ? { projectId } : {},
+    repository: requestedRepository
+  };
+}
 async function resolveIssueGitHubLinkMapping(ctx, params) {
   const issue = await ctx.issues.get(params.issueId, params.companyId);
   if (!issue) {
@@ -7213,10 +7478,11 @@ async function linkPaperclipIssueToGitHubIssue(ctx, params) {
     repositoryUrl: params.repositoryUrl,
     issueNumber: params.issueNumber
   });
-  const scope = await resolveIssueGitHubLinkMapping(ctx, {
+  const scope = await resolveIssueGitHubLinkScope(ctx, {
     companyId,
     issueId,
-    repositoryUrl: reference.repositoryUrl
+    repositoryUrl: reference.repositoryUrl,
+    allowUnmapped: params.allowUnmapped
   });
   const octokit = await createGitHubToolOctokit(ctx, companyId);
   const response = await octokit.rest.issues.get({
@@ -7233,18 +7499,29 @@ async function linkPaperclipIssueToGitHubIssue(ctx, params) {
   }
   const githubIssue = normalizeGitHubIssueRecord(rawIssue);
   const linkedPullRequests = await listLinkedPullRequestsForIssue(octokit, scope.repository, githubIssue.number);
-  await upsertGitHubIssueLinkRecord(ctx, scope.mapping, issueId, githubIssue, linkedPullRequests);
-  const importRegistry = normalizeImportRegistry(await ctx.state.get(IMPORT_REGISTRY_SCOPE));
-  upsertImportedIssueRecord(
-    importRegistry,
-    buildImportedIssueRecord(scope.mapping, githubIssue, issueId, (/* @__PURE__ */ new Date()).toISOString())
-  );
-  await ctx.state.set(IMPORT_REGISTRY_SCOPE, importRegistry);
-  invalidateProjectPullRequestCaches({
+  const linkTarget = {
     companyId,
-    projectId: scope.mapping.paperclipProjectId ?? scope.projectId,
-    repository: scope.repository
-  });
+    ...scope.mapping?.paperclipProjectId ?? scope.projectId ? { paperclipProjectId: scope.mapping?.paperclipProjectId ?? scope.projectId } : {},
+    repositoryUrl: scope.repository.url
+  };
+  await upsertGitHubIssueLinkRecord(ctx, linkTarget, issueId, githubIssue, linkedPullRequests);
+  await rememberExternalGitHubLinkCompany(ctx, companyId);
+  if (scope.mapping) {
+    const importRegistry = normalizeImportRegistry(await ctx.state.get(IMPORT_REGISTRY_SCOPE));
+    upsertImportedIssueRecord(
+      importRegistry,
+      buildImportedIssueRecord(scope.mapping, githubIssue, issueId, (/* @__PURE__ */ new Date()).toISOString())
+    );
+    await ctx.state.set(IMPORT_REGISTRY_SCOPE, importRegistry);
+  }
+  const projectIdForCacheInvalidation = scope.mapping?.paperclipProjectId ?? scope.projectId;
+  if (projectIdForCacheInvalidation) {
+    invalidateProjectPullRequestCaches({
+      companyId,
+      projectId: projectIdForCacheInvalidation,
+      repository: scope.repository
+    });
+  }
   return {
     kind: "issue",
     paperclipIssueId: issueId,
@@ -7272,10 +7549,11 @@ async function linkPaperclipIssueToGitHubPullRequest(ctx, params) {
     pullRequestNumber: params.pullRequestNumber,
     pullRequestUrl: params.pullRequestUrl
   });
-  const scope = await resolveIssueGitHubLinkMapping(ctx, {
+  const scope = await resolveIssueGitHubLinkScope(ctx, {
     companyId,
     issueId,
-    repositoryUrl: reference.repositoryUrl
+    repositoryUrl: reference.repositoryUrl,
+    allowUnmapped: params.allowUnmapped
   });
   const octokit = await createGitHubToolOctokit(ctx, companyId);
   const response = await octokit.rest.pulls.get({
@@ -7293,7 +7571,7 @@ async function linkPaperclipIssueToGitHubPullRequest(ctx, params) {
   });
   await upsertGitHubPullRequestLinkRecord(ctx, {
     companyId,
-    projectId: scope.mapping.paperclipProjectId ?? scope.projectId,
+    projectId: scope.mapping?.paperclipProjectId ?? scope.projectId,
     issueId,
     repositoryUrl: scope.repository.url,
     pullRequestNumber: reference.pullRequestNumber,
@@ -7301,11 +7579,15 @@ async function linkPaperclipIssueToGitHubPullRequest(ctx, params) {
     pullRequestTitle: response.data.title || `Pull request #${reference.pullRequestNumber}`,
     pullRequestState
   });
-  invalidateProjectPullRequestCaches({
-    companyId,
-    projectId: scope.mapping.paperclipProjectId ?? scope.projectId,
-    repository: scope.repository
-  });
+  await rememberExternalGitHubLinkCompany(ctx, companyId);
+  const projectIdForCacheInvalidation = scope.mapping?.paperclipProjectId ?? scope.projectId;
+  if (projectIdForCacheInvalidation) {
+    invalidateProjectPullRequestCaches({
+      companyId,
+      projectId: projectIdForCacheInvalidation,
+      repository: scope.repository
+    });
+  }
   return {
     kind: "pull_request",
     paperclipIssueId: issueId,
@@ -7433,6 +7715,7 @@ async function unlinkPaperclipIssueFromGitHub(ctx, params) {
   if (Object.keys(issuePatch).length > 0) {
     await ctx.issues.update(issueId, issuePatch, companyId);
   }
+  await forgetExternalGitHubLinkCompanyIfEmpty(ctx, companyId);
   return {
     paperclipIssueId: issueId,
     unlinked: issueLinkRecords.length > 0 || pullRequestLinkRecords.length > 0 || removedImportRegistryEntries.length > 0 || shouldClearGitHubOrigin || nextDescription !== void 0,
@@ -9329,7 +9612,7 @@ async function synchronizePaperclipIssueStatuses(ctx, octokit, repository, mappi
   };
 }
 async function synchronizePaperclipPullRequestIssueStatuses(ctx, octokit, mapping, advancedSettings, pullRequestLinks, paperclipApiBaseUrl, pullRequestStatusCache, syncFailureContext, failures, assertNotCancelled, onProgress) {
-  if (!mapping.companyId || !mapping.paperclipProjectId || !ctx.issues || typeof ctx.issues.get !== "function" || typeof ctx.issues.update !== "function") {
+  if (!mapping.companyId || !ctx.issues || typeof ctx.issues.get !== "function" || typeof ctx.issues.update !== "function") {
     return {
       updatedStatusesCount: 0
     };
@@ -9778,14 +10061,6 @@ function parseCompanyMetricApiRouteBody(input) {
   return input.body;
 }
 async function handleCompanyMetricApiRoute(ctx, input) {
-  if (input.routeKey !== COMPANY_METRIC_API_ROUTE_KEY) {
-    return {
-      status: 404,
-      body: {
-        error: `Unsupported plugin API route: ${input.routeKey}.`
-      }
-    };
-  }
   if (input.actor.actorType !== "agent") {
     throw new Error("Company KPI metric events must be recorded by an authenticated Paperclip agent.");
   }
@@ -9885,6 +10160,83 @@ async function handleCompanyMetricApiRoute(ctx, input) {
     }
   };
 }
+function parseIssueLinkApiRouteBody(input) {
+  if (!input.body || typeof input.body !== "object" || Array.isArray(input.body)) {
+    throw new Error("Issue link route body must be a JSON object.");
+  }
+  return input.body;
+}
+function normalizeIssueLinkApiRouteKind(payload) {
+  const explicitKind = normalizeIssueGitHubLinkKind(payload.kind);
+  if (explicitKind) {
+    return explicitKind;
+  }
+  const reference = normalizeOptionalString2(payload.reference);
+  if (normalizeGitHubPullRequestHtmlUrl(normalizeOptionalString2(payload.pullRequestUrl)) || normalizeToolPositiveInteger(payload.pullRequestNumber) || reference && parseGitHubPullRequestHtmlUrl(reference)) {
+    return "pull_request";
+  }
+  if (normalizeToolPositiveInteger(payload.issueNumber) || reference && parseGitHubIssueHtmlUrl(reference)) {
+    return "issue";
+  }
+  return null;
+}
+async function handleIssueLinkApiRoute(ctx, input) {
+  if (input.actor.actorType !== "agent") {
+    throw new Error("GitHub issue links must be recorded by an authenticated Paperclip agent.");
+  }
+  const companyId = normalizeCompanyId(input.companyId);
+  if (!companyId) {
+    throw new Error("GitHub issue links require the host to provide the authenticated agent company.");
+  }
+  const payload = parseIssueLinkApiRouteBody(input);
+  const requestedCompanyId = normalizeCompanyId(payload.companyId);
+  if (requestedCompanyId && requestedCompanyId !== companyId) {
+    throw new Error("companyId must match the authenticated Paperclip agent company.");
+  }
+  const kind = normalizeIssueLinkApiRouteKind(payload);
+  if (!kind) {
+    throw new Error('kind must be "issue" or "pull_request", or the payload must include a full GitHub URL.');
+  }
+  const paperclipIssueId = normalizeOptionalString2(payload.paperclipIssueId) ?? normalizeOptionalString2(payload.issueId);
+  if (!paperclipIssueId) {
+    throw new Error("paperclipIssueId is required.");
+  }
+  const linkResult = kind === "issue" ? await linkPaperclipIssueToGitHubIssue(ctx, {
+    companyId,
+    issueId: paperclipIssueId,
+    reference: payload.reference,
+    repositoryUrl: normalizeOptionalString2(payload.repository),
+    issueNumber: payload.issueNumber,
+    allowUnmapped: true
+  }) : await linkPaperclipIssueToGitHubPullRequest(ctx, {
+    companyId,
+    issueId: paperclipIssueId,
+    reference: payload.reference,
+    repositoryUrl: normalizeOptionalString2(payload.repository),
+    pullRequestNumber: payload.pullRequestNumber,
+    pullRequestUrl: payload.pullRequestUrl,
+    allowUnmapped: true
+  });
+  ctx.logger.info("GitHub Sync recorded a GitHub issue link API route event.", {
+    routeKey: input.routeKey,
+    companyId,
+    kind,
+    paperclipIssueId,
+    repositoryUrl: normalizeOptionalString2(linkResult.repositoryUrl),
+    githubIssueNumber: normalizeToolPositiveInteger(linkResult.githubIssueNumber),
+    githubPullRequestNumber: normalizeToolPositiveInteger(linkResult.githubPullRequestNumber),
+    agentId: input.actor.agentId ?? null,
+    runId: input.actor.runId ?? null
+  });
+  return {
+    status: 201,
+    body: {
+      status: "linked",
+      companyId,
+      ...linkResult
+    }
+  };
+}
 async function createGitHubToolOctokit(ctx, companyId, context = {}) {
   const token = (await resolveGithubToken(ctx, { companyId })).trim();
   if (!token) {
@@ -12836,10 +13188,14 @@ function shouldRunScheduledSync(settings, scheduledAt) {
   }
   return now - lastCheckedAt >= settings.scheduleFrequencyMinutes * 6e4;
 }
-function listScheduledSyncTargets(settings) {
+async function listScheduledSyncTargets(ctx, settings) {
+  const externalLinkCompanyIds = await getExternalGitHubLinkCompanyIds(ctx);
   const companyIds = [
-    ...new Set(
-      settings.mappings.map((mapping) => normalizeCompanyId(mapping.companyId)).filter((companyId) => Boolean(companyId))
+    .../* @__PURE__ */ new Set(
+      [
+        ...settings.mappings.map((mapping) => normalizeCompanyId(mapping.companyId)).filter((companyId) => Boolean(companyId)),
+        ...externalLinkCompanyIds
+      ]
     )
   ];
   if (companyIds.length === 0) {
@@ -12858,6 +13214,9 @@ async function performSync(ctx, trigger, options = {}) {
   const token = typeof options.resolvedToken === "string" ? options.resolvedToken : await resolveGithubToken(ctx, { companyId: targetCompanyId });
   const paperclipApiBaseUrl = getConfiguredPaperclipApiBaseUrl(baseSettings, config, targetCompanyId);
   const mappings = getSyncableMappingsForTarget(settings.mappings, options.target);
+  const externalSyncWork = options.externalSyncWork ?? await listExternalGitHubLinkSyncWork(ctx, settings.mappings, options.target);
+  const externalLinkAuthMappings = buildExternalLinkAuthMappings(externalSyncWork);
+  const externalLinkCount = externalSyncWork.issueLinks.length + externalSyncWork.pullRequestLinks.length;
   activePaperclipApiAuthTokensByCompanyId = null;
   const failureContext = {
     phase: "configuration"
@@ -12869,14 +13228,18 @@ async function performSync(ctx, trigger, options = {}) {
     };
     return saveSettingsSyncState(ctx, settings, next.syncState, targetCompanyId);
   }
-  if (mappings.length === 0) {
+  if (mappings.length === 0 && externalLinkCount === 0) {
     const next = {
       ...settings,
       syncState: createSetupConfigurationErrorSyncState("missing_mapping", trigger)
     };
     return saveSettingsSyncState(ctx, settings, next.syncState, targetCompanyId);
   }
-  const mappingsMissingBoardAccess = getMappingsMissingPaperclipBoardAccess(settings, config, mappings);
+  const mappingsMissingBoardAccess = getMappingsMissingPaperclipBoardAccess(
+    settings,
+    config,
+    [...mappings, ...externalLinkAuthMappings]
+  );
   if (mappingsMissingBoardAccess.length > 0 && await detectPaperclipBoardAccessRequirement(paperclipApiBaseUrl)) {
     const next = {
       ...settings,
@@ -12884,7 +13247,7 @@ async function performSync(ctx, trigger, options = {}) {
     };
     return saveSettingsSyncState(ctx, settings, next.syncState, targetCompanyId);
   }
-  if (!ctx.issues || typeof ctx.issues.create !== "function") {
+  if (mappings.length > 0 && (!ctx.issues || typeof ctx.issues.create !== "function")) {
     const errorDetails = {
       phase: "configuration",
       suggestedAction: "Update Paperclip to a runtime that supports plugin issue creation, then retry sync."
@@ -12910,7 +13273,12 @@ async function performSync(ctx, trigger, options = {}) {
     };
     return saveSettingsSyncState(ctx, settings, next.syncState, targetCompanyId);
   }
-  activePaperclipApiAuthTokensByCompanyId = await resolvePaperclipApiAuthTokens(ctx, settings, config, mappings);
+  activePaperclipApiAuthTokensByCompanyId = await resolvePaperclipApiAuthTokens(
+    ctx,
+    settings,
+    config,
+    [...mappings, ...externalLinkAuthMappings]
+  );
   const octokitLogContext = {
     companyId: targetCompanyId,
     operation: "sync.github-issues",
@@ -13162,6 +13530,8 @@ async function performSync(ctx, trigger, options = {}) {
         continue;
       }
     }
+    totalTrackedIssueCount += externalLinkCount;
+    syncedIssuesCount = totalTrackedIssueCount;
     recordCompanyBacklogSnapshotsFromPlans(repositoryPlans);
     if (repositoryPlans.length > 0) {
       const firstPlan = repositoryPlans[0];
@@ -13174,6 +13544,14 @@ async function performSync(ctx, trigger, options = {}) {
         totalIssueCount: totalTrackedIssueCount,
         detailLabel: "Loading linked pull requests, review threads, and CI status before syncing."
       };
+    } else if (externalLinkCount > 0) {
+      currentProgress = {
+        phase: "preparing",
+        totalRepositoryCount: countExternalLinkRepositories(externalSyncWork),
+        completedIssueCount: completedTrackedIssueCount,
+        totalIssueCount: totalTrackedIssueCount,
+        detailLabel: "Loading linked GitHub issues and pull requests before syncing."
+      };
     } else {
       currentProgress = {
         phase: "preparing",
@@ -13438,6 +13816,194 @@ async function performSync(ctx, trigger, options = {}) {
         continue;
       }
     }
+    for (const [externalIssueIndex, issueLink] of externalSyncWork.issueLinks.entries()) {
+      await throwIfSyncCancelled();
+      try {
+        const companyId = normalizeCompanyId(issueLink.data.companyId);
+        if (!companyId) {
+          continue;
+        }
+        const repository = requireRepositoryReference(issueLink.data.repositoryUrl);
+        octokitLogContext.repositoryUrl = repository.url;
+        const advancedSettings = getCompanyAdvancedSettings(settings, companyId);
+        let availableLabels = companyLabelDirectoryCache.get(companyId);
+        if (!availableLabels) {
+          updateSyncFailureContext(failureContext, {
+            phase: "loading_paperclip_labels",
+            repositoryUrl: repository.url,
+            githubIssueNumber: issueLink.data.githubIssueNumber
+          });
+          availableLabels = supportsPaperclipLabelMapping ? await buildPaperclipLabelDirectory(ctx, companyId, paperclipApiBaseUrl) : /* @__PURE__ */ new Map();
+          companyLabelDirectoryCache.set(companyId, availableLabels);
+        }
+        currentProgress = {
+          phase: "syncing",
+          totalRepositoryCount: Math.max(mappings.length, countExternalLinkRepositories(externalSyncWork)),
+          currentRepositoryUrl: repository.url,
+          completedIssueCount: completedTrackedIssueCount,
+          totalIssueCount: totalTrackedIssueCount,
+          currentIssueNumber: issueLink.data.githubIssueNumber,
+          detailLabel: `Syncing linked GitHub issue #${issueLink.data.githubIssueNumber} in ${repository.owner}/${repository.repo}.`
+        };
+        await persistRunningProgress(true);
+        updateSyncFailureContext(failureContext, {
+          phase: "evaluating_github_status",
+          repositoryUrl: repository.url,
+          githubIssueNumber: issueLink.data.githubIssueNumber
+        });
+        const response = await octokit.rest.issues.get({
+          owner: repository.owner,
+          repo: repository.repo,
+          issue_number: issueLink.data.githubIssueNumber,
+          headers: {
+            "X-GitHub-Api-Version": GITHUB_API_VERSION
+          }
+        });
+        const githubIssue = normalizeGitHubIssueRecord(response.data);
+        if (response.data.pull_request) {
+          continue;
+        }
+        const virtualMapping = {
+          id: `external-link:${companyId}:${repository.url}`,
+          repositoryUrl: repository.url,
+          paperclipProjectName: "",
+          ...issueLink.data.paperclipProjectId ? { paperclipProjectId: issueLink.data.paperclipProjectId } : {},
+          companyId
+        };
+        const importedIssue = {
+          mappingId: virtualMapping.id,
+          githubIssueId: githubIssue.id,
+          githubIssueNumber: githubIssue.number,
+          paperclipIssueId: issueLink.paperclipIssueId,
+          importedAt: issueLink.createdAt ?? issueLink.data.syncedAt,
+          lastSeenCommentCount: issueLink.data.commentsCount,
+          lastSeenGitHubState: issueLink.data.githubIssueState,
+          linkedPullRequestCommentCounts: [],
+          repositoryUrl: repository.url,
+          ...issueLink.data.paperclipProjectId ? { paperclipProjectId: issueLink.data.paperclipProjectId } : {},
+          companyId
+        };
+        const synchronizationResult = await synchronizePaperclipIssueStatuses(
+          ctx,
+          octokit,
+          repository,
+          virtualMapping,
+          advancedSettings,
+          /* @__PURE__ */ new Map([[githubIssue.id, githubIssue]]),
+          [importedIssue],
+          /* @__PURE__ */ new Set(),
+          availableLabels,
+          paperclipApiBaseUrl,
+          /* @__PURE__ */ new Map(),
+          /* @__PURE__ */ new Map(),
+          /* @__PURE__ */ new Map(),
+          repositoryMaintainerCache,
+          failureContext,
+          recoverableFailures,
+          throwIfSyncCancelled,
+          async (params) => {
+            const recorded = recordCompanyActivityMetricEvent(companyKpiState, {
+              companyId: params.companyId,
+              metric: "githubIssuesClosedCount",
+              eventKey: `${params.repositoryUrl}/issues/${params.githubIssueNumber}:${coerceDate(params.occurredAt).toISOString()}`,
+              repositoryUrl: params.repositoryUrl,
+              occurredAt: params.occurredAt
+            });
+            companyKpiState = recorded.state;
+            companyKpiStateDirty = companyKpiStateDirty || recorded.recorded;
+          },
+          async (progress) => {
+            completedTrackedIssueCount += 1;
+            currentProgress = {
+              phase: "syncing",
+              totalRepositoryCount: Math.max(mappings.length, countExternalLinkRepositories(externalSyncWork)),
+              currentRepositoryUrl: repository.url,
+              completedIssueCount: completedTrackedIssueCount,
+              totalIssueCount: totalTrackedIssueCount,
+              ...progress.currentIssueNumber !== void 0 ? { currentIssueNumber: progress.currentIssueNumber } : {}
+            };
+            await persistRunningProgress(externalIssueIndex === externalSyncWork.issueLinks.length - 1);
+          }
+        );
+        updatedStatusesCount += synchronizationResult.updatedStatusesCount;
+        updatedLabelsCount += synchronizationResult.updatedLabelsCount;
+        updatedDescriptionsCount += synchronizationResult.updatedDescriptionsCount;
+      } catch (error) {
+        if (error instanceof SyncCancellationError || isGitHubRateLimitError(error)) {
+          throw error;
+        }
+        recordRecoverableSyncFailure(ctx, recoverableFailures, error, failureContext);
+        continue;
+      }
+    }
+    const externalPullRequestLinksByCompanyId = /* @__PURE__ */ new Map();
+    for (const pullRequestLink of externalSyncWork.pullRequestLinks) {
+      const companyId = normalizeCompanyId(pullRequestLink.data.companyId);
+      if (!companyId) {
+        continue;
+      }
+      const companyLinks = externalPullRequestLinksByCompanyId.get(companyId) ?? [];
+      companyLinks.push(pullRequestLink);
+      externalPullRequestLinksByCompanyId.set(companyId, companyLinks);
+    }
+    for (const [companyId, pullRequestLinks] of externalPullRequestLinksByCompanyId.entries()) {
+      await throwIfSyncCancelled();
+      try {
+        const firstRepositoryUrl = pullRequestLinks[0]?.data.repositoryUrl;
+        if (!firstRepositoryUrl) {
+          continue;
+        }
+        const repository = requireRepositoryReference(firstRepositoryUrl);
+        octokitLogContext.repositoryUrl = repository.url;
+        currentProgress = {
+          phase: "syncing",
+          totalRepositoryCount: Math.max(mappings.length, countExternalLinkRepositories(externalSyncWork)),
+          currentRepositoryUrl: repository.url,
+          completedIssueCount: completedTrackedIssueCount,
+          totalIssueCount: totalTrackedIssueCount,
+          detailLabel: `Syncing ${pullRequestLinks.length} linked GitHub pull request${pullRequestLinks.length === 1 ? "" : "s"}.`
+        };
+        await persistRunningProgress(true);
+        const pullRequestStatusCache = /* @__PURE__ */ new Map();
+        const synchronizationResult = await synchronizePaperclipPullRequestIssueStatuses(
+          ctx,
+          octokit,
+          {
+            id: `external-link:${companyId}:${repository.url}`,
+            repositoryUrl: repository.url,
+            paperclipProjectName: "",
+            companyId
+          },
+          getCompanyAdvancedSettings(settings, companyId),
+          pullRequestLinks,
+          paperclipApiBaseUrl,
+          pullRequestStatusCache,
+          failureContext,
+          recoverableFailures,
+          throwIfSyncCancelled,
+          async (progress) => {
+            completedTrackedIssueCount += 1;
+            const pullRequestRepository = requireRepositoryReference(progress.pullRequestLink.data.repositoryUrl);
+            currentProgress = {
+              phase: "syncing",
+              totalRepositoryCount: Math.max(mappings.length, countExternalLinkRepositories(externalSyncWork)),
+              currentRepositoryUrl: pullRequestRepository.url,
+              completedIssueCount: completedTrackedIssueCount,
+              totalIssueCount: totalTrackedIssueCount,
+              detailLabel: `Synced pull request #${progress.pullRequestLink.data.githubPullRequestNumber} in ${pullRequestRepository.owner}/${pullRequestRepository.repo}.`
+            };
+            await persistRunningProgress(progress.completedIssueCount === progress.totalIssueCount);
+          }
+        );
+        updatedStatusesCount += synchronizationResult.updatedStatusesCount;
+      } catch (error) {
+        if (error instanceof SyncCancellationError || isGitHubRateLimitError(error)) {
+          throw error;
+        }
+        recordRecoverableSyncFailure(ctx, recoverableFailures, error, failureContext);
+        continue;
+      }
+    }
     if (recoverableFailures.length > 0) {
       const primaryFailure = recoverableFailures[0];
       const errorDetails = buildSyncErrorDetails(primaryFailure.error, primaryFailure.context);
@@ -13566,10 +14132,12 @@ async function startSync(ctx, trigger, options = {}) {
   if (getActiveGitHubRateLimitPause(currentSettings.syncState)) {
     return currentSettings;
   }
-  if (trigger !== "manual" && getSyncableMappingsForTarget(currentSettings.mappings, options.target).length === 0) {
+  if (trigger !== "manual" && !token.trim()) {
     return currentSettings;
   }
-  if (trigger !== "manual" && !token.trim()) {
+  const externalSyncWork = await listExternalGitHubLinkSyncWork(ctx, currentSettings.mappings, options.target);
+  const externalLinkCount = externalSyncWork.issueLinks.length + externalSyncWork.pullRequestLinks.length;
+  if (trigger !== "manual" && getSyncableMappingsForTarget(currentSettings.mappings, options.target).length === 0 && externalLinkCount === 0) {
     return currentSettings;
   }
   await setSyncCancellationRequest(ctx, null);
@@ -13583,7 +14151,7 @@ async function startSync(ctx, trigger, options = {}) {
       message: getSyncTargetRunningMessage(options.target),
       progress: {
         phase: "preparing",
-        totalRepositoryCount: syncableMappings.length
+        totalRepositoryCount: syncableMappings.length + countExternalLinkRepositories(externalSyncWork)
       }
     });
     activeRunningSyncState = {
@@ -13598,7 +14166,8 @@ async function startSync(ctx, trigger, options = {}) {
       await runningStatePromise;
       return await performSync(ctx, trigger, {
         resolvedToken: token,
-        target: options.target
+        target: options.target,
+        externalSyncWork
       });
     } catch (error) {
       return await createUnexpectedSyncErrorResult(ctx, trigger, error, targetCompanyId);
@@ -14493,6 +15062,42 @@ function registerGitHubAgentTools(ctx) {
       );
     })
   );
+  ctx.tools.register(
+    "link_github_item",
+    getGitHubAgentToolDeclaration("link_github_item"),
+    async (params, runCtx) => executeGitHubTool(async () => {
+      const input = getToolInputRecord(params);
+      const kind = normalizeIssueGitHubLinkKind(input.kind);
+      if (!kind) {
+        throw new Error('kind must be "issue" or "pull_request".');
+      }
+      const paperclipIssueId = normalizeOptionalToolString(input.paperclipIssueId);
+      if (!paperclipIssueId) {
+        throw new Error("paperclipIssueId is required.");
+      }
+      const linkResult = kind === "issue" ? await linkPaperclipIssueToGitHubIssue(ctx, {
+        companyId: runCtx.companyId,
+        issueId: paperclipIssueId,
+        reference: input.reference,
+        repositoryUrl: normalizeOptionalToolString(input.repository),
+        issueNumber: input.issueNumber,
+        allowUnmapped: true
+      }) : await linkPaperclipIssueToGitHubPullRequest(ctx, {
+        companyId: runCtx.companyId,
+        issueId: paperclipIssueId,
+        reference: input.reference,
+        repositoryUrl: normalizeOptionalToolString(input.repository),
+        pullRequestNumber: input.pullRequestNumber,
+        pullRequestUrl: input.pullRequestUrl,
+        allowUnmapped: true
+      });
+      const itemLabel = kind === "issue" ? `issue #${normalizeToolPositiveInteger(linkResult.githubIssueNumber) ?? ""}`.trim() : `pull request #${normalizeToolPositiveInteger(linkResult.githubPullRequestNumber) ?? ""}`.trim();
+      return buildToolSuccessResult(
+        `Linked Paperclip issue ${paperclipIssueId} to GitHub ${itemLabel}.`,
+        linkResult
+      );
+    })
+  );
 }
 function shouldStartWorkerHost(moduleUrl, entry = process.argv[1]) {
   if (typeof entry !== "string" || !entry.trim()) {
@@ -14901,7 +15506,7 @@ var plugin = definePlugin({
     ctx.jobs.register("sync.github-issues", async (job) => {
       const settings = normalizeSettings(await ctx.state.get(SETTINGS_SCOPE));
       const trigger = job.trigger === "retry" ? "retry" : "schedule";
-      const scheduledTargets = listScheduledSyncTargets(settings);
+      const scheduledTargets = await listScheduledSyncTargets(ctx, settings);
       if (scheduledTargets.length === 0) {
         const reconciledSettings = await reconcileOrphanedRunningSyncState(ctx);
         if (job.trigger === "schedule" && !shouldRunScheduledSync(reconciledSettings, job.scheduledAt)) {
@@ -14923,7 +15528,18 @@ var plugin = definePlugin({
     if (!pluginRuntimeContext) {
       throw new Error("GitHub Sync worker is not ready to handle API routes yet.");
     }
-    return handleCompanyMetricApiRoute(pluginRuntimeContext, input);
+    if (input.routeKey === COMPANY_METRIC_API_ROUTE_KEY) {
+      return handleCompanyMetricApiRoute(pluginRuntimeContext, input);
+    }
+    if (input.routeKey === ISSUE_LINK_API_ROUTE_KEY) {
+      return handleIssueLinkApiRoute(pluginRuntimeContext, input);
+    }
+    return {
+      status: 404,
+      body: {
+        error: `Unsupported plugin API route: ${input.routeKey}.`
+      }
+    };
   },
   async onShutdown() {
     pluginRuntimeContext = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paperclip-github-plugin",
-  "version": "0.8.7",
+  "version": "0.8.8",
   "description": "Paperclip plugin for synchronizing GitHub issues into Paperclip projects.",
   "license": "Apache-2.0",
   "type": "module",