paperclip-github-plugin 0.9.6 → 0.9.8

package/README.md

@@ -94,6 +94,8 @@ If a Paperclip issue was created locally or by an agent workflow before GitHub S
 
 Manual GitHub issue links are added to the same import registry and issue-link entity used by normal sync, so future syncs update the Paperclip issue from the GitHub issue. Manual pull request links are added to the PR-link entity used by the project Pull Requests page, so future syncs monitor PR status even when there is no closing GitHub issue.
 
+When a Paperclip issue is linked to a GitHub issue and also has older direct pull request links, the GitHub issue remains the status source of truth. Direct pull request links only drive status for PR-only Paperclip issues, which prevents stale merged PR metadata from closing work while the GitHub issue and its current linked PR are still open.
+
 Operators can unlink a linked Paperclip issue from the GitHub detail surface when they intentionally want GitHub Sync to stop updating it. Agent-facing tools and native agent API routes can create durable issue and pull request links, but they do not expose an unlink operation; internal sync repair may still tombstone a link when GitHub transfers an issue to an unmapped repository.
 
 ### Agent workflows built in
@@ -184,6 +186,7 @@ Additional behavior:
 - Sync-driven handoffs to agent assignees best-effort enqueue an explicit wakeup so the next reviewer, approver, or executor can pick the issue up even when their agent is not running heartbeats.
 - Open imported issues that are already in `backlog` stay in `backlog` until someone changes them in Paperclip.
 - If an imported issue is `done` or `cancelled` and GitHub shows it open again with no linked pull request, sync moves it to `todo` so agents can pick it up again.
+- When an issue has an active Paperclip issue monitor, GitHub Sync lets that monitor own the wait. It still refreshes GitHub metadata, but it does not change the issue's Paperclip status, assignee, execution state, transition comments, or wakeups until the monitor is no longer active.
 - Trusted new GitHub comments from the original issue author or a verified maintainer/admin can move an open imported issue back into active work, whether the new comment lands on the source issue, in a linked pull request's top-level comment stream, or in a linked pull request review thread; GitHub Sync uses `in_progress` when it can route the issue to an executor and otherwise `todo`.
 - When the sync changes a Paperclip issue status, it adds a Paperclip comment explaining what changed and why.
 

package/dist/manifest.js

