mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-09 16:02:36 +01:00
DottaandPaperclip
c66b4a55ef
## Thinking Path > - Paperclip manages work performed by AI agents. > - Task monitors schedule later checks through execution admission. > - A native run must save its work before a monitor starts another run. > - The monitor banner can show an overdue warning during this valid wait. > - It also promises the next tick and offers a check that cannot start. > - This change explains the active run hold on both monitor surfaces. > - Users can see why the check waits without changing execution guards. ## Linked Issues or Issue Description Refs #16975 and #17863. The branch also preserves the quiet workspace-wait behavior from #19507. These changes added the native settlement guard and monitor deadline worker. A search found no open PR for this display case. **What happened?** A monitor became due while its native run was still saving work. The banner showed an overdue warning and “Fires on next tick.” The check later ran. The warning did not explain the execution hold. **Expected behavior** Show the active run wait. Keep the saved check time. Restore the normal display when the run clears. **Steps to reproduce** 1. Keep a task run active and set a monitor on that task. 2. Let the saved check time pass. 3. Inspect the monitor banner and composer strip. **Paperclip version or commit** Reproduced in mounted production components ata434edf991. The branch also includes current master. **Deployment mode** Source checkout on Linux. PostgreSQL tests use an isolated embedded database. No staging deployment is part of this PR. ## What Changed - Pass the existing task live-run state to both monitor surfaces. - Explain the current run wait. Keep its tone neutral and its saved check time visible. - Hide Check now during the hold. Restore it when the run clears. - Keep pending GitHub PR links visible during the hold. Restore Check status after the run clears. - Preserve blocked-task, retry, and idle-overdue display behavior. - Add rendered regressions and PostgreSQL finalization-release tests. - Document the distinction between a deadline and admission. The monitor display owns this change. The page already reads task run state, so this adds no API request. The scheduler and its guards are unchanged. The PostgreSQL tests confirm existing behavior. They are not evidence of a repaired scheduler fault. ## Verification - Before the repair, all three new rendered cases failed: future, due-now, and two-minute-overdue monitors during an active run. - After the repair, 50 UI tests pass across IssueMonitorBanner and issue-monitor. The same tests check return to normal display when the run clears. - Deadline, scheduled-work, and delivery-coordinator tests pass: 50 tests. The combined five-file run before the final safety assertion passed 99 tests. - PostgreSQL regressions cover release of committed and terminal_failure holds, rollback, one admitted wake, and quiet workers after settlement. - UI typecheck, token gates, and git diff --check pass. - A frozen install and plugin SDK dependency build were required for server test collection. The first collection attempt could not resolve the unbuilt SDK. That attempt had no test verdict. - At initial headee030bdf22, the focused three-file run passes 52 tests: 50 UI tests plus both PostgreSQL finalization-release cases. UI typecheck and token gates pass again after the master merge. - The complete PostgreSQL scheduling suite passes all 56 tests before the master merge. The earlier 54-test baseline also passes. - A real local task page passes in Chromium with fresh embedded PostgreSQL and a process run. Both monitor surfaces explain the hold. Check now stays hidden. Advancing the client clock past the deadline keeps the neutral wait. Reload preserves it. No page errors occur. - The first browser probe used an already-due monitor on a legacy process fixture. That path consumed the schedule before the page loaded, so the expected banner was absent. The corrected probe saves a future monitor and advances only the client clock. It verifies the display; it does not claim native scheduling acceptance. - [CI run 42260573923](https://github.com/paperclipai/paperclip/actions/runs/42260573923) passed foree030bdf22. A later review found hidden PR links during an active run;c3604bf4b4repairs that case. That revision later needed a master conflict repair before build/test CI could start. Final head is 7fe2417e4005378a8c2aee9451ae14f6f49c54ff; its required checks have completed successfully. The incident data establishes an active-run hold at the first due time. It does not fully explain the later interval between terminal status and monitor admission. This PR fixes the confirmed display defect. It does not claim to repair an unproven lost wake. - The review regression failed first in two cases with no PR links: future and overdue GitHub monitors during an active run. After the repair, 52 UI tests pass. They cover links on both surfaces, held check actions, return to Check status, and removal of merged PR links. UI typecheck and token gates also pass. - Current master was merged at7fe2417e40. Both the PR-link tests and master’s quiet workspace-wait tests are retained. All 65 tests across IssueMonitorBanner, issue-monitor, and IssueScheduledRetryCard pass. UI typecheck, token gates, and diff checks pass. [Final-head CI](https://github.com/paperclipai/paperclip/actions/runs/42267525907) completed successfully: 55 successful checks, three skipped, and one neutral. Build, Typecheck + Release Registry, and ci / verify passed. Greptile reviewed this exact head at 5/5 with no actionable findings. The prior reviewer thread is resolved; no review threads remain open. The real Chromium acceptance above was performed at ee030bdf22; the final link handling and merged workspace-wait cases are covered by the mounted component tests and fresh CI. ## Risks - The wait display depends on the page’s existing live-run query. A stale query can briefly keep the wait visible. - A monitor with no active run still shows an overdue warning. A blocked task keeps its existing pause controls. - No schema, scheduling, ownership, or authorization change. ## Model Used OpenAI Codex, GPT-6 family, with repository inspection, code editing, shell tools, and test execution. The exact serving snapshot and context-window size are not exposed in 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>
46 lines
2.5 KiB
Markdown
46 lines
2.5 KiB
Markdown
# Issue monitor scheduling
|
|
|
|
Paperclip reconstructs monitor deadlines from saved issue rows at server startup.
|
|
While running, supported issue, execution, company, and native-run services
|
|
notify the monitor worker when their database transactions commit. The worker
|
|
uses those notifications to re-read durable state. It does not depend on a
|
|
process-local queue count for correctness.
|
|
|
|
Notifications are batched for up to the configured heartbeat interval (normally
|
|
30 seconds). This bounds global monitor scans during frequent task edits. An
|
|
already-known monitor deadline can fire earlier than the batching window.
|
|
After all work settles, no periodic monitor scan remains. Pending claims and
|
|
failed or deferred admissions retain their bounded deadlines.
|
|
|
|
A monitor deadline is the earliest time for a check. An active native run or an
|
|
unfinished finalization holds the check until the prior work settles. The task
|
|
banner explains the active run wait instead of promising the next scheduler tick
|
|
or showing it as overdue. Once the run clears, the banner resumes its countdown
|
|
and offers Check now. Finalization notifications restore monitor scheduling from
|
|
the saved rows; they do not bypass execution admission.
|
|
|
|
Both idle drains and ordinary maintenance drains pause monitor dispatch. The
|
|
worker retains its pending request without repeatedly reading monitor tables.
|
|
After an explicit drain stop or TTL expiry, a bounded in-memory retry resumes
|
|
that request. Shutdown cancels local timers; restart reconstructs durable work.
|
|
|
|
## Supported writers
|
|
|
|
Use Paperclip's API and services to create or change monitor work. These writers
|
|
share the serving process's database-work notification scope, including nested
|
|
transactions and uncertain commit reconciliation. Supported import paths also
|
|
use these service boundaries or startup reconstruction.
|
|
|
|
Independent SQL clients, other service processes, and additional server replicas
|
|
do not publish into that process-local scope. Their direct writes are not
|
|
supported live monitor producers. Restart reconstructs saved rows, but that is
|
|
not a live cross-process delivery guarantee. Such integrations need an explicit
|
|
ingress or durable notification contract before they can rely on monitor wakes.
|
|
There is no unconditional recovery poll for unsupported writers.
|
|
|
|
## Scope of the sleep claim
|
|
|
|
An idle monitor worker can stop its SQL activity. This alone does not prove that
|
|
the host or database will suspend. Cloud's existing external alarm and sleep
|
|
safety checks remain in place; an in-process timer cannot wake a suspended host.
|