Introducing a new way to review your PRs.

Read the announcement

paperclipai / paperclip

The open-source app everyone uses to manage agents at work

View on GitHub

30 documents · Updated Nov 20, 2026

docs / decisions-approvals-and-attention

Decisions, approvals, and attention

Paperclip gives human operators control over work that cannot continue without a person. Decision queues, approvals, inbox items, alerts, status cards, and summaries collect the signals that need review, while safe resolution paths return the result to the work that requested it.

This page is a child of Automation and control. For automated issue work that creates these requests, see Routines and pipelines.

Control surfaces

The system separates work that needs a human choice from work that needs a status view. The Decisions desk ranks current attention items, the Inbox gathers personal work and alerts, and status cards and summary slots provide context for action. The attention service also exposes a compact summary, a related task index, and decision history so clients can load counts and history without rebuilding the full desk.

SurfaceMain purposeTypical outcome
Decisions deskRank and resolve items that need a human responseA choice, answer, route, retry, or dismissal
Decision queueGroup a repeatable class of attention itemsA focused review list
InboxShow personal tasks and non-decision work itemsWork is opened, archived, retried, or resolved
ApprovalsReview requests that need board approvalApproved, rejected, sent back for revision, or cancelled
Status cardsKeep a living summary of a watched issue setThe operator reads the current state or refreshes it
Summary slotsShow a scoped summary with revision historyThe operator reads the latest or a prior revision

Decision proposals

A decision is a choice proposed by an agent run for a human to make. It carries a question, named options, optional input fields, and effects that describe the work to apply after the choice. The decision keeps its source issue and run so the result can return to the work that requested it. A proposal must come from an issue-scoped origin run, and an idempotency key prevents the same request from creating a second proposal. server/…/decisions.ts• L139-150 server/…/decisions.ts• L207-268 packages/…/decision.ts• L6-17

Decision lifecycle

An open decision stays on the attention desk until a person chooses an option, dismisses it, it expires, or its source cancels it. The default expiry is seven days. A decision can also request a wake of its source agent after the outcome is recorded. A repeated submission for the same decision is treated as a replay when it has the same actor and choice, so effect work can resume without applying the choice twice. server/…/decisions.ts• L229-233 server/…/decisions.ts• L683-717

The outcome has two parts:

  • The recorded human choice and input values.
  • The execution result for each effect.

This split lets one choice produce several effects. The human choice can be complete while the effects finish with success, partial success, or failure.

This diagram shows how a proposal becomes a recorded choice and then an effect result or an expiry outcome.

flowchart LR
    A[Agent run] --> B[Open decision]
    B --> C{Human response}
    C -->|Choose option| D[Run effects]
    C -->|Dismiss| E[Record dismissal]
    B -->|Expiry| F[Mark expired]
    D --> G[Record per-effect result]
    D --> H[Wake source agent when requested]
    E --> H
    F --> H

References: server/…/decisions.ts• L600-664 server/…/decisions.ts• L683-717

Decision effects

An effect is the business action attached to an option. Effects can change issue work, such as adding a comment, creating an issue, changing status, assigning work, removing a blocker, or cancelling an issue tree. The decision card shows a short preview before the operator commits the choice. packages/…/decision.ts• L19-68 ui/…/DecisionCard.tsx• L91-120

The proposal records a snapshot of each target. If strict work changed after proposal, the effect is skipped instead of applying an old plan. Permission checks cover both the source authority and the human actor. The card reports each effect result so the operator can see what ran, what was skipped, and what failed. Each effect is claimed and audited separately, which lets recovery resume unfinished work without repeating a completed effect. Concurrent recovery attempts share one in-flight execution, so they do not run the same decision effects in parallel. server/…/decisions.ts• L410-483 server/…/decisions.ts• L587-604 server/…/decisions.ts• L665-679 ui/…/DecisionCard.tsx• L123-183

Attention archive proposals use the same decision path. Their signed target manifest identifies the exact attention items under review, and the archive succeeds only when that manifest still matches the current items. server/…/decisions.ts• L610-664

References: packages/…/decision.ts• L19-68 server/…/decisions.ts• L410-483 server/…/decisions.ts• L587-604 server/…/decisions.ts• L610-679 ui/…/DecisionCard.tsx• L91-183

Decision bundles

A decision bundle groups related proposals under one title and summary. The operator still resolves each decision as its own choice, so the bundle improves review without changing the unit of execution. server/…/decisions.ts• L33-34 server/…/attention.ts• L1288-1343

References: server/…/decisions.ts• L33-34 server/…/attention.ts• L1288-1343

Decision model service

The decision model service provides bounded model help for decision features. It checks company settings, access, the acting user or agent run, the selected connection, and budget before it sends a request to a provider. A decision feature is a registered server capability that declares whether background use is allowed. server/…/decision-models.ts• L22-36 server/…/decision-models.ts• L84-129

