feat(decisions): add desk workflow and retention (#10672)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - The Decisions desk shows work that needs a human decision
> - The queue foundation can group and rank decision work
> - Operators also need a focused daily view and a safe way to handle
old work
> - This pull request adds the desk controls, the aging shelf, and
reversible retention
> - It also binds bulk archive decisions to the exact reviewed item set
> - The benefit is a smaller daily queue without lost or orphaned work

## Linked Issues or Issue Description

**Subsystem affected**

Cross-cutting: server, UI, database, and shared contracts.

**Problem or motivation**

Decision work can grow into one large company list. Operators need quick
queue and date controls. Old items also need a safe retention path that
does not delete work.

**Proposed solution**

Add queue and date controls to the Decisions desk. Compute the aging
shelf on the server. Archive idle items after 90 days unless an operator
keeps them. Keep archived items searchable and revivable. Notify origin
agents in one batch per sweep. Bind bulk archive proposals to a signed,
exact item manifest.

**Alternatives considered**

Client-only aging can drift across browsers and source kinds. Deleting
old rows removes audit and recovery paths. An unsigned dynamic bulk
query can archive items that the reviewer did not inspect.

**Roadmap alignment**

This work supports the Work Queues and decision-memory directions in
`ROADMAP.md`. It extends the Decisions and attention-feed foundation
from #10651. Related earlier work includes #9380, #10010, and #10474.

## What Changed

- Added the queue rail, date chips, decide split, triage strip, queue
page, and aging shelf UI.
- Added server-owned shelf state with per-queue retention overrides.
- Added reversible retention state, archive history, and an idempotent
notification outbox.
- Added the 90-day archive sweeper, Keep exemption, archived feed query,
and revive actions.
- Added one origin-agent notification per agent and sweep.
- Added signed bulk archive proposals with exact-set and version checks.
- Persisted queue-exclusion reasons atomically and kept cross-domain
source resolution per-item until it has an exact-set transaction
contract.
- Added API contracts, OpenAPI entries, migration coverage, focused
tests, and Storybook screens.

## Verification

- `pnpm -r typecheck`
- `pnpm test:run` (server: 329 files and 3,453 tests passed; UI: 408
files and 3,362 tests passed)
- `env -u AWS_ACCESS_KEY_ID -u AWS_SECRET_ACCESS_KEY pnpm exec vitest
run cli/src/__tests__/secrets.test.ts`
- `pnpm build`
- `pnpm check:token-gates`
- Focused retention, attention, decisions, migration replay, startup,
and UI API tests.
- Complete queue snapshot regression with 51 items across the normal
50-item page boundary.

The unmodified CLI test reports one warning assertion in this runtime
because the harness injects static AWS credential variables. The
isolated test passes when those two variables are removed.

## Risks

- The migration adds retention and notification outbox tables. It uses
idempotent table, index, and foreign-key creation.
- Retention runs on the heartbeat scheduler interval. Compare-and-set
version checks prevent stale archive writes.
- Bulk archive acceptance fails closed when authority, activity,
version, or the reviewed set changes.
- Archive is reversible and does not delete source records.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

OpenAI Codex with `gpt-5.6-sol`. The model used tool calls, code
execution, database migration generation, and test execution. The
context-window size is not exposed in 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: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: Paperclip <noreply@paperclip.ing>

server/src/routes/attention.ts

@@ -25,6 +25,8 @@ export function attentionRoutes(db: Db) {
     }
 
     const includeDismissed = req.query.includeDismissed === "true";
+    const archived = req.query.archived === "true";
+    const all = req.query.all === "true";
     const activitySince = optionalQueryString(req.query.activitySince, "activitySince");
     const activityUntil = optionalQueryString(req.query.activityUntil, "activityUntil");
     const queue = optionalQueryString(req.query.queue, "queue");
@@ -39,6 +41,8 @@ export function attentionRoutes(db: Db) {
     const feed = await svc.list(companyId, {
       userId: req.actor.userId,
       includeDismissed,
+      archived,
+      all,
       activitySince,
       activityUntil,
       queue,

server/src/routes/decision-queues.ts

@@ -4,7 +4,9 @@ import {
   addDecisionQueueItemSchema,
   createDecisionQueueSchema,
   decisionAttentionSourceKindSchema,
+  removeDecisionQueueItemSchema,
   updateDecisionQueueSchema,
+  updateDecisionRetentionSchema,
   updateDecisionTriageSchema,
 } from "@paperclipai/shared";
 import { forbidden } from "../errors.js";
@@ -20,6 +22,7 @@ import {
   type DecisionMutationActor,
 } from "../services/decision-queues.js";
 import { assertBoardOrAgent, assertCompanyAccess, getActorInfo } from "./authz.js";
+import { decisionRetentionService } from "../services/decision-retention.js";
 
 function mutationActor(req: Parameters<typeof getActorInfo>[0]): DecisionMutationActor {
   const actor = getActorInfo(req);
@@ -63,6 +66,7 @@ function sourceParams(req: Parameters<typeof getActorInfo>[0]) {
 export function decisionQueueRoutes(db: Db) {
   const router = Router();
   const svc = decisionQueueService(db);
+  const retention = decisionRetentionService(db);
 
   router.get("/companies/:companyId/decision-queue-seed-rules", async (req, res) => {
     const companyId = req.params.companyId as string;
@@ -124,22 +128,27 @@ export function decisionQueueRoutes(db: Db) {
     },
   );
 
-  router.delete("/companies/:companyId/decision-queues/:key/items/:sourceKind/:sourceId", async (req, res) => {
-    const companyId = req.params.companyId as string;
-    await assertDecisionAccess(db, req, companyId, "decision_queue:manage");
-    const source = sourceParams(req);
-    if (!source) {
-      res.status(400).json({ error: "Invalid attention source identity" });
-      return;
-    }
-    res.json(await svc.removeItem({
-      companyId,
-      key: req.params.key as string,
-      ...source,
-      authActor: req.actor,
-      actor: mutationActor(req),
-    }));
-  });
+  router.delete(
+    "/companies/:companyId/decision-queues/:key/items/:sourceKind/:sourceId",
+    validate(removeDecisionQueueItemSchema),
+    async (req, res) => {
+      const companyId = req.params.companyId as string;
+      await assertDecisionAccess(db, req, companyId, "decision_queue:manage");
+      const source = sourceParams(req);
+      if (!source) {
+        res.status(400).json({ error: "Invalid attention source identity" });
+        return;
+      }
+      res.json(await svc.removeItem({
+        companyId,
+        key: req.params.key as string,
+        ...source,
+        reason: req.body.reason,
+        authActor: req.actor,
+        actor: mutationActor(req),
+      }));
+    },
+  );
 
   router.get("/companies/:companyId/decision-triage/:sourceKind/:sourceId", async (req, res) => {
     const companyId = req.params.companyId as string;
@@ -173,5 +182,48 @@ export function decisionQueueRoutes(db: Db) {
     },
   );
 
+  router.patch(
+    "/companies/:companyId/decision-retention/:sourceKind/:sourceId",
+    validate(updateDecisionRetentionSchema),
+    async (req, res) => {
+      const companyId = req.params.companyId as string;
+      await assertDecisionAccess(db, req, companyId, "decision_triage:manage");
+      const source = sourceParams(req);
+      if (!source) {
+        res.status(400).json({ error: "Invalid attention source identity" });
+        return;
+      }
+      res.json(await retention.setKeep({
+        companyId,
+        ...source,
+        keep: req.body.keep,
+        authActor: req.actor,
+        actor: mutationActor(req),
+      }));
+    },
+  );
+
+  router.post("/companies/:companyId/decision-retention/:sourceKind/:sourceId/archive", async (req, res) => {
+    const companyId = req.params.companyId as string;
+    await assertDecisionAccess(db, req, companyId, "decision_triage:manage");
+    const source = sourceParams(req);
+    if (!source) {
+      res.status(400).json({ error: "Invalid attention source identity" });
+      return;
+    }
+    res.json(await retention.archive({ companyId, ...source, authActor: req.actor, actor: mutationActor(req) }));
+  });
+
+  router.post("/companies/:companyId/decision-retention/:sourceKind/:sourceId/revive", async (req, res) => {
+    const companyId = req.params.companyId as string;
+    await assertDecisionAccess(db, req, companyId, "decision_triage:manage");
+    const source = sourceParams(req);
+    if (!source) {
+      res.status(400).json({ error: "Invalid attention source identity" });
+      return;
+    }
+    res.json(await retention.revive({ companyId, ...source, authActor: req.actor, actor: mutationActor(req) }));
+  });
+
   return router;
 }

server/src/routes/decisions.ts

@@ -1,10 +1,23 @@
 import { Router } from "express";
 import { z } from "zod";
 import type { Db } from "@paperclipai/db";
-import { decisionInputsSchema, decisionOptionsSchema } from "@paperclipai/shared";
+import {
+  createDecisionArchiveProposalSchema,
+  decisionInputsSchema,
+  decisionOptionsSchema,
+  type AttentionArchiveManifestEntry,
+  type AttentionArchiveTargetSnapshot,
+  type AttentionItem,
+  type CreateDecisionArchiveProposalInput,
+} from "@paperclipai/shared";
 import { validate } from "../middleware/validate.js";
 import { decisionService, type DecisionServiceOptions } from "../services/decisions.js";
 import { assertBoard, assertBoardOrAgent, assertCompanyAccess, getAccessibleResource, getActorInfo } from "./authz.js";
+import { attentionService } from "../services/attention.js";
+import { authorizationDeniedDetails, authorizationService } from "../services/authorization.js";
+import { canReadDecisionSource } from "../services/decision-queues.js";
+import { hashAttentionArchiveManifest } from "../services/decision-retention.js";
+import { forbidden, unprocessable } from "../errors.js";
 
 const createSchema = z.object({
   title: z.string().trim().min(1).max(500),
@@ -39,6 +52,89 @@ function boardUserId(req: Parameters<typeof getActorInfo>[0]) {
 export function decisionRoutes(db: Db, options: DecisionServiceOptions) {
   const router = Router();
   const svc = decisionService(db, options);
+  router.post(
+    "/companies/:companyId/decision-archive-proposals",
+    validate(createDecisionArchiveProposalSchema),
+    async (req, res) => {
+      const companyId = req.params.companyId as string;
+      assertCompanyAccess(req, companyId);
+      const agent = agentContext(req);
+      if (!agent) {
+        res.status(403).json({ error: "Agent run context required" });
+        return;
+      }
+      const access = await authorizationService(db).decide({
+        actor: req.actor,
+        action: "decision_triage:manage",
+        resource: { type: "company", companyId },
+      });
+      if (!access.allowed) throw forbidden(access.explanation, authorizationDeniedDetails(access));
+
+      const proposal = req.body as CreateDecisionArchiveProposalInput;
+      const requested = new Map<string, CreateDecisionArchiveProposalInput["items"][number]>(proposal.items.map((item) => [
+        `${item.sourceKind}:${item.sourceId}`,
+        item,
+      ]));
+      const found = new Map<string, AttentionItem>();
+      const snapshot = await db.transaction(async (tx) => attentionService(tx as unknown as Db).list(companyId, {
+        includeDismissed: true,
+        all: true,
+        allowUnscopedAll: true,
+      }), { isolationLevel: "repeatable read" });
+      for (const item of snapshot.items) {
+        const key = `${item.sourceKind}:${item.subject.id}`;
+        if (requested.has(key)) found.set(key, item);
+      }
+
+      const manifest: AttentionArchiveManifestEntry[] = [];
+      for (const [key, item] of [...requested.entries()].sort(([left], [right]) => left.localeCompare(right))) {
+        const attentionItem = found.get(key);
+        if (!attentionItem || !attentionItem.shelf || attentionItem.archivedAt) {
+          throw unprocessable("Every archive proposal item must be on the current aging shelf");
+        }
+        if (!(await canReadDecisionSource(db, req.actor, companyId, attentionItem.sourceKind, attentionItem.subject.id))) {
+          throw unprocessable("Every archive proposal item must be on the current aging shelf");
+        }
+        manifest.push({
+          companyId,
+          sourceKind: attentionItem.sourceKind,
+          sourceId: attentionItem.subject.id,
+          expectedVersion: attentionItem.retentionVersion,
+          activityAt: attentionItem.activityAt,
+          reason: item.reason,
+        });
+      }
+      const manifestHash = hashAttentionArchiveManifest(manifest);
+      const targetSnapshots = Object.fromEntries(manifest.map((entry) => [
+        `attention:${entry.sourceKind}:${entry.sourceId}`,
+        {
+          status: "attention",
+          assigneeAgentId: null,
+          assigneeUserId: null,
+          updatedAt: entry.activityAt,
+          attentionArchive: entry,
+        } satisfies AttentionArchiveTargetSnapshot,
+      ]));
+      const body = manifest.map((entry) => `- **${entry.sourceKind}:${entry.sourceId}** — ${entry.reason}`).join("\n");
+      const created = await svc.create({
+        companyId,
+        actor: req.actor,
+        ...agent,
+        title: `Archive ${manifest.length} aging decision${manifest.length === 1 ? "" : "s"}?`,
+        body,
+        ruleKey: "attention.bulk_archive",
+        idempotencyKey: proposal.idempotencyKey ?? `attention-archive:${manifestHash}:${agent.runId}`,
+        continuationPolicy: "wake_origin_agent",
+        options: [
+          { id: "archive", label: "Archive reviewed items", style: "destructive", effects: [] },
+          { id: "keep", label: "Keep items", effects: [] },
+        ],
+        metadata: { kind: "attention_archive_proposal", manifestHash },
+        additionalTargetSnapshots: targetSnapshots,
+      });
+      res.status(201).json(created);
+    },
+  );
   router.post("/companies/:companyId/decisions", validate(createSchema), async (req, res) => {
     const companyId = req.params.companyId as string; assertCompanyAccess(req, companyId);
     const agent = agentContext(req); if (!agent) { res.status(403).json({ error: "Agent run context required" }); return; }

server/src/routes/openapi.ts

@@ -50,11 +50,14 @@ import {
   // Decisions
   addDecisionQueueItemSchema,
   createDecisionQueueSchema,
+  createDecisionArchiveProposalSchema,
   decisionAttentionSourceKindSchema,
   decisionInputsSchema,
   decisionOptionsSchema,
+  removeDecisionQueueItemSchema,
   updateDecisionQueueSchema,
   updateDecisionTriageSchema,
+  updateDecisionRetentionSchema,
   // Routine
   createRoutineSchema,
   updateRoutineSchema,
@@ -3276,7 +3279,20 @@ registry.registerPath({
   path: "/api/companies/{companyId}/attention",
   tags: ["inbox"],
   summary: "List decision-only attention feed items",
-  request: { params: z.object({ companyId: z.string() }) },
+  request: {
+    params: z.object({ companyId: z.string() }),
+    query: z.object({
+      includeDismissed: z.enum(["true", "false"]).optional(),
+      archived: z.enum(["true", "false"]).optional(),
+      all: z.enum(["true", "false"]).optional(),
+      activitySince: z.string().datetime().optional(),
+      activityUntil: z.string().datetime().optional(),
+      queue: z.string().min(1).optional(),
+      sort: z.enum(["activity", "decide"]).optional(),
+      cursor: z.string().min(1).optional(),
+      limit: z.coerce.number().int().min(1).max(100).optional(),
+    }),
+  },
   responses: { 200: r.ok(), 401: r.unauthorized, 403: r.forbidden },
 });
 
@@ -3343,6 +3359,25 @@ const decisionTriageSchema = z.object({
   updatedAt: z.string().datetime(),
 }).strict();
 
+const decisionRetentionSchema = z.object({
+  id: z.string(),
+  companyId: z.string(),
+  sourceKind: decisionAttentionSourceKindSchema,
+  sourceId: z.string(),
+  sourceActivityAt: z.string().datetime(),
+  keep: z.boolean(),
+  archivedAt: z.string().datetime().nullable(),
+  archivedReason: z.string().nullable(),
+  archivedByType: z.enum(["agent", "user", "system"]).nullable(),
+  archivedByAgentId: z.string().nullable(),
+  archivedByUserId: z.string().nullable(),
+  archivedByRunId: z.string().nullable(),
+  version: z.number().int().positive(),
+  archiveVersion: z.number().int().nonnegative(),
+  createdAt: z.string().datetime(),
+  updatedAt: z.string().datetime(),
+}).strict();
+
 registerCurrentRoute({
   method: "get",
   path: "/api/companies/{companyId}/decision-queue-seed-rules",
@@ -3423,6 +3458,7 @@ registerCurrentRoute({
   path: "/api/companies/{companyId}/decision-queues/{key}/items/{sourceKind}/{sourceId}",
   tags: ["decision-queues"],
   summary: "Remove an item from a decision queue",
+  body: removeDecisionQueueItemSchema,
   responses: {
     200: r.ok(decisionQueueItemSchema),
     400: r.badRequest,
@@ -3462,6 +3498,34 @@ registerCurrentRoute({
   },
 });
 
+registerCurrentRoute({
+  method: "patch",
+  path: "/api/companies/{companyId}/decision-retention/{sourceKind}/{sourceId}",
+  tags: ["decision-queues"],
+  summary: "Set Keep for an attention source",
+  body: updateDecisionRetentionSchema,
+  responses: { 200: r.ok(decisionRetentionSchema), 400: r.badRequest, 401: r.unauthorized, 403: r.forbidden, 404: r.notFound },
+});
+
+for (const action of ["archive", "revive"] as const) {
+  registerCurrentRoute({
+    method: "post",
+    path: `/api/companies/{companyId}/decision-retention/{sourceKind}/{sourceId}/${action}`,
+    tags: ["decision-queues"],
+    summary: action === "archive" ? "Archive an attention source" : "Revive an archived attention source",
+    responses: { 200: r.ok(decisionRetentionSchema), 400: r.badRequest, 401: r.unauthorized, 403: r.forbidden, 404: r.notFound },
+  });
+}
+
+registerCurrentRoute({
+  method: "post",
+  path: "/api/companies/{companyId}/decision-archive-proposals",
+  tags: ["decisions"],
+  summary: "Propose one signed bulk archive decision",
+  body: createDecisionArchiveProposalSchema,
+  responses: { 201: r.ok(), 400: r.badRequest, 401: r.unauthorized, 403: r.forbidden, 409: r.conflict, 422: r.unprocessable },
+});
+
 // Decisions
 
 const createDecisionBodySchema = z.object({