PaperClipAI/doc/idle-agent-timers.md

Agent timer deadlines

The agent timer worker reconstructs its next deadline from existing agent, company, issue, run, and cost records. It no longer receives a wake from the server's recurring heartbeat interval. The queue service owns timer policy and admission; scheduling selects eligible agents and registers the earliest result with the shared delivery coordinator. No table or independent scheduler is added.

Deadline and quiet conditions

For an enabled timer with a positive interval, the ordinary deadline is (lastHeartbeatAt ?? createdAt) + intervalSec. Reading it does not advance it. A due timer retains the existing atomic timestamp claim and queue admission checks. Successful finalization updates the last heartbeat and moves the next deadline. An attempted admission still follows the existing claim semantics; this change does not promise replay of every elapsed interval.

Only active companies and invokable agents with valid reporting chains qualify. Worktree execution suppression and the worktree issue creation cutoff still apply. A disabled timer or zero interval has no deadline. When skipTimerWhenNoActionableWork is enabled, the queue's existing actionable-work predicate must match an assigned, visible, non-conversation task in Todo or In Progress without a user assignee. Completed history does not qualify.

A reached positive daily run or cost cap defers work until the next UTC day, or the ordinary interval deadline if later. Either zero cap leaves no timed obligation: only a policy change can make that timer runnable. An accounting correction or released run claim can lower today's usage and bring a saved midnight deadline forward. These producers notify the worker.

Enabled timers that do not require actionable work remain real periodic obligations. This migration does not silently disable those timers. With no eligible timer, unresolved transaction, or pending reconciliation, the worker has no recurring SQL or network scan.

Producer and transaction ownership

Every notification is registered before the relevant write in its existing transaction. Nested transactions retain outer commit/rollback ownership through packages/db/src/work-signals.ts. Durable records are the source of truth; notifications request another read and are not an in-memory queue length.

Changed facts	Owning producers
Timer configuration or reporting chain	Agent configuration service, including updateAgentConfigurationInTransaction; agent deletion's report reassignment
Agent eligibility	Lifecycle status transition hook, including rejection through a saved hire approval
Company eligibility	Company update/archive; company budget pause/resume
Last heartbeat and daily run claim	Queue timer claim/skip paths, suppression claim release, heartbeat finalization, active-run watchdog finalization
Actionable task creation/status/assignment/visibility	Issue create/update/checkout/release/admin release/delete, including checkout's second adoption transaction
Restored or reassigned tasks	Subtree cancellation restoration, member archival reassignment, native workspace reconstruction
Direct task disarm paths	Queue's invalid workspace block, unrecoverable execution disposition, expired skill harness hiding
Conversation/worktree eligibility	Agent conversation prepare/settle; external conversation resume/settle
Daily cost corrections	Accounting correction transaction
Worktree activation	Experimental settings owner; scheduling requests a fresh suppression read

Agent creation/approval remains governed by lifecycle preparation and its eventual status transition. Company deletion requires completed agent termination, which already removes timer eligibility. Ordinary run insertion, execution-lock changes, monitor metadata, nonnegative cost accumulation, and terminal run retention do not create earlier timer eligibility by themselves. In particular, a conversation cannot satisfy the actionable-task predicate, but its status can change the separate worktree cutoff gate, so those status writers are still covered.

Supported live writers are the serving process's API and service boundaries. Independent SQL writers and additional server replicas do not share process-local notifications. Startup reconstructs their saved state, but there is no live cross-process delivery promise or unconditional recovery polling fallback. Such writers require an explicit ingress or durable notification contract.

Lifecycle and failure behavior

Notifications coalesce for up to the configured heartbeat interval, normally 30 seconds; already-known deadlines can run sooner. Failed reconciliation keeps bounded retries through the shared coordinator. Intent uncertainty is resolved by the shared transaction protocol, never by assuming an empty query means a write cannot commit later.

Idle and maintenance drains pause timer work. The worker retains its request without passive database polling, then retries in memory until admission resumes. The timer scan checks cancellation/admission between agents. A skipped candidate keeps its unclaimed deadline; shutdown stops local scheduling, and restart reconstructs deadlines from the database. This uses the shared registerDeadlineWork generation protocol rather than a timer-specific recovery loop.

Verification and limits

agent-timer-deadlines.test.ts exercises real PostgreSQL producers, the queue's deadline policy and CAS, and the delivery coordinator. It measures no SQL after settlement for empty, disabled, completed-history, capped, and disarmed states; first-work reactivation; outer commit and rollback; restart; failed reads; concurrent claims; both drain modes; and interruption between due agents. Native reconstruction and external conversation suites separately verify outer transaction visibility and timer notification at their realistic boundaries. The timer scheduling fixture substitutes adapter enqueue, so these tests do not prove provider execution or replace existing queue/admission regressions.

Worker quiet is not host sleep qualification. The Cloud alarm protocol still covers only its explicitly supported durable schedules. Legacy agent timers remain blocked by the existing sleep-safety proof; this change neither exports them as Cloud alarms nor relaxes that proof. Deployed database suspension, host suspension, and wake correctness require separate qualification.

October 29 master reconciliation and current acceptance

The existing agent-timer slice was reconciled with the qualified issue-monitor parent using normal merges. Four conflicts needed explicit composition. Startup keeps both task-drain expiry registration and the timer worker's fresh drain read; scheduled work keeps the new timer deadline owner; a comment-only conflict has no runtime effect. The shared deadline helper retains the parent's explicit continuation interval alongside the new per-worker minimum scan spacing. All other paths match the automatic merge, and packages remain byte-identical to the qualified profile-80 parent tree.

Source 32db86c1974dcbf794f01a8c5e42024e2ad071fc passed 1,710 cases in 49 complete files, without skips, in 653.08 seconds. This includes the 35 previously qualified monitor/deadline-consumer files plus real timer policy, CAS and producer coverage, stale-queue invalidation, native workspace reconstruction, Slack conversation lifecycle, skill/settings/configuration producers, claim isolation, five agent-lifecycle module suites, and the new deadline composition regression. Database build, production server typechecking/build, module boundaries, migration order and Runner profile identity pass. Twenty-nine fresh PostgreSQL 17 schemas plus per-file fixtures applied all 412 journal entries through index 413. Every selected source hash and temporary fixture import was restored exactly.

Four new deadline cases check future and overdue work with and without an explicit minimum spacing, no dispatch before the selected time, and complete disarming after settlement. A controlled mutation discarded only the inherited continuation option while retaining timer spacing: the regression failed. Restoring the composed source made all four cases pass with the same assertions and timers. This guards against fixing the timer floor by restoring a 30-second delay for other workers that deliberately use shorter bounded continuations.

The final monitor-parent publication changed only its audit. All production trees and 49 selected test hashes remain identical to this accepted source. Final publication must also adopt the actual merged prerequisite and receive fresh exact-head CI, security and reviews. No full local repository-suite, live provider, external alarm delivery, measured instance/database suspension or fleet-cost claim is made. Existing Cloud alarm coverage and timer sleep-safety gates remain intact.