Issue execution and collaboration
Issue execution is the work loop that turns a tracked request into agent or human action. It joins ownership, dependency order, thread messages, review decisions, approvals, wakeups, recovery, and visible work products so work can move from creation to completion without losing the next responsible actor. See the agent work management page for the wider model, execution environments for workspace choices, agent instructions for agent behavior, adapter integrations for external channels, native runner execution for native runs, runner evaluation and conformance for runner contracts, case handoffs and continuity for same-task transfers, and reusable workflows for repeatable work.
Issue lifecycle
Issue states
An issue is a unit of work with a status that tells the system whether it is available, active, waiting, or complete. The main path is backlog to todo to in_progress to in_review to done; blocked and cancelled describe alternate paths. A backlog issue is parked and does not wake its assignee. A todo issue is executable when its dependencies and execution gates allow it.
Status changes carry meaning for the next actor. Moving work to in_progress starts its work timing. Moving it to done or cancelled records completion or cancellation time. Leaving active work or changing its assignee clears the active run claim, advances the status version when needed, and invalidates old user-directed wakes. This prevents a late run or stale request from acting as the current owner. An agent also cannot leave blocked while an execution recovery hold is active; the hold must be released through recovery before the agent can resume. Terminal changes settle governed thread actions and stop live native question work while keeping ordinary question history visible.
The issue read model exposes the latest run's interruption state, scheduled retry, recovery action, dependency attention, review attention, successful-run handoff, execution blocker, and current execution workspace. These views let the list and detail surfaces explain whether work is active, retrying, failed, waiting for a user, or resolved without exposing every recovery record.
References: server/…/issues.ts• L7286-7299 server/…/issues.ts• L15199-15215 server/…/issues.ts• L11889-11938
Execution handoffs
An execution handoff records that a successful run needs a clear disposition before the issue can safely move on. The issue read model exposes whether the handoff is required, resolved, or escalated, together with the source run and the actor who must continue the work. This keeps a successful process result separate from the decision about issue status.
The continuation summary gives the next run the objective, acceptance criteria, recent actions, blockers, paths, and next action. A failed or timed-out run points to the latest concrete action and error. A review or approval wait points to the decision path instead of inviting duplicate implementation work.
References: server/…/issue-continuation-summary.ts• L137-214 server/…/issues.ts• L5574-5705 server/…/issues.ts• L10162-10248
Execution ownership
An assignee is the actor expected to advance an issue. Checkout marks an issue as claimed by an agent run. Release gives the work back without changing the broader issue history.
The system checks assignment rights, dependency readiness, pause state, project pause state, and run identity before checkout. Changing an assignee invalidates the old execution claim, cancels pending user-directed wakes, and expires ownership-bound connection requests. A same-task case handoff is a controlled ownership transfer, so an old run must not mutate work after responsibility moves.
Some external agents keep execution outside Paperclip. Stopping such work revokes Paperclip session authority but cannot prove that the remote process stopped. The operator must inspect the external agent at that boundary.
References: server/…/issues.ts• L17102-17152 server/…/issues.ts• L12017-12026 server/…/issues.ts• L12227-12250
Issue creation and delegation
Issue creation
Issue creation is the entry point for new work. The creator supplies a request and can choose the title, status, priority, assignee, project, work mode, review participants, workspace intent, execution policy, and supporting files. The same flow supports a child issue under an existing issue.
The creation path checks company access, assignment scope, environment choice, and monitor authority before it saves the issue. It prevents agent-created work from inventing human attribution and rejects unsafe workspace command input. Idempotency and recent-title checks can return an existing open issue instead of creating duplicate work. A successful assigned creation may enqueue a fast response so the assignee can start without waiting for a later poll.
Standing agent chats use the issue record as a durable conversation. Their display title is resolved from the current agent name when the chat is saved, while ordinary execution issues keep their own titles and numbered identifiers. This lets a renamed agent appear correctly in a newly opened chat without consuming an execution task number.
The route preserves the source run as creation context when an agent delegates work. If the caller omits a parent, an ordinary delegated follow-up can inherit the run's issue as its structural parent. Agents cannot create arbitrary deep trees: requests can be placed beside the requester when the parent-depth policy requires flattening. Watchdog follow-ups and board actions use their own permitted nesting rules.
If an assigned issue is executable, creation can wake the assignee. If it is assigned to backlog, the agent stays asleep until the issue is resumed. An onboarding first task is a deliberate exception: it starts with a greeting and opening question, then waits for the user's first message. A task created as done or cancelled is recorded without a wake.
References: server/…/issues.ts• L13222-13520 server/…/issues.ts• L13823-13864 server/…/issues.ts• L10582-10662
Child issue delegation
A child issue is a separate work item linked to a parent issue. It can have its own owner, status, workspace, and conversation while the parent provides context and coordination. A completed child can wake its parent with a bounded summary so the parent can decide the next step.
Agents can suggest a task tree inside a thread. Suggestions remain drafts until a resolver accepts them. Acceptance creates real child issues in dependency order. Accepted plan decomposition is tied to the approved plan revision, so a retry of the same accepted plan is safe and does not silently create a second tree.
Structural parentage is separate from creation provenance. The issue that produced a run is not necessarily its parent or blocker. Idempotent delegation records whether a requested child was newly created or an existing open issue was reused.
References: server/…/issues.ts• L13531-13805 server/…/issues.ts• L13808-14074 server/…/issue-thread-interactions.ts• L3717-3916
Issue privacy
Issue privacy controls who can discover, read, and collaborate on work. An issue can be private by direct choice or because it belongs to a private project or issue tree. New work can inherit the private boundary from its parent or source run.
The effective audience combines issue owners, project members, inherited grants, and explicit user or agent grants. The issue view and relation edges redact work outside the reader's boundary. Responsible users, issue owners, and administrators manage grants on the exact issue. Assignment to private work can create an access grant for the new assignee.
References: server/…/issues.ts• L3765-3827 server/…/issues.ts• L14156-14208 server/…/issues.ts• L14210-14296
Dependency coordination
Blocker relationships
A blocker is an issue that must finish before another issue can proceed. The dependency graph uses blocks relationships rather than status text alone. A dependent issue reports direct blockers and can show the deepest unresolved leaf in a blocker chain.
Only a blocker in done resolves a dependency. A cancelled blocker remains unresolved until an operator removes or replaces the relationship. A done blocker can still hold its dependent while its shared execution workspace has not reached a successful finalization. A successful workspace-finalize record from recovery can settle that barrier for the same recovered task and run without marking the shared workspace finalized for other work.
The service rejects self-blocking and blocking cycles. This protects the dependency graph from an order that no issue can satisfy.
References: server/…/issues.ts• L2475-2486 server/…/issues.ts• L2775-2853 server/…/issues.ts• L1299-1379
Dependency readiness
Dependency readiness is the gate that decides if an issue may be woken or started. A dependent is ready only when all blocker edges are resolved and no finalization barrier remains. Status changes to in_progress and recovery retries are rejected when unresolved blockers remain.
The issue view explains the gate in human terms. It names unresolved work, shows parked blockers, and distinguishes a stalled review from healthy live work. Diagnostic responses are bounded and hide blockers outside the actor's access scope.
References: server/…/issues.ts• L2775-2853 server/…/issues.ts• L1299-1442 server/…/issues.ts• L10035-10082
Dependency wakeups
When the last blocker resolves, the system requests a wake for the dependent assignee. The wake represents the current ready state rather than one isolated edge. This makes repeated status updates safe and prevents old completed wake requests from suppressing a new ready state.
Wake requests can be queued, claimed, completed, coalesced, deferred, skipped, failed, or cancelled. Issue diagnostics join wake requests with related activity so an engineer can tell whether no wake was needed, a wake is waiting, a tree hold deferred it, or a wake failed.
References: server/…/issues.ts• L1450-1660 server/…/issues.ts• L368-383 server/…/issue-dependency-wakeups.ts• L1-220
Thread collaboration
Issue thread
The issue thread is the shared record of work. It combines human and agent comments with run output, tool activity, status changes, work-mode changes, interaction cards, blocker notices, and recovery notices. This gives the next actor the request, the work already done, and the reason the issue is waiting.
Comments can ask a question, provide context, mention an agent, request a follow-up, or explicitly resume work. A genuine human comment can supersede a replaceable pending request. The server records a comment and its coupled status decision together when both must succeed as one action.
Queued comments form a versioned message set for an active run. Editing and reordering change the pending set only when the caller has the current queue revision. Steering can deliver a message during a supported native turn. Interrupting uses the runner's stop path when same-turn steering is not available. A first-turn queue can instead join a run before its first provider turn.
References: server/…/issues.ts• L2243-2335 server/…/issues.ts• L17460-17757 server/…/issues.ts• L19470-19544
Thread interactions
A thread interaction is a structured request that waits for a response. It differs from a plain comment because it has a type, audience, target, and result. Supported interactions include task suggestions, user questions, confirmations, item verdicts, and connection requests.
Question interactions use one canonical question form. The server validates answers against that form before recording completion. The interaction card stays visible after resolution so the thread retains the decision and its result. Interaction creation is idempotent when the caller supplies an idempotency key.
Pending interactions can wake a named addressee. Accepting a task suggestion can create child issues and wake their assignees. Resolving a confirmation or verdict can queue a continuation wake for the issue owner. A plan confirmation uses a fresh session so the next run sees the accepted plan as its new decision point.
Governed tool actions and secret proposals are server-owned records rather than caller-supplied approval metadata. Older result shapes are shown as unresolved results instead of breaking the thread.
References: server/…/issues.ts• L17811-17994 server/…/issues.ts• L18026-18353 server/…/issues.ts• L18475-18667
Historical questions
An ordinary question is saved conversation data, not proof that the issue still has a blocker. When a later genuine human comment moves work forward, the earlier question becomes historical. It remains visible without making the agent repeat the request or stop unrelated work.
Approval, permission, credential, connection, and configured review gates remain independent. When an issue reaches a terminal state, live native question work is cancelled while an ordinary historical question can remain in the feed.
References: server/…/issue-question-context.ts• L4-70 server/…/issues.ts• L12434-12489 server/…/issues.ts• L18500-18564
Question response delivery
An answered question must reach the agent that asked it or the next run that owns the issue. The system records the answer on the interaction and creates one durable delivery receipt. Delivery first tries an active native question or running successor. If that path is not available, it reuses or creates one idempotent wake request.
The following flow shows how a response reaches an active run or a continuation wake.
flowchart LR
A[Answer question] --> B[Store answer and delivery receipt]
B --> C{Active question or successor?}
C -->|Yes| D[Deliver to run]
C -->|No| E{Wake available?}
E -->|Yes| F[Reuse or create wake]
E -->|No| G[Keep receipt pending]
D --> H[Record delivered]
F --> H
G --> B
The delivery route can complete synchronously when the target is available. If delivery fails, the durable receipt remains available for the outbox to retry.
References: server/…/issues.ts• L18500-18564 server/…/question-response-delivery.ts• L498-776 packages/…/issue_question_response_deliveries.ts• L17-64
Resolver audience
The resolver audience defines who may close a thread interaction. anyone permits the normal company audience. not_creator excludes the creator. human_only requires a human user. A named agent addressee narrows agent resolution to that agent.
The server evaluates the audience again when the actor submits the response. Missing run attribution, an addressee mismatch, a stale target, a closed issue, and a policy violation fail as explicit resolution errors. Governed tool actions and secret proposals always require independent human authorization.
Skipping has a narrower meaning than accepting or rejecting. It does not normally start a continuation, while an application question can use a skip as the user's answer and wake the waiting app path.
References: server/…/issue-thread-interaction-resolution.ts• L8-315 server/…/issues.ts• L18026-18667 ui/…/IssueThreadInteractionCard.tsx• L52-91
Review and approvals
Review decisions
Review is a controlled handoff from execution to judgment. A review policy can allow anyone, require a human, or require a writer other than the actor who moved the issue into review. The system identifies that requester from the status transition and applies the policy to the verdict.
Review can approve the issue, request changes, or become stalled if no valid decision path remains. Stalled review appears in the Decisions queue, where an operator can choose a reviewer, return the issue to work, or accept it. Several required reviewers must all decide before the issue is complete.
References: server/…/issue-review-policy.ts• L23-147 server/…/issues.ts• L4513-4934 server/…/issues.ts• L14300-14431
Approval links
An approval is a separate decision record that can link to one or more issues. The link makes the approval visible from the issue and lets it participate in a larger approval flow without copying the approval payload into the issue. The issue and approval must belong to the same company.
Issue approval links are part of the issue control plane. Link and unlink actions are recorded in activity history. These links are separate from a thread confirmation, although a thread confirmation can govern a concrete action.
References: server/…/issues.ts• L13202-13295 server/…/issue-approvals.ts• L12-172
Governed action approvals
A governed action is a confirmation that controls a real external or sensitive action. Approval means the action can run; it does not mean that execution succeeded. The UI shows pending, running, executed, failed, declined, and expired states so permission and outcome remain separate.
Plan confirmations bind the decision to the current plan revision. Secret proposals keep the sensitive value behind the proposal workflow. Withdrawal, skip, close, or supersession settles linked executable requests and secret proposals.
References: server/…/issues.ts• L18066-18245 server/…/issue-thread-interactions.ts• L1069-1207 ui/…/IssueThreadInteractionCard.tsx• L324-523
Recovery and wakeups
Recovery actions
A recovery action is a tracked repair path for an issue that cannot safely advance on its normal path. It records the cause, evidence, current owner, next action, wake or monitor plan, attempt count, and outcome. The recovery owner repairs the path; the source issue keeps its task owner unless an explicit decision changes it.
There is one active recovery path for a source issue and failure identity. When the retry budget is exhausted, the action becomes board-owned and loses automatic wake and monitor paths until an operator chooses the next step. Recovery can retry the source owner, hand the repair to another agent, or escalate to the board. While an execution recovery hold is active, the source issue remains blocked for agent-initiated resume or status changes; recovery must release the hold before normal execution can continue.
System recovery is shown as an interruption rather than an ordinary task decision. A retry creates one durable intent and returns a receipt before dispatch. Workers can redeliver that intent after a lost response or process restart. A retry of a saved result can finish the accepted result without starting another provider turn.
References: server/…/issues.ts• L10035-10150 server/…/issues.ts• L10252-10799 server/…/issues.ts• L4539-4679
Workspace recovery
Workspace recovery protects work when the execution workspace no longer matches the recorded branch or when a run stopped before it could hand back a safe next step. The operator can use forward reconciliation when ancestry is safe, a guarded override, a clean repair path, or a fresh isolated re-issue when the workspace is contested.
Saved workspace results have dedicated recovery paths. An operator can resume finalization after verifying that the previous workspace controller stopped, retry an export after repairing the retained sandbox, or reconstruct a workspace from saved sources. These paths preserve the accepted result and do not start another provider turn unless the selected action requires one. A recovered finalize can release a parent's dependency wait only for the matching task and run.
References: server/…/issues.ts• L10153-10250 server/…/issues.ts• L10342-10673 server/…/issues.ts• L2489-2853
Task retry
Task Retry is an explicit request to continue a failed, interrupted, scheduled, or saved-result path. The route first records an idempotent receipt and then nudges the suitable worker. This order lets maintenance recover the request if the process stops after the response or before dispatch.
The retry path still checks current ownership, status, blockers, pending interactions, run identity, and workspace safety. It does not reopen terminal work or silently retry a different assignee from an old notice. Connected chat retries use their own delivery owner, while saved native results use result finalization.
References: server/…/issues.ts• L10084-10150 server/…/issues.ts• L10520-10673 server/…/task-retry.ts• L53-165
Wakeup paths
A wakeup asks an agent runtime to look at an issue again. Assignment, dependency resolution, interaction creation, comments, scheduled timers, execution-stage changes, recovery actions, and a deliberate task Retry can all produce wakes. Wakeups are coalesced when several events point to the same issue and agent.
A tree pause hold can defer a wake until the operator releases the hold. On release, the system rechecks current status, assignee, and execution blockers. It wakes only eligible current assignees; blocked and parked backlog work remain idle. If a paused assignee is resumed from the detail page, the UI reissues the assignment wake for executable work because the original wake may have been dropped.
References: server/…/issues.ts• L13447-13520 server/…/issues.ts• L14379-14423 server/…/issues.ts• L12181-12237 ui/…/IssueDetail.tsx• L4665-4724
Access and inbox attention
Issue access
Issue access determines which work appears in lists, detail views, searches, and relation summaries. The access boundary applies before execution data is shown. A reader can see a locked relation edge without learning the private issue's content.
Private work can be read through effective grants, owner and project membership rules, or an audited administrator path. An ancestor privacy root does not by itself grant authority to mutate a child.
References: server/…/issues.ts• L14156-14208 server/…/issues.ts• L11162-11299
Inbox attention
Inbox attention is a per-user view of issue activity that still needs a response. A user archive hides the issue until a later interaction, meaningful status transition, mention, or external human comment creates new attention. Completion archives the responsible user's inbox so done work does not remain as an open task.
Personal task views can also include archived work or show only archived work. The list marks the archive state for the current user, while the underlying issue status remains independent. This lets an operator recover an old conversation without treating archive state as a new execution request.
Inbox state is a durable view of attention rather than a second source of issue status. The personal inbox uses a dedicated snapshot with a fixed attention filter, while the organization task list supports broader filters and pagination. Archive writes coordinate with issue completion so a delayed request does not replace a newer archive timestamp.
References: server/…/issues.ts• L8822-8830 server/…/issues.ts• L8984-9002 server/…/issues.ts• L8595-8606 server/…/issues.ts• L8840-9000
UI workflow
Issue list workflow
The task surface is the entry point for finding work by personal attention or organization scope. In the combined task surface, personal views render the inbox list while organization views render the task collection. View changes are URL-addressable and start with the new view's own search and filters.
The task collection can filter by assignee, participant agent, workspace, origin, status, search text, and dependency attention. Personal views can include archived issues when an operator needs to recover past attention. Workflow sorting includes blocker information. It uses paged projections, request coalescing, and shared live-run updates so the collection can show current work without making every row load the full issue detail.
The normal list flow is:
- Select the task view that matches personal attention or organization work.
- Search or filter the collection.
- Include archived work when the needed conversation is no longer active in the inbox.
- Open the issue that needs action.
- Follow its owner, blocker, review, interruption, or recovery path.
References: ui/…/Issues.tsx• L93-168 ui/…/Issues.tsx• L171-313 server/…/issues.ts• L8775-9062
Issue detail workflow
The issue detail page is the main control surface for execution. It brings the request, thread, sub-tasks, documents, runs, workspace, related work, approvals, recovery state, interruption state, and activity into one place. The task chat shell makes the thread the main work surface; the classic interface keeps separate tabs when that mode is selected.
The page loads a small core projection first, including saved documents and work products, then adds richer issue and thread data. It can show recent history first, load a linked comment directly, and expand older history when the operator needs it.
The normal operator sequence is:
- Read the issue brief and current status.
- Check the assignee, live run, blocker chain, review path, interruption state, scheduled retry, and workspace state.
- Add context or a follow-up comment when the agent needs direction.
- Resolve any pending interaction or review decision.
- Edit, steer, interrupt, or cancel queued comments when the active run has not consumed them.
- Use Retry, recovery, reconciliation, or a scheduled retry when the normal path is stalled.
- Pause or resume a leaf issue or issue subtree when work needs a controlled hold.
- Confirm the final status, owner, handoff state, produced artifacts, and activity record.
References: ui/…/IssueDetail.tsx• L3339-3479 ui/…/IssueDetail.tsx• L8150-8287 ui/…/IssueDetail.tsx• L8462-8699 server/…/issues.ts• L10035-10799
Execution feedback
The detail thread shows live runs while they work and keeps a run ledger after they finish. Run status, latest output, and next-step notices remain visible even when reasoning and tool activity are collapsed. A transcript fallback keeps the issue readable if the rich chat renderer fails.
Live updates reduce polling while the runtime connection is healthy. The page keeps a bounded fallback when that connection is unavailable. Queued human messages appear as soon as the user submits them, with controls to cancel or interrupt. If delivery fails or the run stops, the queue and inline error can be restored so the user can retry without losing the message.
The execution notice presents system-owned failures as a saved-message state, countdown, or Retry action. User-owned gates remain visible as approval, reconnect, assignment, model, budget, or resume actions. Interaction cards show who may act and keep server denial reasons beside the action.
References: ui/…/IssueDetail.tsx• L8193-8224 ui/…/IssueDetail.tsx• L8502-8699 ui/…/IssueDetail.tsx• L7022-7061
Sub-task workflow
The detail page connects the parent task to its child work. A sub-task list shows child status, dependency order, checklist steps, and progress so the parent view can relate execution state to completed work below it. The parent can also create a new sub-task with defaults derived from the current issue.
When the list is grouped in a way that hides order, the checklist affordance is not used. This keeps the visible task order and the meaning of progress aligned.
References: ui/…/IssueDetail.tsx• L8241-8287 server/…/issues.ts• L13531-13805
Continuation handoff
The continuation handoff is the visible bridge between a finished run and its next actor. It presents the current handoff summary with its revision and update time. Another agent can use the summary without repeating earlier work.
Results from monitor continuations and question-driven successors retain their accepted explanation and verified conversation origin. A successful provider run therefore does not look complete when the issue still needs another run.
References: ui/…/IssueContinuationHandoff.tsx• L10-89 server/…/issues.ts• L1121-1209 server/…/issues.ts• L5574-5705
Artifact workflow
The artifacts view shows what the issue produced after execution. It groups work products by producing run and combines them with issue documents and agent-produced files. User uploads remain in the conversation thread.
Native agent helpers can read a named document across a bounded set of readable issues in one request. The batch uses the normal issue access boundary and can return revision metadata without bodies, so helpers can compare work before fetching changed content.
Markdown work products can expand into the review document surface. Unsupported or large files remain available through raw open or download. Pull request products have a direct review surface that keeps saved state visible when provider data is stale or unavailable.
References: ui/…/IssuePropertiesArtifactsTab.tsx• L75-274 ui/…/IssuePropertiesArtifactsTab.tsx• L354-641 ui/…/IssuePullRequestLinks.tsx• L8-46 server/…/issue-document-batch.ts• L44-95
Change checklist
When these files or sections are changed, remember to consider these:
- Keep issue status rules aligned with assignment wake behavior. Do not wake an assignee for parked backlog work.
- Keep blocked recovery holds aligned with every agent path that can move work to
todoorin_progress. A recovery notice must not be bypassed by checkout, status update, or follow-up comment. - Keep blocker readiness, workspace finalization, and dependency-resolved wake idempotency aligned. A dependent must not start before synced blocker work is ready.
- Keep recovery-finalize matching aligned with the dependency barrier. A recovered child's saved files can release its parent's wait only for the same task and run; it must not clear the shared workspace barrier for unrelated work.
- Keep interruption presentation aligned with the latest run, recovery state, pause state, approval state, and the user action that can unblock work. Presentation must not grant dispatch authority.
- Keep task Retry idempotency, observed-run checks, durable receipts, chat ownership, and recovery generations aligned. A lost response must not create a second retry generation.
- Keep issue-tree pause preview and release eligibility aligned. Recheck current status, assignee, blockers, and execution blockers when a hold is released.
- Keep interaction payload kinds, canonical question forms, resolver audience rules, and UI card states aligned. Define stale, superseded, closed, and governed-action behavior for each response path.
- Keep ordinary-question history separate from active interaction gates. A later message must not make an old question a blocker.
- Keep answered question results and delivery receipts aligned. A retry must reuse the same interaction identity and continuation contract.
- Keep review requester attribution aligned with the
in_reviewtransition. - Keep same-task handoff guards and assignment transitions aligned. An old run must not mutate work after transfer.
- Keep continuation publication lineage and provider authority aligned across monitor runs, question successors, and long chains. Reject cycles or ambiguous origins.
- Keep recovery ownership separate from source issue ownership. Recovery hand-back must still honor active runs, review gates, approvals, pause holds, and budget gates.
- Keep saved workspace recovery actions separate from ordinary recovery resolution. Verify a stopped workspace owner before resuming finalization.
- Keep linked tool actions and secret proposals in the same lifecycle as their interaction. Terminal issue expiry must not leave a sensitive or executable resource active.
- Keep private issue inheritance, effective grants, relation redaction, and privacy-tree writes aligned.
- Keep inbox archive filters,
isArchivedForMe, archive timestamps, and issue-list cache freshness aligned. Archived work must be recoverable without changing issue status or showing stale rows after archive and undo. - Keep inbox archive ordering aligned with terminal issue completion.
- Keep live-update state and polling fallback aligned. A lost runtime connection must not leave the issue detail page with stale run state.
- Keep compact history, linked-comment loading, and full-history expansion aligned. A direct comment link must not discard the current recent window.
- Keep queued-comment wake queries scoped to the current issue. A wake from another issue must not become visible as pending input.
- Keep paused-agent resume aligned with assignment wake behavior. Resuming the agent alone must not leave executable assigned work idle.
- Keep child-creation activity provenance aligned with idempotent reuse. A reused issue must not appear as a new child.
- Keep accepted plan revision checks aligned with child creation. A stale plan must not create a new task tree.
- Keep interaction continuation wake rules aligned with the interaction kind. A skipped ordinary card must not start work when only an app question requires a wake.
- Keep sub-task checklist and progress-summary affordances aligned with list grouping and parent scope.
- Keep coordinator task-view routing aligned with inbox and organization filters. Personal views must not lose their inbox meaning.
- Keep list projections, filters, pagination, live-run summaries, interruption state, and recovery state aligned. A task row must not show a different next action from its detail view.
- Keep generated standing-chat titles separate from execution task identity. Agent rename and chat creation must not alter custom titles or consume numbered task identifiers.
- Keep bulk document reads aligned with issue visibility, response and concurrency limits, and native child or handoff read receipts. An agent must not treat omitted unreadable issues as an empty document.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
An issue is assigned but remains in backlog | The assignee is not woken and the issue stays parked | Resume it to todo before expecting execution |
An agent tries to leave blocked while an execution recovery hold is active | The status, checkout, or follow-up is rejected and the issue stays blocked | Release the recovery hold through its recovery action before resuming |
A dependent has a blocker marked done but workspace finalization is pending | The dependent remains not ready | Wait for successful workspace finalization and the readiness wake |
| A done child has recovered and saved its files, but the recovery finalize is not matched to the child run | A parent's Retry can remain held on a dependency that is already saved | Match the successful recovery finalize to the same child issue and run before releasing the child barrier |
| A paused subtree is released while affected work is blocked, parked, or reassigned | The pause is removed but some work does not start | Read the release preview and eligible wake count |
An issue enters in_review without a real review path | The status change is rejected instead of creating ownerless review work | Add a reviewer, interaction, approval, participant, or monitor first |
| An accepted plan uses an old document revision | Child creation is rejected or the wrong plan is applied | Resolve the current plan revision before accepting decomposition |
| A Retry uses a stale observed run or targets terminal work | No new attempt is admitted | Refresh the issue and retry the current non-terminal run |
| A retry response is lost after its receipt commits | A second request can create duplicate work if the caller retries blindly | Reuse the durable retry intent and let maintenance reconcile dispatch |
| A queue edit uses an old queue revision | The mutation is rejected to avoid ambiguous runtime input | Reload the queue and apply the change to its current revision |
| A queued wake from another issue matches a broad agent query | Unrelated input can appear in the detail view | Scope the wake to the issue identifier |
| A plan confirmation targets an old document revision | The interaction becomes stale | Create a confirmation for the current revision |
| A terminal issue retains a live native question run | The run can keep waiting after the issue closes | Cancel live question execution while retaining history |
| A recovery retry budget is exhausted | Automatic wake and monitor paths stop | Let a board operator choose the next repair step |
| A saved result has an unverified workspace controller | Recovery cannot safely settle the accepted result | Verify the controller stopped, then resume the saved result |
| Paperclip stops external-agent work | Local authority ends but the remote process may continue | Inspect the external agent |
| A successful run has no disposition | The issue stays open without a safe next action | Resolve or escalate the handoff |
| A compact detail view treats a linked comment as full history | The reader can lose recent conversation | Load the linked comment into the current window |
| An agent is resumed without reissuing a dropped assignment wake | Executable assigned work remains idle | Resume the agent and issue the task wake |
| A pending interaction has no valid addressee or resolver | The issue waits with no actor able to advance it | Set a valid audience and check it again at resolution time |
| A question answer is stored but delivery is unavailable | The agent does not receive the answer in the current turn | Keep the durable delivery receipt and let the wake outbox retry |
| A task view with personal inbox meaning uses organization routing | The user opens the wrong task surface | Keep personal views on Inbox and organization views on Tasks |
| An archived issue is queried through a stale cached task list | The operator cannot find restored work or sees a row with the wrong archive state | Bypass stale list bodies for archive filters and return the current user's archive state |
| A newly opened chat uses a stale agent name or an execution number | The chat label is misleading or task numbering has a gap | Resolve the generated chat title during the locked create path and keep chats outside numbered execution work |
| A bulk document read includes unreadable or too many issues | The helper may receive a bounded error or treat omitted issues as absent | Apply issue access checks, split large requests, and verify the requested issue set before declaring a scan complete |
Key files
| File | Why to read it |
|---|---|
| server/…/issues.ts | Main issue API boundary for list projections, archive-aware task views, detail context, creation, child delegation, comments, interactions, approvals, recovery, diagnostics, wake decisions, Retry, workspace restoration, and tree-hold release |
| server/…/issues.ts | Issue lifecycle, dependency readiness, blocked recovery holds, assignment, comments, privacy, inbox attention and archive state, handoff protection, workspace-finalize barriers, terminal interaction cleanup, durable wake notifications, and conversation creation |
| server/…/issue-document-batch.ts | Bounded cross-issue document reads for native helpers under the normal issue access boundary |
| server/…/task-retry.ts | Durable Retry intent, idempotency, stale-run checks, recovery generation changes, and receipt reconciliation |
| server/…/task-interruption-presentation.ts | Shared task-level view of working, waiting, retrying, failed, and resolved states |
| server/…/issue-continuation-summary.ts | Run-to-run handoff that carries the next action and accepted result |
| server/…/issue-thread-interactions.ts | Structured thread requests, questions, confirmations, task suggestions, and governed actions |
| server/…/issue-queued-comment-queue.ts | Queued comment identity, revisions, and runtime input projections |
| server/…/question-response-delivery.ts | Durable routing of answered questions to active runs or continuation wakes |
| server/…/issue-review-policy.ts | Review requester discovery and verdict policy |
| server/…/issue-dependency-wakeups.ts | Dependency-ready wake behavior and duplicate suppression |
| server/…/issue-recovery-actions.ts | Recovery ownership, retry budget, active-path uniqueness, and resolution |
| ui/…/IssueDetail.tsx | Issue execution control surface, task chat, compact and full history, linked comments, queued input, interaction decisions, recovery, workspace repair, pause and resume controls, live-run refresh, and sub-task progress views |
| ui/…/Issues.tsx | Combined task and inbox views, coordinator routing, URL-backed filters and sorting, archive-aware task loading, paged task loading, and live-run collection updates |
| ui/…/useTaskRetry.ts | Optimistic Retry behavior and same-request reconciliation after a lost response |
| ui/…/ExecutionBlockerNotice.tsx | User-facing saved-message, retry countdown, and failure notice |
| ui/…/IssueChatThread.tsx | Thread view for comments, run feedback, queued input, interaction cards, blockers, and recovery |
| ui/…/IssueThreadInteractionCard.tsx | Human workflow for questions, confirmations, verdicts, and resolution errors |
| ui/…/IssuePropertiesArtifactsTab.tsx | Operator view of work products, documents, produced files, and review fallbacks |