long-waits

name: long-waits description: Use when the user asks you to wait longer than 10 minutes before performing an action, implement delayed execution, schedule tasks for a specific time, or do something after a condition becomes true

Long Waits

Overview

Chain sequential background sleeps to wait for extended periods. Bash has a 10-minute (600,000ms) maximum timeout, so longer waits require multiple intervals triggered by completion notifications.

Core insight: Background tasks create an event-driven loop: start timer → receive completion notification → start next timer.

When to Use

• "Wait until the checkin that fixes the widgets hits main, then rebase onto it, merge, and deploy"
• "Implement the spec after my tokens reset at 1am"
• "Run the live tests when the new version arrives on staging"
• Any delay >10 minutes or condition that takes indefinite time

Implementation

Calculate Intervals

Total wait ÷ 10 minutes = Number of intervals
4 hours = 240 min ÷ 10 = 24 intervals

Start First Interval

sleep 600  # With run_in_background: true

Returns immediately with task ID. Sleep runs asynchronously.

Handle Notifications

When sleep completes, you receive <task-notification>. Start next interval:

sleep 600  # Next interval, run_in_background: true

Track with TodoWrite: "Waiting interval 2/24 (10 min each, ~4 hours total)"

Execute

After final notification, perform the scheduled task.

Wall Clock / Calendar Times

When the user specifies a target time (e.g., "at 3pm", "tomorrow at noon"):

1. Check system time: date
2. Assume user's time zone matches system. Don't ask.
3. Calculate with Python:

python3 -c "
from datetime import datetime
target = datetime(2024, 1, 15, 15, 0, 0)  # Jan 15, 3:00 PM
now = datetime.now()
diff = target - now
print(f'Seconds: {int(diff.total_seconds())}')
print(f'Minutes: {diff.total_seconds() / 60:.1f}')
"

4. Verify the output makes sense (positive, reasonable magnitude).
5. Tell the user: "I'm going to wait 3 hours, 25 minutes until 3:00 PM PT, then [task]."
6. Convert to intervals and execute.

Condition-Based Waiting ("Do This After...")

For conditions like "after the deploy succeeds" or "after the file appears":

Pattern:

check condition → false? → sleep 600 (background) → notification → check again → true? → execute

1. Translate to concrete check:

2. Establish baseline for relative conditions ("two new versions").
3. Tell the user: "I'll check every 10 minutes for [condition]."
4. Poll loop: Check → if false, sleep 600 (background) → on notification, repeat.
5. Execute when condition is true.

Track: "Polling for [condition] - check #5 (started 50 min ago)"

Quick Reference

Common Mistakes