paperclip-github-plugin 0.8.7 → 0.8.9

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"];
@@ -726,15 +782,15 @@ var PaperclipLabelSyncError = class extends Error {
     const location = params.paperclipApiBaseUrl ? ` at ${params.paperclipApiBaseUrl}` : "";
     let message;
     if (failure?.requiresAuthentication) {
-      message = `Could not map ${labelSubject} because the worker reached an authenticated Paperclip API response${location} instead of JSON. Connect Paperclip board access in plugin settings, set \`PAPERCLIP_API_URL\` to a worker-accessible Paperclip API origin, or expose the local Paperclip API to the worker without browser-session auth.`;
+      message = `Could not map ${labelSubject} because the worker reached an authenticated Paperclip API response${location} instead of JSON. Connect Paperclip board access in plugin settings, set Worker Paperclip API URL to a worker-accessible Paperclip API origin, or expose the local Paperclip API to the worker without browser-session auth.`;
     } else if (failure?.status === 404 || failure?.status === 405) {
-      message = `Could not map ${labelSubject} because the Paperclip label API${location} is not available to the worker. Set \`PAPERCLIP_API_URL\` to a worker-accessible Paperclip API origin, then retry sync.`;
+      message = `Could not map ${labelSubject} because the Paperclip label API${location} is not available to the worker. Set Worker Paperclip API URL to a worker-accessible Paperclip API origin, then retry sync.`;
     } else if (failure?.errorMessage) {
       message = `Could not map ${labelSubject} because the Paperclip label API${location} failed: ${failure.errorMessage}`;
     } else if (params.paperclipApiBaseUrl) {
       message = `Could not map ${labelSubject} because the Paperclip label API at ${params.paperclipApiBaseUrl} is unavailable to the worker.`;
     } else {
-      message = `Could not map ${labelSubject} because no worker-accessible Paperclip label API is configured. Set \`PAPERCLIP_API_URL\` to a worker-accessible Paperclip API origin, then retry sync.`;
+      message = `Could not map ${labelSubject} because no worker-accessible Paperclip label API is configured. Set Worker Paperclip API URL to a worker-accessible Paperclip API origin, then retry sync.`;
     }
     super(message);
     this.status = failure?.status;
@@ -1458,6 +1514,39 @@ function getErrorMessage(error) {
   }
   return String(error);
 }
+function getErrorCause(error) {
+  if (!error || typeof error !== "object" || !("cause" in error)) {
+    return void 0;
+  }
+  return error.cause;
+}
+function getErrorCode(error) {
+  if (!error || typeof error !== "object" || !("code" in error)) {
+    return void 0;
+  }
+  const code = error.code;
+  return typeof code === "string" && code.trim() ? code.trim() : void 0;
+}
+function getErrorDiagnosticMessage(error) {
+  const primaryMessage = getErrorMessage(error).trim();
+  const cause = getErrorCause(error);
+  const causeMessage = cause ? getErrorMessage(cause).trim() : "";
+  const errorCode = getErrorCode(error);
+  const causeCode = cause ? getErrorCode(cause) : void 0;
+  const code = errorCode ?? causeCode;
+  const parts = [primaryMessage || String(error)];
+  if (causeMessage && causeMessage !== primaryMessage) {
+    parts.push(`cause: ${causeMessage}`);
+  }
+  if (code) {
+    parts.push(`code: ${code}`);
+  }
+  return parts.join(" | ");
+}
+function formatPaperclipApiFetchErrorMessage(error, url, init) {
+  const method = typeof init?.method === "string" && init.method.trim() ? init.method.trim().toUpperCase() : "GET";
+  return `Paperclip API fetch failed (${method} ${url}): ${getErrorDiagnosticMessage(error)}`;
+}
 function isPaperclipLabelSyncError(error) {
   return error instanceof PaperclipLabelSyncError;
 }
@@ -2079,12 +2168,12 @@ function getSyncFailureSuggestedAction(error, context) {
   }
   if (isPaperclipLabelSyncError(error)) {
     if (error.requiresAuthentication || error.status === 401 || error.status === 403) {
-      return "The worker could not reuse the board login session for the Paperclip label API. Connect Paperclip board access in settings, or set `PAPERCLIP_API_URL` to a worker-accessible Paperclip API origin, then retry sync.";
+      return "The worker could not reuse the board login session for the Paperclip label API. Connect Paperclip board access in settings, or set Worker Paperclip API URL to a worker-accessible Paperclip API origin, then retry sync.";
     }
     if (error.paperclipApiBaseUrl) {
       return `Confirm that the Paperclip label API at ${error.paperclipApiBaseUrl} is reachable from the plugin worker and returns JSON, then retry sync.`;
     }
-    return "Set `PAPERCLIP_API_URL` to a worker-accessible Paperclip API origin, then retry sync.";
+    return "Set Worker Paperclip API URL to a worker-accessible Paperclip API origin, then retry sync.";
   }
   const rawMessage = getErrorMessage(error).trim().toLowerCase();
   if (rawMessage.includes("could not resolve to a pullrequest")) {
@@ -2544,19 +2633,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,
@@ -3912,17 +3988,7 @@ function normalizePaperclipApiBaseUrlByCompanyId(value) {
   }).filter((entry) => entry !== null);
   return entries.length > 0 ? Object.fromEntries(entries) : void 0;
 }