The service records each invocation with its actor, source work, usage, cost, and result. It reserves budget before provider work and settles the reservation after the provider returns. It also marks interrupted work so a stale running invocation does not remain unresolved. server/…/decision-models.ts• L140-172 server/…/decision-models.ts• L188-247

The provider boundary returns normalized answers and a receipt. The receipt keeps token counts, provider request identity, cost status, and pricing source. Provider errors are reduced to safe error codes, and provider response bodies are not sent to callers or logs. server/…/decision-model-provider.ts• L6-11 server/…/decision-model-provider.ts• L42-90

References: server/…/decision-models.ts• L22-36 server/…/decision-models.ts• L84-129 server/…/decision-models.ts• L140-247 server/…/decision-model-provider.ts• L6-11 server/…/decision-model-provider.ts• L42-90

Approval handling

An approval is a request for a board user to allow or deny a change. It stores the request type, payload, requester, decision note, and deciding user. Approval detail views add linked work and a comment thread so the board can review the request in context. Approval comments stay within the approval's company and follow the instance setting for current-user text redaction. packages/…/approval.ts• L3-25 ui/…/ApprovalDetail.tsx• L201-261 server/…/approvals.ts• L125-166

Pending and revision-requested approvals are actionable. A board user can approve or reject either state. A pending approval can instead be sent back for changes, and a revision-requested approval can return to pending with new or unchanged payload data. Repeated approval or rejection is safe to retry and does not emit follow-up work a second time. server/…/approvals.ts• L63-127 server/…/approvals.ts• L191-203

Approval resolution records the authenticated decision maker and checks company scope before changing state. An open request can also be cancelled during cleanup without a board decision. These rules prevent a caller from changing another company's request or attributing a decision to a different user. server/…/approvals.ts• L64-84 server/…/approvals.ts• L119-143

Hire approval has direct product effects through the agent lifecycle. Approval or rejection updates the prepared agent state, then an approved built-in agent is reconciled, pending budget enforcement is delivered, and a hire-approved notice is sent after approval succeeds. server/…/approvals.ts• L171-187

References: server/…/approvals.ts• L63-127 server/…/approvals.ts• L125-166 server/…/approvals.ts• L171-203 packages/…/approval.ts• L3-25 ui/…/ApprovalDetail.tsx• L201-261

Approval follow-up

After approval or rejection, Paperclip records activity and tries to wake the requesting agent. If a linked issue lost its review path, the system also queues a recovery wake for the issue owner. This moves work toward its next owner without requiring the board to search for it. server/…/approvals.ts• L288-399 server/…/approvals.ts• L404-437

Status-only recovery runs cannot create or change approvals. A recovery run that only reports state cannot create a request, resubmit one, or add approval comments. server/…/approval-routes-idempotency.test.ts• L369-441

References: server/…/approvals.ts• L288-399 server/…/approvals.ts• L404-437 server/…/approval-routes-idempotency.test.ts• L369-441

Attention feed

An attention item is a common description of one thing that needs a human response. The feed gives each item a source kind, reason, severity, activity time, entry and exit rules, available actions, and a link to the related object. This supports both an inline card and a deeper review page. packages/…/attention.ts• L218-257

Attention sources

The feed combines signals from several product areas and removes duplicates before ranking them. Eligibility rules then remove signals that no longer need a person, such as an interaction addressed to an invokable agent, an older confirmation replaced by a newer one, a failed run superseded by a newer run, or a review with a live path. One underlying problem therefore does not create a misleading set of repeated rows. server/…/attention.ts• L1870-1878 server/…/attention-source-eligibility.ts• L14-41 server/…/attention-source-eligibility.ts• L52-80

Source groupExamplesHuman path
ChoicesAgent decisions, confirmations, questions, item verdictsChoose, answer, accept, reject, or dismiss
Permission and accessApprovals and join requestsApprove, reject, or request revision
Work healthFailed runs, agent errors, budget incidentsRetry, inspect, raise budget, or keep paused
Work flowBlockers, review items, productivity reviewsUnblock, reassign, approve, request changes, or resolve
RecoveryRecovery actions owned by a user or the boardResolve, reassign, or cancel

The feed ranks recent activity first by default. It can sort by activity or requested decide-by time, then uses severity and source order to break ties. Its badge count covers the full filtered set, so pagination does not hide new or due items. Board clients can request summary counts, related task IDs, and decision history through the attention routes. server/…/attention.ts• L428-435 server/…/attention.ts• L1880-1937 server/…/attention.ts• L20-49

References: server/…/attention.ts• L74-116 server/…/attention.ts• L1870-1976 server/…/attention-source-eligibility.ts• L4-12 server/…/attention-source-eligibility.ts• L14-41 server/…/attention-source-eligibility.ts• L52-80 packages/…/attention.ts• L218-257

