@c4t4/heyamigo 0.9.20 → 0.9.22

package/config/memory-instructions.md

@@ -227,3 +227,89 @@ A shared Chrome runs on the server at `localhost:9222` with the owner's real ses
 **Never call `browser_*` / `mcp__*playwright*` tools inline.** All browser work goes via `[ASYNC-BROWSER:...]`. See the two-track section above.
 
 To send a screenshot back: the browser worker takes it (saving to `storage/outbox/`), then includes `[IMAGE: /absolute/path.png]` in its result message.
+
+## Scheduling: reminders and recurring crons
+
+The bot has a built-in scheduler. When the user asks for any future or recurring action, you MUST emit a marker at the END of your reply — saying "I'll remind you" without a marker creates no schedule and the user gets nothing.
+
+The current local time is shown at the top of every chat preamble in the SENDER's timezone. Use it when interpreting "at 10:30am" / "tomorrow morning" / etc.
+
+### One-shot reminders — ONE canonical format
+
+```
+[REMIND: YYYY-MM-DD HH:MM — <text the user will receive>]
+```
+
+The time is always in the SENDER's timezone (shown in your preamble each
+turn as "Current local time"). YOU translate the user's natural-language
+date/time into the ISO form. Never pass through their raw phrasing.
+
+Translation table (assume current time = `2026-05-25 11:25` BA tz):
+
+| User says | You emit |
+|---|---|
+| `in 30 minutes` | `[REMIND: 2026-05-25 11:55 — ...]` |
+| `in 3 hours` | `[REMIND: 2026-05-25 14:25 — ...]` |
+| `tomorrow` | `[REMIND: 2026-05-26 09:00 — ...]` |
+| `tomorrow morning` | `[REMIND: 2026-05-26 09:00 — ...]` |
+| `tomorrow at 9am` | `[REMIND: 2026-05-26 09:00 — ...]` |
+| `at 10:30am` | `[REMIND: 2026-05-26 10:30 — ...]` (past today → rolls to tomorrow) |
+| `at 2pm` | `[REMIND: 2026-05-25 14:00 — ...]` (still future today) |
+| `20.10` / `20/10` | `[REMIND: 2026-10-20 09:00 — ...]` |
+| `20.10 at 14:00` | `[REMIND: 2026-10-20 14:00 — ...]` |
+| `october 20 at 2pm` | `[REMIND: 2026-10-20 14:00 — ...]` |
+| `next monday` | `[REMIND: 2026-06-01 09:00 — ...]` |
+| `monday morning` | `[REMIND: 2026-06-01 09:00 — ...]` |
+| `december 25` | `[REMIND: 2026-12-25 09:00 — ...]` |
+| `next week` | `[REMIND: 2026-06-01 11:25 — ...]` (+7 days, same time) |
+| `in a couple hours` | `[REMIND: 2026-05-25 13:25 — ...]` (interpret as 2h) |
+
+**Defaults when fields are missing:**
+- No time given → 09:00 sender-tz
+- No date given (just a time) → today, roll to tomorrow if past
+- No year given → current year, roll to next year if past
+
+Examples in actual reply text:
+
+```
+[REMIND: 2026-05-25 11:55 — take the chicken out of the oven]
+[REMIND: 2026-05-26 09:00 — gym]
+[REMIND: 2026-06-01 09:00 — weekly planning]
+```
+
+Do NOT use `in 30m`, `tomorrow at 9am`, or other shorthands. The parser
+accepts them as a fallback but the ISO form is the contract. Single
+format = no ambiguity, no locale concerns, no parser surprises.
+
+### Recurring crons — `[CRON: <recurrence> — <text>]`
+
+Recurrence forms:
+
+| Form | Example | Meaning |
+|---|---|---|
+| `@every N<unit>` | `@every 1h` / `@every 5m` | Fires repeatedly at that interval. |
+| `@daily HH:MM` | `@daily 09:00` | Every day at that user-local time (24h format). |
+| `@weekly <DOW> HH:MM` | `@weekly mon 09:00` | Every week on that weekday at that time. |
+
+Examples:
+```
+[CRON: @daily 09:00 — morning check-in: what's the focus today?]
+[CRON: @weekly sun 18:00 — weekly review: what worked, what didn't]
+[CRON: @every 2h — hydration reminder]
+```
+
+### Cross-chat send — `[SEND-TEXT: ...]`
+
+Send a text to a DIFFERENT chat than the one you're responding in. Rare; usually owner-only.
+
+```
+[SEND-TEXT: address=wa:dm:5491234567890@s.whatsapp.net body="heads up: just posted"]
+```
+
+### Rules
+
+- Acknowledge the schedule in your CHAT REPLY ("got it, reminding you at 10:30") so the user has immediate feedback. The marker is the side effect; the text is what they see right now.
+- ONE marker per scheduled item. Multiple markers in one reply OK.
+- Times are always in the **sender's timezone**, never the server's. The preamble shows the current local time so you can compute deltas if needed.
+- If parsing fails (malformed marker), the bot logs a warning and the schedule is dropped silently. Stick to the grammars above.
+- To cancel a scheduled item, the user types `/reminders` or `/crons` to see what's pending, then deletes via chat command.