@@ -642,7 +642,7 @@ var PULL_REQUEST_ASSET_API_ROUTE_URL_PATH = `/api/plugins/${GITHUB_SYNC_PLUGIN_I
 var require2 = createRequire(import.meta.url);
 var packageJson = require2("../package.json");
 var SCHEDULE_TICK_CRON = "* * * * *";
-var MANIFEST_VERSION = "0.9.6"?.trim() || typeof packageJson.version === "string" && packageJson.version.trim() || process.env.npm_package_version?.trim() || "0.0.0-dev";
+var MANIFEST_VERSION = "0.9.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,

package/dist/worker.js

@@ -5418,7 +5418,8 @@ function normalizePaperclipIssueExecutionState(value) {
   const lastDecisionId = normalizeOptionalString2(record.lastDecisionId) ?? null;
   const lastDecisionOutcome = normalizeOptionalString2(record.lastDecisionOutcome) ?? null;
   const completedStageIds = Array.isArray(record.completedStageIds) ? record.completedStageIds.map((stageId) => normalizeOptionalString2(stageId)).filter((stageId) => Boolean(stageId)) : [];
-  if (!status && currentStageId === null && currentStageIndex === null && currentStageType === null && currentParticipant === null && returnAssignee === null && completedStageIds.length === 0 && lastDecisionId === null && lastDecisionOutcome === null) {
+  const monitor = normalizePaperclipIssueMonitorState(record.monitor);
+  if (!status && currentStageId === null && currentStageIndex === null && currentStageType === null && currentParticipant === null && returnAssignee === null && completedStageIds.length === 0 && lastDecisionId === null && lastDecisionOutcome === null && monitor === null) {
     return null;
   }
   return {
@@ -5430,7 +5431,25 @@ function normalizePaperclipIssueExecutionState(value) {
     returnAssignee,
     completedStageIds,
     ...lastDecisionId !== null ? { lastDecisionId } : {},
-    ...lastDecisionOutcome !== null ? { lastDecisionOutcome } : {}
+    ...lastDecisionOutcome !== null ? { lastDecisionOutcome } : {},
+    ...monitor !== null ? { monitor } : {}
+  };
+}
+function normalizePaperclipIssueMonitorState(value) {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+  const record = value;
+  const status = normalizeOptionalString2(record.status);
+  const clearedAt = normalizeOptionalString2(record.clearedAt) ?? null;
+  const clearReason = normalizeOptionalString2(record.clearReason) ?? null;
+  if (!status && clearedAt === null && clearReason === null && Object.keys(record).length === 0) {
+    return null;
+  }
+  return {
+    ...status ? { status } : {},
+    clearedAt,
+    clearReason
   };
 }
 function getPaperclipIssueAssigneePrincipal(issue) {
@@ -5456,6 +5475,17 @@ function getPaperclipIssueSyncContext(issue) {
     executionState: normalizePaperclipIssueExecutionState(record.executionState)
   };
 }
+function hasActivePaperclipIssueMonitor(syncContext) {
+  const monitor = syncContext.executionState?.monitor;
+  if (!monitor) {
+    return false;
+  }
+  if (monitor.clearedAt || monitor.clearReason) {
+    return false;
+  }
+  const normalizedStatus = monitor.status?.trim().toLowerCase();
+  return normalizedStatus !== "cleared" && normalizedStatus !== "completed" && normalizedStatus !== "cancelled" && normalizedStatus !== "canceled";
+}
 function hasUnresolvedPaperclipIssueBlockerSummary(blockers) {
   if (!Array.isArray(blockers)) {
     return false;
@@ -5675,6 +5705,13 @@ function isClearableMaintainerWaitExecutionState(executionState) {
   if (executionState === null) {
     return true;
   }
+  if (hasActivePaperclipIssueMonitor({
+    assignee: null,
+    executionPolicy: null,
+    executionState
+  })) {
+    return false;
+  }
   if (executionState.currentParticipant !== null || executionState.returnAssignee !== null || executionState.currentStageId !== null || executionState.currentStageIndex !== null || executionState.currentStageType !== null || executionState.completedStageIds.length > 0 || executionState.lastDecisionId || executionState.lastDecisionOutcome) {
     return false;
   }
@@ -7347,6 +7384,23 @@ async function listGitHubPullRequestIssueLinksForMapping(ctx, mapping, target) {
   }
   return [...recordsByKey.values()];
 }
+async function listGitHubIssueLinkedPaperclipIssueIdsForMapping(ctx, mapping, importedIssueRecords, target) {
+  const issueIds = new Set(
+    importedIssueRecords.map((record) => record.paperclipIssueId).filter(Boolean)
+  );
+  if (target?.kind === "issue" && target.issueId && target.githubIssueNumber) {
+    issueIds.add(target.issueId);
+  }
+  const issueLinks = await listGitHubIssueLinkRecords(ctx, {
+    ...target?.kind === "issue" && target.issueId ? { paperclipIssueId: target.issueId } : {}
+  });
+  for (const record of issueLinks) {
+    if (doesGitHubIssueLinkRecordMatchMapping(record, mapping) && doesGitHubIssueLinkRecordMatchTarget(record, target)) {
+      issueIds.add(record.paperclipIssueId);
+    }
+  }
+  return issueIds;
+}
 function doesGitHubIssueLinkRecordMatchMapping(record, mapping) {
   if (record.data.repositoryUrl !== getNormalizedMappingRepositoryUrl(mapping)) {
     return false;
@@ -7384,6 +7438,7 @@ async function listExternalGitHubLinkSyncWork(ctx, mappings, target) {
   const syncableMappings = getSyncableMappingsForTarget(mappings, target);
   const issueLinksByKey = /* @__PURE__ */ new Map();
   const pullRequestLinksByKey = /* @__PURE__ */ new Map();
+  const issueLinkedPaperclipIssueIds = /* @__PURE__ */ new Set();
   const [issueLinks, pullRequestLinks] = await Promise.all([
     listGitHubIssueLinkRecords(ctx, {
       ...target?.kind === "issue" && target.issueId ? { paperclipIssueId: target.issueId } : {}
@@ -7393,7 +7448,11 @@ async function listExternalGitHubLinkSyncWork(ctx, mappings, target) {
     })
   ]);
   for (const record of issueLinks) {
-    if (!doesGitHubIssueLinkRecordMatchTarget(record, target) || isGitHubIssueLinkCoveredByMappings(record, syncableMappings)) {
+    if (!doesGitHubIssueLinkRecordMatchTarget(record, target)) {
+      continue;
+    }
+    issueLinkedPaperclipIssueIds.add(record.paperclipIssueId);
+    if (isGitHubIssueLinkCoveredByMappings(record, syncableMappings)) {
       continue;
     }
     issueLinksByKey.set(
@@ -7402,7 +7461,7 @@ async function listExternalGitHubLinkSyncWork(ctx, mappings, target) {
     );
   }
   for (const record of pullRequestLinks) {
-    if (!doesGitHubPullRequestLinkRecordMatchTarget(record, target) || isGitHubPullRequestLinkCoveredByMappings(record, syncableMappings)) {
+    if (!doesGitHubPullRequestLinkRecordMatchTarget(record, target) || issueLinkedPaperclipIssueIds.has(record.paperclipIssueId) || isGitHubPullRequestLinkCoveredByMappings(record, syncableMappings)) {
       continue;
     }
     pullRequestLinksByKey.set(
@@ -9496,6 +9555,19 @@ async function cancelUnmappedTransferredGitHubIssue(ctx, params) {
       updatedStatusesCount: 0
     };
   }
+  const paperclipIssueSyncContext = getPaperclipIssueSyncContext(paperclipIssue);
+  if (hasActivePaperclipIssueMonitor(paperclipIssueSyncContext)) {
+    ctx.logger.info("GitHub sync skipped transferred issue cancellation because an issue monitor is active.", {
+      companyId,
+      issueId: params.importedIssue.paperclipIssueId,
+      transferredRepositoryUrl: params.transferredRepository.url,
+      currentStatus: paperclipIssue.status,
+      resolvedStatus: "cancelled"
+    });
+    return {
+      updatedStatusesCount: 0
+    };
+  }
   await unlinkPaperclipIssueFromGitHub(ctx, {
     companyId,
     issueId: params.importedIssue.paperclipIssueId
@@ -9505,7 +9577,7 @@ async function cancelUnmappedTransferredGitHubIssue(ctx, params) {
     companyId,
     issueId: params.importedIssue.paperclipIssueId,
     currentStatus: paperclipIssue.status,
-    syncContext: getPaperclipIssueSyncContext(paperclipIssue),
+    syncContext: paperclipIssueSyncContext,
     nextStatus,
     transitionComment: buildUnmappedTransferredIssueCancellationComment({
       previousStatus: paperclipIssue.status,
@@ -9824,6 +9896,17 @@ async function synchronizePaperclipIssueStatuses(ctx, octokit, repository, mappi
       importedIssue.lastSeenCommentCount = snapshot.commentCount;
       importedIssue.lastSeenGitHubState = snapshot.state;
       importedIssue.linkedPullRequestCommentCounts = currentLinkedPullRequestCommentCounts;
+      if (hasActivePaperclipIssueMonitor(paperclipIssueSyncContext)) {
+        ctx.logger.info("GitHub sync skipped Paperclip issue state changes because an issue monitor is active.", {
+          companyId: mapping.companyId,
+          issueId: importedIssue.paperclipIssueId,
+          repositoryUrl: repository.url,
+          githubIssueNumber: githubIssue.number,
+          currentStatus: paperclipIssue.status,
+          resolvedStatus: nextStatus
+        });
+        continue;
+      }
       if (paperclipIssue.status === nextStatus) {
         if (shouldClearTransitionAssignee || shouldClearCompletedExecutionPolicy) {
           updateSyncFailureContext(syncFailureContext, {
@@ -10080,6 +10163,16 @@ async function synchronizePaperclipPullRequestIssueStatuses(ctx, octokit, mappin
       const shouldClearTransitionAssignee = nextStatus === "in_review" && (nextTransitionAssignee === null || shouldPreserveMaintainerWaitRouting) && paperclipIssueSyncContext.assignee !== null;
       const nextAssigneeChanged = nextTransitionAssignee ? !doesPaperclipIssueAssigneeMatch(paperclipIssueSyncContext.assignee, nextTransitionAssignee.principal) : false;
       const shouldWakeTransitionAssignee = paperclipIssue.status !== nextStatus && nextTransitionAssignee?.principal.kind === "agent" && isActionablePaperclipIssueStatus(nextStatus) && (nextAssigneeChanged || paperclipIssue.status !== nextStatus);
+      if (hasActivePaperclipIssueMonitor(paperclipIssueSyncContext)) {
+        ctx.logger.info("GitHub sync skipped Paperclip pull request issue state changes because an issue monitor is active.", {
+          companyId: mapping.companyId,
+          issueId: paperclipIssueId,
+          repositoryUrl: primaryRepository?.url,
+          currentStatus: paperclipIssue.status,
+          resolvedStatus: nextStatus
+        });
+        continue;
+      }
       if (paperclipIssue.status === nextStatus) {
         if (shouldClearTransitionAssignee || shouldClearCompletedExecutionPolicy) {
           updateSyncFailureContext(syncFailureContext, {
@@ -14142,7 +14235,13 @@ async function performSync(ctx, trigger, options = {}) {
         const importRegistryByIssueId = new Map(
           importedIssueRecords.map((entry) => [entry.githubIssueId, entry])
         );
-        const pullRequestLinks = await listGitHubPullRequestIssueLinksForMapping(ctx, mapping, options.target);
+        const githubIssueLinkedPaperclipIssueIds = await listGitHubIssueLinkedPaperclipIssueIdsForMapping(
+          ctx,
+          mapping,
+          importedIssueRecords,
+          options.target
+        );
+        const pullRequestLinks = (await listGitHubPullRequestIssueLinksForMapping(ctx, mapping, options.target)).filter((record) => !githubIssueLinkedPaperclipIssueIds.has(record.paperclipIssueId));
         const ensuredPaperclipIssueIds = /* @__PURE__ */ new Map();
         const trackedIssueIds = /* @__PURE__ */ new Set([
           ...issues.map((issue) => issue.id),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paperclip-github-plugin",
-  "version": "0.9.6",
+  "version": "0.9.8",
   "description": "Paperclip plugin for synchronizing GitHub issues into Paperclip projects.",
   "license": "Apache-2.0",
   "type": "module",
@@ -49,11 +49,11 @@
     "remark-gfm": "^4.0.1"
   },
   "devDependencies": {
-    "@types/node": "24.12.3",
+    "@types/node": "24.12.4",
     "@types/react": "19.2.14",
     "esbuild": "0.28.0",
-    "playwright": "1.59.1",
-    "tsx": "4.21.0",
+    "playwright": "1.60.0",
+    "tsx": "4.22.0",
     "typescript": "6.0.3"
   }
 }