Inline resolution

An inline-resolvable item contains enough data to show its action in the desk. Decisions use their decision resolver. Thread interactions use an interaction resolver that supports confirmations, questions, suggested tasks, checkbox choices, and item verdicts without leaving the queue. Reviews use their owning view instead. server/…/attention.ts• L1146-1155 ui/…/AttentionInteractionResolver.tsx• L44-71 ui/…/DecisionResolver.tsx• L37-42

The interaction resolver refreshes the issue thread only while workspace sync is pending. After an action succeeds, it stores the server's full result before refreshing the attention feed. The operator therefore sees the real effect result instead of a temporary generic accepted state. ui/…/issue-thread-interactions.ts• L61-72 ui/…/AttentionInteractionResolver.tsx• L73-127

The feed shows the requested resolver policy and relevant identity as guidance. The server checks access again when the operator submits the action. The displayed audience does not grant permission by itself. packages/…/attention.ts• L188-216 server/…/attention.ts• L727-765

References: packages/…/attention.ts• L188-216 server/…/attention.ts• L727-765 ui/…/AttentionInteractionResolver.tsx• L44-167 ui/…/issue-thread-interactions.ts• L61-72

Some items need a full task or settings view instead of a small card. Recovery actions, review items, failed runs, and agent alerts link to the object that owns the next action. A row can still offer route, retry, or dismiss actions while the source object waits for the operator's choice. server/…/attention.ts• L1388-1449 server/…/attention.ts• L1668-1719 ui/…/AttentionQueueRow.tsx• L159-228

References: server/…/attention.ts• L1388-1449 server/…/attention.ts• L1668-1719 ui/…/AttentionQueueRow.tsx• L159-228

Conversation decision receipts

Conversation decision receipts connect a standing agent conversation to the same questions and decision history that appear in the attention system. The conversation view shows pending questions from readable tasks handed off in the current chat session, plus ordinary tasks created by the user and assigned to that conversation's agent. It excludes the conversation's own questions and does not copy questions into chat or start another agent turn. server/…/conversation-decision-receipts.ts• L12-23 server/…/conversation-decision-receipts.ts• L49-59 server/…/openapi.ts• L8682-8691

The scope preserves chat session boundaries. Handoff tasks keep the agent and session that created them. Ordinary-task questions remain current across chat resets, while ordinary-task receipts begin at the current boundary comment; if reset provenance is missing, that history is omitted. The service checks conversation audience and task access on every read, then merges the task sources into one newest-first history with a shared cursor. server/…/conversation-decision-receipts.ts• L24-46 server/…/conversation-decision-receipts.ts• L61-101 server/…/conversation-decision-receipts.ts• L103-129

This diagram shows how a conversation obtains current questions and past outcomes without becoming a second decision system.

