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/services/attention.ts

@@ -51,6 +51,10 @@ import { issueService } from "./issues.js";
 import { parseIssueExecutionState } from "./issue-execution-policy.js";
 import { isProspectiveBlockedTransition } from "./routable-blocked.js";
 import { decisionQueueService } from "./decision-queues.js";
+import {
+  decisionRetentionService,
+  DEFAULT_DECISION_SHELF_DAYS,
+} from "./decision-retention.js";
 
 const ATTENTION_SOURCE_KINDS: AttentionSourceKind[] = [
   "approval",
@@ -135,6 +139,8 @@ type BlockingIssueSummary = {
 
 type AttentionListOptions = AttentionFeedQuery & {
   userId?: string | null;
+  /** Internal-only escape hatch for callers that need one stable, unpaginated feed snapshot. */
+  allowUnscopedAll?: boolean;
 };
 
 type AttentionServiceOptions = {
@@ -344,6 +350,11 @@ type CreateAttentionItemInput = Omit<AttentionItem,
   | "ruleKey"
   | "originAgentName"
   | "queues"
+  | "shelf"
+  | "retentionDays"
+  | "keep"
+  | "archivedAt"
+  | "retentionVersion"
   | "decideBy"
   | "decideByAttribution"
   | "snoozedUntil"
@@ -370,6 +381,11 @@ function createItem(input: CreateAttentionItemInput): AttentionItem {
     ruleKey: input.ruleKey ?? null,
     originAgentName: input.originAgentName ?? null,
     queues: [],
+    shelf: false,
+    retentionDays: DEFAULT_DECISION_SHELF_DAYS,
+    keep: false,
+    archivedAt: null,
+    retentionVersion: 0,
     decideBy: null,
     decideByAttribution: null,
     snoozedUntil: null,
@@ -479,7 +495,7 @@ function parseActivityBoundary(value: string | undefined, field: "activitySince"
   return parsed;
 }
 
-async function enrichAttentionItems(db: Db, companyId: string, items: AttentionItem[]) {
+async function enrichAttentionItems(db: Db, companyId: string, items: AttentionItem[], now: number) {
   if (items.length === 0) return items;
   const sourceIds = [...new Set(items.map((item) => item.subject.id))];
   const queueRows = await db
@@ -488,6 +504,7 @@ async function enrichAttentionItems(db: Db, companyId: string, items: AttentionI
       sourceId: decisionQueueItems.sourceId,
       key: decisionQueues.key,
       title: decisionQueues.title,
+      retentionDays: decisionQueues.retentionDays,
     })
     .from(decisionQueueItems)
     .innerJoin(decisionQueues, and(
@@ -500,11 +517,17 @@ async function enrichAttentionItems(db: Db, companyId: string, items: AttentionI
     ))
     .orderBy(asc(decisionQueues.title), asc(decisionQueues.key));
   const queuesBySource = new Map<string, AttentionQueueRef[]>();
+  const retentionDaysBySource = new Map<string, number[]>();
   for (const row of queueRows) {
     const key = sourceKey(row.sourceKind as AttentionSourceKind, row.sourceId);
     const queues = queuesBySource.get(key) ?? [];
     queues.push({ key: row.key, title: row.title });
     queuesBySource.set(key, queues);
+    if (row.retentionDays != null) {
+      const values = retentionDaysBySource.get(key) ?? [];
+      values.push(row.retentionDays);
+      retentionDaysBySource.set(key, values);
+    }
   }
 
   const triageRows = await db
@@ -529,7 +552,7 @@ async function enrichAttentionItems(db: Db, companyId: string, items: AttentionI
     .where(and(eq(agents.companyId, companyId), inArray(agents.id, agentIds)))
     .then((rows) => rows.map((row) => [row.id, row.name] as const)));
 
-  return items.map((item) => {
+  const enriched = items.map((item) => {
     const triage = triageBySource.get(itemSourceKey(item));
     const decideBy = triage?.decideBy === "date" ? triage.decideByDate : triage?.decideBy ?? null;
     const decideByAttribution: AttentionTriageAttribution | null = triage ? {
@@ -551,6 +574,21 @@ async function enrichAttentionItems(db: Db, companyId: string, items: AttentionI
       snoozedUntil: triage?.snoozedUntil ? toIso(triage.snoozedUntil) : null,
     };
   });
+  const retentionBySource = await decisionRetentionService(db).syncItems(companyId, enriched);
+  return enriched.map((item) => {
+    const key = itemSourceKey(item);
+    const retention = retentionBySource.get(key);
+    const overrides = retentionDaysBySource.get(key) ?? [];
+    const retentionDays = overrides.length > 0 ? Math.min(...overrides) : DEFAULT_DECISION_SHELF_DAYS;
+    return {
+      ...item,
+      shelf: timestamp(item.activityAt) <= now - retentionDays * 86_400_000,
+      retentionDays,
+      keep: retention?.keep ?? false,
+      archivedAt: retention?.archivedAt ? toIso(retention.archivedAt) : null,
+      retentionVersion: retention?.version ?? 0,
+    };
+  });
 }
 
 function betterDuplicate(left: AttentionItem, right: AttentionItem) {
@@ -824,6 +862,9 @@ export function attentionService(db: Db, serviceOptions: AttentionServiceOptions
   );
   return {
     list: async (companyId: string, options: AttentionListOptions = {}): Promise<AttentionFeed> => {
+      if (options.all && !options.queue && !options.allowUnscopedAll) {
+        throw badRequest("all requires a queue filter");
+      }
       const prefix = await companyPrefix(db, companyId);
       const dismissals = await dismissalByKey(db, companyId, options.userId);
       const includeDismissed = options.includeDismissed === true;
@@ -1592,7 +1633,7 @@ export function attentionService(db: Db, serviceOptions: AttentionServiceOptions
 
       const collectedItems = [...deduped.values()].sort(compareAttentionItems);
       await decisionQueueService(db).materializeSeededQueues(companyId, collectedItems);
-      const enrichedItems = await enrichAttentionItems(db, companyId, collectedItems);
+      const enrichedItems = await enrichAttentionItems(db, companyId, collectedItems, now);
 
       const activitySince = parseActivityBoundary(options.activitySince, "activitySince");
       const activityUntil = parseActivityBoundary(options.activityUntil, "activityUntil");
@@ -1601,6 +1642,7 @@ export function attentionService(db: Db, serviceOptions: AttentionServiceOptions
       }
       const queueKey = options.queue?.trim() || null;
       const visibleItems = enrichedItems.filter((item) => {
+        if (options.archived === true ? !item.archivedAt : Boolean(item.archivedAt)) return false;
         if (!includeDismissed && item.snoozedUntil && timestamp(item.snoozedUntil) > now) return false;
         const activity = timestamp(item.activityAt);
         if (activitySince != null && activity < activitySince) return false;
@@ -1616,20 +1658,30 @@ export function attentionService(db: Db, serviceOptions: AttentionServiceOptions
           ? (left, right) => compareDecideItems(left, right, now)
           : compareAttentionItems)
         .map((item, index) => ({ ...item, rank: index + 1 }));
-      const limit = options.limit ?? ATTENTION_PAGE_DEFAULT_LIMIT;
-      if (!Number.isInteger(limit) || limit < 1 || limit > ATTENTION_PAGE_MAX_LIMIT) {
-        throw badRequest(`limit must be an integer between 1 and ${ATTENTION_PAGE_MAX_LIMIT}`);
+      let items: AttentionItem[];
+      let nextCursor: string | null;
+      if (options.all) {
+        if (options.cursor || options.limit !== undefined) {
+          throw badRequest("all cannot be combined with cursor or limit");
+        }
+        items = rankedItems;
+        nextCursor = null;
+      } else {
+        const limit = options.limit ?? ATTENTION_PAGE_DEFAULT_LIMIT;
+        if (!Number.isInteger(limit) || limit < 1 || limit > ATTENTION_PAGE_MAX_LIMIT) {
+          throw badRequest(`limit must be an integer between 1 and ${ATTENTION_PAGE_MAX_LIMIT}`);
+        }
+        let pageStart = 0;
+        if (options.cursor) {
+          const cursorItemId = decodeCursor(options.cursor, sort);
+          const cursorIndex = rankedItems.findIndex((item) => item.id === cursorItemId);
+          if (cursorIndex < 0) throw badRequest("Attention cursor no longer matches the filtered feed");
+          pageStart = cursorIndex + 1;
+        }
+        items = rankedItems.slice(pageStart, pageStart + limit);
+        const hasNextPage = pageStart + items.length < rankedItems.length;
+        nextCursor = hasNextPage && items.length > 0 ? encodeCursor(sort, items[items.length - 1]!) : null;
       }
-      let pageStart = 0;
-      if (options.cursor) {
-        const cursorItemId = decodeCursor(options.cursor, sort);
-        const cursorIndex = rankedItems.findIndex((item) => item.id === cursorItemId);
-        if (cursorIndex < 0) throw badRequest("Attention cursor no longer matches the filtered feed");
-        pageStart = cursorIndex + 1;
-      }
-      const items = rankedItems.slice(pageStart, pageStart + limit);
-      const hasNextPage = pageStart + items.length < rankedItems.length;
-      const nextCursor = hasNextPage && items.length > 0 ? encodeCursor(sort, items[items.length - 1]!) : null;
 
       if (options.userId) {
         const trainable: Array<{ sourceKind: "approval" | "interaction"; sourceId: string }> = [];

server/src/services/decision-queues.ts

@@ -534,6 +534,7 @@ export function decisionQueueService(db: Db) {
       key: string;
       sourceKind: AttentionSourceKind;
       sourceId: string;
+      reason?: string;
       authActor: AuthorizationActor;
       actor: DecisionMutationActor;
     }) => {
@@ -569,6 +570,7 @@ export function decisionQueueService(db: Db) {
           sourceKind: input.sourceKind,
           sourceId: input.sourceId,
           action: "queue_item.removed",
+          details: input.reason ? { reason: input.reason } : {},
           ...eventActorColumns(input.actor),
         });
         await recordActivity(txDb, input.actor, {
@@ -576,7 +578,11 @@ export function decisionQueueService(db: Db) {
           action: "decision_queue_item.removed",
           entityType: "decision_queue",
           entityId: queue.id,
-          details: { sourceKind: input.sourceKind, sourceId: input.sourceId },
+          details: {
+            sourceKind: input.sourceKind,
+            sourceId: input.sourceId,
+            ...(input.reason ? { reason: input.reason } : {}),
+          },
         });
         return toQueueItem(removed);
       });

server/src/services/decision-retention.ts

@@ -0,0 +1,482 @@
+import { createHash } from "node:crypto";
+import { and, asc, eq, inArray, isNotNull, isNull, lte, ne, or, sql } from "drizzle-orm";
+import type { Db } from "@paperclipai/db";
+import {
+  agents,
+  approvals,
+  decisionArchiveNotificationOutbox,
+  decisionRetention,
+  decisions,
+  heartbeatRuns,
+  issueApprovals,
+  issueRecoveryActions,
+  issueThreadInteractions,
+  issues,
+} from "@paperclipai/db";
+import type {
+  AttentionArchiveManifestEntry,
+  AttentionItem,
+  AttentionSourceKind,
+} from "@paperclipai/shared";
+import { conflict, notFound, unprocessable } from "../errors.js";
+import { logActivity } from "./activity-log.js";
+import type { AuthorizationActor } from "./authorization.js";
+import {
+  canReadDecisionSource,
+  type DecisionMutationActor,
+} from "./decision-queues.js";
+
+export const DEFAULT_DECISION_SHELF_DAYS = 30;
+export const DEFAULT_DECISION_ARCHIVE_DAYS = 90;
+const DAY_MS = 86_400_000;
+
+export type DecisionRetentionState = typeof decisionRetention.$inferSelect;
+export type ArchiveNotificationBatch = {
+  companyId: string;
+  agentId: string;
+  items: Array<{
+    sourceKind: AttentionSourceKind;
+    sourceId: string;
+    archiveVersion: number;
+    issueId: string;
+  }>;
+};
+
+function sourceKey(sourceKind: string, sourceId: string) {
+  return `${sourceKind}:${sourceId}`;
+}
+
+function canonicalManifest(manifest: readonly AttentionArchiveManifestEntry[]) {
+  return [...manifest].sort((left, right) => {
+    const leftKey = `${left.companyId}:${left.sourceKind}:${left.sourceId}`;
+    const rightKey = `${right.companyId}:${right.sourceKind}:${right.sourceId}`;
+    return leftKey.localeCompare(rightKey);
+  }).map((entry) => ({
+    companyId: entry.companyId,
+    sourceKind: entry.sourceKind,
+    sourceId: entry.sourceId,
+    expectedVersion: entry.expectedVersion,
+    activityAt: entry.activityAt,
+    reason: entry.reason,
+  }));
+}
+
+export function hashAttentionArchiveManifest(manifest: readonly AttentionArchiveManifestEntry[]) {
+  return createHash("sha256").update(JSON.stringify(canonicalManifest(manifest))).digest("hex");
+}
+
+function archiveActorColumns(actor: DecisionMutationActor) {
+  return {
+    archivedByType: actor.actorType,
+    archivedByAgentId: actor.agentId,
+    archivedByUserId: actor.userId,
+    archivedByRunId: actor.runId,
+  };
+}
+
+async function resolveOrigin(
+  db: Db,
+  companyId: string,
+  sourceKind: AttentionSourceKind,
+  sourceId: string,
+) {
+  let originAgentId: string | null = null;
+  let originIssueId: string | null = null;
+  if (sourceKind === "approval") {
+    const row = await db.select({ agentId: approvals.requestedByAgentId, issueId: issueApprovals.issueId })
+      .from(approvals)
+      .leftJoin(issueApprovals, and(eq(issueApprovals.companyId, companyId), eq(issueApprovals.approvalId, approvals.id)))
+      .where(and(eq(approvals.companyId, companyId), eq(approvals.id, sourceId)))
+      .then((rows) => rows[0] ?? null);
+    originAgentId = row?.agentId ?? null;
+    originIssueId = row?.issueId ?? null;
+  } else if (sourceKind === "decision") {
+    const row = await db.select({ agentId: decisions.originAgentId, issueId: decisions.originIssueId })
+      .from(decisions).where(and(eq(decisions.companyId, companyId), eq(decisions.id, sourceId)))
+      .then((rows) => rows[0] ?? null);
+    originAgentId = row?.agentId ?? null;
+    originIssueId = row?.issueId ?? null;
+  } else if (sourceKind === "issue_thread_interaction") {
+    const row = await db.select({ agentId: issueThreadInteractions.createdByAgentId, issueId: issueThreadInteractions.issueId })
+      .from(issueThreadInteractions)
+      .where(and(eq(issueThreadInteractions.companyId, companyId), eq(issueThreadInteractions.id, sourceId)))
+      .then((rows) => rows[0] ?? null);
+    originAgentId = row?.agentId ?? null;
+    originIssueId = row?.issueId ?? null;
+  } else if (sourceKind === "failed_run") {
+    const row = await db.select({ agentId: heartbeatRuns.agentId, context: heartbeatRuns.contextSnapshot })
+      .from(heartbeatRuns).where(and(eq(heartbeatRuns.companyId, companyId), eq(heartbeatRuns.id, sourceId)))
+      .then((rows) => rows[0] ?? null);
+    const context = row?.context && typeof row.context === "object" ? row.context as Record<string, unknown> : {};
+    originAgentId = row?.agentId ?? null;
+    originIssueId = typeof context.issueId === "string" ? context.issueId : typeof context.taskId === "string" ? context.taskId : null;
+  } else {
+    const issueId = sourceKind === "recovery_action"
+      ? await db.select({ issueId: issueRecoveryActions.sourceIssueId }).from(issueRecoveryActions)
+        .where(and(eq(issueRecoveryActions.companyId, companyId), eq(issueRecoveryActions.id, sourceId)))
+        .then((rows) => rows[0]?.issueId ?? null)
+      : (["productivity_review", "blocker_attention", "review"] as string[]).includes(sourceKind) ? sourceId : null;
+    if (issueId) {
+      const row = await db.select({ agentId: issues.createdByAgentId, issueId: issues.id }).from(issues)
+        .where(and(eq(issues.companyId, companyId), eq(issues.id, issueId)))
+        .then((rows) => rows[0] ?? null);
+      originAgentId = row?.agentId ?? null;
+      originIssueId = row?.issueId ?? null;
+    }
+  }
+  if (!originAgentId || !originIssueId) return null;
+  const activeAgent = await db.select({ id: agents.id }).from(agents)
+    .where(and(eq(agents.companyId, companyId), eq(agents.id, originAgentId), eq(agents.status, "active")))
+    .then((rows) => rows[0] ?? null);
+  return activeAgent ? { originAgentId, originIssueId } : null;
+}
+
+export function decisionRetentionService(
+  db: Db,
+  options: { notifyOriginAgent?: (batch: ArchiveNotificationBatch) => Promise<unknown> } = {},
+) {
+  async function syncItems(companyId: string, items: readonly AttentionItem[]) {
+    if (items.length === 0) return new Map<string, DecisionRetentionState>();
+    const unique = [...new Map(items.map((item) => [itemSourceKey(item), item])).values()];
+    await db.insert(decisionRetention).values(unique.map((item) => ({
+      companyId,
+      sourceKind: item.sourceKind,
+      sourceId: item.subject.id,
+      sourceActivityAt: new Date(item.activityAt),
+    }))).onConflictDoNothing({
+      target: [decisionRetention.companyId, decisionRetention.sourceKind, decisionRetention.sourceId],
+    });
+    let rows = await db.select().from(decisionRetention).where(and(
+      eq(decisionRetention.companyId, companyId),
+      inArray(decisionRetention.sourceId, unique.map((item) => item.subject.id)),
+    ));
+    const byKey = new Map(rows.map((row) => [sourceKey(row.sourceKind, row.sourceId), row]));
+    for (const item of unique) {
+      const key = itemSourceKey(item);
+      const row = byKey.get(key);
+      const activityAt = new Date(item.activityAt);
+      if (!row || row.sourceActivityAt.getTime() === activityAt.getTime()) continue;
+      const updated = await db.update(decisionRetention).set({
+        sourceActivityAt: activityAt,
+        version: sql`${decisionRetention.version} + 1`,
+        updatedAt: new Date(),
+      }).where(and(
+        eq(decisionRetention.id, row.id),
+        ne(decisionRetention.sourceActivityAt, activityAt),
+      )).returning().then((values) => values[0] ?? null);
+      if (updated) byKey.set(key, updated);
+    }
+    rows = [...byKey.values()];
+    return new Map(rows.map((row) => [sourceKey(row.sourceKind, row.sourceId), row]));
+  }
+
+  function itemSourceKey(item: AttentionItem) {
+    return sourceKey(item.sourceKind, item.subject.id);
+  }
+
+  async function getState(companyId: string, sourceKind: AttentionSourceKind, sourceId: string) {
+    return db.select().from(decisionRetention).where(and(
+      eq(decisionRetention.companyId, companyId),
+      eq(decisionRetention.sourceKind, sourceKind),
+      eq(decisionRetention.sourceId, sourceId),
+    )).then((rows) => rows[0] ?? null);
+  }
+
+  async function setKeep(input: {
+    companyId: string;
+    sourceKind: AttentionSourceKind;
+    sourceId: string;
+    keep: boolean;
+    authActor: AuthorizationActor;
+    actor: DecisionMutationActor;
+  }) {
+    if (!(await canReadDecisionSource(db, input.authActor, input.companyId, input.sourceKind, input.sourceId))) {
+      throw notFound("Attention source not found");
+    }
+    const updated = await db.update(decisionRetention).set({
+      keep: input.keep,
+      version: sql`${decisionRetention.version} + 1`,
+      updatedAt: new Date(),
+    }).where(and(
+      eq(decisionRetention.companyId, input.companyId),
+      eq(decisionRetention.sourceKind, input.sourceKind),
+      eq(decisionRetention.sourceId, input.sourceId),
+    )).returning().then((rows) => rows[0] ?? null);
+    if (!updated) throw notFound("Attention source not found");
+    await logActivity(db, {
+      companyId: input.companyId,
+      actorType: input.actor.actorType,
+      actorId: input.actor.actorId,
+      agentId: input.actor.agentId,
+      runId: input.actor.runId,
+      agentApiKeyId: input.actor.agentApiKeyId,
+      responsibleUserIdOverride: input.actor.responsibleUserId,
+      action: "decision_retention.keep_updated",
+      entityType: "attention_source",
+      entityId: input.sourceId,
+      details: { sourceKind: input.sourceKind, keep: input.keep },
+    });
+    return updated;
+  }
+
+  async function changeArchived(input: {
+    companyId: string;
+    sourceKind: AttentionSourceKind;
+    sourceId: string;
+    archived: boolean;
+    authActor: AuthorizationActor;
+    actor: DecisionMutationActor;
+  }) {
+    if (!(await canReadDecisionSource(db, input.authActor, input.companyId, input.sourceKind, input.sourceId))) {
+      throw notFound("Attention source not found");
+    }
+    const now = new Date();
+    const updated = await db.update(decisionRetention).set(input.archived ? {
+      archivedAt: now,
+      archivedReason: "manual",
+      ...archiveActorColumns(input.actor),
+      archiveVersion: sql`${decisionRetention.archiveVersion} + 1`,
+      version: sql`${decisionRetention.version} + 1`,
+      updatedAt: now,
+    } : {
+      archivedAt: null,
+      archivedReason: null,
+      archivedByType: null,
+      archivedByAgentId: null,
+      archivedByUserId: null,
+      archivedByRunId: null,
+      version: sql`${decisionRetention.version} + 1`,
+      updatedAt: now,
+    }).where(and(
+      eq(decisionRetention.companyId, input.companyId),
+      eq(decisionRetention.sourceKind, input.sourceKind),
+      eq(decisionRetention.sourceId, input.sourceId),
+      input.archived ? isNull(decisionRetention.archivedAt) : isNotNull(decisionRetention.archivedAt),
+    )).returning().then((rows) => rows[0] ?? null);
+    if (!updated) {
+      const current = await getState(input.companyId, input.sourceKind, input.sourceId);
+      if (!current) throw notFound("Attention source not found");
+      return current;
+    }
+    await logActivity(db, {
+      companyId: input.companyId,
+      actorType: input.actor.actorType,
+      actorId: input.actor.actorId,
+      agentId: input.actor.agentId,
+      runId: input.actor.runId,
+      agentApiKeyId: input.actor.agentApiKeyId,
+      responsibleUserIdOverride: input.actor.responsibleUserId,
+      action: input.archived ? "decision_retention.archived" : "decision_retention.revived",
+      entityType: "attention_source",
+      entityId: input.sourceId,
+      details: { sourceKind: input.sourceKind },
+    });
+    return updated;
+  }
+
+  async function archiveReviewedManifest(input: {
+    companyId: string;
+    manifest: AttentionArchiveManifestEntry[];
+    originActor: AuthorizationActor;
+    decidingActor: AuthorizationActor;
+    decidedByUserId: string;
+  }) {
+    const keys = input.manifest.map((entry) => sourceKey(entry.sourceKind, entry.sourceId));
+    if (new Set(keys).size !== keys.length || input.manifest.some((entry) => entry.companyId !== input.companyId)) {
+      throw unprocessable("Archive manifest must contain one exact company-scoped set");
+    }
+    return db.transaction(async (tx) => {
+      const txDb = tx as unknown as Db;
+      for (const entry of input.manifest) {
+        const kind = entry.sourceKind as AttentionSourceKind;
+        if (!(await canReadDecisionSource(txDb, input.originActor, input.companyId, kind, entry.sourceId))
+          || !(await canReadDecisionSource(txDb, input.decidingActor, input.companyId, kind, entry.sourceId))) {
+          throw conflict("archive_proposal_authority_changed", { code: "archive_proposal_authority_changed" });
+        }
+        await txDb.execute(sql`select pg_advisory_xact_lock(hashtextextended(${`decision-retention:${input.companyId}:${entry.sourceKind}:${entry.sourceId}`}, 0))`);
+        const state = await txDb.select().from(decisionRetention).where(and(
+          eq(decisionRetention.companyId, input.companyId),
+          eq(decisionRetention.sourceKind, entry.sourceKind),
+          eq(decisionRetention.sourceId, entry.sourceId),
+        )).then((rows) => rows[0] ?? null);
+        if (!state || state.version !== entry.expectedVersion || state.sourceActivityAt.toISOString() !== entry.activityAt || state.archivedAt) {
+          throw conflict("archive_proposal_stale", { code: "archive_proposal_stale" });
+        }
+      }
+      const now = new Date();
+      for (const entry of input.manifest) {
+        const archived = await txDb.update(decisionRetention).set({
+          archivedAt: now,
+          archivedReason: "accepted_proposal",
+          archivedByType: "user",
+          archivedByAgentId: null,
+          archivedByUserId: input.decidedByUserId,
+          archivedByRunId: null,
+          archiveVersion: sql`${decisionRetention.archiveVersion} + 1`,
+          version: sql`${decisionRetention.version} + 1`,
+          updatedAt: now,
+        }).where(and(
+          eq(decisionRetention.companyId, input.companyId),
+          eq(decisionRetention.sourceKind, entry.sourceKind),
+          eq(decisionRetention.sourceId, entry.sourceId),
+          eq(decisionRetention.version, entry.expectedVersion),
+          isNull(decisionRetention.archivedAt),
+        )).returning({ id: decisionRetention.id });
+        if (archived.length !== 1) {
+          throw conflict("archive_proposal_stale", { code: "archive_proposal_stale" });
+        }
+        await logActivity(txDb, {
+          companyId: input.companyId,
+          actorType: "system",
+          actorId: "decision-archive-proposal",
+          responsibleUserIdOverride: input.decidedByUserId,
+          action: "decision_retention.archived",
+          entityType: "attention_source",
+          entityId: entry.sourceId,
+          details: { sourceKind: entry.sourceKind, reason: "accepted_proposal" },
+        });
+      }
+      return { archived: input.manifest.length };
+    });
+  }
+
+  async function autoArchive(input: { companyId: string; items: AttentionItem[]; now?: Date }) {
+    const now = input.now ?? new Date();
+    const cutoff = new Date(now.getTime() - DEFAULT_DECISION_ARCHIVE_DAYS * DAY_MS);
+    const candidates = input.items.filter((item) => new Date(item.activityAt) <= cutoff && !item.keep && !item.archivedAt);
+    let archived = 0;
+    await db.transaction(async (tx) => {
+      const txDb = tx as unknown as Db;
+      for (const item of candidates) {
+        const updated = await txDb.update(decisionRetention).set({
+          archivedAt: now,
+          archivedReason: "idle_ttl",
+          archivedByType: "system",
+          archivedByAgentId: null,
+          archivedByUserId: null,
+          archivedByRunId: null,
+          archiveVersion: sql`${decisionRetention.archiveVersion} + 1`,
+          version: sql`${decisionRetention.version} + 1`,
+          updatedAt: now,
+        }).where(and(
+          eq(decisionRetention.companyId, input.companyId),
+          eq(decisionRetention.sourceKind, item.sourceKind),
+          eq(decisionRetention.sourceId, item.subject.id),
+          eq(decisionRetention.version, item.retentionVersion),
+          eq(decisionRetention.keep, false),
+          isNull(decisionRetention.archivedAt),
+          lte(decisionRetention.sourceActivityAt, cutoff),
+        )).returning().then((rows) => rows[0] ?? null);
+        if (!updated) continue;
+        archived += 1;
+        const origin = await resolveOrigin(txDb, input.companyId, item.sourceKind, item.subject.id);
+        if (origin) {
+          await txDb.insert(decisionArchiveNotificationOutbox).values({
+            companyId: input.companyId,
+            sourceKind: item.sourceKind,
+            sourceId: item.subject.id,
+            archiveVersion: updated.archiveVersion,
+            originAgentId: origin.originAgentId,
+            originIssueId: origin.originIssueId,
+          }).onConflictDoNothing();
+        }
+        await logActivity(txDb, {
+          companyId: input.companyId,
+          actorType: "system",
+          actorId: "decision-retention-sweeper",
+          action: "decision_retention.auto_archived",
+          entityType: "attention_source",
+          entityId: item.subject.id,
+          details: { sourceKind: item.sourceKind, archiveVersion: updated.archiveVersion },
+        });
+      }
+    });
+    return archived;
+  }
+
+  async function deliverNotifications(limit = 500) {
+    if (!options.notifyOriginAgent) return { notifiedAgents: 0, delivered: 0 };
+    const claimAt = new Date();
+    const staleClaimAt = new Date(claimAt.getTime() - 5 * 60_000);
+    await db.update(decisionArchiveNotificationOutbox).set({ status: "pending", updatedAt: claimAt })
+      .where(and(
+        eq(decisionArchiveNotificationOutbox.status, "delivering"),
+        or(isNull(decisionArchiveNotificationOutbox.lastAttemptAt), lte(decisionArchiveNotificationOutbox.lastAttemptAt, staleClaimAt)),
+      ));
+    const rows = await db.transaction(async (tx) => {
+      const pendingIds = await tx.select({ id: decisionArchiveNotificationOutbox.id })
+        .from(decisionArchiveNotificationOutbox)
+        .where(eq(decisionArchiveNotificationOutbox.status, "pending"))
+        .orderBy(asc(decisionArchiveNotificationOutbox.createdAt), asc(decisionArchiveNotificationOutbox.id))
+        .limit(limit)
+        .then((values) => values.map((value) => value.id));
+      if (pendingIds.length === 0) return [];
+      return tx.update(decisionArchiveNotificationOutbox).set({
+        status: "delivering",
+        lastAttemptAt: claimAt,
+        attemptCount: sql`${decisionArchiveNotificationOutbox.attemptCount} + 1`,
+        updatedAt: claimAt,
+      }).where(and(
+        inArray(decisionArchiveNotificationOutbox.id, pendingIds),
+        eq(decisionArchiveNotificationOutbox.status, "pending"),
+      )).returning();
+    });
+    const groups = new Map<string, typeof rows>();
+    for (const row of rows) {
+      const key = `${row.companyId}:${row.originAgentId}`;
+      const grouped = groups.get(key) ?? [];
+      grouped.push(row);
+      groups.set(key, grouped);
+    }
+    let notifiedAgents = 0;
+    let delivered = 0;
+    for (const grouped of groups.values()) {
+      const first = grouped[0]!;
+      try {
+        await options.notifyOriginAgent({
+          companyId: first.companyId,
+          agentId: first.originAgentId,
+          items: grouped.map((row) => ({
+            sourceKind: row.sourceKind as AttentionSourceKind,
+            sourceId: row.sourceId,
+            archiveVersion: row.archiveVersion,
+            issueId: row.originIssueId,
+          })),
+        });
+        const deliveredAt = new Date();
+        await db.update(decisionArchiveNotificationOutbox).set({
+          status: "delivered",
+          deliveredAt,
+          lastAttemptAt: deliveredAt,
+          updatedAt: deliveredAt,
+        }).where(and(
+          inArray(decisionArchiveNotificationOutbox.id, grouped.map((row) => row.id)),
+          eq(decisionArchiveNotificationOutbox.status, "delivering"),
+        ));
+        notifiedAgents += 1;
+        delivered += grouped.length;
+      } catch {
+        await db.update(decisionArchiveNotificationOutbox).set({
+          status: "pending",
+          lastAttemptAt: new Date(),
+          updatedAt: new Date(),
+        }).where(and(
+          inArray(decisionArchiveNotificationOutbox.id, grouped.map((row) => row.id)),
+          eq(decisionArchiveNotificationOutbox.status, "delivering"),
+        ));
+      }
+    }
+    return { notifiedAgents, delivered };
+  }
+
+  return {
+    syncItems,
+    getState,
+    setKeep,
+    archive: (input: Omit<Parameters<typeof changeArchived>[0], "archived">) => changeArchived({ ...input, archived: true }),
+    revive: (input: Omit<Parameters<typeof changeArchived>[0], "archived">) => changeArchived({ ...input, archived: false }),
+    archiveReviewedManifest,
+    autoArchive,
+    deliverNotifications,
+  };
+}

server/src/services/decision-wakeup.ts

@@ -1,4 +1,5 @@
 import type { DecisionServiceOptions } from "./decisions.js";
+import type { ArchiveNotificationBatch } from "./decision-retention.js";
 
 type HeartbeatWakeup = (
   agentId: string,
@@ -30,3 +31,22 @@ export function createDecisionWakeOriginAgent(
     },
   });
 }
+
+export function createDecisionRetentionNotifyOriginAgent(
+  wakeup: HeartbeatWakeup | null,
+): (batch: ArchiveNotificationBatch) => Promise<unknown> {
+  if (!wakeup) return async () => null;
+  return async (batch) => wakeup(batch.agentId, {
+    source: "automation",
+    triggerDetail: "system",
+    reason: "attention_auto_archived",
+    payload: {
+      issueIds: [...new Set(batch.items.map((item) => item.issueId))],
+      archives: batch.items.map((item) => ({
+        sourceKind: item.sourceKind,
+        sourceId: item.sourceId,
+        archiveVersion: item.archiveVersion,
+      })),
+    },
+  });
+}

server/src/services/decisions.ts

@@ -1,16 +1,18 @@
 import { randomUUID } from "node:crypto";
 import { and, asc, count, desc, eq, gt, gte, inArray, lte, or, sql } from "drizzle-orm";
 import type { Db } from "@paperclipai/db";
-import { companyMemberships, decisionBundles, decisionEffectExecutions, decisions, decisionTargetIssues, heartbeatRuns, issueRelations, issues } from "@paperclipai/db";
-import type { DecisionEffect, DecisionInput, DecisionOption, DecisionStatsCounts, DecisionStatsResponse } from "@paperclipai/shared";
+import { companyMemberships, decisionBundles, decisionEffectExecutions, decisionRetention, decisions, decisionTargetIssues, heartbeatRuns, issueRelations, issues } from "@paperclipai/db";
+import { ATTENTION_SOURCE_KINDS } from "@paperclipai/shared";
+import type { AttentionArchiveManifestEntry, DecisionEffect, DecisionInput, DecisionOption, DecisionStatsCounts, DecisionStatsResponse } from "@paperclipai/shared";
 import { conflict, forbidden, notFound, tooManyRequests, unprocessable } from "../errors.js";
 import { authorizationService, type AuthorizationActor } from "./authorization.js";
 import { logActivity, publishActivity, type ActivityPublication } from "./activity-log.js";
 import { signDecisionSpec, verifyDecisionSpec } from "./decision-signing.js";
 import { issueService } from "./issues.js";
+import { decisionRetentionService, hashAttentionArchiveManifest } from "./decision-retention.js";
 
 type Snapshot = { status: string; assigneeAgentId: string | null; assigneeUserId: string | null; updatedAt: string;
-  descendantCount?: number; descendantIds?: string[]; childCount?: number };
+  descendantCount?: number; descendantIds?: string[]; childCount?: number; attentionArchive?: unknown };
 type Wake = (input: { companyId: string; agentId: string; issueId: string; decisionId: string; outcome: "decided" | "expired" | "cancelled" }) => Promise<unknown>;
 export type DecisionServiceOptions = { wakeOriginAgent: Wake };
 const DAY = 86_400_000;
@@ -78,6 +80,43 @@ function canonicalJson(value: unknown): string {
   return JSON.stringify(value);
 }
 
+function parseAttentionArchiveManifest(
+  companyId: string,
+  targetSnapshots: Record<string, Snapshot>,
+): AttentionArchiveManifestEntry[] | null {
+  const entries: AttentionArchiveManifestEntry[] = [];
+  const seen = new Set<string>();
+  for (const [key, snapshot] of Object.entries(targetSnapshots)) {
+    if (!key.startsWith("attention:")) return null;
+    const entry = snapshot.attentionArchive;
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) return null;
+    const candidate = entry as Record<string, unknown>;
+    if (candidate.companyId !== companyId
+      || typeof candidate.sourceKind !== "string"
+      || !ATTENTION_SOURCE_KINDS.includes(candidate.sourceKind as (typeof ATTENTION_SOURCE_KINDS)[number])
+      || typeof candidate.sourceId !== "string"
+      || !candidate.sourceId
+      || !Number.isInteger(candidate.expectedVersion)
+      || Number(candidate.expectedVersion) < 1
+      || typeof candidate.activityAt !== "string"
+      || !Number.isFinite(Date.parse(candidate.activityAt))
+      || typeof candidate.reason !== "string"
+      || !candidate.reason.trim()) return null;
+    const expectedKey = `attention:${candidate.sourceKind}:${candidate.sourceId}`;
+    if (key !== expectedKey || seen.has(expectedKey)) return null;
+    seen.add(expectedKey);
+    entries.push({
+      companyId,
+      sourceKind: candidate.sourceKind,
+      sourceId: candidate.sourceId,
+      expectedVersion: Number(candidate.expectedVersion),
+      activityAt: candidate.activityAt,
+      reason: candidate.reason,
+    });
+  }
+  return entries.length > 0 ? entries : null;
+}
+
 function boardCanActDirectly(actor: AuthorizationActor, companyId: string) {
   if (actor.type !== "board") return false;
   if (actor.source === "local_implicit" || actor.isInstanceAdmin) return true;
@@ -91,6 +130,7 @@ export function decisionService(db: Db, options: DecisionServiceOptions) {
   type CreateInput = { companyId: string; actor: AuthorizationActor; agentId: string; runId: string; bundleId?: string | null;
     ruleKey?: string | null; title: string; body: string; options: DecisionOption[]; inputs?: DecisionInput[] | null; expiresAt?: Date | null;
     idempotencyKey?: string | null; continuationPolicy?: "none" | "wake_origin_agent"; metadata?: Record<string, unknown> };
+  type CreateInputWithSnapshots = CreateInput & { additionalTargetSnapshots?: Record<string, Snapshot> };
 
   async function origin(companyId: string, agentId: string, runId: string) {
     const run = await db.select().from(heartbeatRuns).where(and(eq(heartbeatRuns.id, runId), eq(heartbeatRuns.companyId, companyId), eq(heartbeatRuns.agentId, agentId)))
@@ -155,7 +195,7 @@ export function decisionService(db: Db, options: DecisionServiceOptions) {
     return result;
   }
 
-  async function createInStore(input: CreateInput, dbOrTx: Db) {
+  async function createInStore(input: CreateInputWithSnapshots, dbOrTx: Db) {
     if (input.idempotencyKey) {
       const lockKey = `decision-create:${input.companyId}:${input.idempotencyKey}`;
       await dbOrTx.execute(sql`select pg_advisory_xact_lock(hashtextextended(${lockKey}, 0))`);
@@ -165,8 +205,14 @@ export function decisionService(db: Db, options: DecisionServiceOptions) {
       const existing = await dbOrTx.select().from(decisions).where(and(eq(decisions.companyId, input.companyId), eq(decisions.idempotencyKey, input.idempotencyKey)))
         .then((rows) => rows[0] ?? null);
       if (existing) {
+        const archiveEquivalent = input.additionalTargetSnapshots === undefined || (
+          canonicalJson(existing.metadata ?? {}) === canonicalJson(input.metadata ?? {}) &&
+          canonicalJson(Object.fromEntries(Object.entries(existing.targetSnapshots as Record<string, Snapshot>)
+            .filter(([key]) => key.startsWith("attention:")))) === canonicalJson(input.additionalTargetSnapshots)
+        );
         const equivalent = existing.title === input.title && existing.body === input.body &&
-          canonicalJson(existing.options) === canonicalJson(input.options) && canonicalJson(existing.inputs ?? null) === canonicalJson(input.inputs ?? null);
+          canonicalJson(existing.options) === canonicalJson(input.options) && canonicalJson(existing.inputs ?? null) === canonicalJson(input.inputs ?? null) &&
+          archiveEquivalent;
         if (!equivalent) throw conflict("Decision idempotency key already used with a different payload");
         return existing;
       }
@@ -179,7 +225,10 @@ export function decisionService(db: Db, options: DecisionServiceOptions) {
     const ids = targetIds(input.options);
     const cancellationTargetIds = new Set(input.options.flatMap((option) => option.effects
       .filter((effect) => effect.type === "cancel_issue_tree").map((effect) => effect.targetIssueId)));
-    const targetSnapshots = await snapshots(input.companyId, ids, input.actor, targetActions(input.options), cancellationTargetIds, dbOrTx);
+    const targetSnapshots = {
+      ...await snapshots(input.companyId, ids, input.actor, targetActions(input.options), cancellationTargetIds, dbOrTx),
+      ...(input.additionalTargetSnapshots ?? {}),
+    };
     const id = randomUUID();
     const [created] = await dbOrTx.insert(decisions).values({ id, companyId: input.companyId, bundleId: input.bundleId ?? null,
       originAgentId: input.agentId, originIssueId: provenance.issueId, originRunId: input.runId, ruleKey: input.ruleKey ?? null,
@@ -190,8 +239,14 @@ export function decisionService(db: Db, options: DecisionServiceOptions) {
       const existing = input.idempotencyKey
         ? await dbOrTx.select().from(decisions).where(and(eq(decisions.companyId, input.companyId), eq(decisions.idempotencyKey, input.idempotencyKey))).then((rows) => rows[0] ?? null)
         : null;
+      const archiveEquivalent = !existing || input.additionalTargetSnapshots === undefined || (
+        canonicalJson(existing.metadata ?? {}) === canonicalJson(input.metadata ?? {}) &&
+        canonicalJson(Object.fromEntries(Object.entries(existing.targetSnapshots as Record<string, Snapshot>)
+          .filter(([key]) => key.startsWith("attention:")))) === canonicalJson(input.additionalTargetSnapshots)
+      );
       const equivalent = existing && existing.title === input.title && existing.body === input.body &&
-        canonicalJson(existing.options) === canonicalJson(input.options) && canonicalJson(existing.inputs ?? null) === canonicalJson(input.inputs ?? null);
+        canonicalJson(existing.options) === canonicalJson(input.options) && canonicalJson(existing.inputs ?? null) === canonicalJson(input.inputs ?? null) &&
+        archiveEquivalent;
       if (equivalent) return existing;
       throw conflict("Decision idempotency key already used with a different payload");
     }
@@ -202,7 +257,7 @@ export function decisionService(db: Db, options: DecisionServiceOptions) {
     return created;
   }
 
-  async function create(input: CreateInput, dbOrTx?: Db) {
+  async function create(input: CreateInputWithSnapshots, dbOrTx?: Db) {
     if (dbOrTx) return createInStore(input, dbOrTx);
     return db.transaction((tx) => createInStore(input, tx as unknown as Db));
   }
@@ -226,13 +281,29 @@ export function decisionService(db: Db, options: DecisionServiceOptions) {
     }
     const rows = await db.select().from(decisions).where(and(...conditions)).orderBy(desc(decisions.createdAt)).limit(Math.min(filter.limit ?? 50, 100));
     const openDecisionIds = rows.filter((decision) => decision.status === "open").map((decision) => decision.id);
-    const currentTargets = openDecisionIds.length
+    const currentIssueTargetIds = rows.flatMap((decision) => Object.keys(decision.targetSnapshots as Record<string, Snapshot>))
+      .filter((id) => /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(id));
+    const currentTargets = openDecisionIds.length && currentIssueTargetIds.length
       ? await db.select({ id: issues.id, updatedAt: issues.updatedAt })
         .from(decisionTargetIssues)
         .innerJoin(issues, and(eq(issues.companyId, companyId), eq(issues.id, decisionTargetIssues.issueId)))
-        .where(and(eq(decisionTargetIssues.companyId, companyId), inArray(decisionTargetIssues.decisionId, openDecisionIds)))
+        .where(and(eq(decisionTargetIssues.companyId, companyId), inArray(decisionTargetIssues.decisionId, openDecisionIds), inArray(issues.id, currentIssueTargetIds)))
       : [];
     const currentTargetsById = new Map(currentTargets.map((target) => [target.id, target.updatedAt]));
+    const attentionSnapshotIds = rows.flatMap((decision) => Object.values(decision.targetSnapshots as Record<string, Snapshot>))
+      .map((snapshot) => snapshot.attentionArchive as AttentionArchiveManifestEntry | undefined)
+      .filter((entry): entry is AttentionArchiveManifestEntry => Boolean(entry))
+      .map((entry) => entry.sourceId);
+    const currentAttentionStates = attentionSnapshotIds.length
+      ? await db.select().from(decisionRetention).where(and(
+        eq(decisionRetention.companyId, companyId),
+        inArray(decisionRetention.sourceId, attentionSnapshotIds),
+      ))
+      : [];
+    const currentAttentionByKey = new Map(currentAttentionStates.map((state) => [
+      `attention:${state.sourceKind}:${state.sourceId}`,
+      state,
+    ]));
     const terminalDecisionIds = rows.filter((decision) => decision.status !== "open").map((decision) => decision.id);
     const terminalExecutions = terminalDecisionIds.length
       ? await db.select().from(decisionEffectExecutions)
@@ -248,6 +319,13 @@ export function decisionService(db: Db, options: DecisionServiceOptions) {
     return rows.map((decision) => {
       const changed: Record<string, boolean> = {};
       if (decision.status === "open") for (const [id, snapshot] of Object.entries(decision.targetSnapshots as Record<string, Snapshot>)) {
+        if (id.startsWith("attention:")) {
+          const entry = snapshot.attentionArchive as AttentionArchiveManifestEntry | undefined;
+          const current = currentAttentionByKey.get(id);
+          changed[id] = !entry || !current || current.version !== entry.expectedVersion
+            || current.sourceActivityAt.toISOString() !== entry.activityAt || Boolean(current.archivedAt);
+          continue;
+        }
         const currentUpdatedAt = currentTargetsById.get(id);
         changed[id] = !currentUpdatedAt || currentUpdatedAt.toISOString() !== snapshot.updatedAt;
       }
@@ -468,6 +546,58 @@ export function decisionService(db: Db, options: DecisionServiceOptions) {
     const option = decision.options.find((item) => item.id === decision.chosenOptionId);
     if (!option || !decision.decidedByUserId) throw unprocessable("Stored decision outcome is invalid");
     const run = await db.select({ responsibleUserId: heartbeatRuns.responsibleUserId }).from(heartbeatRuns).where(eq(heartbeatRuns.id, decision.originRunId)).then((rows) => rows[0] ?? null);
+    const metadata = decision.metadata as Record<string, unknown>;
+    if (metadata.kind === "attention_archive_proposal") {
+      if (!verifyDecisionSpec(spec({
+        id: decision.id,
+        options: decision.options,
+        targetSnapshots: decision.targetSnapshots as Record<string, Snapshot>,
+      }), decision.signedSpec)) {
+        await db.update(decisions).set({ executionStatus: "failed", updatedAt: new Date(), metadata: { ...metadata, archiveProposalError: "invalid_signature" } })
+          .where(eq(decisions.id, decision.id));
+        return outcome(decision.id);
+      }
+      if (option.id === "archive") {
+        const manifest = parseAttentionArchiveManifest(
+          decision.companyId,
+          decision.targetSnapshots as Record<string, Snapshot>,
+        );
+        const manifestHash = manifest ? hashAttentionArchiveManifest(manifest) : null;
+        if (!manifest || manifestHash !== metadata.manifestHash) {
+          await db.update(decisions).set({ executionStatus: "failed", updatedAt: new Date(), metadata: { ...metadata, archiveProposalError: "manifest_mismatch" } })
+            .where(eq(decisions.id, decision.id));
+          return outcome(decision.id);
+        }
+        const originActor: AuthorizationActor = {
+          type: "agent",
+          agentId: decision.originAgentId,
+          companyId: decision.companyId,
+          runId: decision.originRunId,
+          onBehalfOfUserId: run?.responsibleUserId ?? null,
+          source: "agent_jwt",
+        };
+        try {
+          await decisionRetentionService(db).archiveReviewedManifest({
+            companyId: decision.companyId,
+            manifest,
+            originActor,
+            decidingActor: userActor,
+            decidedByUserId: decision.decidedByUserId,
+          });
+        } catch (error) {
+          const message = error instanceof Error ? error.message : "archive_proposal_failed";
+          await db.update(decisions).set({ executionStatus: "failed", updatedAt: new Date(), metadata: { ...metadata, archiveProposalError: message } })
+            .where(eq(decisions.id, decision.id));
+          return outcome(decision.id);
+        }
+      }
+      await db.update(decisions).set({
+        executionStatus: "succeeded",
+        updatedAt: new Date(),
+        metadata: { ...metadata, ...(decision.continuationPolicy === "wake_origin_agent" ? { continuationPending: true } : {}) },
+      }).where(eq(decisions.id, decision.id));
+      return outcome(decision.id);
+    }
     for (let index = 0; index < option.effects.length; index += 1) await executeEffect(decision, option.effects[index]!, index, userActor, decision.decidedByUserId, run?.responsibleUserId ?? null);
     const rows = await db.select().from(decisionEffectExecutions).where(eq(decisionEffectExecutions.decisionId, decision.id));
     const successful = rows.filter((row) => row.status === "executed").length;

server/src/services/index.ts

@@ -66,6 +66,7 @@ export { workTimelineService, normalizeTimelineWindow } from "./work-timeline.js
 export { attentionService } from "./attention.js";
 export { captureDecisionSnapshot, decisionTrainingService } from "./decision-training.js";
 export { decisionService } from "./decisions.js";
+export { decisionRetentionService } from "./decision-retention.js";
 export type {
   WorkTimelineActor,
   WorkTimelineEdge,