Summary

Adds optional scheduled_at (INTEGER, unix epoch) column to the Kanban tasks table. When set, the dispatcher and claim path skip the task until scheduled_at <= now. When NULL (default), existing behavior is unchanged.

Closes #24299

Changes

hermes_cli/kanban_db.py

• Schema: scheduled_at INTEGER column added to CREATE TABLE tasks
• Index: idx_tasks_scheduled_at partial index on scheduled_at WHERE scheduled_at IS NOT NULL
• Task dataclass: scheduled_at: Optional[int] = None field + from_row parsing
• Migration: ALTER TABLE tasks ADD COLUMN scheduled_at INTEGER (idempotent)
• create_task: signature extended with scheduled_at param, INSERT includes column
• dispatch_once: AND (scheduled_at IS NULL OR scheduled_at <= ?) guard clause
• claim_task: same guard in CAS UPDATE + now added to param tuple

tools/kanban_tools.py

• kanban_create handler: passes scheduled_at from args to create_task()
• KANBAN_CREATE_SCHEMA: added scheduled_at parameter definition

Design decisions

• Purely additive: no new task status, no lifecycle changes
• NULL = existing behavior: unscheduled tasks dispatch immediately as before
• Column type INTEGER: matches created_at, started_at, completed_at convention
• Dispatcher guard only: the task is still ready in status, just invisible to dispatch until due
• Single guard clause: AND (scheduled_at IS NULL OR scheduled_at <= ?) applied in both dispatch_once and claim_task

Testing

Live-tested against a running Hermes Agent gateway (v2.3.0-based):

1. Syntax verification: both patched files compile cleanly (python3 -m py_compile)
2. Migration: ALTER TABLE applied successfully, column appears in PRAGMA table_info
3. Future-scheduled tasks: planted two tasks with scheduled_at set 2min and 3min in the future
   • Both stayed at status=ready with started_at=NULL while now < scheduled_at
   • Dispatcher ticked every 60s and correctly skipped both
4. Due tasks dispatched: after scheduled_at elapsed, both tasks were picked up by the dispatcher and completed normally (status=done)
5. No regression: existing unscheduled tasks continued to dispatch immediately
6. Cleanup: all test tasks removed after verification