[Feat] Let Fast Sessions schedule reminders and recurring checks

[daniel-lxs]

​Opened on behalf of @daniel-lxs. Follow up by mentioning @roomote-roomote, in the web UI, or in Slack.

Related issue

No linked issue; maintainer-authored feature work.

Why this PR exists

• A maintainer explicitly invited this PR in the linked issue or discussion
• I am a maintainer / this is internal Roomote work

Fast Sessions need reminders and recurring checks that resume the same conversation instead of detached automations or waiting inference turns.

What changed

• Add conversation-scoped manage_wakeups create/list/get/cancel with relative, absolute, interval, and timezone-aware cron schedules. Tight cadences require bounds.
• Persist wakeups in additive migration 0077. BullMQ hints feed the durable parent-event inbox before schedule advancement, with idempotent occurrence admission and lost-hint recovery.
• Serialize create admission to enforce the ten-active cap. Dedupe handles JSONB key ordering and relative-delay identity across retries.
• Deliver as the creating user in the existing Session, checking cancellation/archive before running and replying. Include tool guidance and documentation.
• Archive now acquires the same Fast conversation turn lock held during reply delivery before committing archivedAt. After a two-second contention retry budget, a busy Session returns retryable CONFLICT and stays unarchived. Errors fail closed and acquired locks release in finally; no database transaction spans provider I/O.

Users receive reminders and monitor updates in their existing Session. Archive synchronization is now included with explicit author approval, superseding its earlier deferral. The budget bounds contention retries, not underlying Redis request latency. No new wakeup-management UI or sandbox-task resume is included.

How it was tested

• Archive follow-up: 31 web tests pass, including eight archive regressions using real PostgreSQL, the actual turn-lock implementation and mocked Redis ownership. Covers in-flight reply serialization, timeout without archival, acquisition/update failures, cleanup and permissions. 71 SDK lifecycle tests and web check-types pass.
• Earlier dedupe validation: 12 DB tests, 27 schedule/parser tests, 5 contract tests, and 101 SDK queue/delivery tests passed. Development migrations applied successfully.
• Full pre-push oxlint, residual ESLint, check-types:fast, and Knip pass. No live-provider/model smoke test was rerun in this fixer cycle.
• Visual proof remains blocked (proof capture timed out); no captures are claimed or retried. Remote checks and automatic review must pass at the final head.

Checklist

• The PR title follows the repo convention: [Fix], [Feat], [Improve], [Refactor], [Docs], or [Chore] followed by a user-facing description
• This PR is small and scoped to one change
• pnpm lint and pnpm check-types pass locally
• I added tests or included a clear manual validation note above
• I removed secrets, tokens, private keys, and customer data from code, logs, and screenshots
• If this change should appear in the changelog, I ran pnpm changeset

The static commands were the pre-push equivalents above, not the two literal full commands. The existing .changeset/session-wakeups.md is retained; this fixer did not run the interactive changeset command.

[roomote-community]

No code issues found. See task

• A cancelled or archived wakeup can still be delivered after its parent event has already been admitted (packages/sdk/src/server/lib/fast-agent-parent-event.ts:2198).
• A cron schedule can bypass the tight-interval safety cap and run indefinitely every minute (packages/cloud-agents/src/server/session-wakeups/parse.ts:161).
• An archive can land after the reply-time wakeup check but before dispatch, allowing an archived Session to reply (apps/web/src/trpc/commands/sessions/index.ts:156).
• Retrying a relative one-shot reminder creates duplicate wakeups because its resolved absolute timestamp differs on each call (packages/db/src/lib/session-wakeups.ts:129).

_{Reviewed e92ccc1}

[daniel-lxs]

Local smoke test (2026-09-04)

Ran against a local stack (web, api, bullmq via PM2; Postgres and Redis in Docker; OpenRouter openai/gpt-5.4 through OpenCode).

Step	Result
"Remind me in 2 minutes to check the deploy" in a web Session	One manage_wakeups call, once schedule; Fast confirmed the time in one sentence. Fired 100 ms after its due time; the wake turn replied "Time to check the deploy." in the same Session 19 s later. Row moved to completed.
"Every 1 minute for 3 runs, tell me the current UTC time"	interval with maxRuns: 3; run 1 fired 74 ms after due and replied with the time.
"Cancel that timer" mid-way	Row moved to cancelled; the already-queued run-2 job was skipped by the worker ("Wakeup is cancelled"), no further jobs.
bullmq restart with a pending wakeup	The startup recovery sweep re-added the hint and the wakeup fired once. Also observed: a stale conversation turn lock from a process killed mid-turn delayed one delivery until the lock's TTL expired (~10 min); that is existing Fast lock behaviour, not wakeup-specific.
Archive cancels wakeups	Covered by the db helper test; not exercised through the UI in this run.

