th pearls: schedulable pearls that speak up in the prime hook when due

[brentrager]

Problem

A pearl you want to revisit later (after a deploy, next week, in 2h) has no way to resurface on its own — it just sits in the backlog until someone re-reads the whole list. Brent asked for pearls to "start speaking up in hooks when a scheduled pearl is up."

Solution

Add an optional scheduled_at to pearls and surface due ones through the existing session-priming hook.

• th pearls schedule <id> <when> — set it; omit <when> to clear. <when> is relative (+2h, 30m, 2d, 1w, tomorrow, now; leading - = past) or absolute (2026-07-10, 2026-07-10 09:00, RFC3339), parsed as UTC.
• th pearls due — pearls whose time has arrived (scheduled_at <= now, not closed, soonest-first).
• Prime hook — th prime now prints a ⏰ Scheduled & due section above Ready to work, so a scheduled pearl automatically speaks up at the next session start / compaction once it comes due. show/ready/list render a ⏰ marker.

Storage mirrors closed_at exactly (nullable DATETIME, idempotent ADD COLUMN IF NOT EXISTS migration for existing Dolt stores).

The one non-obvious bit

Due comparison uses a Rust Utc::now() literal, not Dolt NOW(). Dolt's NOW() returns the server's local time while scheduled_at is stored as UTC, so scheduled_at <= NOW() was off by the local UTC offset (a pearl 1h in the past read as not-yet-due on an EDT box). Caught in end-to-end smoke; a store-level regression test (test_due_scheduled_uses_utc_not_dolt_local_now) guards it with a ±1h window that would flip under the bug.

Verification

• cargo test -p smooai-smooth-cli -p smooai-smooth-pearls -p smooai-smooth-diver → 469 passed. New tests: schedule_tests::{relative_offsets,keywords,absolute_forms,garbage_is_rejected} (parser) + test_due_scheduled_uses_utc_not_dolt_local_now (TZ-correct query).
• cargo fmt --check clean, cargo clippy clean on touched crates.
• End-to-end smoke against a throwaway repo: -1h past → due + surfaced in prime; +90m future → not due; clear → gone; absolute past date → due.
• Docs updated in the same PR (docs/Engineering/Using-th-CLI.md).

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: ff431e8

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@smooai/smooth	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR