feat(hub,web): support scheduling messages for future delivery

[junmo-kim]

What

Lets the user defer a Web composer message until a chosen future time. Hub queues the row, fires it at the scheduled instant, and the existing CLI message-consumed ack is reused — no new dispatch path. UX is a clock button next to send; no modal, no new dependencies.

Schedule picker — Relative	Schedule picker — Specific	Queued bar + active clock

Why

Today every Web message is consumed by the CLI immediately. Users have asked for deferred send to cover four flows that currently have no workaround:

• Rate-limit window: while an agent rate-limit window is active (Claude 5h/7d, Codex daily, Gemini quota, …), queuing a follow-up immediately doesn't help — the agent is paused and the message just sits behind the same wall. Scheduling it for the moment the window resets is the only way to make it fire promptly without sitting in front of the screen.
• Away / overnight work: queue tomorrow's prompt before going offline.
• Self-reminder: "check on this in an hour" type re-entry.
• Free-form deferral: arbitrary "send this later" cases.

All four collapse into one mechanism: a scheduled_at column on the messages table plus one extra line on the existing 5s expireInactive tick. No new timer, no new socket event, no new SSE type.

How

Three commits, dependency-ordered (schema → hub logic → web UI). Each is independently buildable and tested; commit messages have the full per-layer detail.

The non-obvious decisions worth flagging up front:

• No new timer — releaseMatureScheduledMessages is called from the existing 5s expireInactive tick.
• releaseMatureScheduledMessages does not write invoked_at. The CLI's messages-consumed ack stays the sole writer, so a hub crash or a disconnected CLI just re-emits on the next tick — the CLI catches up the next time it connects.
• A scheduledAt POST without a localId would silently lose the schedule (addMessage would stamp invoked_at immediately and the mature scan would skip it). Both the REST schema and addMessage reject that combination.

Migration / backward compatibility

• Forward (V8 → V9): idempotent step migration, unit-tested for V6/V7/V8 → V9 multi-hop and fresh-DB.
• Backward (V9 hub → pre-V9 binary): forward-only schema (HAPI convention since V8) — the older binary will throw on boot rather than silently downgrade. Operators rolling back must DROP the column/index and PRAGMA user_version = 8 manually, or restore from backup.
• Existing V8 rows after upgrade: scheduled_at defaults to NULL, the future-emit branch is skipped (so they go through the immediate path unchanged), and the partial index does not list them (cardinality stays at the count of pending schedules only).

Test plan

