External object references across issue surfaces (#8512)

## Thinking Path

> - Paperclip is the open source control plane people use to coordinate
AI agents, issues, approvals, comments, and work products.
> - The involved subsystem is issue context: markdown links, issue
properties, related work, lists, filters, inbox/sidebar status, and
plugin-provided external context.
> - The gap is that URLs to external systems currently remain mostly
plain links, so humans and agents must manually open them to understand
status, identity, and liveness.
> - This matters because external work objects such as GitHub issues and
pull requests are part of the operational state of a Paperclip company.
> - The implementation keeps core provider-neutral: shared contracts,
storage, sync, routes, and UI surfaces live in core while providers can
contribute detection and status resolution.
> - This pull request adds the external object reference foundation,
GitHub provider support, issue-surface rendering, filters,
sidebar/list/inbox signals, and test/story coverage.
> - The benefit is that linked external work becomes inspectable
Paperclip context without hardcoding every provider directly into the
UI.

## Linked Issues or Issue Description

No public GitHub issue exists for this work.

Feature request:

- Problem: URLs in Paperclip issues, comments, documents, and related
surfaces do not expose provider status or object identity inline.
- Proposed behavior: detect supported external object URLs, persist
normalized references, refresh provider status, and render concise
status-aware links across issue surfaces.
- Users affected: board users, agents, and maintainers who triage issues
containing external work links.
- Acceptance: external object references are company-scoped,
provider-extensible, visible in key issue surfaces, filterable where
relevant, and covered by focused shared/server/UI tests.

Related PR search:

- No open duplicate PRs found for `external object references`.
- Closed related prior attempt: #4556.

## What Changed

- Added shared external-object contracts, validators, status/liveness
helpers, and plugin protocol declarations.
- Added database schema and additive migrations for external objects,
source mentions, and display metadata.
- Added server services/routes for detecting, syncing, summarizing,
refreshing, and resolving external objects across issues, documents,
comments, projects, and plugins.
- Added a GitHub external-object provider plus plugin SDK authoring
docs.
- Wired UI presentation across markdown links, comments, issue chat,
documents, properties, related work, issue rows, filters, inbox/sidebar
badges, and Storybook stories.
- Rebasing cleanup: moved the branch onto current `master`, repaired
stale worktree provision config, hardened environment-sensitive
tests/mocks, and removed committed screenshot artifacts from the PR
branch to keep the reviewable file set below tool limits.

## Verification

- `pnpm exec vitest run packages/shared/src/external-objects.test.ts
server/src/__tests__/external-object-routes.test.ts
server/src/__tests__/external-objects-service.test.ts
ui/src/components/ExternalObjectPill.test.tsx
ui/src/lib/external-objects.test.ts` passed after rebasing: 5 files, 56
tests.
- Historical branch verification before this PR creation included `pnpm
test:run`, `pnpm -r typecheck`, and `pnpm build`; this PR body does not
claim those were rerun after the final rebase.

## Risks

- Medium: this adds a new cross-surface sync path on
issue/document/comment writes. The implementation uses safe sync
wrappers so external-object failures warn instead of blocking core
mutations.
- Medium: the migrations introduce new tables and indexes. They are
additive and company-scoped.
- Medium: provider-specific URL parsing can miss or misclassify edge
cases. Shared canonicalization tests and provider tests cover current
GitHub shapes.
- Low: UI badge/filter behavior could add visual noise for object-heavy
issues; component tests and Storybook stories cover the intended
surfaces.

> Roadmap checked: `ROADMAP.md` references the plugin system as the
current extension path and does not list a duplicate core feature.
Related long-range docs discuss external references, work products,
preview URLs, and plugin extension points; this PR implements the scoped
external-object reference foundation.

## Model Used

OpenAI Codex, GPT-5 coding-agent runtime, with shell and GitHub CLI tool
use. Reasoning mode: medium. Exact deployed runtime model ID and context
window were not exposed in the environment.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

ui/src/components/ExternalObjectStatusIcon.tsx

@@ -0,0 +1,94 @@
+import type {
+  ExternalObjectLivenessState,
+  ExternalObjectStatusCategory,
+} from "@paperclipai/shared";
+import { Clock } from "lucide-react";
+import {
+  externalObjectStatusIcon,
+  externalObjectStatusIconDefault,
+} from "../lib/status-colors";
+import {
+  externalObjectCategoryLabel,
+  externalObjectIconForCategory,
+  externalObjectIconForKey,
+  externalObjectLivenessLabel,
+} from "../lib/external-objects";
+import { usePrefersReducedMotion } from "../hooks/usePrefersReducedMotion";
+import { cn } from "../lib/utils";
+
+interface ExternalObjectStatusIconProps {
+  category: ExternalObjectStatusCategory;
+  liveness: ExternalObjectLivenessState;
+  statusIconKey?: string | null;
+  /** Optional override label used in `aria-label` (e.g. provider-specific copy). */
+  label?: string | null;
+  className?: string;
+  /** Tailwind size class — defaults to `h-3.5 w-3.5` (compact pill use). */
+  sizeClassName?: string;
+  /**
+   * When true the icon renders inline at 12 px with the `mr-1`/`align`
+   * adjustments used by `MarkdownIssueLink`. Used by the markdown decorator.
+   */
+  inline?: boolean;
+}
+
+/**
+ * Pure presentational icon for an external object's status. Combines:
+ *
+ * - A category icon (lucide) from `externalObjectIconForCategory`.
+ * - Tone classes (text + border) from `externalObjectStatusIcon`.
+ * - An overlaid clock micro-mark when liveness is `stale`.
+ * - Reduced-motion-aware spinner for the `running` category.
+ *
+ * Never mounts plugin React; the host is the sole renderer of identity glyphs.
+ */
+export function ExternalObjectStatusIcon({
+  category,
+  liveness,
+  statusIconKey,
+  label,
+  className,
+  sizeClassName = "h-3.5 w-3.5",
+  inline = false,
+}: ExternalObjectStatusIconProps) {
+  const reducedMotion = usePrefersReducedMotion();
+  const Icon = externalObjectIconForKey(statusIconKey) ?? externalObjectIconForCategory(category);
+  const tone = statusIconKey === "git-merge"
+    ? "text-violet-600 border-violet-600 dark:text-violet-400 dark:border-violet-400"
+    : externalObjectStatusIcon[category] ?? externalObjectStatusIconDefault;
+  const livenessSuffix = liveness === "fresh" || liveness === "unknown"
+    ? ""
+    : ` (${externalObjectLivenessLabel(liveness)})`;
+  const ariaLabel = `${label ?? externalObjectCategoryLabel(category)}${livenessSuffix}`;
+
+  // The clock overlay needs a positioned wrapper. Inline mode keeps the icon
+  // tight to the surrounding text; pill mode expects to size by sizeClassName.
+  const wrapperBase = inline
+    ? "relative mr-1 inline-flex shrink-0 align-[-0.125em]"
+    : "relative inline-flex shrink-0";
+  const iconSize = inline ? "h-3 w-3" : sizeClassName;
+  const isSpinner = category === "running";
+  const animateClass = isSpinner && !reducedMotion ? "animate-spin" : "";
+
+  return (
+    <span
+      role="img"
+      aria-label={ariaLabel}
+      className={cn(wrapperBase, className)}
+    >
+      <Icon
+        aria-hidden="true"
+        className={cn(iconSize, tone.split(" ").filter((c) => c.startsWith("text-")).join(" "), animateClass)}
+      />
+      {liveness === "stale" ? (
+        <Clock
+          aria-hidden="true"
+          className={cn(
+            "absolute -bottom-0.5 -right-0.5 h-2 w-2 rounded-full bg-background text-muted-foreground",
+            inline ? "" : "p-px",
+          )}
+        />
+      ) : null}
+    </span>
+  );
+}