flowchart LR
    A[Conversation read] --> B[Check conversation audience]
    B --> C[Find current-session handoffs]
    B --> D[Find user's direct tasks]
    C --> E[Filter canonical attention questions]
    D --> E
    C --> F[Read handoff decision history]
    D --> G[Read history after session boundary]
    F --> H[Merge newest-first receipts]
    G --> H

References: server/…/conversation-decision-receipts.ts• L16-23 server/…/conversation-decision-receipts.ts• L24-46 server/…/conversation-decision-receipts.ts• L49-129 server/…/issues.ts• L18379-18427

Decision queues and triage

A decision queue is a named company-level view over attention sources. It can receive items directly or through seed rules. Triage adds operator context without changing the source item, such as a decide-by time, snooze time, and actor identity. packages/…/decision-queue.ts• L14-63

Queue seed rules

Built-in queues focus on pull-request decisions, plan confirmation, and questions. The attention feed checks current items against these signals and creates matching queues and memberships when seed rules are enabled. server/…/decision-queues.ts• L46-84 server/…/decision-queues.ts• L684-777 server/…/attention.ts• L1870-1878

References: server/…/decision-queues.ts• L46-84 server/…/decision-queues.ts• L684-777 server/…/attention.ts• L1870-1878

Triage states

The desk separates urgent work from work that can wait. Operators can filter, group, sort, set a decide-by value, snooze an item, restore it, and review aging items. Snooze hides an item until its time. Dismissal hides it until new activity makes it relevant again. server/…/attention.ts• L191-211 ui/…/AttentionQueueRow.tsx• L64-78

References: server/…/attention.ts• L191-211 server/…/decision-queues.ts• L590-647 ui/…/AttentionQueueRow.tsx• L64-78

Signing and retention

Decision signing protects the proposal that the operator is about to execute. Paperclip signs a canonical decision specification with an HMAC key and verifies it before accepting a choice. The specification covers the decision identity, options, and target snapshots. This check also protects archive proposals before they can change retained attention items. server/…/decision-signing.ts• L146-163 server/…/decisions.ts• L610-631

Decision target safety

Target snapshots make stale work visible. Open decision listings compare current targets with saved snapshots, and the card marks changed targets before the operator chooses. Strict effects then skip changed targets instead of silently applying an old plan. server/…/decisions.ts• L283-345 server/…/decisions.ts• L478-483 ui/…/DecisionCard.tsx• L246-257

References: server/…/decisions.ts• L283-345 server/…/decisions.ts• L478-483 ui/…/DecisionCard.tsx• L246-257

Attention retention

Retention controls how long an attention item stays on the active decision shelf and when an old item moves to the archive. The default shelf is 30 days and the default automatic archive age is 90 days. A human can keep, archive, or revive an item, with the actor and activity recorded. The retention worker checks current source eligibility before it archives an item, so a stale or no-longer-visible source is not treated as a valid archive target. server/…/decision-retention.ts• L29-31 server/…/attention.ts• L639-652 server/…/attention-retention.ts• L17-25 server/…/attention-retention.ts• L268-334

The retention worker checks due items in company, source, and issue scopes. It reads candidates in bounded pages, then rechecks the source under a lock before it archives only the current version. It uses the same rules for pending questions, reviews, failed runs, agent and budget alerts, recovery actions, and blockers that decide whether those items still need attention. Blocker attention can produce separate owner and terminal paths, while unknown bounded blocker graphs remain deferred until later source activity can revalidate them. server/…/attention-retention.ts• L95-125 server/…/attention-retention.ts• L146-263 server/…/attention-retention.ts• L268-334

Bulk archive uses a signed manifest of the exact items under review. If an item or its authority changes before acceptance, the archive fails instead of archiving a different set. The manifest is carried through a decision proposal, so archive work gets the same replay and effect recovery behavior as other decisions. server/…/decisions.ts• L55-134 server/…/decision-retention.ts• L277-340 server/…/decisions.ts• L614-663

References: server/…/decision-retention.ts• L29-31 server/…/attention.ts• L639-652 server/…/attention-retention.ts• L17-25 server/…/attention-retention.ts• L95-125 server/…/attention-retention.ts• L146-371 server/…/decisions.ts• L55-134 server/…/decision-retention.ts• L277-395 server/…/decisions.ts• L610-663

Inbox policies and alerts

The Inbox combines a user's tasks with approvals, failed runs, and join requests. In the streamlined experience, it also serves as the My work half of Tasks; the same surface can still run as a standalone Inbox page. Its views are Mine, Recent, Unread, Blocked, and All. ui/…/Inbox.tsx• L813-835 ui/…/Inbox.tsx• L2530-2542

The All view can filter the mixed list by touched tasks, approvals, failed runs, join requests, or alerts. It can also narrow approvals to all, actionable, or resolved states. The Blocked view has its own task filters, grouping, and sort controls, so blocked work can be reviewed as a focused queue. ui/…/Inbox.tsx• L1384-1426 ui/…/Inbox.tsx• L2502-2518 ui/…/Inbox.tsx• L2575-2603

The Inbox presents issue tasks, approvals, failed runs, and join requests in one work list. Search can add archived or other matching tasks to the result without treating them as active Inbox work. Operators can group rows, nest parent and child tasks, choose visible task fields, and keep date separators as view preferences. ui/…/Inbox.tsx• L1418-1539 ui/…/Inbox.tsx• L1579-1592 ui/…/Inbox.tsx• L2991-3315

Inbox actions

The Mine view supports direct action on each work type. Operators can approve or reject approvals and join requests, retry failed runs, mark rows read or unread, and archive tasks or non-task rows. An issue-linked failed run retries the task with a stable request key and returns the operator to the task; an unlinked run retries the agent run and opens the new run. Task archive removes the row at once, keeps a short undo path, and restores the cached row if the server rejects the action. ui/…/Inbox.tsx• L1817-1922 ui/…/Inbox.tsx• L1965-2044 ui/…/Inbox.tsx• L2097-2124

The Mine snapshot is a coordinated read of the user's tasks and failed runs. It reports total and phase timing in response headers, and a request that shares an in-flight read reuses the completed read's phase data. This makes slow attention sources visible without changing the work items returned to the operator. server/…/issues.ts• L8826-8891 server/…/inbox-mine-timing.ts• L3-42

References: ui/…/Inbox.tsx• L813-835 ui/…/Inbox.tsx• L1384-1539 ui/…/Inbox.tsx• L1579-1592 ui/…/Inbox.tsx• L1817-2044 ui/…/Inbox.tsx• L2097-2124 ui/…/Inbox.tsx• L2502-2603 ui/…/Inbox.tsx• L2991-3315 server/…/issues.ts• L8826-8891 server/…/inbox-mine-timing.ts• L3-42

Inbox archive policy

An Inbox archive policy controls whether an agent may remove tasks from a user's Inbox on that user's behalf. The policy belongs to the user and company and has three modes:

  • open: any agent managed by the user may archive.
  • allowlist: only selected managed agents may archive.
  • disabled: agents may not archive.

The user can undo an archive, and the task keeps attribution for the agent that archived it. Administrative routes can manage another active company user's policy. packages/…/inbox-agent-policy.ts• L1-13 ui/…/InboxAgentPolicyControl.tsx• L13-45 server/…/inbox-agent-policy.ts• L19-35

References: packages/…/inbox-agent-policy.ts• L1-13 ui/…/InboxAgentPolicyControl.tsx• L13-45 server/…/inbox-agent-policy.ts• L19-35

Company alerts

Company alerts show broad health signals rather than personal work. The Inbox shows them only in the All view. Current aggregate alerts cover agents in error and high company budget use. Dismissing an alert hides it from the Inbox but does not change the health condition. ui/…/inbox.ts• L703-709 ui/…/Inbox.tsx• L2427-2455 ui/…/Inbox.tsx• L3326-3381

The Decisions feed exposes more focused budget and agent-error items. These rows include the measured condition and a direct path such as raising a budget, keeping work paused, inspecting an agent, or dismissing the alert. Budget warnings enter at 85 percent of the limit, while hard stops always enter. server/…/attention.ts• L1761-1812 server/…/attention-source-eligibility.ts• L4-12

References: ui/…/inbox.ts• L703-709 ui/…/Inbox.tsx• L2427-2455 ui/…/Inbox.tsx• L3326-3381 server/…/attention.ts• L1761-1865 server/…/attention-source-eligibility.ts• L4-12

Status cards and summary slots

Status cards and summary slots give the operator a compact view of changing work. They provide context for a decision but do not act as approval records.

Status cards

A status card is a standing interest in a set of company issues. Its prompt defines the watched scope, and it can refresh manually, on a schedule, or after matching changes. Each successful update produces a summary and a change record. packages/…/status-card.ts• L16-52 server/…/status-cards.ts• L71-112

The card lifecycle tells the operator whether the summary is ready, stale, updating, failed, paused by budget, paused by hours, or archived. A failed or paused card keeps its last good summary visible. An archived card stops watching until it is restored. ui/…/status-card-state.ts• L10-35 ui/…/status-card-state.ts• L50-111

References: packages/…/status-card.ts• L16-52 server/…/status-cards.ts• L71-112 ui/…/status-card-state.ts• L10-111

Status decision effects

A status decision records a proposed issue status change with the run and assessment that produced it. Its ordered effects describe the work that must follow, and each effect keeps delivery state, retry data, the last error, and an idempotency key. Effects can create a human gate, bind a blocker owner, schedule a retry, wake an agent, release work, or create a recovery path. A decision can also preserve the current status while it records a wait or continuation. packages/…/status_decisions.ts• L16-34 packages/…/status_decision_effects.ts• L15-55 server/…/status-decision-committer.ts• L619-753 server/…/status-decision-committer.ts• L847-1089

This separates the status choice from the work that applies it. The operator can see the proposed change while the system tracks each linked action, including review participants, dependency wakes, and recovery records. Reconciliation checks the recorded decision and target rows, then delivers only pending or failed ledger work; it does not choose a new status decision. server/…/status-decision-committer.ts• L113-203 server/…/status-decision-committer.ts• L619-817 server/…/status-decision-committer.ts• L872-1089 server/…/status-decision-committer.ts• L2471-2617

The commit path locks the finalization record and issue, then checks that the issue, run, gate, company, evidence, and effect targets still match the proposal. It also proves the required result and deliverable evidence before a task can be marked done. It rejects a stale race instead of applying a decision against newer work. It records the issue status, effect ledger, and finalization result as one protected outcome. A replay returns the existing result rather than creating duplicate effects or wakes. server/…/status-decision-committer.ts• L1682-1919 server/…/status-decision-committer.ts• L1920-2177 server/…/status-decision-committer.ts• L2217-2304 server/…/status-decision-committer.ts• L2355-2663

References: packages/…/status_decisions.ts• L16-34 packages/…/status_decision_effects.ts• L15-55 server/…/status-decision-committer.ts• L113-203 server/…/status-decision-committer.ts• L619-817 server/…/status-decision-committer.ts• L1682-1919 server/…/status-decision-committer.ts• L1920-2177 server/…/status-decision-committer.ts• L2217-2304 server/…/status-decision-committer.ts• L2355-2663

Summary slots

A summary slot is one named summary position for a scope such as a project, project workspace, execution workspace, or workspace overview. It points to a document with a latest body and revision history. A built-in summarizer generates revisions and exposes its active task while it works. packages/…/summary-slot.ts• L9-55 server/…/summary-slots.ts• L244-278

Only the active generation task can write the next revision. A valid write returns the slot to idle, clears its failure state, records the model and agent, and creates the next revision. Operators can read the latest revision or inspect recent history. server/…/summary-slots.ts• L553-607 server/…/summary-slots.ts• L609-754 ui/…/SummarySlotCard.tsx• L455-502

References: packages/…/summary-slot.ts• L9-55 server/…/summary-slots.ts• L244-278 server/…/summary-slots.ts• L553-754 ui/…/SummarySlotCard.tsx• L455-502

Decision training records

A decision training record freezes the context around a human decision so it can be reviewed later. It can capture an issue, comments, related runs, workspaces, the source decision, and the best available code revision at the time of the decision. server/…/decision-training.ts• L89-156 server/…/decision-training.ts• L159-269

The source can be an interaction, approval, or execution decision. For an unresolved source, the capture ends at the time of capture. For a resolved source, it ends at the recorded outcome. This keeps later comments and runs outside the frozen decision context. server/…/decision-training.ts• L89-156

Operators can preview a record before saving it, create one per user and source decision, search and filter records, and update notes with history. Retention protects deleted source content by redacting deleted comments in the snapshot; deleting the issue cascades through the training record. server/…/decision-training.ts• L272-345 server/…/decision-training.ts• L347-403

References: server/…/decision-training.ts• L89-156 server/…/decision-training.ts• L159-269 server/…/decision-training.ts• L272-403

Human intervention paths

Human intervention follows the source of the blockage. The system keeps the original owner and source record where possible, then offers the smallest safe action that can restore progress or make the next owner clear.

Resolution choices

The main paths are:

SituationFirst useful pathResult
Agent asks a bounded questionAnswer or choose an option inlineThe waiting interaction resolves and the agent can continue
Agent proposes an issue changeReview the decision and choose an optionEffects run against checked target snapshots
A request needs permissionApprove, reject, or request revisionThe requester receives the result or can resubmit
Automatic retries endRetry, reassign, or dismissWork gets a new attempt, a new owner, or a recorded dismissal
A blocker has no live pathUnblock, reassign, or nudgeThe blocked work gets a valid next path
Review has no maintained reviewer pathChoose a review path or request changesThe issue returns to a clear review or work owner
An agent or budget is unhealthyInspect, raise the budget, or keep pausedThe operator addresses the health condition before more work runs

These paths appear in row actions and expanded resolvers. An item that cannot resolve safely in place links to the task, run, agent, cost view, or access view that owns the action. packages/…/attention.ts• L48-52 server/…/attention.ts• L1428-1463 server/…/attention.ts• L1715-1744

References: packages/…/attention.ts• L48-52 server/…/attention.ts• L1428-1463 server/…/attention.ts• L1715-1744

Continuation wakes

When a decision or approval controls an agent's next step, resolution can queue a wake for the source agent. Delivery is at least once, so a retry can occur after a process failure. Wake requests coalesce concurrent work and carry the outcome back to the agent. Native status decisions use the same control path to route work to a reviewer, blocker owner, retry, continuation, dependency owner, board response, or recovery owner. The commit records these routes as effects and can leave the issue in place while the human or agent completes the next step. If interaction policy denies a wake, the denial is recorded and the finalization can become terminal instead of retrying an unauthorized action. server/…/decisions.ts• L610-617 server/…/approvals.ts• L321-362 server/…/status-decision-committer.ts• L469-550 server/…/status-decision-committer.ts• L684-1089 server/…/status-decision-committer.ts• L1722-1737 server/…/status-decision-committer.ts• L2692-2707

References: server/…/decisions.ts• L610-617 server/…/approvals.ts• L321-362 server/…/status-decision-committer.ts• L469-550 server/…/status-decision-committer.ts• L684-1089 server/…/status-decision-committer.ts• L1722-1737 server/…/status-decision-committer.ts• L2692-2707

Lost review paths

An issue can reach review without a reviewer, interaction, approval, monitor, live run, or recovery owner. Paperclip surfaces this as a high-severity review item instead of leaving the issue in a silent wait. The operator can choose a maintained review path or request changes. server/…/attention.ts• L1637-1689 server/…/attention-source-eligibility.ts• L108-112

References: server/…/attention.ts• L1637-1689 server/…/attention-source-eligibility.ts• L108-112

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the attention source kind list aligned across feed generation, shared types, queue validation, retention candidate selection, source eligibility, and source access checks.
  • Keep decision creation provenance and idempotency aligned across origin-run checks, duplicate requests, open-decision limits, target snapshots, and signed specifications.
  • Keep decision option effects aligned with target snapshot creation, stale-target checks, effect execution, and card result labels.
  • Keep archive proposals aligned across signed manifests, attention retention state, authority checks, replay handling, and effect recovery.
  • Keep approval status transitions aligned across board actions, requester resubmission, linked issue wakes, Inbox actionable filters, retries, actor attribution, and cleanup cancellation.
  • Keep approval company-scope checks aligned with every route that reads or changes an approval.
  • Keep status-only recovery restrictions aligned across approval creation, resubmission, and comment routes.
  • Keep hire approval side effects aligned across the approval transaction, agent activation or creation, built-in-agent reconciliation, budget policy setup, enforcement delivery, and hire notification.
  • Keep queue seed signals aligned with the attention conditions that they collect.
  • Keep attention summary, task index, history, feed filters, cursor rules, and board access checks aligned across the attention routes and service.
  • Keep source eligibility aligned across the desk and retention worker for confirmations, failed runs, reviews, blockers, human recovery owners, agent errors, and budget warnings.
  • Keep retention candidate paging, scope matching, source locks, blocker variants, and current-version checks aligned with the attention feed's eligibility rules.
  • Keep conversation question projections aligned with handoff session scope, direct-task assignment, attention audience rules, dismissal, snooze, archive, and conversation exclusion.
  • Keep conversation receipt boundaries aligned with reset comments, initial conversation creation, handoff provenance, current task access, and the shared history cursor.
  • Keep decision model availability aligned with company settings, feature registration, actor access, connection grants, credential state, budget admission, provider outcomes, and cost records.
  • Keep provider receipt parsing aligned with usage fields, provider request identity, pricing provenance, safe error codes, and no-work accounting.
  • Keep decision invocation settlement aligned with budget reservation release, cost events, deleted source records, and interrupted work recovery.
  • Keep decision training source capture aligned with interaction, approval, and execution-decision outcomes and their cutoff times.
  • Keep decision training retention aligned with comment deletion redaction and issue deletion cascade behavior.
  • Keep status-card lifecycle labels aligned with stored state, the last good summary, and the actions allowed in the card tile.
  • Keep status decision effect materialization, delivery states, target checks, and idempotency rules aligned with the status decision lifecycle, native commit, and reconciliation.
  • Keep reason-specific status preconditions aligned with the source records they protect, including accepted results, completion evidence, review gates, monitor waits, board responses, and plan waits.
  • Keep native wake permission denials aligned with skipped wake effects, finalization failure state, recovery ownership, and the operator-facing attention path.
  • Keep summary-slot generation writes tied to the active generation task and its scope selector.
  • Keep interaction readiness polling tied to pending workspace sync, and keep receipt caching aligned with attention-feed invalidation.
  • Keep Inbox hosted and standalone views aligned with tab scope, mixed work-item categories, approval filters, blocked-task controls, search supplements, grouping and nesting preferences, read state, archive eligibility, optimistic rollback, alert dismissal, undo behavior, and Mine snapshot timing headers.

Important failure modes

TriggerConsequenceGuard
A decision target changes after proposalA strict effect is skipped and the decision can become partialTarget snapshots and strict stale-target checks
A decision signature does not matchThe choice is rejected before effects runHMAC verification of the canonical specification
A decision expires before responseThe decision becomes expired and the source can receive an expiry wakeExpiry check and expiry transition
A duplicate decision request uses a different payloadThe request conflicts instead of changing the existing proposalIdempotency-key payload comparison
An archive manifest or its signature changes during reviewThe archive fails without archiving the changed setSigned manifest hash and current retention checks
A decision provider is disabled, unavailable, or over budgetNo model answer is producedSettings, connection, access, credential, and budget admission checks
A provider rejects a request or refuses an answerThe invocation fails with a safe code and bounded accounting dataNormalized provider outcome and error redaction
Provider work ends after its source record is deletedAccounting can still settle without broken source linksLive-row checks before cost event links are written
A decision invocation remains running after a process failureThe invocation would remain unresolvedRecovery of stale running invocations
A chosen decision option or decider is no longer valid during effect recoveryThe decision becomes failed or partial instead of remaining stuck in running stateInvalid-effect outcome settlement and recorded recovery error
Pending native status has a different issue version or prior decisionThe native status decision is not appliedLocked issue checks and race validation
A native status decision races with a newer gate, review, wait, or execution ownerThe decision is rejected and the work must be reassessedLocked source checks and reason-specific preconditions
A native status effect targets a missing or cross-company objectThe effect is not deliveredCompany, issue, and target validation before ledger delivery
Agent interaction policy refuses a native wake or assignmentThe wake is skipped or the native finalization becomes terminally refusedPermission checks, denial recording, and terminal finalization state
A pending approval is resolved twiceThe second incompatible action fails without duplicate follow-up workConditional state transition and applied-result check
A hire approval fails during agent or budget setupThe approval and direct hire changes do not commit as a partial resultCompany-locked approval transaction
A bulk archive item changes during reviewThe archive proposal fails without archiving the changed setManifest, version, activity, and authority checks
A summary write comes from the wrong task or scopeThe summary slot rejects the writeActive generation task and scope checks
A status-card refresh reaches a budget or hour limitAutomatic updates pause while the last good summary remainsPolicy evaluation and paused lifecycle state
An interaction is still waiting for workspace syncThe resolver must not accept an interaction that is not readyPending-state readiness polling
A company alert is dismissedThe Inbox hides the alert while the health condition remainsSeparate alert dismissal state from health source
A deleted comment remains in a training snapshotDeleted source text remains visible in training dataComment redaction with retention metadata
An Inbox task archive fails after local removalThe task reappears and the action error is shownCache snapshot restore, local archive cleanup, and query invalidation
A failed-run retry is rejectedThe failed row remains available and the operator sees an errorStable issue retry key and per-run retry state cleanup
A pending confirmation is replaced by a newer confirmationThe older row is hidden so the operator does not answer stale workNewest-confirmation collapse with an exception for independent quality reviews
A failed run has a newer run for the same issue or agentThe old failure is not shown as current attentionNewer-run suppression keyed by issue or agent
A blocker graph exceeds the bounded search or has unknown work beyond its frontierThe root is deferred instead of being falsely marked clear or actionableBounded traversal, visited sets, and deferred-root handling
A retention deadline is reached while the source changesThe item is not archived until the current source is recheckedSource lock, eligibility check, and retention-version match
A conversation reset has no boundary provenanceOrdinary-task decision receipts are omitted rather than showing history from an unknown timeFail-closed session boundary selection
A task's audience or access changes after a conversation readIts questions or receipts are not returnedCurrent conversation and task access checks on every read
A handoff task is also visible as an ordinary taskThe conversation can duplicate or leak a task across sessionsHandoff provenance and exclusion from the direct-task scope
A native status decision has a mismatched accepted result, gate, monitor wait, board wait, or plan waitThe commit is rejected as stale and the source must be reassessedLocked source revalidation and reason-specific proof checks
A native completion lacks required deliverable evidenceThe issue is not marked doneAuthoritative result and deliverable evidence validation
A native wake is denied by interaction policyThe wake is recorded as skipped and the finalization can become terminal failurePermission check, denial detail, and terminal coordinator update

Key files

FileWhy to read it
server/…/attention.tsDefines board-only attention feed, summary, task index, and history entry points and their filters.
server/…/attention.tsDefines the unified attention model, source rules, eligibility-aware feed construction, ranking, triage, retention enrichment, and feed output.
server/…/attention-source-eligibility.tsDefines shared rules for human recovery ownership, confirmation collapse, newer failed runs, review attention, and terminal blockers.
server/…/attention-retention.tsDefines scoped due-item selection, source revalidation, blocker variants, and automatic attention archiving.
packages/…/attention.tsDefines attention items, sources, actions, details, and resolver audiences.
server/…/decisions.tsDefines proposal provenance, idempotency, signing checks, effect execution, archive proposals, outcomes, and wakes.
ui/…/DecisionCard.tsxShows option previews, stale targets, effect results, and failures.
server/…/decision-models.tsDefines model settings, access and budget admission, invocation history, and accounting.
server/…/decision-model-provider.tsDefines provider calls, normalized answers, receipts, pricing, and safe failure codes.
server/…/approvals.tsDefines approval transitions, comments, hire effects, cleanup cancellation, and follow-up hooks.
server/…/approvals.tsConnects board actions to activity records and requester or review-path wakes.
server/…/conversation-decision-receipts.tsConnects conversation views to current-session questions, handoff tasks, and access-checked decision history.
server/…/decision-history.tsDefines the shared decision history query and cursor used by receipts and attention views.
server/…/issues.tsExposes conversation pending-question, handoff-task, and decision-receipt reads.
server/…/decision-training.tsDefines frozen decision context, note history, and retention updates.
server/…/decision-queues.tsDefines queue sources, memberships, seed rules, and triage ownership.
server/…/decision-retention.tsDefines keep, shelf, archive, revive, and bulk archive behavior.
ui/…/Inbox.tsxHosts the Inbox and Tasks work surface, mixed work rows, filters, search, grouping, read state, archive or retry actions, and company alerts.
ui/…/inbox.tsDefines Inbox tabs, categories, actionable approval states, alert visibility, and ordering.
server/…/issues.tsServes the coordinated Mine snapshot and its task, failure, and context reads.
server/…/inbox-mine-timing.tsDefines the phase timing data shared by Mine snapshot responses and coalesced reads.
server/…/status-cards.tsDefines watched issue scope and status-card refresh and summary flow.
server/…/status-decision-committer.tsDefines checked native status effects, human gates, wakes, continuation, recovery, replay, and reconciliation.
server/…/summary-slots.tsDefines scoped summary generation, task ownership, and revision writes.