Support issue identifiers (PAP-39) in URLs and prefer them throughout

Backend: - Add router.param middleware in issues, activity, and agents routes to resolve identifiers (e.g. PAP-39) to UUIDs before handlers run - Simplify GET /issues/:id now that param middleware handles resolution - Include identifier in getAncestors response and issuesForRun query - Add identifier field to IssueAncestor shared type Frontend: - Update all issue navigation links across 15+ files to use issue.identifier ?? issue.id instead of bare UUIDs - Add URL redirect in IssueDetail: navigating via UUID automatically replaces the URL with the human-readable identifier - Fix childIssues filter to use issue.id (UUID) instead of URL param so it works correctly with identifier-based URLs - Add issueUrl() utility in lib/utils.ts Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-20 16:04:05 -06:00
parent 0c0c308594
commit 9906a5ba06
21 changed files with 80 additions and 34 deletions
--- a/packages/shared/src/types/issue.ts
+++ b/packages/shared/src/types/issue.ts
@@ -18,6 +18,7 @@ export interface IssueAncestorGoal {

 export interface IssueAncestor {
  id: string;
+  identifier: string | null;
  title: string;
  description: string | null;
  status: string;
--- a/server/src/routes/activity.ts
+++ b/server/src/routes/activity.ts
@@ -47,6 +47,21 @@ export function activityRoutes(db: Db) {
    res.status(201).json(event);
  });

+  // Resolve issue identifiers (e.g. "PAP-39") to UUIDs
+  router.param("id", async (req, res, next, rawId) => {
+    try {
+      if (/^[A-Z]+-\d+$/i.test(rawId)) {
+        const issue = await issueSvc.getByIdentifier(rawId);
+        if (issue) {
+          req.params.id = issue.id;
+        }
+      }
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });
+
  router.get("/issues/:id/activity", async (req, res) => {
    const id = req.params.id as string;
    const issue = await issueSvc.getById(id);
--- a/server/src/routes/agents.ts
+++ b/server/src/routes/agents.ts
@@ -1017,9 +1017,10 @@ export function agentRoutes(db: Db) {
  });

  router.get("/issues/:id/live-runs", async (req, res) => {
-    const id = req.params.id as string;
+    const rawId = req.params.id as string;
    const issueSvc = issueService(db);
-    const issue = await issueSvc.getById(id);
+    const isIdentifier = /^[A-Z]+-\d+$/i.test(rawId);
+    const issue = isIdentifier ? await issueSvc.getByIdentifier(rawId) : await issueSvc.getById(rawId);
    if (!issue) {
      res.status(404).json({ error: "Issue not found" });
      return;
@@ -1045,7 +1046,7 @@ export function agentRoutes(db: Db) {
        and(
          eq(heartbeatRuns.companyId, issue.companyId),
          inArray(heartbeatRuns.status, ["queued", "running"]),
-          sql`${heartbeatRuns.contextSnapshot} ->> 'issueId' = ${id}`,
+          sql`${heartbeatRuns.contextSnapshot} ->> 'issueId' = ${issue.id}`,
        ),
      )
      .orderBy(desc(heartbeatRuns.createdAt));
@@ -1054,9 +1055,10 @@ export function agentRoutes(db: Db) {
  });

  router.get("/issues/:id/active-run", async (req, res) => {
-    const id = req.params.id as string;
+    const rawId = req.params.id as string;
    const issueSvc = issueService(db);
-    const issue = await issueSvc.getById(id);
+    const isIdentifier = /^[A-Z]+-\d+$/i.test(rawId);
+    const issue = isIdentifier ? await issueSvc.getByIdentifier(rawId) : await issueSvc.getById(rawId);
    if (!issue) {
      res.status(404).json({ error: "Issue not found" });
      return;
--- a/server/src/routes/issues.ts
+++ b/server/src/routes/issues.ts
@@ -106,6 +106,21 @@ export function issueRoutes(db: Db, storage: StorageService) {
    return true;
  }

+  // Resolve issue identifiers (e.g. "PAP-39") to UUIDs for all /issues/:id routes
+  router.param("id", async (req, res, next, rawId) => {
+    try {
+      if (/^[A-Z]+-\d+$/i.test(rawId)) {
+        const issue = await svc.getByIdentifier(rawId);
+        if (issue) {
+          req.params.id = issue.id;
+        }
+      }
+      next();
+    } catch (err) {
+      next(err);
+    }
+  });
+
  router.get("/companies/:companyId/issues", async (req, res) => {
    const companyId = req.params.companyId as string;
    assertCompanyAccess(req, companyId);
@@ -119,8 +134,7 @@ export function issueRoutes(db: Db, storage: StorageService) {

  router.get("/issues/:id", async (req, res) => {
    const id = req.params.id as string;
-    const isIdentifier = /^[A-Z]+-\d+$/i.test(id);
-    const issue = isIdentifier ? await svc.getByIdentifier(id) : await svc.getById(id);
+    const issue = await svc.getById(id);
    if (!issue) {
      res.status(404).json({ error: "Issue not found" });
      return;
--- a/server/src/services/activity.ts
+++ b/server/src/services/activity.ts
@@ -88,6 +88,7 @@ export function activityService(db: Db) {
      db
        .selectDistinctOn([issueIdAsText], {
          issueId: issues.id,
+          identifier: issues.identifier,
          title: issues.title,
          status: issues.status,
          priority: issues.priority,
--- a/server/src/services/issues.ts
+++ b/server/src/services/issues.ts
@@ -574,7 +574,7 @@ export function issueService(db: Db) {

    getAncestors: async (issueId: string) => {
      const raw: Array<{
-        id: string; title: string; description: string | null;
+        id: string; identifier: string | null; title: string; description: string | null;
        status: string; priority: string;
        assigneeAgentId: string | null; projectId: string | null; goalId: string | null;
      }> = [];
@@ -584,14 +584,14 @@ export function issueService(db: Db) {
      while (currentId && !visited.has(currentId) && raw.length < 50) {
        visited.add(currentId);
        const parent = await db.select({
-          id: issues.id, title: issues.title, description: issues.description,
+          id: issues.id, identifier: issues.identifier, title: issues.title, description: issues.description,
          status: issues.status, priority: issues.priority,
          assigneeAgentId: issues.assigneeAgentId, projectId: issues.projectId,
          goalId: issues.goalId, parentId: issues.parentId,
        }).from(issues).where(eq(issues.id, currentId)).then(r => r[0] ?? null);
        if (!parent) break;
        raw.push({
-          id: parent.id, title: parent.title, description: parent.description ?? null,
+          id: parent.id, identifier: parent.identifier ?? null, title: parent.title, description: parent.description ?? null,
          status: parent.status, priority: parent.priority,
          assigneeAgentId: parent.assigneeAgentId ?? null,
          projectId: parent.projectId ?? null, goalId: parent.goalId ?? null,
--- a/ui/src/api/activity.ts
+++ b/ui/src/api/activity.ts
@@ -15,6 +15,7 @@ export interface RunForIssue {

 export interface IssueForRun {
  issueId: string;
+  identifier: string | null;
  title: string;
  status: string;
  priority: string;
--- a/ui/src/components/ActiveAgentsPanel.tsx
+++ b/ui/src/components/ActiveAgentsPanel.tsx
@@ -359,7 +359,7 @@ function AgentRunCard({
        <div className="px-3 py-1.5 border-b border-border/40 text-xs flex items-center gap-1 min-w-0">
          <span className="text-muted-foreground mr-1">Working on:</span>
          <Link
-            to={`/issues/${run.issueId}`}
+            to={`/issues/${issue?.identifier ?? run.issueId}`}
            className="text-blue-400 hover:text-blue-300 hover:underline min-w-0 truncate"
            title={issue?.title ? `${issue?.identifier ?? run.issueId.slice(0, 8)} - ${issue.title}` : issue?.identifier ?? run.issueId.slice(0, 8)}
          >
--- a/ui/src/components/CommandPalette.tsx
+++ b/ui/src/components/CommandPalette.tsx
@@ -149,7 +149,7 @@ export function CommandPalette() {
            <CommandSeparator />
            <CommandGroup heading="Issues">
              {issues.slice(0, 10).map((issue) => (
-                <CommandItem key={issue.id} onSelect={() => go(`/issues/${issue.id}`)}>
+                <CommandItem key={issue.id} onSelect={() => go(`/issues/${issue.identifier ?? issue.id}`)}>
                  <CircleDot className="mr-2 h-4 w-4" />
                  <span className="text-muted-foreground mr-2 font-mono text-xs">
                    {issue.identifier ?? issue.id.slice(0, 8)}
--- a/ui/src/components/IssueProperties.tsx
+++ b/ui/src/components/IssueProperties.tsx
@@ -211,7 +211,7 @@ export function IssueProperties({ issue, onUpdate }: IssuePropertiesProps) {
        {issue.parentId && (
          <PropertyRow label="Parent">
            <Link
-              to={`/issues/${issue.parentId}`}
+              to={`/issues/${issue.ancestors?.[0]?.identifier ?? issue.parentId}`}
              className="text-sm hover:underline"
            >
              {issue.ancestors?.[0]?.title ?? issue.parentId.slice(0, 8)}
--- a/ui/src/components/NewIssueDialog.tsx
+++ b/ui/src/components/NewIssueDialog.tsx
@@ -130,7 +130,7 @@ export function NewIssueDialog() {
        title: `${issue.identifier ?? "Issue"} created`,
        body: issue.title,
        tone: "success",
-        action: { label: `View ${issue.identifier ?? "issue"}`, href: `/issues/${issue.id}` },
+        action: { label: `View ${issue.identifier ?? "issue"}`, href: `/issues/${issue.identifier ?? issue.id}` },
      });
    },
  });
--- a/ui/src/context/LiveUpdatesProvider.tsx
+++ b/ui/src/context/LiveUpdatesProvider.tsx
@@ -100,7 +100,7 @@ function resolveIssueToastContext(
    ref,
    title,
    label: title ? `${ref} - ${truncate(title, 72)}` : ref,
-    href: `/issues/${issueId}`,
+    href: `/issues/${cachedIssue?.identifier ?? issueId}`,
  };
 }

--- a/ui/src/lib/utils.ts
+++ b/ui/src/lib/utils.ts
@@ -36,3 +36,8 @@ export function formatTokens(n: number): string {
  if (n >= 1_000) return `${(n / 1_000).toFixed(1)}k`;
  return String(n);
 }
+
+/** Build an issue URL using the human-readable identifier when available. */
+export function issueUrl(issue: { id: string; identifier?: string | null }): string {
+  return `/issues/${issue.identifier ?? issue.id}`;
+}
--- a/ui/src/pages/AgentDetail.tsx
+++ b/ui/src/pages/AgentDetail.tsx
@@ -670,7 +670,7 @@ export function AgentDetail() {
                  key={issue.id}
                  identifier={issue.identifier ?? issue.id.slice(0, 8)}
                  title={issue.title}
-                  onClick={() => navigate(`/issues/${issue.id}`)}
+                  onClick={() => navigate(`/issues/${issue.identifier ?? issue.id}`)}
                  trailing={<StatusBadge status={issue.status} />}
                />
              ))}
@@ -1210,13 +1210,13 @@ function RunDetail({ run, adapterType }: { run: HeartbeatRun; adapterType: strin
              <button
                key={issue.issueId}
                className="flex items-center justify-between w-full px-3 py-2 text-xs hover:bg-accent/20 transition-colors text-left"
-                onClick={() => navigate(`/issues/${issue.issueId}`)}
+                onClick={() => navigate(`/issues/${issue.identifier ?? issue.issueId}`)}
              >
                <div className="flex items-center gap-2 min-w-0">
                  <StatusBadge status={issue.status} />
                  <span className="truncate">{issue.title}</span>
                </div>
-                <span className="font-mono text-muted-foreground shrink-0 ml-2">{issue.issueId.slice(0, 8)}</span>
+                <span className="font-mono text-muted-foreground shrink-0 ml-2">{issue.identifier ?? issue.issueId.slice(0, 8)}</span>
              </button>
            ))}
          </div>
--- a/ui/src/pages/ApprovalDetail.tsx
+++ b/ui/src/pages/ApprovalDetail.tsx
@@ -149,7 +149,7 @@ export function ApprovalDetail() {
            (linkedIssues?.length ?? 0) > 1
              ? "Review linked issues"
              : "Review linked issue",
-          to: `/issues/${primaryLinkedIssue.id}`,
+          to: `/issues/${primaryLinkedIssue.identifier ?? primaryLinkedIssue.id}`,
        }
      : linkedAgentId
        ? {
@@ -236,7 +236,7 @@ export function ApprovalDetail() {
              {linkedIssues.map((issue) => (
                <Link
                  key={issue.id}
-                  to={`/issues/${issue.id}`}
+                  to={`/issues/${issue.identifier ?? issue.id}`}
                  className="block text-xs rounded border border-border/70 px-2 py-1.5 hover:bg-accent/20"
                >
                  <span className="font-mono text-muted-foreground mr-2">
--- a/ui/src/pages/Dashboard.tsx
+++ b/ui/src/pages/Dashboard.tsx
@@ -266,7 +266,7 @@ export function Dashboard() {
                    <div
                      key={issue.id}
                      className="px-4 py-2 text-sm cursor-pointer hover:bg-accent/50 transition-colors"
-                      onClick={() => navigate(`/issues/${issue.id}`)}
+                      onClick={() => navigate(`/issues/${issue.identifier ?? issue.id}`)}
                    >
                      <div className="flex gap-3">
                        <div className="flex items-start gap-2 min-w-0 flex-1">
--- a/ui/src/pages/Inbox.tsx
+++ b/ui/src/pages/Inbox.tsx
@@ -299,7 +299,7 @@ export function Inbox() {
                          <button
                            type="button"
                            className="truncate text-muted-foreground transition-colors hover:text-foreground"
-                            onClick={() => navigate(`/issues/${issue.id}`)}
+                            onClick={() => navigate(`/issues/${issue.identifier ?? issue.id}`)}
                          >
                            {issue.identifier ?? issue.id.slice(0, 8)} · {issue.title}
                          </button>
@@ -372,7 +372,7 @@ export function Inbox() {
                <div
                  key={issue.id}
                  className="flex cursor-pointer items-center gap-3 px-4 py-3 transition-colors hover:bg-accent/50"
-                  onClick={() => navigate(`/issues/${issue.id}`)}
+                  onClick={() => navigate(`/issues/${issue.identifier ?? issue.id}`)}
                >
                  <Clock className="h-4 w-4 shrink-0 text-muted-foreground" />
                  <PriorityIcon priority={issue.priority} />
--- a/ui/src/pages/IssueDetail.tsx
+++ b/ui/src/pages/IssueDetail.tsx
@@ -189,11 +189,11 @@ export function IssueDetail() {
  }, [agents]);

  const childIssues = useMemo(() => {
-    if (!allIssues || !issueId) return [];
+    if (!allIssues || !issue) return [];
    return allIssues
-      .filter((i) => i.parentId === issueId)
+      .filter((i) => i.parentId === issue.id)
      .sort((a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime());
-  }, [allIssues, issueId]);
+  }, [allIssues, issue]);

  const commentsWithRunMeta = useMemo(() => {
    const runMetaByCommentId = new Map<string, { runId: string; runAgentId: string | null }>();
@@ -281,7 +281,7 @@ export function IssueDetail() {
        title: `${issueRef} updated`,
        body: truncate(updated.title, 96),
        tone: "success",
-        action: { label: `View ${issueRef}`, href: `/issues/${updated.id}` },
+        action: { label: `View ${issueRef}`, href: `/issues/${updated.identifier ?? updated.id}` },
      });
    },
  });
@@ -298,7 +298,7 @@ export function IssueDetail() {
        title: `Comment posted on ${issueRef}`,
        body: issue?.title ? truncate(issue.title, 96) : undefined,
        tone: "success",
-        action: issueId ? { label: `View ${issueRef}`, href: `/issues/${issueId}` } : undefined,
+        action: issueId ? { label: `View ${issueRef}`, href: `/issues/${issue?.identifier ?? issueId}` } : undefined,
      });
    },
  });
@@ -337,6 +337,13 @@ export function IssueDetail() {
    ]);
  }, [setBreadcrumbs, issue, issueId]);

+  // Redirect to identifier-based URL if navigated via UUID
+  useEffect(() => {
+    if (issue?.identifier && issueId !== issue.identifier) {
+      navigate(`/issues/${issue.identifier}`, { replace: true });
+    }
+  }, [issue, issueId, navigate]);
+
  useEffect(() => {
    if (issue) {
      openPanel(
@@ -373,7 +380,7 @@ export function IssueDetail() {
            <span key={ancestor.id} className="flex items-center gap-1">
              {i > 0 && <ChevronRight className="h-3 w-3 shrink-0" />}
              <Link
-                to={`/issues/${ancestor.id}`}
+                to={`/issues/${ancestor.identifier ?? ancestor.id}`}
                className="hover:text-foreground transition-colors truncate max-w-[200px]"
                title={ancestor.title}
              >
@@ -595,7 +602,7 @@ export function IssueDetail() {
              {childIssues.map((child) => (
                <Link
                  key={child.id}
-                  to={`/issues/${child.id}`}
+                  to={`/issues/${child.identifier ?? child.id}`}
                  className="flex items-center justify-between px-3 py-2 text-xs hover:bg-accent/20 transition-colors"
                >
                  <div className="flex items-center gap-2 min-w-0">
--- a/ui/src/pages/Issues.tsx
+++ b/ui/src/pages/Issues.tsx
@@ -157,7 +157,7 @@ export function Issues() {
              key={issue.id}
              identifier={issue.identifier ?? issue.id.slice(0, 8)}
              title={issue.title}
-              onClick={() => navigate(`/issues/${issue.id}`)}
+              onClick={() => navigate(`/issues/${issue.identifier ?? issue.id}`)}
              leading={
                // eslint-disable-next-line jsx-a11y/click-events-have-key-events, jsx-a11y/no-static-element-interactions
                <div className="flex items-center gap-2" onClick={(e) => e.stopPropagation()}>
@@ -220,7 +220,7 @@ export function Issues() {
                  key={issue.id}
                  identifier={issue.identifier ?? issue.id.slice(0, 8)}
                  title={issue.title}
-                  onClick={() => navigate(`/issues/${issue.id}`)}
+                  onClick={() => navigate(`/issues/${issue.identifier ?? issue.id}`)}
                  leading={
                    // eslint-disable-next-line jsx-a11y/click-events-have-key-events, jsx-a11y/no-static-element-interactions
                    <div className="flex items-center gap-2" onClick={(e) => e.stopPropagation()}>
--- a/ui/src/pages/MyIssues.tsx
+++ b/ui/src/pages/MyIssues.tsx
@@ -52,7 +52,7 @@ export function MyIssues() {
              key={issue.id}
              identifier={issue.identifier ?? issue.id.slice(0, 8)}
              title={issue.title}
-              onClick={() => navigate(`/issues/${issue.id}`)}
+              onClick={() => navigate(`/issues/${issue.identifier ?? issue.id}`)}
              leading={
                <>
                  <PriorityIcon priority={issue.priority} />
--- a/ui/src/pages/ProjectDetail.tsx
+++ b/ui/src/pages/ProjectDetail.tsx
@@ -132,7 +132,7 @@ export function ProjectDetail() {
                  identifier={issue.identifier ?? issue.id.slice(0, 8)}
                  title={issue.title}
                  trailing={<StatusBadge status={issue.status} />}
-                  onClick={() => navigate(`/issues/${issue.id}`)}
+                  onClick={() => navigate(`/issues/${issue.identifier ?? issue.id}`)}
                />
              ))}
            </div>