Fixes that came out of the run (second commit)

• BullMQ rejects custom job ids containing :; the delayed fire job never enqueued. Job ids now use -.
• The model fills every optional argument (at: "", wakeupId: "", until: "none", maxRuns: 0) and each strict rejection cost a retry (12 to 17 tool calls in the first two sessions). Arguments are now normalized before validation, once ignores stray maxRuns/until, and inMinutes wins when a computed at is sent alongside it. After the fix the same request took one call.

Local environment notes

• Fast turns were failing locally with OpenCode's generic "Unexpected server error" before any of this: the installed opencode was 1.17.8, which returns 500 when the prompt carries a variant (the session's reasoning effort). The repo pins the 1.18.10 SDK; upgrading the global binary to 1.18.10 fixed it. Worth adding to LOCAL_DEVELOPMENT.md.
• pm2 restart of api/bullmq can leave the previous node --watch dist/index.js child alive and holding the port, so the new process dies with EADDRINUSE. Killing the orphan and restarting again resolves it.

[daniel-lxs]

Schedule is now one string (third commit)

The structured schedule union was the source of the placeholder thrash, so it is gone. create now takes name, prompt, schedule, and an optional reportPolicy; the schedule is a single required string parsed server-side into the same stored shape:

in 2m
at 2026-09-04T15:00:00-04:00
every 10m
every 1m x3
every 10m until 2026-09-04T18:00:00Z
cron 0 9 * * 1-5 America/New_York

maxRuns and until are no longer tool fields; the tight-interval cap is enforced through x<count> / until. Unreadable input gets the grammar back in the error. Parser tests cover spellings like "in 2 minutes", "every minute for 3 runs", and the ambiguous bare "2m".

Local smoke test, repeated on the new contract

Step	Result
"Remind me in 2 minutes to check the deploy"	One manage_wakeups call, once schedule from in 2m; fired 14 ms after due; "Time to check the deploy." posted in the Session 15 s later; row completed.
"Every 1 minute for 3 runs, tell me the current UTC time"	One call, every 1m x3; run 1 fired 49 ms after due and replied with the time.
"Cancel that timer"	One call; row cancelled, the queued run-2 job was skipped by the worker, no delayed jobs left.

Every create and cancel in this run took exactly one tool call, versus 12 to 17 with the union before the argument normalization.

[roomote-roomote]

Following explicit author approval, pushed e92ccc18 to close the archive-versus-reply race. Archive takes the existing Fast conversation turn lock before committing archivedAt; contention beyond its two-second retry budget returns CONFLICT without archival. Acquisition errors fail closed and acquired locks release in finally. No DB transaction spans external reply calls.

Validation passed:

• pnpm exec dotenvx run -f .env.test -- pnpm --filter @roomote/web exec vitest run src/trpc/commands/sessions/archive.test.ts src/trpc/commands/sessions/index.test.ts src/lib/server/sessions.test.ts (31 tests, including 8 archive regressions).
• pnpm exec dotenvx run -f .env.test -- pnpm --filter @roomote/sdk exec vitest run src/server/lib/fast-agent-parent-event.test.ts src/server/lib/session-wakeups.test.ts (71 tests).
• pnpm --filter @roomote/web check-types, changed-file formatting and git diff --check.
• Full pre-push oxlint, residual ESLint, check-types:fast, and Knip.

Final-head CI and Roomote code review now pass. Automatic review reports no code issues and all four findings addressed; all five review threads are resolved. The earlier dedupe fixes remain included. PR metadata and the archive discussion are updated with evidence; worktree is clean.

Remaining merge gate: GitHub reports REVIEW_REQUIRED and BLOCKED, despite conflict-free mergeability and green checks. An eligible reviewer approval is still required. This run did not approve itself, merge, or bypass protection. Branch-protection details could not be inspected with the integration (403), so no specific approval count is claimed.

Test limits: real PostgreSQL with mocked Redis ownership/controlled reply completion, not live provider delivery. The two-second budget bounds contention retries rather than Redis network latency. Visual proof remains blocked (proof capture timed out); no captures were claimed or retried.