0 Fork 0

mirror of https://github.com/paperclipai/paperclip.git synced 2026-10-22 00:30:19 +02:00

Files

T

DottaandPaperclip b928c6698f fix(heartbeat): explain deferred monitor dispatch (#16891 )

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - One-shot task monitors request future work through the normal
heartbeat queue.
> - Queue admission can hold execution until recovery or ownership is
reconciled.
> - The scheduler retained those monitor schedules but recorded no
monitor diagnostic.
> - Agents could repeatedly reschedule the same blocked check without
seeing why it did not run.
> - This pull request records safe deferral and failure activity while
retaining all execution gates.
> - Agents and operators can inspect the actual blocker and use its
existing recovery path.

## Linked Issues or Issue Description

Related: #15556 handles transient monitor client errors. #14590 handles
parked monitor wakes. This change records the diagnosis when queue
admission defers or fails; it does not change their admission or monitor
consumption policies.

**What happened?**

A due monitor on a task with an unresolved execution-recovery hold was
claimed, passed to queue admission, and released without monitor
activity. The saved monitor continued to look scheduled. Unexpected
dispatch errors had the same audit gap. Repeated rearming could not
clear the recovery hold.

**Expected behavior**

Keep the monitor and the recovery hold. Record the reason that prevented
its wake. Do not execute uncertain work or consume an attempt. Limit
repeated identical diagnostics. If audit storage fails, release the
claim so a later tick can retry.

**Steps to reproduce**

1. Schedule a due monitor on an agent-owned task in progress.
2. Add an active recovery action for an interrupted legacy execution.
3. Run the monitor scheduler twice. No provider may start while the hold
remains.
4. Before this fix, neither attempt writes monitor deferral activity.
5. Resolve the hold through its existing recovery path. The saved
monitor can then request one wake.

**Paperclip version or commit**

Reproduced on master 5739a53f5f with real PostgreSQL and the assembled
heartbeat service.

**Deployment mode**

Built from source. This affects the server monitor scheduler.

## What Changed

- Pass the existing execution blocker cause to the monitor scheduler
through a server-owned diagnostic callback.
- Record issue.monitor_deferred for held admission and
issue.monitor_dispatch_failed for unexpected admission failures.
- Keep activity to known reason codes and allowlisted blocker causes. Do
not copy raw provider messages.
- Fence claim release and activity against replacement, reassignment,
completion and competing scheduler instances.
- Limit identical activity for one schedule and cause to one record per
five minutes.
- Keep claim release functional when diagnostic storage fails.
- Update execution documentation and the task verification maps.

## Verification

- Red: explains held monitor dispatch without replaying uncertain
execution failed because it expected one deferral activity row and
received none. The fixture used the real queue, persisted source run and
recovery action.
- Red: records bounded dispatch failure diagnostics while retaining the
schedule failed because no failure activity was recorded.
- Green: both regressions pass after the fix. The held-source test
proves no successor while held, no monitor attempt consumed, and one
wake after explicit hold resolution.
- Passed: all 43 tests in heartbeat/scheduling.test.ts and
issue-monitor-scheduler.test.ts, with at most two workers.
- Additional coverage uses real PostgreSQL for diagnostic rate limits,
replacement races and an audit-insert trigger failure. Audit failure
must not retain the monitor claim. Private error and unknown blocker
text do not reach activity.
- Passed: node scripts/check-maps.mjs and git diff --check.
- Greptile: 5/5 with no actionable issues on
1d0aec738c.
- Latest-head checks: 55 successful, two skipped, and one neutral. No
check remains pending or failed. The branch has no merge conflict.
Paperclip Review ended neutral because its agent did not return a
complete assessment; it is not counted as a validated review pass.
- The dependency added on deferral is one bounded recent activity query
and at most one audit insert. Successful admission adds no new database
read. Existing queue authority checks still decide admission.
- The process fixtures validate queue admission and persisted state.
They log workspace setup errors after admission; this report does not
claim a live provider turn succeeded or that an existing deployment was
repaired.
- Passed: pnpm --dir server exec tsc --noEmit. The wrapper typecheck was
stopped because it started a redundant cold native Runner build. Full
repository checks run in PR CI; no local full-suite or full-build pass
is claimed.

## Risks

- Audit work must not strand a monitor. The storage-failure regression
verifies that rollback is followed by a claim-fenced release.
- Recovery holds still require their current reconciliation path. This
change makes their effect visible and does not bypass ownership, budget,
pause, Stop or company checks.
- Activity can be stale after a later repair, so each entry includes the
checked time and the exact saved deadline. A replacement cannot inherit
an old dispatch diagnostic.

## Model Used

OpenAI Codex, GPT-6 family, with reasoning, tool use and code execution.
The exact runtime model suffix and context window are not exposed to
this session.

## Checklist


- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

2026-10-19 16:11:31 -05:00

8.8 KiB

Raw Blame History

Task creation and lifecycle — agent access

Product map: Task creation and lifecycle.

Review date: 2026-10-12. Source commit: 58e16dbddfc9c8d0cf60867f9d9847f0feda055b. Native REST transport reconciled in this change; see the shared transport contract.

This is a source-reviewed baseline of representative operations and known gaps. Each capability needs operation-level review before its entire scope can be qualified. No live agent execution is claimed. Follow the map contract for format, permission checks, evidence and maintenance.

`create`

Review: baseline.

API: present — representative operation IDs:

POST /api/companies/{companyId}/issues.

Agent access: available — Native create_task; REST / CLI / MCP.

Policy: Company/task visibility, assignment/change policy, active-run checkout ownership and lifecycle rules. Ordinary Board comments preserve queued/running retries; only a parked retry can be superseded. Explicit Stop/Interrupt retain their existing actor and execution authority. Agent comment tools do not acquire Board identity or cancellation authority through this behavior.

Evidence: source-only — implementation at the reviewed commit above.

Gaps: Creation is implemented; agent/user assignment and attachments may need narrower/different APIs.

`organize`

GET /api/companies/{companyId}/issues/summaries?ids=... reads up to five exact UUIDs and returns only navigation summaries. Normal company and task-read permissions apply to ordinary agent REST calls; task-bridge keys are denied. Hidden, missing, foreign and private inaccessible IDs are omitted without an existence disclosure. No dedicated CLI/native tool is added. Embedded database route tests cover same-company agent access and company/task-bridge denials; this does not establish a live native call_api journey.

The issue-list API accepts optional includeAgentCreatedTasks; false restricts independent results to human creation before search/pagination. Omission retains existing agent/API behavior. includeParticipatedTasks=true requires a board user and retains only that authenticated user's existing participation as a creation visibility exception. Company/private-task access checks still apply. Collection preferences and hierarchy presentation are browser state, not additional authority. Source-reviewed behavior; live agent access verification remains separate.

All chat_channel origins count as bot-created for creation visibility, including human-initiated conversations. Existing inbox participation remains independent.

Review: baseline.

API: present — representative operation IDs:

GET /api/companies/{companyId}/issues.

Agent access: available — Native search_tasks; REST / CLI; UI grouping/navigation state separately.

Policy: Company/task visibility, assignment/change policy, active-run checkout ownership and lifecycle rules.

Evidence: source-only — implementation at the reviewed commit above.

Gaps: Search/filter API exists; sorting/grouping/presentation defaults are not necessarily shared server preferences.

`properties`

Review: baseline.

API: present — representative operation IDs:

PATCH /api/issues/{id}.
PUT /api/issues/{id}/title.

Agent access: available — Native set_task_title/reassign_task/set_dependencies and set_task_monitor; call_api for REST-authorized fields; agent REST. Monitor scheduling is a dedicated native tool, not a generic call_api operation.

Policy: Company/task visibility, assignment/change policy, active-run checkout ownership and lifecycle rules. A legacy run can assign its own task to a human without cancelling itself only with its signed run token and matching active run, agent, company and task. The outgoing run cannot mutate its human-owned task afterward, including through a late update already admitted before the handoff. Agent keys, native runs, board reassignment and transfers to another agent retain verified-stop requirements.

Native monitors require standard work mode and an agent-owned task in progress or review. The responsible user's current permissions also apply. A malformed request is rejected before mutation; bounded schema guidance lets the provider correct it without exposing submitted values. Receipt replay never re-arms a consumed schedule.

Evidence: source-only — implementation at the reviewed commit above.

Verification: not-run — exercise a listed permitted operation with actual agent credentials/run context; inspect its result and applicable persistence/attribution. Assert the relevant denied actor, owner, company or mode from Policy. Review the remaining operations before qualifying the whole capability. Focused route regressions in ownership tests cover a human handoff and stop enforcement for other actors, runtimes and targets; they use mocked services and do not claim live execution proof.

Monitor verification: submit flat scheduling fields, observe the schema rejection and unchanged task, then retry with the nested monitor object and the same idempotency key. Inspect the saved schedule and audit, yield, and verify exactly one issue_monitor_due wake. Scheduler integration coverage uses real PostgreSQL, the native tool authority, and the heartbeat scheduler with a no-op process agent. It does not prove live model recovery.

Monitor deferral diagnostics: an unresolved execution-recovery hold keeps a due schedule intact and prevents execution. Read issue.monitor_deferred activity for the safe blocker cause; unexpected dispatch failures record issue.monitor_dispatch_failed. Repeated identical diagnostics are throttled for five minutes. The scheduler regression proves that a held source does not replay and that clearing the hold permits one later wake. This is local PostgreSQL evidence, not live provider recovery.

Gaps: Dedicated tools differ in scope and fields. Generic call_api forwards status, assignment and dependency fields to existing route authorization.

`discussion`

Review: baseline.

API: present — representative operation IDs:

POST /api/issues/{id}/comments.
POST /api/companies/{companyId}/issues/{issueId}/attachments.

Agent access: available — Native report_progress/comment_on_task/register_deliverable; REST / CLI / MCP.

Policy: Company/task visibility, assignment/change policy, active-run checkout ownership and lifecycle rules.

Evidence: source-only — implementation at the reviewed commit above.

Gaps: Other-task comments and active-task progress have separate scopes. Generic call_api forwards explicit reopen/resume/interrupt fields to the existing route checks; it cannot impersonate a user.

`completion`

Review: baseline.

API: present — representative operation IDs:

PATCH /api/issues/{id}.

Agent access: available — Native paperclip_finish/paperclip_block through runner protocol; agent REST / native call_api disposition under route permissions.

Policy: Company/task visibility, assignment/change policy, active-run checkout ownership and lifecycle rules.

Evidence: source-only — implementation at the reviewed commit above.

Gaps: The server governs whether a reported result becomes done/review/blocked. Generic lifecycle PATCH uses existing REST authorization, checkout and approval rules.

8.8 KiB Raw Blame History

Task creation and lifecycle — agent access

create

organize

properties

discussion

completion

8.8 KiB

Raw Blame History

`create`

`organize`

`properties`

`discussion`

`completion`