• 178 hub unit/integration tests (21 files, +1 for ackCalled assertion on cancel short-circuit), 335 web tests (48 files, +2 for formatScheduledTime cross-year, +5 for shouldAutoClearPendingSchedule preset-stays-alive guard), bun typecheck clean across hub/web.
• Migration suite: V6/V7/V8 → V9, V9 reopen idempotency, partial-index existence (fresh + post-migration), migrateFromV8ToV9 PRAGMA guard.
• messageService suite: future scheduledAt skips CLI emit, mature scan picks the row up, the cancel × mature-emit race is documented (the existing PR feat(web,hub): cancel queued messages #568 contract is preserved — not-found ack stamps invoked_at), hub cold-restart re-emits because releaseMatureScheduledMessages does not write invoked_at, REST schema rejects scheduledAt without localId and scheduledAt > +7d.
• End-to-end (real CLI agents in an isolated HAPI_HOME): +30s schedules across Claude Code, Gemini, and OpenCode (nemotron-3-super-free) all matured within sched + 1.5–2.5s and stamped invoked_at exactly once. Gemini happened to be quota-exhausted at the time and replied "Gemini prompt failed: ... quota will reset after 8h34m27s" — which is the exact case this PR is built to solve, and the hub still tracked the schedule cleanly through the downstream rejection.

Notes for the reviewer

• Cancel of a scheduled message races with the 5s mature-emit tick. If the CLI has already shifted the row by the time the cancel reaches it, the existing PR feat(web,hub): cancel queued messages #568 contract returns invoked and stamps invoked_at — the message is processed, not cancelled. This is a wider window than the immediate-queued case (~5s vs sub-second) but the contract itself is unchanged. A test documents the expected behavior.
• Scenario C from the design doc (hub crash between emit and CLI ack) currently relies on the re-emit guarantee plus eventual CLI dedupe. CLI-side 'new-message' payload-id dedup is not in this PR — it would expand the surface to the CLI; a follow-up PR is the cleaner home.
• releaseMatureScheduledMessages is piggybacked on expireInactive to avoid a second timer; a comment notes that they share cadence but are not logically the same operation.

[github-actions]

Findings

• [Major] Mature scheduled messages can be dropped after a later message advances the CLI cursor — releaseMatureScheduledMessages reuses the row's original seq, but the CLI drops any incoming message whose seq <= lastSeenMessageSeq (cli/src/api/apiSession.ts:280). Schedule seq=10, send immediate seq=11, then when seq=10 matures the CLI ignores it and the DB row remains uninvoked. Evidence hub/src/sync/messageService.ts:465.
  Suggested fix:

  private readonly seenMessageIds = new Set<string>()
  
  private handleIncomingMessage(message: { id?: string; seq?: number; localId?: string | null; content: unknown }): void {
      const id = typeof message.id === 'string' ? message.id : null
      if (id && this.seenMessageIds.has(id)) return
  
      const seq = typeof message.seq === 'number' ? message.seq : null
      if (!id && seq !== null && this.lastSeenMessageSeq !== null && seq <= this.lastSeenMessageSeq) return
  
      if (id) this.seenMessageIds.add(id)
      if (seq !== null) this.lastSeenMessageSeq = Math.max(this.lastSeenMessageSeq ?? 0, seq)
      // existing parse/enqueue logic
  }

• [Major] Reconnect backfill can deliver future scheduled messages immediately — /cli/sessions/:id/messages still uses the normal getMessagesAfter stream, and the CLI enqueues every backfilled user message (cli/src/api/apiSession.ts:347). A reconnect before scheduledAt therefore bypasses the new mature-scan path and sends the prompt early. Evidence hub/src/sync/messageService.ts:149.
  Suggested fix:

  export function getDeliverableMessagesAfter(db: Database, sessionId: string, afterSeq: number, limit = 200, now = Date.now()): StoredMessage[] {
      const safeLimit = Number.isFinite(limit) ? Math.max(1, Math.min(200, limit)) : 200
      const rows = db.prepare(`
          SELECT * FROM messages
          WHERE session_id = ?
            AND seq > ?
            AND (scheduled_at IS NULL OR scheduled_at <= ?)
          ORDER BY seq ASC
          LIMIT ?
      `).all(sessionId, afterSeq, now, safeLimit) as DbMessageRow[]
      return rows.map(toStoredMessage)
  }

• [Major] Scheduled attachment sends can persist dangling file paths — the API accepts attachments together with scheduledAt, but uploads are per CLI session and sendSessionDeath removes that upload directory (cli/src/api/apiSession.ts:517). If the CLI exits before the scheduled send matures, the stored attachment paths become invalid; the agent later receives @path references to deleted files (cli/src/utils/attachmentFormatter.ts:11). Evidence hub/src/web/routes/messages.ts:19.
  Suggested fix:

  }).refine(
      (data) => data.scheduledAt == null || !data.attachments?.length,
      { message: 'scheduled messages with attachments are not supported until uploads are retained through invocation', path: ['attachments'] }
  )

Summary
Review mode: initial
Found delivery correctness issues in the scheduling path. The missing tests are schedule -> later immediate -> mature, reconnect before scheduledAt, and scheduled attachments after CLI/session cleanup.

Testing
Not run (automation)

HAPI Bot

[github-actions]

Findings

• [Major] Session-end sweep can drop mature scheduled messages before delivery — getMatureQueuedLocalMessages includes rows where scheduled_at <= now, and sweepImmediateQueuedOnSessionEnd immediately stamps every returned localId as invoked. If a CLI re-attaches after scheduledAt and exits before the 5s releaseMatureScheduledMessages tick emits the row, or exits after emit but before messages-consumed, the scheduled prompt is marked sent without the ack/re-emit guarantee. Evidence hub/src/store/messages.ts:215.
  Suggested fix:

  export function getImmediateQueuedLocalMessages(
      db: Database,
      sessionId: string
  ): StoredMessage[] {
      const rows = db.prepare(`
          SELECT * FROM messages
          WHERE session_id = ?
            AND invoked_at IS NULL
            AND local_id IS NOT NULL
            AND scheduled_at IS NULL
          ORDER BY seq ASC
      `).all(sessionId) as DbMessageRow[]
      return rows.map(toStoredMessage)
  }

Summary
Review mode: follow-up after new commits
One delivery correctness issue remains in the scheduling/session-end interaction. Missing coverage: mature scheduled row present at session end before a messages-consumed ack should remain queued for the release/re-emit path.

Testing
Not run (automation)

HAPI Bot

[github-actions]

Findings
No findings.

Summary
Review mode: follow-up after new commits
No high-confidence issues found in the latest full diff. The prior scheduled-message session-end drop finding appears addressed by limiting the session-end sweep to immediate queued rows (scheduled_at IS NULL). Residual risk: scheduled delivery still depends on the hub mature-message tick and CLI ack path; covered by added tests in the diff, but not re-run here.

Testing
Not run (automation)

HAPI Bot