Harden control-plane safety and issue identifiers (#5292)

## Thinking Path

> - Paperclip relies on issue identifiers, execution policies, and agent
heartbeat rules to keep autonomous work auditable.
> - Safety checks need to reject ambiguous agent handoffs, and
identifier parsing needs to support Cloud tenant prefixes.
> - Agent instructions also need to make final-disposition rules
explicit so work does not stall in vague states.
> - This pull request isolates backend correctness and governance
hardening from the UI and recovery-system-notice branches.
> - The benefit is safer in-review transitions, better identifier
compatibility, and clearer agent operating contracts.

## What Changed

- Fixed run-aware confirmation ordering and interrupted-run state
cleanup.
- Added Cloud tenant identity bootstrap and alphanumeric issue
identifier support across shared parsing and server routes.
- Guarded agent-authored `in_review` updates unless a real review path
exists.
- Tightened heartbeat disposition instructions in adapter
utilities/default AGENTS/Paperclip skill.

## Verification

- `pnpm install --frozen-lockfile`
- `pnpm exec vitest run packages/shared/src/issue-references.test.ts
server/src/__tests__/issue-identifier-routes.test.ts
server/src/__tests__/issue-execution-policy-routes.test.ts
packages/adapter-utils/src/server-utils.test.ts` initially had the first
execution-policy test hit Vitest's 5s timeout under the parallel bundle
while the rest passed.
- `pnpm exec vitest run
server/src/__tests__/issue-execution-policy-routes.test.ts
--testTimeout=20000` passed with 10/10 tests.

- Follow-up: `pnpm run typecheck:build-gaps` passed.
- Follow-up: `pnpm --filter @paperclipai/ui typecheck` passed.
- Follow-up: `pnpm vitest run
server/src/__tests__/issue-comment-reopen-routes.test.ts
server/src/__tests__/company-portability.test.ts
server/src/__tests__/costs-service.test.ts` passed.
- Follow-up: `pnpm vitest run ui/src/context/LiveUpdatesProvider.test.ts
ui/src/lib/issue-chat-messages.test.ts
ui/src/lib/issue-reference.test.ts
ui/src/lib/issue-timeline-events.test.ts` passed.

## Risks

- Medium control-plane risk: in-review update validation changes agent
behavior. The error message is explicit and tests cover allowed review
paths.

## Model Used

- OpenAI GPT-5 Codex via Paperclip `codex_local` adapter, with
shell/git/GitHub CLI tool use.

## 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 run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

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

ui/src/lib/issue-chat-messages.test.ts

@@ -7,7 +7,10 @@ import {
   type IssueChatComment,
   type IssueChatLinkedRun,
 } from "./issue-chat-messages";
-import type { SuggestTasksInteraction } from "./issue-thread-interactions";
+import type {
+  RequestConfirmationInteraction,
+  SuggestTasksInteraction,
+} from "./issue-thread-interactions";
 import type { IssueTimelineEvent } from "./issue-timeline-events";
 import type { LiveRunForIssue } from "../api/heartbeats";
 
@@ -89,6 +92,34 @@ function createInteraction(
   };
 }
 
