Skip to content

Open-source gym & body-weight tracker, now in the App Store (iPhone + Apple Watch) and as an Android APK. Plan routines, log workouts, see which muscles are trained, import from Strong/Hevy/FitNotes. Self-host it or use it on the phone alone.

coach: a weekly review is due until it has run, not for one minute a week

Boris 'B' Kurktchiev300dcd68c49f
diff --git a/api/coach/cadence.js b/api/coach/cadence.js
index c088ea282..7485f20a1 100644
--- a/api/coach/cadence.js
+++ b/api/coach/cadence.js
@@ -18,7 +18,7 @@ const TICK_MS = 60000;
* `reviewedAt` is when the server last finished a review for this person: the client stamps
* lastReview only once someone acts on a proposal, and a review nobody has opened yet — or
* one that found nothing to change — still read those workouts. */
-export function isDue(coach, S, now, reviewedAt = 0) {
+export function isDue(coach, S, now, reviewedAt = 0, tz = null) {
const cadence = coach.cadence;
if (!cadence || cadence === 'off') return false;
const lastAt = Math.max(coach.lastReview?.at || 0, reviewedAt);
@@ -36,15 +36,68 @@ export function isDue(coach, S, now, reviewedAt = 0) {
}
if (cadence.weekly) {
if (!now) return false;
- const wantDay = cadence.weekly.day ?? 0;
- const wantTime = cadence.weekly.time || '18:00';
- if (now.weekday !== wantDay || now.hhmm !== wantTime) return false;
- // One per day, even if the tick sees the same minute twice.
- return new Date(lastAt).toISOString().slice(0, 10) !== now.date;
+ // Due once the week's slot has passed and this week's review has not run — not on the one
+ // minute it falls. The tick is every 60 s and unaligned, so the exact-minute test lost the
+ // whole week to a restart, a redeploy or a busy event loop across that minute; the same
+ // reason the workout reminder stopped asking for its exact minute. `lastAt` is the marker
+ // that says whether it already ran: the server's own finished-review timestamps (the
+ // `reviewedAt` the caller computes from the job history) and the client's lastReview.
+ const at = weeklySlotAt(now, cadence.weekly.day ?? 0, cadence.weekly.time || '18:00', tz);
+ return at != null && lastAt < at;
}
return false;
}
+/* When this week's slot fell, as an epoch timestamp — the clock `lastAt` is on.
+ *
+ * `now` is the user's own wall clock (date, hh:mm, weekday, from their reminder timezone) and
+ * the marker is epoch milliseconds, so a wall clock reading has to be turned into an instant.
+ * What turns one into the other is the zone's offset, and the offset that matters is the one AT
+ * the slot, not the one here now: the slot can be six days old, and twice a year the zone moved
+ * in between. Using today's offset on last Sunday's slot puts it an hour out, which on the
+ * fall-back Sunday is enough to call a review due eight hours before its time — and then again
+ * at its time, so the week gets two.
+ *
+ * So the slot is resolved at its own instant: instant = wall − offset(instant), settled in two
+ * passes. The first uses the offset where the caller is now (at most an hour out), the second the
+ * offset at that approximation, which is the slot's own on either side of a changeover. A wall
+ * clock inside a skipped hour names no instant at all; it lands within the hour either way, which
+ * is as close as the question ("has this week's slot passed") can be asked.
+ *
+ * "This week's" is the slot's most recent occurrence at or before now, so on the slot's own day
+ * but before its time it is last week's — which the last run is already past, so nothing fires
+ * early. Null when the shapes do not parse. */
+function weeklySlotAt(now, wantDay, wantTime, tz) {
+ const d = /^(\d{4})-(\d{2})-(\d{2})$/.exec(now.date || '');
+ const nowMin = hhmmToMin(now.hhmm), wantMin = hhmmToMin(wantTime);
+ if (!d || !Number.isFinite(nowMin) || !Number.isFinite(wantMin)) return null;
+ const midnight = Date.UTC(+d[1], +d[2] - 1, +d[3]);
+ let back = (now.weekday - wantDay + 7) % 7;
+ if (back === 0 && nowMin < wantMin) back = 7;
+ const wall = midnight - back * 86400000 + wantMin * 60000;
+ const here = midnight + nowMin * 60000;
+ return wall - offsetAt(tz, wall - offsetAt(tz, Date.now(), here), here);
+}
+/* The zone's offset from UTC at one instant, in ms: what a wall clock reading there is ahead of
+ * the instant it names. Without a usable zone — no tz, or a string Intl refuses — it falls back
+ * to the offset where the caller is right now, which is all this ever had to go on. */
+function offsetAt(tz, ms, hereWall) {
+ try {
+ const p = new Intl.DateTimeFormat('en-CA', {
+ timeZone: tz, hourCycle: 'h23',
+ year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', second: '2-digit'
+ }).formatToParts(new Date(ms));
+ const g = t => Number(p.find(x => x.type === t).value);
+ return Date.UTC(g('year'), g('month') - 1, g('day'), g('hour'), g('minute'), g('second')) - ms;
+ } catch {
+ return hereWall - Date.now();
+ }
+}
+const hhmmToMin = v => {
+ const m = /^(\d{1,2}):(\d{2})$/.exec(v || '');
+ return m ? Number(m[1]) * 60 + Number(m[2]) : NaN;
+};
+
/**
* @param {object} deps { users(): [{id}], userNow(tz): {date,hhmm,weekday} }
*/
@@ -70,7 +123,7 @@ export function startCadence(deps) {
.map(h => h.at || 0));
const tz = coach.cadence?.weekly ? (S.reminder?.tz || 'UTC') : null;
const now = tz ? deps.userNow(tz) : null;
- if (!isDue(coach, S, now, reviewedAt)) continue;
+ if (!isDue(coach, S, now, reviewedAt, tz)) continue;
jobs.enqueue(user.id, { kind: 'review', trigger: 'scheduled' });
console.log('coach: scheduled review queued for', user.id);
} catch (e) {
diff --git a/api/test/cadence-weekly.test.js b/api/test/cadence-weekly.test.js
new file mode 100644
index 000000000..d612f3b9c
--- /dev/null
+++ b/api/test/cadence-weekly.test.js
@@ -0,0 +1,145 @@
+/* The weekly cadence used to be due for exactly one minute a week: `now.hhmm === wantTime`, on a
+ 60-second tick that is not aligned to anything. A restart across that minute, a redeploy, or an
+ event loop busy with a big state file, and the whole week was skipped in silence — nobody is
+ told a scheduled review did not happen.
+
+ It is now due once the week's slot has passed and this week's review has not run, judged
+ against the run marker the job history already carries. The clock is faked here, because that
+ is the whole of what this function reads. */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { tempData } from './helpers.mjs';
+
+tempData();
+const { isDue } = await import('../coach/cadence.js');
+
+const DAY = 86400000, MIN = 60000;
+// Sunday 20 September 2026, 18:00 UTC — the default slot (day 0, 18:00).
+const SLOT = Date.UTC(2026, 8, 20, 18, 0);
+const weekly = { day: 0, time: '18:00' };
+
+// The shape startCadence hands in: the user's own wall clock, from their reminder timezone.
+const wallClock = ms => {
+ const iso = new Date(ms).toISOString();
+ return { date: iso.slice(0, 10), hhmm: iso.slice(11, 16), weekday: new Date(ms).getUTCDay() };
+};
+// The same wall clock the tick hands in — server.js userNow, for a real zone.
+const wallClockIn = (tz, ms) => {
+ const p = new Intl.DateTimeFormat('en-CA', {
+ timeZone: tz, hourCycle: 'h23',
+ year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit'
+ }).formatToParts(new Date(ms));
+ const g = t => p.find(x => x.type === t).value;
+ const date = `${g('year')}-${g('month')}-${g('day')}`;
+ return { date, hhmm: `${g('hour')}:${g('minute')}`, weekday: new Date(date + 'T12:00:00Z').getUTCDay() };
+};
+const coach = lastReviewAt => ({ cadence: { weekly }, lastReview: { at: lastReviewAt } });
+// One workout, logged right after the last review — so "nothing new to read" is never the reason.
+const state = lastReviewAt => ({ workouts: [{ id: 'w1', d: '2026-09-18', end: lastReviewAt + MIN }] });
+
+/** isDue as the tick calls it, with the clock stopped at `at`. */
+const dueAt = (t, at, lastReviewAt) => {
+ t.mock.timers.enable({ apis: ['Date'], now: at });
+ try { return isDue(coach(lastReviewAt), state(lastReviewAt), wallClock(at), 0); }
+ finally { t.mock.timers.reset(); }
+};
+
+test('a review the tick missed by a minute is still due', t => {
+ // Ran last Sunday on time; this Sunday the tick landed at 18:00:30 and then at 18:01:30.
+ assert.equal(dueAt(t, SLOT + 90 * 1000, SLOT - 7 * DAY), true);
+ // …and half an hour later, if the restart took that long.
+ assert.equal(dueAt(t, SLOT + 30 * MIN, SLOT - 7 * DAY), true);
+ // …and the next morning, which is still this week's review rather than none at all.
+ assert.equal(dueAt(t, SLOT + 15 * 60 * MIN, SLOT - 7 * DAY), true);
+});
+
+test('the minute itself is unchanged, and so is the week after it ran', t => {
+ assert.equal(dueAt(t, SLOT, SLOT - 7 * DAY), true, 'on the slot, as before');
+ assert.equal(dueAt(t, SLOT + MIN, SLOT + 30 * 1000), false, 'it ran half a minute ago');
+ assert.equal(dueAt(t, SLOT + 6 * DAY, SLOT + 30 * 1000), false, 'and still not again this week');
+});
+
+test('before the slot is not due, however long ago the last one was', t => {
+ assert.equal(dueAt(t, SLOT - 2 * DAY, SLOT - 7 * DAY), false, 'Friday: this week has not come round yet');
+ assert.equal(dueAt(t, SLOT - MIN, SLOT - 7 * DAY), false, 'a minute early is early');
+});
+
+test('a box that was off over the slot runs the review when it comes back', t => {
+ // Down from Saturday to Wednesday: the slot passed with nothing running. Three days late is
+ // late; a week with no review at all is what the exact-minute test used to produce.
+ assert.equal(dueAt(t, SLOT + 3 * DAY, SLOT - 8 * DAY), true);
+});
+
+test('the gates that already existed still hold', t => {
+ t.mock.timers.enable({ apis: ['Date'], now: SLOT + 30 * MIN });
+ t.after(() => t.mock.timers.reset());
+ const lastAt = SLOT - 7 * DAY;
+ assert.equal(isDue(coach(lastAt), { workouts: [] }, wallClock(SLOT + 30 * MIN), 0), false, 'nothing logged since');
+ assert.equal(isDue({ cadence: 'off', lastReview: { at: lastAt } }, state(lastAt), wallClock(SLOT + 30 * MIN), 0), false);
+ assert.equal(isDue(coach(lastAt), state(lastAt), null, 0), false, 'an unreadable timezone is skipped, not guessed');
+ // A review the server finished counts even when the client never stamped lastReview.
+ assert.equal(isDue({ cadence: { weekly } }, state(lastAt), wallClock(SLOT + 30 * MIN), SLOT + 60 * 1000), false);
+});
+
+test('the slot is read on the user\'s clock, not the server\'s', t => {
+ // Sunday 18:00 in Tokyo is Sunday 09:00 UTC. At the same instant — 09:01 UTC — the Tokyo
+ // profile's slot passed a minute ago and the UTC profile's is nine hours away.
+ const at = Date.UTC(2026, 8, 20, 9, 1);
+ t.mock.timers.enable({ apis: ['Date'], now: at });
+ t.after(() => t.mock.timers.reset());
+ // Last week's review, after both profiles' slots on that Sunday.
+ const lastAt = Date.UTC(2026, 8, 13, 19, 0);
+ const tokyo = { date: '2026-09-20', hhmm: '18:01', weekday: 0 };
+ assert.equal(isDue(coach(lastAt), state(lastAt), tokyo, 0), true, 'Tokyo is a minute past its slot');
+ assert.equal(isDue(coach(lastAt), state(lastAt), wallClock(at), 0), false, 'UTC has not reached 18:00');
+});
+
+/* The slot has to be resolved at its own instant, not at today's offset. `lastAt` is an epoch
+ timestamp and the slot arrives as a wall clock reading, and twice a year the zone moves in
+ between: on the fall-back Sunday, last Sunday's 18:00 read with today's offset lands an hour
+ late, which makes the week's review due at ten in the morning — and then due again at six,
+ so the week gets two of them. */
+const dueIn = (t, tz, at, lastReviewAt) => {
+ t.mock.timers.enable({ apis: ['Date'], now: at });
+ try { return isDue(coach(lastReviewAt), state(lastReviewAt), wallClockIn(tz, at), 0, tz); }
+ finally { t.mock.timers.reset(); }
+};
+
+test('the clocks going back does not make the week\'s review due eight hours early', t => {
+ const TZ = 'America/New_York'; // EDT (−4) until Sun 1 Nov 2026 02:00
+ const ranLastWeek = Date.UTC(2026, 9, 25, 22, 0); // Sun 25 Oct 18:00 EDT — the slot before
+
+ assert.equal(dueIn(t, TZ, Date.UTC(2026, 10, 1, 15, 0), ranLastWeek), false,
+ '10:00 EST on the fall-back Sunday: the slot is eight hours away, and it used to read due');
+ assert.equal(dueIn(t, TZ, Date.UTC(2026, 10, 1, 22, 59), ranLastWeek), false, '17:59 EST, a minute early');
+ assert.equal(dueIn(t, TZ, Date.UTC(2026, 10, 1, 23, 1), ranLastWeek), true, "18:01 EST: this week's slot has passed");
+
+ // And the hour is not lost on the way back either: at 18:01 EST, a review that already ran
+ // this week (at its slot, 23:00 UTC) is not due again.
+ assert.equal(dueIn(t, TZ, Date.UTC(2026, 10, 1, 23, 1), Date.UTC(2026, 10, 1, 23, 0) + 1000), false);
+});
+
+test('the clocks going forward are unchanged', t => {
+ const TZ = 'America/New_York'; // EST (−5) until Sun 8 Mar 2026 02:00
+ const ranLastWeek = Date.UTC(2026, 2, 1, 23, 0); // Sun 1 Mar 18:00 EST
+
+ assert.equal(dueIn(t, TZ, Date.UTC(2026, 2, 8, 21, 59), ranLastWeek), false, '17:59 EDT, a minute early');
+ assert.equal(dueIn(t, TZ, Date.UTC(2026, 2, 8, 22, 1), ranLastWeek), true, "18:01 EDT: this week's slot");
+ assert.equal(dueIn(t, TZ, Date.UTC(2026, 2, 8, 22, 30), ranLastWeek), true, 'and still due half an hour later');
+});
+
+test('a zone that never moves is unaffected', t => {
+ const TZ = 'Asia/Tokyo'; // no DST, ever
+ const ranLastWeek = Date.UTC(2026, 8, 13, 9, 0); // Sun 13 Sep 18:00 JST
+
+ assert.equal(dueIn(t, TZ, Date.UTC(2026, 8, 20, 8, 59), ranLastWeek), false, '17:59 JST');
+ assert.equal(dueIn(t, TZ, Date.UTC(2026, 8, 20, 9, 1), ranLastWeek), true, '18:01 JST');
+ // A caller with no zone to give falls back to the offset at the wall clock it did give, which
+ // is all this had to go on before. In a zone that never moves the two agree by definition.
+ // (The tick never reaches here without a zone: userNow returns null for one Intl refuses, and
+ // isDue skips a profile with no `now` at all.)
+ const at = Date.UTC(2026, 8, 20, 9, 1);
+ t.mock.timers.enable({ apis: ['Date'], now: at });
+ t.after(() => t.mock.timers.reset());
+ assert.equal(isDue(coach(ranLastWeek), state(ranLastWeek), wallClockIn(TZ, at), 0), true);
+});