#8307: fix(cron): improve tool description with reliable reminder guidance

Fixes #8298 ## Problem Users reported cron reminders failing with: 1. **Silent failures**: Status shows "ok" but no message is delivered to the user 2. **"Skipped" status**: Jobs get stuck in "skipped" state with retry spam in the UI 3. **Configuration confusion**: Unclear which parameters ensure reliable delivery ### Root Causes Identified - `sessionTarget="main"` + `wakeMode="next-heartbeat"`: Marks job as "ok" immediately but the systemEvent sits in queue until the next natural heartbeat occurs. If there's no user activity, the message never gets delivered. - `sessionTarget="main"` + `wakeMode="now"`: Can get stuck waiting for the main lane to become idle (up to 2 minutes), often resulting in "skipped" status and retry spam. - The working pattern (`sessionTarget="isolated"` + `payload.kind="agentTurn"` + `deliver=true`) was not documented in the tool description. ## Solution **Updated the cron tool description** to guide agents toward the reliable pattern: 1. ✅ Added **"RECOMMENDED PATTERN FOR REMINDERS"** section with the proven configuration 2. ✅ Clarified that `wakeMode="next-heartbeat"` may delay delivery indefinitely 3. ✅ Documented `wakeMode` and `deleteAfterRun` in the job schema section 4. ✅ Added code comment explaining the delivery timing nuance in `timer.ts` ### Recommended Pattern (now documented) ```json { "sessionTarget": "isolated", "wakeMode": "now", "deleteAfterRun": true, "payload": { "kind": "agentTurn", "deliver": true, "message": "<your reminder text>" } } ``` This pattern ensures reminders: - Execute immediately (`wakeMode="now"`) - Deliver reliably via auto-routing (`deliver=true`) - Clean up after completion (`deleteAfterRun=true`) ## Changes - `src/agents/tools/cron-tool.ts`: Enhanced tool description with recommended pattern and clearer wake mode documentation - `src/cron/service/timer.ts`: Added comment explaining why `next-heartbeat` mode may not deliver messages ## Impact - **No behavioral changes** to the cron execution logic - Guides AI agents toward the working configuration pattern - Reduces user frustration with failed reminders - Better aligns agent behavior with user expectations 🤖 Generated with AgentGit <!-- greptile_comment --> <h2>Greptile Overview</h2> <h3>Greptile Summary</h3> This PR updates the Cron agent tool description to document a recommended, reliable reminder configuration (isolated session + agentTurn + deliver) and clarifies wake modes and `deleteAfterRun`. It also adds an inline comment in the cron timer execution path explaining why `next-heartbeat` can lead to “ok” status while messages remain queued until a heartbeat occurs. Overall this is a documentation-focused change that should reduce user confusion around reminder delivery semantics, with no intended behavioral changes to cron execution. <h3>Confidence Score: 4/5</h3> - This PR is likely safe to merge since it primarily updates documentation/comments and does not change cron behavior. - Review focused on the two modified files; changes are confined to tool description text plus a code comment. The only issue spotted is a likely mismatch between the description claiming `wakeMode` is required for job creation and the actual tool schema/runtime behavior where it appears optional for jobs. - src/agents/tools/cron-tool.ts (tool description accuracy) <!-- greptile_other_comments_section --> <!-- /greptile_comment -->