+function createRequestConfirmation(
+  overrides: Partial<RequestConfirmationInteraction> = {},
+): RequestConfirmationInteraction {
+  return {
+    id: "confirmation-1",
+    companyId: "company-1",
+    issueId: "issue-1",
+    kind: "request_confirmation",
+    title: "Approve the plan",
+    summary: "Review and approve the latest plan.",
+    status: "pending",
+    continuationPolicy: "wake_assignee",
+    createdByAgentId: "agent-1",
+    createdByUserId: null,
+    resolvedByAgentId: null,
+    resolvedByUserId: null,
+    createdAt: new Date("2026-04-06T12:01:00.000Z"),
+    updatedAt: new Date("2026-04-06T12:01:00.000Z"),
+    resolvedAt: null,
+    payload: {
+      version: 1,
+      prompt: "Approve the plan?",
+    },
+    result: null,
+    ...overrides,
+  };
+}
+
 describe("buildAssistantPartsFromTranscript", () => {
   it("maps assistant text, reasoning, and tool activity while omitting noisy stderr", () => {
     const result = buildAssistantPartsFromTranscript([
@@ -438,6 +469,130 @@ describe("buildIssueChatMessages", () => {
     });
   });
 
+  it("places request confirmations after later same-run handoff status and comment", () => {
+    const messages = buildIssueChatMessages({
+      comments: [
+        createComment({
+          id: "comment-handoff",
+          authorAgentId: "agent-1",
+          authorUserId: null,
+          body: "Ready for approval.",
+          createdAt: new Date("2026-04-06T12:03:00.000Z"),
+          updatedAt: new Date("2026-04-06T12:03:00.000Z"),
+          runId: "run-1",
+          runAgentId: "agent-1",
+        }),
+        createComment({
+          id: "comment-user-reply",
+          body: "Approved.",
+          createdAt: new Date("2026-04-06T12:04:00.000Z"),
+          updatedAt: new Date("2026-04-06T12:04:00.000Z"),
+        }),
+      ],
+      interactions: [
+        createRequestConfirmation({
+          id: "confirmation-1",
+          sourceRunId: "run-1",
+          status: "expired",
+          result: {
+            version: 1,
+            outcome: "superseded_by_comment",
+            commentId: "comment-user-reply",
+          },
+        }),
+      ],
+      timelineEvents: [
+        {
+          id: "event-in-review",
+          actorType: "agent",
+          actorId: "agent-1",
+          createdAt: new Date("2026-04-06T12:02:00.000Z"),
+          runId: "run-1",
+          statusChange: {
+            from: "in_progress",
+            to: "in_review",
+          },
+        },
+      ],
+      linkedRuns: [],
+      liveRuns: [],
+      currentUserId: "user-1",
+    });
+
+    expect(messages.map((message) => `${message.role}:${message.id}`)).toEqual([
+      "system:activity:event-in-review",
+      "assistant:comment-handoff",
+      "system:interaction:confirmation-1",
+      "user:comment-user-reply",
+    ]);
+  });
+
+  it("keeps request confirmations chronological without later same-run handoff evidence", () => {
+    const messages = buildIssueChatMessages({
+      comments: [
+        createComment({
+          id: "comment-later",
+          createdAt: new Date("2026-04-06T12:02:00.000Z"),
+          updatedAt: new Date("2026-04-06T12:02:00.000Z"),
+        }),
+      ],
+      interactions: [
+        createRequestConfirmation({
+          id: "confirmation-1",
+          sourceRunId: "run-1",
+        }),
+      ],
+      timelineEvents: [],
+      linkedRuns: [],
+      liveRuns: [],
+      currentUserId: "user-1",
+    });
+
+    expect(messages.map((message) => `${message.role}:${message.id}`)).toEqual([
+      "system:interaction:confirmation-1",
+      "user:comment-later",
+    ]);
+  });
+
+  it("does not move request confirmations past unrelated comments before same-run handoff", () => {
+    const messages = buildIssueChatMessages({
+      comments: [
+        createComment({
+          id: "comment-user-reply",
+          body: "I have a question first.",
+          createdAt: new Date("2026-04-06T12:02:00.000Z"),
+          updatedAt: new Date("2026-04-06T12:02:00.000Z"),
+        }),
+        createComment({
+          id: "comment-handoff",
+          authorAgentId: "agent-1",
+          authorUserId: null,
+          body: "Ready for approval.",
+          createdAt: new Date("2026-04-06T12:03:00.000Z"),
+          updatedAt: new Date("2026-04-06T12:03:00.000Z"),
+          runId: "run-1",
+          runAgentId: "agent-1",
+        }),
+      ],
+      interactions: [
+        createRequestConfirmation({
+          id: "confirmation-1",
+          sourceRunId: "run-1",
+        }),
+      ],
+      timelineEvents: [],
+      linkedRuns: [],
+      liveRuns: [],
+      currentUserId: "user-1",
+    });
+
+    expect(messages.map((message) => `${message.role}:${message.id}`)).toEqual([
+      "system:interaction:confirmation-1",
+      "user:comment-user-reply",
+      "assistant:comment-handoff",
+    ]);
+  });
+
   it("keeps succeeded runs as assistant messages when transcript output exists", () => {
     const agentMap = new Map<string, Agent>([["agent-1", createAgent("agent-1", "CodexCoder")]]);
     const messages = buildIssueChatMessages({

ui/src/lib/issue-chat-messages.ts

@@ -89,6 +89,11 @@ type MessageWithOrder = {
   message: ThreadMessage;
 };
 
+type SortBoundaryItem = {
+  createdAtMs: number;
+  runId?: string | null;
+};
+
 export interface StableThreadMessageCacheEntry {
   fingerprint: string;
   message: ThreadMessage;
@@ -145,6 +150,64 @@ function sortByCreated<T extends { createdAt: Date | string; id: string }>(items
   });
 }
 
+function latestSameRunHandoffTimestamp(args: {
+  interactionCreatedAtMs: number;
+  sourceRunId: string;
+  comments: readonly IssueChatComment[];
+  timelineEvents: readonly IssueTimelineEvent[];
+  linkedRuns: readonly IssueChatLinkedRun[];
+  liveRuns: readonly LiveRunForIssue[];
+}) {
+  const {
+    interactionCreatedAtMs,
+    sourceRunId,
+    comments,
+    timelineEvents,
+    linkedRuns,
+    liveRuns,
+  } = args;
+  const handoffItems: SortBoundaryItem[] = [
+    ...comments.map((comment) => ({
+      createdAtMs: toTimestamp(comment.createdAt),
+      runId: comment.runId ?? null,
+    })),
+    ...timelineEvents.map((event) => ({
+      createdAtMs: toTimestamp(event.createdAt),
+      runId: event.runId ?? null,
+    })),
+  ];
+  const barrierItems: SortBoundaryItem[] = [
+    ...handoffItems,
+    ...linkedRuns.map((run) => ({
+      createdAtMs: toTimestamp(runTimestamp(run)),
+      runId: run.runId,
+    })),
+    ...liveRuns.map((run) => ({
+      createdAtMs: toTimestamp(run.startedAt ?? run.createdAt),
+      runId: run.id,
+    })),
+  ];
+  const barrierAtMs = barrierItems
+    .filter((item) => item.createdAtMs > interactionCreatedAtMs && item.runId !== sourceRunId)
+    .reduce<number | null>(
+      (earliest, item) =>
+        earliest === null ? item.createdAtMs : Math.min(earliest, item.createdAtMs),
+      null,
+    );
+
+  return handoffItems
+    .filter((item) =>
+      item.createdAtMs > interactionCreatedAtMs
+      && item.runId === sourceRunId
+      && (barrierAtMs === null || item.createdAtMs < barrierAtMs)
+    )
+    .reduce<number | null>(
+      (latest, item) =>
+        latest === null ? item.createdAtMs : Math.max(latest, item.createdAtMs),
+      null,
+    );
+}
+
 function normalizeJsonValue(input: unknown): JsonValue {
   if (
     input === null ||
@@ -832,8 +895,19 @@ export function buildIssueChatMessages(args: {
   }
 
   for (const interaction of sortByCreated(interactions)) {
+    const createdAtMs = toTimestamp(interaction.createdAt);
+    const handoffAtMs = interaction.kind === "request_confirmation" && interaction.sourceRunId
+      ? latestSameRunHandoffTimestamp({
+        interactionCreatedAtMs: createdAtMs,
+        sourceRunId: interaction.sourceRunId,
+        comments,
+        timelineEvents,
+        linkedRuns,
+        liveRuns,
+      })
+      : null;
     orderedMessages.push({
-      createdAtMs: toTimestamp(interaction.createdAt),
+      createdAtMs: handoffAtMs ?? createdAtMs,
       order: 2,
       message: createInteractionMessage(interaction),
     });

ui/src/lib/issue-reference.test.ts

@@ -5,6 +5,7 @@ describe("issue-reference", () => {
   it("extracts issue ids from company-scoped issue paths", () => {
     expect(parseIssuePathIdFromPath("/PAP/issues/PAP-1271")).toBe("PAP-1271");
     expect(parseIssuePathIdFromPath("/PAP/issues/pap-1272")).toBe("PAP-1272");
+    expect(parseIssuePathIdFromPath("/issues/pc1a2-7")).toBe("PC1A2-7");
     expect(parseIssuePathIdFromPath("/PC1A2/issues/pc1a2-7")).toBe("PC1A2-7");
     expect(parseIssuePathIdFromPath("/issues/PAP-1179")).toBe("PAP-1179");
     expect(parseIssuePathIdFromPath("/issues/:id")).toBeNull();

ui/src/lib/issue-timeline-events.test.ts

@@ -66,6 +66,7 @@ describe("extractIssueTimelineEvents", () => {
         createdAt: new Date("2026-03-31T12:01:00.000Z"),
         actorType: "user",
         actorId: "local-board",
+        runId: null,
         statusChange: {
           from: "todo",
           to: "in_progress",
@@ -76,6 +77,7 @@ describe("extractIssueTimelineEvents", () => {
         createdAt: new Date("2026-03-31T12:02:00.000Z"),
         actorType: "user",
         actorId: "local-board",
+        runId: null,
         assigneeChange: {
           from: {
             agentId: "agent-1",
@@ -118,6 +120,7 @@ describe("extractIssueTimelineEvents", () => {
         createdAt: new Date("2026-03-31T12:01:00.000Z"),
         actorType: "agent",
         actorId: "agent-1",
+        runId: "run-1",
         statusChange: {
           from: "done",
           to: "todo",
@@ -157,6 +160,7 @@ describe("extractIssueTimelineEvents", () => {
         createdAt: new Date("2026-03-31T12:01:00.000Z"),
         actorType: "agent",
         actorId: "agent-1",
+        runId: "run-1",
         commentId: "comment-1",
         followUpRequested: true,
         statusChange: {
@@ -194,6 +198,7 @@ describe("extractIssueTimelineEvents", () => {
         createdAt: new Date("2026-03-31T12:01:00.000Z"),
         actorType: "agent",
         actorId: "agent-1",
+        runId: "run-1",
         commentId: "comment-1",
         followUpRequested: true,
       },

ui/src/lib/issue-timeline-events.ts

@@ -10,6 +10,7 @@ export interface IssueTimelineEvent {
   createdAt: Date | string;
   actorType: ActivityEvent["actorType"];
   actorId: string;
+  runId?: string | null;
   statusChange?: {
     from: string | null;
     to: string | null;
@@ -67,6 +68,7 @@ export function extractIssueTimelineEvents(activity: ActivityEvent[] | null | un
         createdAt: event.createdAt,
         actorType: event.actorType,
         actorId: event.actorId,
+        runId: event.runId ?? null,
         commentId,
         followUpRequested: true,
       });
@@ -81,6 +83,7 @@ export function extractIssueTimelineEvents(activity: ActivityEvent[] | null | un
       createdAt: event.createdAt,
       actorType: event.actorType,
       actorId: event.actorId,
+      runId: event.runId ?? null,
     };
     if (details.followUpRequested === true || details.resumeIntent === true) {
       timelineEvent.followUpRequested = true;