feat(server): log an activity row for each queued-comment queue mutation (#13159)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The server records actions that change issues and their queued
comments
> - The queued-comment edit, reorder, and discard routes changed queue
state without activity rows
> - Operators could not inspect these queue mutations in the activity
feed
> - This pull request adds one identifier-only activity row for each
successful queue mutation
> - The benefit is a durable audit trail with no comment text in the
activity log

## Linked Issues or Issue Description

**What existing behavior does this improve?**

The queued-comment edit, reorder, and discard routes now record their
successful mutations in the activity feed.

**Subsystem affected**

Cross-cutting (server and ui).

**Current behavior**

The three queue mutation routes change queued comments but do not write
an activity row. The activity feed has no label for these actions.

**Proposed behavior**

Each successful route writes one activity row with the actor fields,
entity fields, queue identifiers, and queue revision. The discard row
also includes the cancelled run identifier. The activity feed shows a
label for each action.

**Reason and benefit**

Operators need a durable record of queue changes. Identifier-only
details support audit and troubleshooting without storing comment text.

**Breaking changes**

None. The routes keep their existing response and authorization
behavior.

**Additional context**

Each mutation writes its activity row on the same locked transaction
that applies the mutation, so the two commit or roll back together. The
route publishes the live activity event only after that transaction
commits. The separate comment-cancel route opts out of this write and
keeps its existing single activity row.

## What Changed

- Add activity rows for queued-comment edit, reorder, and discard
mutations.
- Include queue identifiers, revisions, ordered comment identifiers, and
cancelled run identifiers as applicable.
- Add activity-feed labels for the three new actions.
- Add route and activity-format tests for the new behavior.
- Write each activity row on the same transaction as the mutation it
records, through a new port method that the adapter implements.
- Keep the comment-delete route opted out of that write, so a
cancellation does not log two rows.

## Verification

- [x] `npx vitest run
server/src/__tests__/issue-queued-comments-routes.test.ts` passes.
- [x] `npx vitest run ui/src/lib/activity-format.test.ts` passes.
- [x] `pnpm --filter @paperclipai/server typecheck` exits 0.
- [x] `pnpm --filter @paperclipai/ui typecheck` exits 0.
- [x] `node scripts/check-module-boundaries.mjs` passes.
- [x] The full CI suite is green.

## Risks

Low risk. The change adds activity rows after successful mutations and
does not change route responses, authorization, or stored comment text.

## Model Used

OpenAI Codex, GPT-5 Codex. The model used repository inspection, Git
operations, and command execution. The context window and reasoning mode
are not exposed by this runtime.

## 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>

server/src/modules/wake-queue/application/queued-comment-ports.ts

@@ -13,6 +13,33 @@ export type QueuedCommentActor = {
   actorId: string;
   /** Null for a user actor. */
   agentId: string | null;
+  runId: string | null;
+  agentApiKeyId: string | null;
+};
+
+/** The fields a mutation needs to log its own activity row; entity type is always "issue". */
+export type QueuedCommentActivityLogInput = {
+  actorType: "agent" | "user";
+  actorId: string;
+  agentId: string | null;
+  runId: string | null;
+  agentApiKeyId: string | null;
+  action: string;
+  entityId: string;
+  details: Record<string, unknown>;
+};
+
+/**
+ * Structurally mirrors the server's `ActivityPublication` (from
+ * `services/activity-log.ts`), which this layer cannot import by name --
+ * the module boundary check forbids the application layer from importing
+ * server services. The route casts this back to `ActivityPublication`
+ * before calling `publishActivity`.
+ */
+export type QueuedCommentActivityPublication = {
+  companyId: string;
+  payload: Record<string, unknown>;
+  pluginEvent: unknown;
 };
 
 export type QueuedCommentIssueContext = {
@@ -121,6 +148,13 @@ export interface QueuedCommentQueueTransaction {
   syncCommentReferences(commentId: string): Promise<void>;
   deleteCommentReferenceSource(commentId: string): Promise<void>;
   syncCommentExternalObjectsSafely(commentId: string): Promise<void>;
+  /**
+   * Persists the activity row on this same transaction, so a mutation and
+   * its audit record commit or roll back together. Returns the publication
+   * for the caller to publish once the transaction has committed; this
+   * write never publishes the live event itself.
+   */
+  logActivity(input: QueuedCommentActivityLogInput): Promise<QueuedCommentActivityPublication>;
 }
 
 export interface QueuedCommentIssueLockWriter {

server/src/modules/wake-queue/application/queued-comment-use-cases.test.ts

@@ -9,6 +9,7 @@ import {
 } from "./queued-comment-use-cases.js";
 import type {
   LockedQueuedCommentState,
+  QueuedCommentActivityPublication,
   QueuedCommentActor,
   QueuedCommentEntrySnapshot,
   QueuedCommentIssueContext,
@@ -26,8 +27,24 @@ const ISSUE: QueuedCommentIssueContext = {
   executionRunId: null,
 };
 
-const USER_ACTOR: QueuedCommentActor = { actorType: "user", actorId: "user-1", agentId: null };
-const AGENT_ACTOR: QueuedCommentActor = { actorType: "agent", actorId: "agent-1", agentId: "agent-1" };
+const USER_ACTOR: QueuedCommentActor = {
+  actorType: "user",
+  actorId: "user-1",
+  agentId: null,
+  runId: null,
+  agentApiKeyId: null,
+};
+const AGENT_ACTOR: QueuedCommentActor = {
+  actorType: "agent",
+  actorId: "agent-1",
+  agentId: "agent-1",
+  runId: "run-1",
+  agentApiKeyId: "api-key-1",
+};
+
+function activityPublicationFixture(overrides: Partial<QueuedCommentActivityPublication> = {}): QueuedCommentActivityPublication {
+  return { companyId: ISSUE.companyId, payload: {}, pluginEvent: null, ...overrides };
+}
 
 function wakeRow(overrides: Partial<QueuedCommentWakeRow> = {}): QueuedCommentWakeRow {
   return { id: "wake-1", agentId: "agent-1", status: "deferred_issue_execution", runId: null, payload: {}, ...overrides };
@@ -103,6 +120,7 @@ function createFakeTransaction(overrides: Partial<QueuedCommentQueueTransaction>
     syncCommentReferences: vi.fn(async () => {}),
     deleteCommentReferenceSource: vi.fn(async () => {}),
     syncCommentExternalObjectsSafely: vi.fn(async () => {}),
+    logActivity: vi.fn(async () => activityPublicationFixture()),
     ...overrides,
   };
 }
@@ -135,7 +153,20 @@ describe("editQueuedComment", () => {
     );
     expect(transaction.syncCommentReferences).toHaveBeenCalledWith("comment-1");
     expect(transaction.syncCommentExternalObjectsSafely).toHaveBeenCalledWith("comment-1");
-    expect(result).toEqual(queueSnapshot());
+    expect(result.queue).toEqual(queueSnapshot());
+    // Proves the activity write runs on the same locked transaction as the
+    // mutation, not as a separate statement after it commits.
+    expect(transaction.logActivity).toHaveBeenCalledWith({
+      actorType: "user",
+      actorId: "user-1",
+      agentId: null,
+      runId: null,
+      agentApiKeyId: null,
+      action: "issue.queued_comment_edited",
+      entityId: "issue-1",
+      details: { commentId: "comment-1", queueId: "wake-1", revision: "rev-1" },
+    });
+    expect(result.activityPublication).toEqual(activityPublicationFixture());
   });
 
   it("rejects a stale queue id with queued_comment_stale_queue", async () => {
@@ -219,7 +250,7 @@ describe("reorderQueuedComments", () => {
     const transaction = createFakeTransaction();
     const reorderQueuedComments = createReorderQueuedComments({ issueLock: createFakeIssueLock(locked, transaction) });
 
-    await reorderQueuedComments({
+    const result = await reorderQueuedComments({
       issue: ISSUE,
       actor: USER_ACTOR,
       queueId: "wake-1",
@@ -231,6 +262,19 @@ describe("reorderQueuedComments", () => {
     expect(transaction.updateWakeQueuedCommentIds).toHaveBeenCalledWith(
       expect.objectContaining({ wakeId: "wake-1", ids: ["b", "a"] }),
     );
+    // Proves the activity write runs on the same locked transaction as the
+    // mutation, not as a separate statement after it commits.
+    expect(transaction.logActivity).toHaveBeenCalledWith({
+      actorType: "user",
+      actorId: "user-1",
+      agentId: null,
+      runId: null,
+      agentApiKeyId: null,
+      action: "issue.queued_comments_reordered",
+      entityId: "issue-1",
+      details: { queueId: "wake-1", revision: "rev-1", orderedCommentIds: ["b", "a"] },
+    });
+    expect(result.activityPublication).toEqual(activityPublicationFixture());
   });
 
   it("rejects an order that is not a permutation of the current queue", async () => {
@@ -266,6 +310,7 @@ describe("discardQueuedComment", () => {
       queueId: "wake-1",
       revision: "rev-1",
       now: new Date(),
+      logActivity: true,
     });
 
     expect(transaction.cancelWake).toHaveBeenCalledWith(expect.objectContaining({ wakeId: "wake-1" }));
@@ -274,6 +319,37 @@ describe("discardQueuedComment", () => {
       expect.objectContaining({ executionRunId: "run-1" }),
     );
     expect(result.cancelledRun).toEqual({ id: "run-1" });
+    // Proves the activity write runs on the same locked transaction as the
+    // mutation, and that the cancelled run's own id lands in its details.
+    expect(transaction.logActivity).toHaveBeenCalledWith({
+      actorType: "user",
+      actorId: "user-1",
+      agentId: null,
+      runId: null,
+      agentApiKeyId: null,
+      action: "issue.queued_comment_discarded",
+      entityId: "issue-1",
+      details: { commentId: "comment-1", queueId: "wake-1", revision: "rev-1", cancelledRunId: "run-1" },
+    });
+    expect(result.activityPublication).toEqual(activityPublicationFixture());
+  });
+
+  it("logs no activity row when the caller does not request one, matching the comment-delete route's cancellation call site", async () => {
+    const locked = lockedState({ state: "queued", queueRun: runRow({ id: "run-1" }) });
+    const transaction = createFakeTransaction();
+    const discardQueuedComment = createDiscardQueuedComment({ issueLock: createFakeIssueLock(locked, transaction) });
+
+    const result = await discardQueuedComment({
+      issue: ISSUE,
+      actor: USER_ACTOR,
+      commentId: "comment-1",
+      queueId: "wake-1",
+      revision: "rev-1",
+      now: new Date(),
+    });
+
+    expect(transaction.logActivity).not.toHaveBeenCalled();
+    expect(result.activityPublication).toBeNull();
   });
 
   it("rewrites the remaining ids when other queued comments are left", async () => {

server/src/modules/wake-queue/application/queued-comment-use-cases.ts

@@ -4,6 +4,7 @@ import {
   decideQueuedCommentReorder,
 } from "../domain/policy.js";
 import type {
+  QueuedCommentActivityPublication,
   QueuedCommentActor,
   QueuedCommentIssueContext,
   QueuedCommentIssueLockWriter,
@@ -74,8 +75,13 @@ export type EditQueuedCommentInput = {
   now: Date;
 };
 
+export type EditQueuedCommentResult = {
+  queue: QueuedCommentQueueSnapshot;
+  activityPublication: QueuedCommentActivityPublication;
+};
+
 export function createEditQueuedComment(deps: { issueLock: QueuedCommentIssueLockWriter }) {
-  return async function editQueuedComment(input: EditQueuedCommentInput): Promise<QueuedCommentQueueSnapshot> {
+  return async function editQueuedComment(input: EditQueuedCommentInput): Promise<EditQueuedCommentResult> {
     return deps.issueLock.withLockedQueue(
       { issue: input.issue, actor: input.actor, queueId: input.queueId },
       async (locked, tx) => {
@@ -108,7 +114,7 @@ export function createEditQueuedComment(deps: { issueLock: QueuedCommentIssueLoc
           updatedAt: input.now,
         });
 
-        return tx.buildQueueSnapshot({
+        const queue = await tx.buildQueueSnapshot({
           issue: input.issue,
           actor: input.actor,
           wake: locked.wake,
@@ -116,6 +122,23 @@ export function createEditQueuedComment(deps: { issueLock: QueuedCommentIssueLoc
           queueRun: updatedQueueRun ?? locked.queueRun,
           activeRun: locked.activeRun,
         });
+
+        const activityPublication = await tx.logActivity({
+          actorType: input.actor.actorType,
+          actorId: input.actor.actorId,
+          agentId: input.actor.agentId,
+          runId: input.actor.runId,
+          agentApiKeyId: input.actor.agentApiKeyId,
+          action: "issue.queued_comment_edited",
+          entityId: input.issue.id,
+          details: {
+            commentId: input.commentId,
+            queueId: input.queueId,
+            revision: queue.revision,
+          },
+        });
+
+        return { queue, activityPublication };
       },
     );
   };
@@ -130,8 +153,13 @@ export type ReorderQueuedCommentsInput = {
   now: Date;
 };
 
+export type ReorderQueuedCommentsResult = {
+  queue: QueuedCommentQueueSnapshot;
+  activityPublication: QueuedCommentActivityPublication;
+};
+
 export function createReorderQueuedComments(deps: { issueLock: QueuedCommentIssueLockWriter }) {
-  return async function reorderQueuedComments(input: ReorderQueuedCommentsInput): Promise<QueuedCommentQueueSnapshot> {
+  return async function reorderQueuedComments(input: ReorderQueuedCommentsInput): Promise<ReorderQueuedCommentsResult> {
     return deps.issueLock.withLockedQueue(
       { issue: input.issue, actor: input.actor, queueId: input.queueId },
       async (locked, tx) => {
@@ -158,7 +186,7 @@ export function createReorderQueuedComments(deps: { issueLock: QueuedCommentIssu
           updatedAt: input.now,
         });
 
-        return tx.buildQueueSnapshot({
+        const queue = await tx.buildQueueSnapshot({
           issue: input.issue,
           actor: input.actor,
           wake: updatedWake,
@@ -166,6 +194,23 @@ export function createReorderQueuedComments(deps: { issueLock: QueuedCommentIssu
           queueRun: updatedQueueRun ?? locked.queueRun,
           activeRun: locked.activeRun,
         });
+
+        const activityPublication = await tx.logActivity({
+          actorType: input.actor.actorType,
+          actorId: input.actor.actorId,
+          agentId: input.actor.agentId,
+          runId: input.actor.runId,
+          agentApiKeyId: input.actor.agentApiKeyId,
+          action: "issue.queued_comments_reordered",
+          entityId: input.issue.id,
+          details: {
+            queueId: input.queueId,
+            revision: queue.revision,
+            orderedCommentIds: input.orderedCommentIds,
+          },
+        });
+
+        return { queue, activityPublication };
       },
     );
   };
@@ -179,6 +224,13 @@ export type DiscardQueuedCommentInput = {
   /** Skipped entirely when omitted, matching the comment-delete route's cancellation call site, which does not carry a revision. */
   revision?: string;
   now: Date;
+  /**
+   * Set only by the queue-discard route. The comment-delete route's
+   * cancellation call site omits this: it already logs its own
+   * `issue.comment_cancelled` row outside this use case, and this flag
+   * would otherwise double-log that same discard.
+   */
+  logActivity?: boolean;
 };
 
 export type DiscardQueuedCommentResult = {
@@ -187,6 +239,8 @@ export type DiscardQueuedCommentResult = {
   queue: QueuedCommentQueueSnapshot;
   /** Set only when the discard emptied the queue and cancelled a queued run; the caller emits telemetry for it after the transaction commits. */
   cancelledRun: { id: string } | null;
+  /** Set only when `input.logActivity` was true; the caller publishes it once the transaction commits. */
+  activityPublication: QueuedCommentActivityPublication | null;
 };
 
 export function createDiscardQueuedComment(deps: { issueLock: QueuedCommentIssueLockWriter }) {
@@ -278,7 +332,25 @@ export function createDiscardQueuedComment(deps: { issueLock: QueuedCommentIssue
           activeRun: locked.activeRun,
         });
 
-        return { deleted, queue, cancelledRun };
+        const activityPublication = input.logActivity
+          ? await tx.logActivity({
+              actorType: input.actor.actorType,
+              actorId: input.actor.actorId,
+              agentId: input.actor.agentId,
+              runId: input.actor.runId,
+              agentApiKeyId: input.actor.agentApiKeyId,
+              action: "issue.queued_comment_discarded",
+              entityId: input.issue.id,
+              details: {
+                commentId: input.commentId,
+                queueId: input.queueId,
+                revision: queue.revision,
+                cancelledRunId: cancelledRun?.id ?? null,
+              },
+            })
+          : null;
+
+        return { deleted, queue, cancelledRun, activityPublication };
       },
     );
   };