package/dist/db/identity-sync.js

@@ -133,7 +133,7 @@ export function syncIdentitiesFromAccess() {
     logger.info({ personsUpserted, identitiesUpserted, seeded: seeds.length }, 'identity sync from access.json complete');
     return { personsUpserted, identitiesUpserted };
 }
-// Lookup helper used by the inbound resolution step (in later phases).
+// Lookup helper used by the inbound resolution step.
 // Returns null if the address has no matching person — caller decides
 // whether to auto-create or treat as stranger.
 export function personIdForAddress(address) {
@@ -145,3 +145,35 @@ export function personIdForAddress(address) {
         .get();
     return row?.personId ?? null;
 }
+// Timezone for a person, falling back to owner timezone when unknown.
+// Used by scheduling code (REMIND/CRON) so absolute times like "at
+// 10:30am" land in the SENDER's local time, not the server's.
+export function getTimezoneForPerson(personId) {
+    if (!personId)
+        return config.owner.timezone;
+    const db = getDb();
+    const row = db
+        .select({ tz: persons.timezone })
+        .from(persons)
+        .where(eq(persons.id, personId))
+        .get();
+    return row?.tz ?? config.owner.timezone;
+}
+// Convenience: resolve sender's address → person → timezone.
+// Address can be a WA jid or a wa:dm:... formatted address.
+export function getTimezoneForAddress(address) {
+    const pid = personIdForAddress(address);
+    return getTimezoneForPerson(pid);
+}
+// Sender-number → tz (handles the senderNumber field on Job/inbound
+// rows). Builds the wa:dm: address shape internally so we don't have
+// to duplicate the format-from-number logic at every call site.
+export function getTimezoneForSenderNumber(senderNumber) {
+    if (!senderNumber)
+        return config.owner.timezone;
+    const sanitized = senderNumber.replace(/\D/g, '');
+    if (!sanitized)
+        return config.owner.timezone;
+    const address = formatAddress(jidToAddress(`${sanitized}@s.whatsapp.net`));
+    return getTimezoneForAddress(address);
+}

package/dist/db/schema.js

@@ -115,6 +115,10 @@ export const crons = sqliteTable('crons', {
     enqueueInto: text('enqueue_into').notNull(), // 'inbound'|'async'|'outbound'|'memory_writes'
     payload: text('payload').notNull(), // JSON passed to the target queue
     recurrence: text('recurrence'), // null = one-shot
+    // IANA timezone for resolving @daily HH:MM / @weekly DOW HH:MM
+    // recurrences. Set to the sender's local tz when an agent emits a
+    // [CRON:] tag; nullable for system crons that prefer owner tz.
+    timezone: text('timezone'),
     nextRunAt: integer('next_run_at').notNull(),
     lastRunAt: integer('last_run_at'),
     enabled: integer('enabled').notNull().default(1), // SQLite bool = int

package/dist/gateway/commands.js

@@ -68,5 +68,16 @@ export async function tryCommand(ctx) {
         await sendText(ctx.sock, ctx.jid, formatQueuesSnapshot(snap), ctx.quoted);
         return true;
     }
+    if (cmd === 'reminders' || cmd === 'crons') {
+        const { listChatSchedules, formatScheduleList } = await import('../queue/schedule-list.js');
+        const { formatAddress, jidToAddress } = await import('../db/address.js');
+        const { getTimezoneForSenderNumber } = await import('../db/identity-sync.js');
+        const chatAddress = formatAddress(jidToAddress(ctx.jid));
+        const tz = getTimezoneForSenderNumber(ctx.senderNumber);
+        const onlyKind = cmd === 'reminders' ? 'one-shot' : 'recurring';
+        const items = listChatSchedules(chatAddress, onlyKind);
+        await sendText(ctx.sock, ctx.jid, formatScheduleList(items, tz, onlyKind), ctx.quoted);
+        return true;
+    }
     return false;
 }

package/dist/memory/digest-flag.js

@@ -8,6 +8,8 @@
 // drops it entirely. That bug leaked two real markers into user-facing
 // replies today (DIGEST ~morning, ASYNC later). This parser closes that
 // whole class of failure.
+import { logger } from '../logger.js';
+import { parseTimeExpression } from '../queue/time-expr.js';
 const KINDS = [
     'DIGEST',
     'JOURNAL',
@@ -115,16 +117,22 @@ export function extractFlags(reply) {
             const parsed = parseSendTextPayload(payload);
             if (parsed)
                 sendTexts.unshift(parsed);
+            else
+                logger.warn({ payload }, 'SEND-TEXT tag dropped: unparseable payload');
         }
         else if (kind === 'CRON') {
             const parsed = parseCronPayload(payload);
             if (parsed)
                 crons.unshift(parsed);
+            else
+                logger.warn({ payload }, 'CRON tag dropped: unparseable payload');
         }
         else if (kind === 'REMIND') {
             const parsed = parseRemindPayload(payload);
             if (parsed)
                 reminds.unshift(parsed);
+            else
+                logger.warn({ payload }, 'REMIND tag dropped: unparseable payload');
         }
     }
     return {
@@ -178,7 +186,10 @@ function parseCronPayload(payload) {
         return null;
     return { recurrence, body };
 }
-// Parse `in <n><unit> — <body>` payload. Supported units: s,m,h,d.
+// Parse `<time-spec> — <body>` payload. Time spec is anything the
+// TimeExpression parser accepts: `in 30m`, `at 10:30am`, `tomorrow
+// at 9am`, `mon at 9am`, `YYYY-MM-DD HH:MM`. Resolution happens
+// later in the worker using the sender's timezone.
 function parseRemindPayload(payload) {
     const sepMatch = payload.match(/\s+[—–-]\s+/);
     if (!sepMatch || sepMatch.index === undefined)
@@ -187,15 +198,10 @@ function parseRemindPayload(payload) {
     const body = payload.slice(sepMatch.index + sepMatch[0].length).trim();
     if (!timeSpec || !body)
         return null;
-    const m = timeSpec.match(/^in\s+(\d+)\s*([smhd])$/i);
-    if (!m)
+    const when = parseTimeExpression(timeSpec);
+    if (!when)
         return null;
-    const n = parseInt(m[1], 10);
-    const unit = m[2].toLowerCase();
-    const mult = unit === 's' ? 1 : unit === 'm' ? 60 : unit === 'h' ? 3600 : 86400;
-    if (n <= 0)
-        return null;
-    return { whenSecondsFromNow: n * mult, body };
+    return { when, body };
 }
 // Parse `address=<addr> body="..."` style key=value payload.
 // Body is delimited by double quotes; everything else by whitespace.

package/dist/memory/preamble.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from 'fs';
 import { resolve } from 'path';
 import { config } from '../config.js';
+import { getTimezoneForSenderNumber } from '../db/identity-sync.js';
 import { listAsyncTasks } from '../queue/async-tasks.js';
 import { readCompressed } from './compressed.js';
 import { buildJournalsPreambleBlock, ensureJournalsScaffold, } from './journals.js';
@@ -11,6 +12,50 @@ import { getRoleForContext } from '../wa/whitelist.js';
 const DIGEST_REMINDER = `When something worth remembering happens (new preference, key fact, life event, changed plan), append [DIGEST: <one-line reason>] to the END of your reply. It will be stripped before sending. Flag sparingly.`;
 const JOURNAL_REMINDER = `When a message contains info for one of the journals above, append [JOURNAL:<slug> — <one-line note>] to the END of your reply. Multiple tags OK. Only use slugs listed; never invent. Full rules are in your memory instructions.`;
 const ASYNC_REMINDER = `TWO TRACKS run in parallel: you are the chat track, a separate browser track runs a persistent Claude session dedicated to the shared Chrome at localhost:9222. Never call browser tools (browser_*, mcp__*playwright*) yourself — delegate via [ASYNC-BROWSER: <self-sufficient task description>] at the END of your reply, plus a short ack ("On it, will report back."). For non-browser long work (>30s, multi-step reasoning) use [ASYNC: ...]. Irreversible actions (DM send, post, purchase) split into gather→confirm→act phases — never send on your own judgment.`;
+// Buildable per-turn so the agent always sees the SENDER's current
+// time and timezone — not the server's. Critical for resolving
+// "today at 10:30am" / "tomorrow morning" relative to the user.
+function buildSchedulingReminder(nowLocal, tz) {
+    return [
+        `SCHEDULING (reminders and recurring schedules):`,
+        `Current local time for THIS sender: ${nowLocal} (${tz}).`,
+        `Saying "I'll remind you" is NOT enough — you must emit a tag.`,
+        `Without the tag, NO schedule is created and the user gets nothing.`,
+        ``,
+        `### One-shot reminder — ONE canonical format, always:`,
+        `  [REMIND: YYYY-MM-DD HH:MM — <text the user will receive>]`,
+        ``,
+        `The time is in the sender's timezone (${tz}). YOU compute the`,
+        `absolute date and time from the user's natural language using the`,
+        `CURRENT LOCAL TIME above. NEVER pass the user's raw phrasing to`,
+        `the tag.`,
+        ``,
+        `Translation examples (current time = ${nowLocal}):`,
+        `  user: "in 30 minutes"          → [REMIND: <now + 30m> — <text>]`,
+        `  user: "in 3 hours"             → [REMIND: <now + 3h> — <text>]`,
+        `  user: "tomorrow"               → [REMIND: <tomorrow> 09:00 — <text>]`,
+        `  user: "tomorrow morning"       → [REMIND: <tomorrow> 09:00 — <text>]`,
+        `  user: "at 10:30am"             → [REMIND: <today or tomorrow if past> 10:30 — <text>]`,
+        `  user: "20.10" / "20/10"        → [REMIND: <yyyy>-10-20 09:00 — <text>]`,
+        `  user: "october 20 at 2pm"      → [REMIND: <yyyy>-10-20 14:00 — <text>]`,
+        `  user: "next monday"            → [REMIND: <next-mon> 09:00 — <text>]`,
+        `  user: "december 25"            → [REMIND: <yyyy>-12-25 09:00 — <text>]`,
+        ``,
+        `Default time when user omits one: 09:00 sender-tz.`,
+        `Default date when user only gives a time: today (roll to tomorrow if past).`,
+        `Year: current year if the resulting date is in the future, else next year.`,
+        ``,
+        `### Recurring schedule — same shape, recurrence is symbolic:`,
+        `  [CRON: @daily HH:MM — <text>]        (HH:MM in sender's tz)`,
+        `  [CRON: @every N(s|m|h|d) — <text>]   (every N units)`,
+        `  [CRON: @weekly <DOW> HH:MM — <text>] (DOW = mon..sun)`,
+        ``,
+        `### Cross-chat send (rare):`,
+        `  [SEND-TEXT: address=wa:dm:1234567890@s.whatsapp.net body="..."]`,
+        ``,
+        `Acknowledge the schedule in your chat reply ("got it, reminding you tomorrow at 9am") and emit the tag at the END. Reply text is what the user sees right now; the tag is the side effect.`,
+    ].join('\n');
+}
 function buildCriticalSection(params) {
     const { senderNumber, roleName, role, userName } = params;
     const who = userName
@@ -131,6 +176,23 @@ export function buildMemoryPreamble(params) {
         sections.push(`[Journals: active]\n${journalsBlock}`);
         instructions.push(JOURNAL_REMINDER);
     }
+    // Scheduling reminder — tells the agent the current local time in
+    // the SENDER's timezone + lists the REMIND/CRON/SEND-TEXT grammar.
+    // Without this the agent never emits the tag and reminders silently
+    // never fire (was the root-cause of the May 2026 reminders-not-
+    // working bug).
+    const senderTz = getTimezoneForSenderNumber(params.senderNumber);
+    const nowLocal = new Intl.DateTimeFormat('en-GB', {
+        timeZone: senderTz,
+        weekday: 'short',
+        year: 'numeric',
+        month: 'short',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        hour12: false,
+    }).format(new Date());
+    instructions.push(buildSchedulingReminder(nowLocal, senderTz));
     // Async tasks in progress for this chat — so Claude doesn't re-promise or
     // contradict work already running in the background.
     const asyncTasks = listAsyncTasks(params.jid);

package/dist/queue/crons.js

@@ -23,6 +23,7 @@ export function enqueueCron(input) {
     const db = getDb();
     const now = Math.floor(Date.now() / 1000);
     const enabled = (input.enabled ?? true) ? 1 : 0;
+    const tz = input.timezone ?? config.owner.timezone;
     if (input.recurrence) {
         const existing = db
             .select()
@@ -36,6 +37,7 @@ export function enqueueCron(input) {
                 enqueueInto: input.enqueueInto,
                 payload: JSON.stringify(input.payload),
                 recurrence: input.recurrence,
+                timezone: tz,
                 enabled,
             })
                 .where(eq(crons.name, input.name))
@@ -44,7 +46,7 @@ export function enqueueCron(input) {
             return updated;
         }
     }
-    const firstRunAt = input.firstRunAt ?? computeNextRun(input.recurrence, now);
+    const firstRunAt = input.firstRunAt ?? computeNextRun(input.recurrence, now, tz);
     if (firstRunAt === null) {
         throw new Error(`enqueueCron(${input.name}): one-shot requires firstRunAt`);
     }
@@ -55,6 +57,7 @@ export function enqueueCron(input) {
         enqueueInto: input.enqueueInto,
         payload: JSON.stringify(input.payload),
         recurrence: input.recurrence,
+        timezone: tz,
         nextRunAt: firstRunAt,
         lastRunAt: null,
         enabled,
@@ -74,7 +77,8 @@ export function listDueCrons(asOf = Math.floor(Date.now() / 1000)) {
 }
 // Called by orchestrator after the cron's payload has been enqueued
 // into its target queue. Recurring crons get nextRunAt advanced;
-// one-shots get deleted.
+// one-shots get deleted. Uses the row's stored timezone for @daily /
+// @weekly resolution; falls back to owner tz for legacy rows.
 export function markCronFired(row) {
     const db = getDb();
     const now = Math.floor(Date.now() / 1000);
@@ -82,7 +86,8 @@ export function markCronFired(row) {
         db.delete(crons).where(eq(crons.id, row.id)).run();
         return;
     }
-    const next = computeNextRun(row.recurrence, now);
+    const tz = row.timezone ?? config.owner.timezone;
+    const next = computeNextRun(row.recurrence, now, tz);
     if (next === null) {
         logger.error({ id: row.id, name: row.name, recurrence: row.recurrence }, 'cron has unparseable recurrence after firing; disabling');
         db.update(crons)
@@ -128,8 +133,10 @@ const DOW_INDEX = {
     sun: 0, mon: 1, tue: 2, wed: 3, thu: 4, fri: 5, sat: 6,
 };
 // Returns the next-run timestamp (unix seconds) for a recurrence, or
-// null for an unparseable format.
-export function computeNextRun(recurrence, nowSec) {
+// null for an unparseable format. tz defaults to owner timezone but
+// per-user crons should pass the sender's local tz so @daily HH:MM
+// fires in the user's wall-clock time, not the server's.
+export function computeNextRun(recurrence, nowSec, tz = config.owner.timezone) {
     if (!recurrence)
         return null;
     const everyMatch = EVERY_RE.exec(recurrence);
@@ -142,20 +149,19 @@ export function computeNextRun(recurrence, nowSec) {
     }
     const dailyMatch = DAILY_RE.exec(recurrence);
     if (dailyMatch) {
-        return nextLocalHourMinute(nowSec, parseInt(dailyMatch[1], 10), parseInt(dailyMatch[2], 10), null);
+        return nextLocalHourMinute(nowSec, parseInt(dailyMatch[1], 10), parseInt(dailyMatch[2], 10), null, tz);
     }
     const weeklyMatch = WEEKLY_RE.exec(recurrence);
     if (weeklyMatch) {
         const dow = DOW_INDEX[weeklyMatch[1].toLowerCase()];
-        return nextLocalHourMinute(nowSec, parseInt(weeklyMatch[2], 10), parseInt(weeklyMatch[3], 10), dow);
+        return nextLocalHourMinute(nowSec, parseInt(weeklyMatch[2], 10), parseInt(weeklyMatch[3], 10), dow, tz);
     }
     return null;
 }
-// Compute the next unix-seconds at HH:MM in the owner timezone,
+// Compute the next unix-seconds at HH:MM in the given timezone,
 // optionally constrained to a day-of-week. Always returns a moment
 // strictly in the future (> nowSec).
-function nextLocalHourMinute(nowSec, hour, minute, dayOfWeek) {
-    const tz = config.owner.timezone;
+function nextLocalHourMinute(nowSec, hour, minute, dayOfWeek, tz) {
     const fmt = new Intl.DateTimeFormat('en-CA', {
         timeZone: tz,
         year: 'numeric', month: '2-digit', day: '2-digit',

package/dist/queue/schedule-list.js

@@ -0,0 +1,61 @@
+// Helpers for the /reminders and /crons chat commands. Lists pending
+// cron rows that target a particular chat address, formatted for
+// reading on a phone.
+import { and, asc, eq, like } from 'drizzle-orm';
+import { getDb } from '../db/index.js';
+import { crons } from '../db/schema.js';
+import { formatLocalTime } from './time-expr.js';
+// Pull crons whose payload targets the given chat address. We tag
+// chat-emitted crons with names prefixed by 'chat-cron-' (recurring)
+// or 'chat-remind-' (one-shot), so a LIKE filter on the JSON address
+// is the simplest way to scope per chat.
+export function listChatSchedules(chatAddress, kind) {
+    const db = getDb();
+    // SQLite has no JSON containment operator that's portable; use a
+    // simple substring search on the serialized payload. Payloads
+    // include `"address":"<addr>"` which is unique enough.
+    const addressNeedle = `%"address":"${chatAddress.replace(/"/g, '\\"')}"%`;
+    const rows = db
+        .select()
+        .from(crons)
+        .where(and(eq(crons.enabled, 1), like(crons.payload, addressNeedle)))
+        .orderBy(asc(crons.nextRunAt))
+        .all();
+    return rows
+        .filter((r) => kind === 'one-shot' ? r.recurrence === null : r.recurrence !== null)
+        .map((r) => ({
+        id: r.id,
+        name: r.name,
+        recurrence: r.recurrence,
+        nextRunAt: r.nextRunAt,
+        bodyPreview: extractBodyPreview(r.payload),
+    }));
+}
+function extractBodyPreview(payload) {
+    try {
+        const obj = JSON.parse(payload);
+        const t = obj.text ?? '';
+        return t.length > 80 ? t.slice(0, 77) + '...' : t;
+    }
+    catch {
+        return '';
+    }
+}
+export function formatScheduleList(items, tz, kind) {
+    if (items.length === 0) {
+        return kind === 'one-shot'
+            ? 'No reminders pending for this chat.'
+            : 'No recurring schedules for this chat.';
+    }
+    const header = kind === 'one-shot' ? '*Pending reminders*' : '*Recurring schedules*';
+    const lines = [header];
+    for (const item of items) {
+        const when = formatLocalTime(item.nextRunAt, tz);
+        const tail = item.recurrence ? ` · ${item.recurrence}` : '';
+        lines.push(`  ${when}${tail}`);
+        if (item.bodyPreview)
+            lines.push(`    "${item.bodyPreview}"`);
+    }
+    lines.push(`Timezone: ${tz}`);
+    return lines.join('\n');
+}

package/dist/queue/time-expr.js

@@ -0,0 +1,192 @@
+// Time expression parsing and resolution.
+//
+// Split into two stages so timezone application happens at resolve
+// time, not parse time. The parser doesn't know whose timezone to
+// use — it just produces a structured TimeExpression. The worker
+// looks up the sender's timezone and calls resolveTimeExpression()
+// to get a unix-second timestamp.
+//
+// Grammars supported (case-insensitive, trimmed):
+//   in <n>(s|m|h|d)              relative
+//   in <n> second(s)|minute(s)|hour(s)|day(s)
+//   at <H>(:MM)?(am|pm)?         today, user-tz
+//   tomorrow at <H>(:MM)?(am|pm)?
+//   <mon|tue|wed|thu|fri|sat|sun> at <H>(:MM)?(am|pm)?
+//   YYYY-MM-DD HH:MM             ISO-style, user-tz
+//
+// Past times today (e.g. user says "at 9am" at 11am) shift to
+// tomorrow. Weekday targets land on the NEXT occurrence of that
+// weekday including today if it's still in the future.
+const DOW_INDEX = {
+    sun: 0, mon: 1, tue: 2, wed: 3, thu: 4, fri: 5, sat: 6,
+};
+const UNIT_SECONDS = {
+    s: 1, second: 1, seconds: 1,
+    m: 60, minute: 60, minutes: 60,
+    h: 3600, hour: 3600, hours: 3600,
+    d: 86400, day: 86400, days: 86400,
+};
+const REL_RE = /^in\s+(\d+)\s*([a-z]+)$/i;
+const TODAY_RE = /^at\s+(\d{1,2})(?::(\d{2}))?\s*(am|pm)?$/i;
+const TOMORROW_RE = /^tomorrow(?:\s+at)?\s+(\d{1,2})(?::(\d{2}))?\s*(am|pm)?$/i;
+const WEEKDAY_RE = /^(mon|tue|wed|thu|fri|sat|sun)(?:day)?(?:\s+at)?\s+(\d{1,2})(?::(\d{2}))?\s*(am|pm)?$/i;
+const ISO_RE = /^(\d{4})-(\d{2})-(\d{2})\s+(\d{1,2}):(\d{2})$/;
+export function parseTimeExpression(input) {
+    const s = input.trim();
+    const m1 = REL_RE.exec(s);
+    if (m1) {
+        const n = parseInt(m1[1], 10);
+        const unit = m1[2].toLowerCase();
+        const mult = UNIT_SECONDS[unit];
+        if (!mult || n <= 0)
+            return null;
+        return { kind: 'relative', seconds: n * mult };
+    }
+    const m2 = TODAY_RE.exec(s);
+    if (m2) {
+        const hm = parseHourMinute(m2[1], m2[2], m2[3]);
+        if (!hm)
+            return null;
+        return { kind: 'today', hour: hm.hour, minute: hm.minute };
+    }
+    const m3 = TOMORROW_RE.exec(s);
+    if (m3) {
+        const hm = parseHourMinute(m3[1], m3[2], m3[3]);
+        if (!hm)
+            return null;
+        return { kind: 'tomorrow', hour: hm.hour, minute: hm.minute };
+    }
+    const m4 = WEEKDAY_RE.exec(s);
+    if (m4) {
+        const dow = DOW_INDEX[m4[1].toLowerCase()];
+        if (dow === undefined)
+            return null;
+        const hm = parseHourMinute(m4[2], m4[3], m4[4]);
+        if (!hm)
+            return null;
+        return { kind: 'weekday', dayOfWeek: dow, hour: hm.hour, minute: hm.minute };
+    }
+    const m5 = ISO_RE.exec(s);
+    if (m5) {
+        const year = parseInt(m5[1], 10);
+        const month = parseInt(m5[2], 10);
+        const day = parseInt(m5[3], 10);
+        const hour = parseInt(m5[4], 10);
+        const minute = parseInt(m5[5], 10);
+        if (month < 1 || month > 12 || day < 1 || day > 31)
+            return null;
+        if (hour < 0 || hour > 23 || minute < 0 || minute > 59)
+            return null;
+        return { kind: 'iso', year, month, day, hour, minute };
+    }
+    return null;
+}
+function parseHourMinute(hStr, mStr, ampm) {
+    let h = parseInt(hStr, 10);
+    const m = mStr ? parseInt(mStr, 10) : 0;
+    if (m < 0 || m > 59)
+        return null;
+    if (ampm) {
+        const meridiem = ampm.toLowerCase();
+        if (h < 1 || h > 12)
+            return null;
+        if (meridiem === 'am')
+            h = h === 12 ? 0 : h;
+        else
+            h = h === 12 ? 12 : h + 12;
+    }
+    else {
+        // 24h form when no am/pm
+        if (h < 0 || h > 23)
+            return null;
+    }
+    return { hour: h, minute: m };
+}
+// Resolve to absolute unix seconds in the given timezone. Always
+// returns a moment strictly in the future relative to `nowSec`.
+export function resolveTimeExpression(expr, tz, nowSec) {
+    if (expr.kind === 'relative') {
+        return nowSec + expr.seconds;
+    }
+    if (expr.kind === 'today') {
+        const today = localCalendarDate(nowSec, tz);
+        const candidate = makeDateInTz(today.year, today.month, today.day, expr.hour, expr.minute, tz);
+        // If already past today, roll to tomorrow.
+        return candidate > nowSec
+            ? candidate
+            : makeDateInTz(today.year, today.month, today.day + 1, expr.hour, expr.minute, tz);
+    }
+    if (expr.kind === 'tomorrow') {
+        const today = localCalendarDate(nowSec, tz);
+        return makeDateInTz(today.year, today.month, today.day + 1, expr.hour, expr.minute, tz);
+    }
+    if (expr.kind === 'weekday') {
+        // Walk forward 0..7 days in user-tz until day-of-week matches AND
+        // the resulting moment is in the future.
+        const today = localCalendarDate(nowSec, tz);
+        for (let offset = 0; offset < 8; offset++) {
+            const candidate = makeDateInTz(today.year, today.month, today.day + offset, expr.hour, expr.minute, tz);
+            const candidateDow = localCalendarDate(candidate, tz).dayOfWeek;
+            if (candidateDow === expr.dayOfWeek && candidate > nowSec) {
+                return candidate;
+            }
+        }
+        // Shouldn't reach — fallback to a week from now.
+        return nowSec + 7 * 86400;
+    }
+    // ISO
+    return makeDateInTz(expr.year, expr.month - 1, expr.day, expr.hour, expr.minute, tz);
+}
+// Build a unix-seconds for a given Y/M/D HH:MM interpreted in a named
+// timezone. Guess-and-correct via Intl.DateTimeFormat — same technique
+// the cron parser uses. Handles DST seamlessly.
+function makeDateInTz(year, month, day, hour, minute, tz) {
+    const guessUtcMs = Date.UTC(year, month, day, hour, minute, 0);
+    const fmt = new Intl.DateTimeFormat('en-US', {
+        timeZone: tz,
+        year: 'numeric', month: '2-digit', day: '2-digit',
+        hour: '2-digit', minute: '2-digit', second: '2-digit',
+        hour12: false,
+    });
+    const parts = fmt.formatToParts(new Date(guessUtcMs));
+    const get = (type) => parts.find((p) => p.type === type)?.value ?? '0';
+    let parsedHour = parseInt(get('hour'), 10);
+    // Intl formats midnight as "24" in some locale/version combos; normalize.
+    if (parsedHour === 24)
+        parsedHour = 0;
+    const renderedUtcMs = Date.UTC(parseInt(get('year'), 10), parseInt(get('month'), 10) - 1, parseInt(get('day'), 10), parsedHour, parseInt(get('minute'), 10), parseInt(get('second'), 10));
+    const offsetMs = guessUtcMs - renderedUtcMs;
+    return Math.floor((guessUtcMs + offsetMs) / 1000);
+}
+// Decompose a unix-second into Y/M/D and day-of-week in a named
+// timezone. Returns calendar fields as the local user would see
+// them — used to compute "today" anchors before applying HH:MM.
+function localCalendarDate(sec, tz) {
+    const fmt = new Intl.DateTimeFormat('en-CA', {
+        timeZone: tz,
+        year: 'numeric', month: '2-digit', day: '2-digit',
+        weekday: 'short',
+    });
+    const parts = fmt.formatToParts(new Date(sec * 1000));
+    const get = (type) => parts.find((p) => p.type === type)?.value ?? '';
+    return {
+        year: parseInt(get('year'), 10),
+        month: parseInt(get('month'), 10) - 1, // 0-indexed for makeDateInTz Date.UTC compat
+        day: parseInt(get('day'), 10),
+        dayOfWeek: (DOW_INDEX[get('weekday').toLowerCase()] ?? 0),
+    };
+}
+// Human-readable formatter used in chat acks. Renders an absolute
+// resolved time back into the user's local time.
+export function formatLocalTime(unixSec, tz) {
+    return new Intl.DateTimeFormat('en-GB', {
+        timeZone: tz,
+        weekday: 'short',
+        year: 'numeric',
+        month: 'short',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        hour12: false,
+    }).format(new Date(unixSec * 1000));
+}