-function getRuntimePaperclipApiBaseUrl() {
-  if (typeof process === "undefined" || !process?.env) {
-    return void 0;
-  }
-  return normalizePaperclipApiBaseUrl(process.env.PAPERCLIP_API_URL);
-}
 function resolvePaperclipApiBaseUrl(...values) {
-  const runtimePaperclipApiBaseUrl = getRuntimePaperclipApiBaseUrl();
-  if (runtimePaperclipApiBaseUrl) {
-    return runtimePaperclipApiBaseUrl;
-  }
   for (const value of values) {
     const normalizedValue = normalizePaperclipApiBaseUrl(value);
     if (normalizedValue) {
@@ -3940,10 +4006,6 @@ function getConfiguredPaperclipApiBaseUrl(settings, config, companyId) {
   ) : resolvePaperclipApiBaseUrl(config?.paperclipApiBaseUrl, settings?.paperclipApiBaseUrl);
 }
 function resolveTrustedPaperclipApiBaseUrlInput(value, settings, config, companyId) {
-  const runtimePaperclipApiBaseUrl = getRuntimePaperclipApiBaseUrl();
-  if (runtimePaperclipApiBaseUrl) {
-    return runtimePaperclipApiBaseUrl;
-  }
   const requestedPaperclipApiBaseUrl = normalizePaperclipApiBaseUrl(value);
   const configuredPaperclipApiBaseUrl = normalizePaperclipApiBaseUrl(config?.paperclipApiBaseUrl);
   const normalizedCompanyId = normalizeCompanyId(companyId);
@@ -4481,6 +4543,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) {
@@ -5542,9 +5656,6 @@ function resolvePaperclipIssueStatus(params) {
 }
 function resolvePaperclipPullRequestIssueStatus(params) {
   const { currentStatus, pullRequest, hasExecutorHandoffTarget } = params;
-  if (currentStatus === "done" || currentStatus === "cancelled") {
-    return currentStatus;
-  }
   if (shouldPreserveBlockedExternalPullRequestWait({
     currentStatus,
     linkedPullRequests: [pullRequest]
@@ -5553,7 +5664,7 @@ function resolvePaperclipPullRequestIssueStatus(params) {
   }
   return resolvePaperclipStatusFromLinkedPullRequests([pullRequest], {
     preferInProgress: hasExecutorHandoffTarget,
-    preserveTransientUnknownMergeabilityWait: currentStatus === "in_review"
+    preserveTransientUnknownMergeabilityWait: currentStatus === "done" || currentStatus === "in_review"
   });
 }
 async function listLinkedPullRequestsForIssue(octokit, repository, issueNumber) {
@@ -6967,6 +7078,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 +7283,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 +7322,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 +7494,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 +7515,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 +7565,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 +7587,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 +7595,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 +7731,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,
@@ -7545,7 +7844,14 @@ function applyPaperclipApiAuthentication(init, companyId) {
   };
 }
 async function fetchPaperclipApi(url, init, options) {
-  return fetch(url, applyPaperclipApiAuthentication(init, options?.companyId));
+  const authenticatedInit = applyPaperclipApiAuthentication(init, options?.companyId);
+  try {
+    return await fetch(url, authenticatedInit);
+  } catch (error) {
+    throw new Error(formatPaperclipApiFetchErrorMessage(error, url, authenticatedInit), {
+      cause: error
+    });
+  }
 }
 async function detectPaperclipBoardAccessRequirement(paperclipApiBaseUrl) {
   if (!paperclipApiBaseUrl) {
@@ -9329,7 +9635,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 +10084,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 +10183,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 +13211,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 +13237,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 +13251,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 +13270,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 +13296,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 +13553,8 @@ async function performSync(ctx, trigger, options = {}) {
         continue;
       }
     }
+    totalTrackedIssueCount += externalLinkCount;
+    syncedIssuesCount = totalTrackedIssueCount;
     recordCompanyBacklogSnapshotsFromPlans(repositoryPlans);
     if (repositoryPlans.length > 0) {
       const firstPlan = repositoryPlans[0];
@@ -13174,6 +13567,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 +13839,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 +14155,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 +14174,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 +14189,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 +15085,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()) {
@@ -14508,6 +15136,7 @@ function shouldStartWorkerHost(moduleUrl, entry = process.argv[1]) {
 var __testing = {
   buildSyncFallbackExecutionStatePatch,
   createGitHubToolOctokit,
+  formatPaperclipApiFetchErrorMessage,
   hasUnresolvedPaperclipIssueBlocker,
   isHealthyMaintainerWaitTransition,
   resolveSyncTransitionAssignee
@@ -14543,6 +15172,7 @@ var plugin = definePlugin({
         ...getPublicSettingsForScope(settingsForResponse, requestedCompanyId),
         ...includeAssignees ? { availableAssignees } : {},
         totalSyncedIssuesCount: countImportedIssuesForMappings(importRegistry, scopedMappings),
+        paperclipApiBaseUrlConfigured: Boolean(normalizePaperclipApiBaseUrl(config.paperclipApiBaseUrl)),
         githubTokenConfigured,
         paperclipBoardAccessConfigured: requestedCompanyId ? hasConfiguredPaperclipBoardAccess(settingsForResponse, config, requestedCompanyId) : hasConfiguredPaperclipBoardAccessForMappings(settingsForResponse, config, scopedMappings),
         ...savedBoardTokenRef ? { paperclipBoardAccessConfigSyncRef: savedBoardTokenRef } : {},
@@ -14901,7 +15531,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 +15553,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;