@amenophis1er/foreman 0.1.16 → 0.1.17

package/src/notify.test.ts

@@ -123,6 +123,67 @@ test('a transport that throws costs a failure count, never an exception on the e
   assert.equal(hub.delivered, 0);
 });
 
+test('a paused schedule says which one and why, and is gated by its cause', () => {
+  const c = ctx()();
+  const cap = shape(env('schedule_paused', { scheduleId: 's1', name: 'nightly deps', reason: 'monthly-cap' }), c)!;
+  assert.equal(cap.key, 'schedule:s1');
+  assert.equal(cap.gate, 'budget', 'the monthly ceiling is a spending guard');
+  assert.match(cap.text, /nightly deps/);
+  assert.match(cap.text, /this month's scheduled spend would go past the ceiling|this month's scheduled spend would go past the ceiling/);
+
+  const fail = shape(env('schedule_paused', { scheduleId: 's1', name: 'nightly deps', reason: 'failures' }), c)!;
+  assert.equal(fail.key, 'schedule:s1');
+  assert.equal(fail.gate, 'needsYou', 'only a human can resume it');
+  assert.match(fail.text, /two scheduled runs in a row failed/);
+
+  // Resuming is deliberately a dashboard act, so there is nothing to tap.
+  for (const s of [cap, fail]) {
+    assert.match(s.text, /Resume it from the Foreman dashboard/);
+    assert.equal(s.buttons, undefined);
+  }
+});
+
+test('an unknown pause reason still shapes, and does not throw', () => {
+  const c = ctx()();
+  assert.doesNotThrow(() => shape(env('schedule_paused', { scheduleId: 's1', name: 'nightly deps', reason: 'kaput' }), c));
+  const s = shape(env('schedule_paused', { scheduleId: 's1', name: 'nightly deps', reason: 'kaput' }), c)!;
+  assert.equal(s.key, 'schedule:s1');
+  assert.equal(s.gate, 'done');
+  assert.match(s.text, /nightly deps/);
+  assert.doesNotThrow(() => shape(env('schedule_skipped', { scheduleId: 's1', name: 'nightly deps', reason: 'moon phase' }), c));
+});
+
+test('a skipped scheduled run is informational, and consecutive skips are not deduped', () => {
+  const c = ctx()();
+  const s = shape(env('schedule_skipped', { scheduleId: 's1', name: 'nightly deps', reason: 'project busy' }), c)!;
+  assert.equal(s.gate, 'done');
+  assert.equal(s.key, 'skip:s1:1000000');
+  assert.match(s.text, /nightly deps/);
+  assert.match(s.text, /already had a mission running/);
+  assert.match(s.text, /next scheduled run stands/);
+  // Like a stall, the timestamp is in the key so tonight's skip is not
+  // swallowed by last night's.
+  const later = shape(env('schedule_skipped', { scheduleId: 's1', name: 'nightly deps', reason: 'project busy' }, { ts: 1_000_500 }), c)!;
+  assert.notEqual(later.key, s.key);
+});
+
+test('a scheduled run says nobody pressed start; an ordinary one reads exactly as before', () => {
+  const c = ctx()();
+  const plain = shape(env('run_finished', { status: 'done' }), c)!;
+  assert.equal(plain.text,
+    '<b>Mission done</b> · shop\n<i>Build the checkout page</i>' +
+    '\n<a href="http://box.local:4177/#/p/p1/r/r1">Open in Foreman</a>');
+
+  const sched = shape(env('run_finished', { status: 'done', scheduled: true, scheduleName: 'nightly deps' }), c)!;
+  assert.equal(sched.key, plain.key, 'same key, so it still edits and dedupes as before');
+  assert.equal(sched.gate, plain.gate);
+  assert.match(sched.text, /Mission done · scheduled · nightly deps/);
+
+  // Without a name it still marks itself as unattended.
+  const anon = shape(env('run_finished', { status: 'error', scheduled: true }), c)!;
+  assert.match(anon.text, /Mission failed · scheduled/);
+});
+
 // ---------------------------------------------------------------------------
 // Telegram, against a stub of the Bot API
 // ---------------------------------------------------------------------------

package/src/notify.ts

@@ -260,12 +260,56 @@ export function shape(env: Envelope, ctx: NotifyContext): Shaped | null {
     case 'run_finished': {
       const status = String(d.status ?? 'done');
       const title = status === 'done' ? 'Mission done' : status === 'error' ? 'Mission failed' : 'Mission interrupted';
+      // A scheduled run says so in its title: nobody pressed start, so the
+      // first question a phone raises — "who did this?" — is already answered.
+      const sched = d.scheduled
+        ? ` · scheduled${d.scheduleName ? ` · ${clip(d.scheduleName, 40)}` : ''}`
+        : '';
       return { key: `finished:${env.runId}`, gate: 'done',
-        text: `${head(title)}${runLine}${foot}` };
+        text: `${head(title + sched)}${runLine}${foot}` };
     }
     case 'run_error':
       return { key: `error:${env.runId}:${env.ts ?? ''}`, gate: 'done',
         text: `${head('Mission error')}${runLine}\n${esc(clip(d.error))}${foot}` };
+
+    // --- scheduled missions -------------------------------------------
+    case 'schedule_paused': {
+      // A paused schedule is the one thing here that stays broken until
+      // someone acts, so it says why in plain words. Which toggle carries it
+      // follows the cause: the monthly ceiling is a spending guard, repeated
+      // failures are a thing only a human can clear. Anything else — a hand
+      // on the switch — is news, not a summons.
+      const reason = String(d.reason ?? '');
+      const gate: keyof NotifyPrefs = reason === 'monthly-cap' ? 'budget' : reason === 'failures' ? 'needsYou' : 'done';
+      const why = reason === 'failures'
+        ? 'two scheduled runs in a row failed'
+        : reason === 'monthly-cap'
+          ? "this month's scheduled spend would go past the ceiling"
+          : reason === 'human'
+            ? 'you paused it'
+            : `paused${reason ? ` — ${esc(clip(reason, 60))}` : ''}`;
+      return {
+        key: `schedule:${d.scheduleId}`, gate,
+        // No buttons on purpose: resuming a schedule is a dashboard act, where
+        // the cadence, the caps and what it last did are all in view.
+        text: `${head('Schedule paused')}\n<b>${esc(clip(d.name, 60))}</b> — ${why}.` +
+          `\n<i>Resume it from the Foreman dashboard; there is no resume from here.</i>${foot}`,
+      };
+    }
+    case 'schedule_skipped': {
+      // Nothing is wrong and nothing is owed: the cadence simply stepped over
+      // a busy project. Keyed by timestamp like a stall, so a run of skips
+      // reads as a run of skips rather than one deduped line.
+      const reason = String(d.reason ?? '');
+      const why = reason === 'project busy'
+        ? 'the project already had a mission running, so this turn was not started'
+        : `not started${reason ? ` — ${esc(clip(reason, 60))}` : ''}`;
+      return {
+        key: `skip:${d.scheduleId}:${env.ts ?? ''}`, gate: 'done',
+        text: `${head('Scheduled run skipped')}\n<b>${esc(clip(d.name, 60))}</b> — ${why}.` +
+          `\n<i>The next scheduled run stands.</i>${foot}`,
+      };
+    }
     default:
       return null;
   }

package/src/schedule-guards.test.ts

@@ -0,0 +1,236 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import type { Schedule } from './types.js';
+import {
+  DEFAULT_SCHEDULED_MONTHLY_CAP_USD,
+  monthlyScheduledSpend,
+  isFailedOutcome,
+  afterRunOutcome,
+  decideTicks,
+  type TickAction,
+} from './schedule-guards.js';
+
+/** Local time, because months and cadences are both local here. */
+const at = (y: number, m: number, d: number, h = 0, min = 0) => new Date(y, m, d, h, min, 0, 0);
+
+/** A run row as monthlyScheduledSpend sees one. */
+function run(over: Partial<{ projectId: string; scheduleId: string; createdAt: number; costUsd: number }> = {}) {
+  return { projectId: 'p1', scheduleId: 's1', createdAt: at(2026, 4, 10, 3).getTime(), costUsd: 1, ...over };
+}
+
+/** A schedule, due at `nextRunAt`, with only the fields the ticker reads. */
+function schedule(over: Partial<Schedule> = {}): Schedule {
+  return {
+    id: 's1', projectId: 'p1', name: 'nightly', brief: 'tidy up',
+    cadence: { kind: 'daily', at: '03:00' },
+    budgetUsd: 5,
+    enabled: true,
+    createdAt: at(2026, 0, 1).getTime(),
+    nextRunAt: at(2026, 4, 10, 3).getTime(),
+    consecutiveFailures: 0,
+    pausedReason: null,
+    ...over,
+  };
+}
+
+/** decideTicks with the plumbing filled in; NOW is 2026-05-10 09:00 local. */
+const NOW = at(2026, 4, 10, 9);
+function decide(schedules: Schedule[], over: Partial<Parameters<typeof decideTicks>[0]> = {}): TickAction[] {
+  return decideTicks({
+    schedules,
+    now: NOW,
+    busyProjectIds: [],
+    monthSpend: {},
+    capFor: () => DEFAULT_SCHEDULED_MONTHLY_CAP_USD,
+    ...over,
+  });
+}
+
+test('monthlyScheduledSpend: only this project\'s scheduled runs, only this month', () => {
+  const now = at(2026, 4, 20, 12);
+  const runs = [
+    run({ costUsd: 3 }),
+    run({ costUsd: 4, scheduleId: 's2' }),
+    // A hand-started mission spends the human's attention, not the allowance.
+    run({ costUsd: 100, scheduleId: undefined }),
+    // Another project's schedule, and a run with no project at all.
+    run({ costUsd: 100, projectId: 'p2' }),
+    run({ costUsd: 100, projectId: undefined }),
+    // Last month, and next month.
+    run({ costUsd: 100, createdAt: at(2026, 3, 30, 23, 59).getTime() }),
+    run({ costUsd: 100, createdAt: at(2026, 5, 1, 0, 0).getTime() }),
+  ];
+  assert.equal(monthlyScheduledSpend(runs, 'p1', now), 7);
+  assert.equal(monthlyScheduledSpend(runs, 'p2', now), 100);
+  assert.equal(monthlyScheduledSpend([], 'p1', now), 0);
+});
+
+test('monthlyScheduledSpend: the month boundary is local midnight, and December rolls to January', () => {
+  // The last minute of April and the first of May are different months even
+  // though they are a minute apart.
+  const april = [run({ costUsd: 2, createdAt: at(2026, 3, 30, 23, 59).getTime() })];
+  const may = [run({ costUsd: 2, createdAt: at(2026, 4, 1, 0, 0).getTime() })];
+  assert.equal(monthlyScheduledSpend(april, 'p1', at(2026, 3, 15)), 2);
+  assert.equal(monthlyScheduledSpend(april, 'p1', at(2026, 4, 15)), 0);
+  assert.equal(monthlyScheduledSpend(may, 'p1', at(2026, 4, 15)), 2);
+  assert.equal(monthlyScheduledSpend(may, 'p1', at(2026, 3, 15)), 0);
+
+  // December 2026 and January 2027 are both "month 0-ish" traps: the same
+  // month number, or the same year, is not the same month.
+  const dec = run({ costUsd: 6, createdAt: at(2026, 11, 31, 23, 30).getTime() });
+  const jan = run({ costUsd: 9, createdAt: at(2027, 0, 1, 0, 30).getTime() });
+  assert.equal(monthlyScheduledSpend([dec, jan], 'p1', at(2026, 11, 31, 23, 59)), 6);
+  assert.equal(monthlyScheduledSpend([dec, jan], 'p1', at(2027, 0, 2)), 9);
+  // Same month number, previous year: not this month.
+  assert.equal(monthlyScheduledSpend([run({ costUsd: 5, createdAt: at(2025, 4, 10).getTime() })], 'p1', at(2026, 4, 10)), 0);
+});
+
+test('isFailedOutcome: errors and capped interruptions, not restarts', () => {
+  assert.equal(isFailedOutcome({ status: 'error' }), true);
+  assert.equal(isFailedOutcome({ status: 'interrupted', stopReason: 'budget' }), true);
+  assert.equal(isFailedOutcome({ status: 'interrupted', stopReason: 'turns' }), true);
+  assert.equal(isFailedOutcome({ status: 'interrupted', stopReason: 'time' }), true);
+  assert.equal(isFailedOutcome({ status: 'interrupted', stopReason: 'tokens' }), true);
+  // A sweep on startup leaves no stopReason: the server restarted, the
+  // schedule did nothing wrong.
+  assert.equal(isFailedOutcome({ status: 'interrupted' }), false);
+  assert.equal(isFailedOutcome({ status: 'interrupted', stopReason: null }), false);
+  assert.equal(isFailedOutcome({ status: 'done' }), false);
+  assert.equal(isFailedOutcome({ status: 'running' }), false);
+});
+
+test('afterRunOutcome: two failures in a row pause, a success resets', () => {
+  const fresh = { consecutiveFailures: 0, pausedReason: null } as const;
+  const once = afterRunOutcome(fresh, { status: 'error' });
+  assert.deepEqual(once, { consecutiveFailures: 1, pausedReason: null, pausedNow: false });
+
+  const twice = afterRunOutcome({ consecutiveFailures: 1, pausedReason: null }, { status: 'interrupted', stopReason: 'budget' });
+  assert.deepEqual(twice, { consecutiveFailures: 2, pausedReason: 'failures', pausedNow: true });
+
+  // A done run clears the count before it ever reaches two.
+  assert.deepEqual(
+    afterRunOutcome({ consecutiveFailures: 1, pausedReason: null }, { status: 'done' }),
+    { consecutiveFailures: 0, pausedReason: null, pausedNow: false },
+  );
+  // A restart is not a failure, so it does not count towards the pause.
+  assert.deepEqual(
+    afterRunOutcome({ consecutiveFailures: 1, pausedReason: null }, { status: 'interrupted' }),
+    { consecutiveFailures: 0, pausedReason: null, pausedNow: false },
+  );
+});
+
+test('afterRunOutcome: does not un-pause, and does not re-report a pause it did not cause', () => {
+  // A schedule the human stopped, or one the monthly cap stopped, stays
+  // stopped until they resume it — a stray success is not consent.
+  for (const reason of ['human', 'monthly-cap', 'failures'] as const) {
+    assert.deepEqual(
+      afterRunOutcome({ consecutiveFailures: 0, pausedReason: reason }, { status: 'done' }),
+      { consecutiveFailures: 0, pausedReason: reason, pausedNow: false },
+    );
+    assert.deepEqual(
+      afterRunOutcome({ consecutiveFailures: 3, pausedReason: reason }, { status: 'error' }),
+      { consecutiveFailures: 4, pausedReason: reason, pausedNow: false },
+    );
+  }
+});
+
+test('decideTicks: nothing to do for schedules that are not due, disabled or paused', () => {
+  assert.deepEqual(decide([schedule({ nextRunAt: at(2026, 4, 11, 3).getTime() })]), []);
+  assert.deepEqual(decide([schedule({ nextRunAt: null })]), []);
+  assert.deepEqual(decide([schedule({ enabled: false })]), []);
+  for (const reason of ['failures', 'monthly-cap', 'human'] as const) {
+    assert.deepEqual(decide([schedule({ pausedReason: reason })]), []);
+  }
+});
+
+test('decideTicks: a due schedule starts, and its next firing is after now', () => {
+  const actions = decide([schedule()]);
+  assert.equal(actions.length, 1);
+  const a = actions[0];
+  assert.equal(a.kind, 'start');
+  assert.equal(a.scheduleId, 's1');
+  assert.equal(a.kind === 'start' && a.at, NOW.getTime());
+  // Daily 03:00 from 09:00 today is 03:00 tomorrow.
+  assert.equal(a.nextRunAt, at(2026, 4, 11, 3).getTime());
+});
+
+test('decideTicks: a busy project misses the mission rather than queueing it', () => {
+  const busy = decide([schedule()], { busyProjectIds: new Set(['p1']) });
+  assert.deepEqual(busy, [{ kind: 'skip', scheduleId: 's1', reason: 'project busy', nextRunAt: at(2026, 4, 11, 3).getTime() }]);
+  // The array form of busyProjectIds says the same thing.
+  assert.deepEqual(decide([schedule()], { busyProjectIds: ['p1'] }), busy);
+  // Another project being busy is not this one's problem.
+  assert.equal(decide([schedule()], { busyProjectIds: ['p2'] })[0].kind, 'start');
+});
+
+test('decideTicks: catch-up happens once, however long Foreman was down', () => {
+  // A schedule whose slot was three months ago fires once now and then goes
+  // back to its cadence — the next firing is computed from now, not from the
+  // 90 missed 03:00s.
+  const stale = schedule({ nextRunAt: at(2026, 1, 4, 3).getTime() });
+  const [start] = decide([stale]);
+  assert.equal(start.kind, 'start');
+  assert.equal(start.nextRunAt, at(2026, 4, 11, 3).getTime());
+
+  // Same for a skip: the missed slot does not linger in the past waiting to
+  // fire again on the next pass.
+  const [skip] = decide([stale], { busyProjectIds: ['p1'] });
+  assert.equal(skip.kind, 'skip');
+  assert.ok(skip.nextRunAt !== null && skip.nextRunAt > NOW.getTime());
+});
+
+test('decideTicks: the monthly ceiling pauses, and equal to the cap is still allowed', () => {
+  const s = schedule({ budgetUsd: 5 });
+  // 20 spent + 5 budget = 25 = the cap: allowed, the rule is strictly past it.
+  assert.equal(decide([s], { monthSpend: { p1: 20 } })[0].kind, 'start');
+  // A cent more and the run would cross it.
+  assert.deepEqual(decide([s], { monthSpend: { p1: 20.01 } }), [
+    { kind: 'pause', scheduleId: 's1', reason: 'monthly-cap', spent: 20.01, cap: 25 },
+  ]);
+  // The Map form says the same thing, and a pause does not advance the next
+  // firing: a human resumes it and gets a fresh next time.
+  const paused = decide([s], { monthSpend: new Map([['p1', 30]]) });
+  assert.deepEqual(paused, [{ kind: 'pause', scheduleId: 's1', reason: 'monthly-cap', spent: 30, cap: 25 }]);
+  assert.ok(!('nextRunAt' in paused[0]));
+  // The ceiling is per project, and capFor decides it.
+  assert.equal(decide([s], { monthSpend: { p1: 30 }, capFor: () => 100 })[0].kind, 'start');
+});
+
+test('decideTicks: one start per project, earliest due first, and the start charges the month', () => {
+  const early = schedule({ id: 's-early', nextRunAt: at(2026, 4, 10, 3).getTime(), createdAt: 200 });
+  const late = schedule({ id: 's-late', nextRunAt: at(2026, 4, 10, 7).getTime(), createdAt: 100 });
+  // Given in the wrong order on purpose: due time decides, not array order.
+  const actions = decide([late, early]);
+  assert.deepEqual(actions.map((a) => [a.kind, a.scheduleId]), [['start', 's-early'], ['skip', 's-late']]);
+  assert.equal(actions[1].kind === 'skip' && actions[1].reason, 'project busy');
+
+  // Due at the same moment: the older schedule wins, so a later-created
+  // neighbour cannot starve it night after night.
+  const tie = decide([
+    schedule({ id: 's-new', createdAt: 999 }),
+    schedule({ id: 's-old', createdAt: 1 }),
+  ]);
+  assert.deepEqual(tie.map((a) => [a.kind, a.scheduleId]), [['start', 's-old'], ['skip', 's-new']]);
+
+  // Different projects: both start, each on its own allowance.
+  const two = decide([schedule({ id: 'a', projectId: 'p1' }), schedule({ id: 'b', projectId: 'p2' })]);
+  assert.deepEqual(two.map((a) => a.kind), ['start', 'start']);
+
+  // A start charges the project's month straight away, so no second schedule
+  // can slip under the ceiling by being decided in the same pass. Here 24
+  // spent leaves room for exactly one $1 run: the first takes it, and the
+  // second is turned away — as busy, because one mission per project is the
+  // stricter rule and it is checked first.
+  const cheap = [
+    schedule({ id: 'a', projectId: 'p1', budgetUsd: 1, createdAt: 1 }),
+    schedule({ id: 'b', projectId: 'p1', budgetUsd: 1, createdAt: 2 }),
+  ];
+  const charged = decide(cheap, { monthSpend: { p1: 24 } });
+  assert.deepEqual(charged.map((a) => [a.kind, a.scheduleId]), [['start', 'a'], ['skip', 'b']]);
+  assert.equal(charged[1].kind === 'skip' && charged[1].reason, 'project busy');
+  // Nothing started, so nothing is charged: both are judged against the same
+  // spend, and the ceiling is what turns them away once the project is free.
+  const none = decide(cheap, { monthSpend: { p1: 24.5 }, busyProjectIds: ['p1'] });
+  assert.deepEqual(none.map((a) => a.kind), ['skip', 'skip']);
+  assert.deepEqual(decide([cheap[0]], { monthSpend: { p1: 24.5 } }).map((a) => a.kind), ['pause']);
+});

package/src/schedule-guards.ts

@@ -0,0 +1,149 @@
+/**
+ * The rules a scheduled mission has to get past before it spends anything.
+ *
+ * A schedule fires while nobody is watching, which is the whole point and also
+ * the whole danger: a mission that fails at 03:00 will fail again at 03:00
+ * tomorrow, and a cadence that costs $3 a firing costs $90 a month if nothing
+ * counts. So the ticker asks four questions every pass — is it due, is the
+ * project free, has it been failing, and can the project still afford it — and
+ * every one of those answers lives here rather than in the server.
+ *
+ * The point of the separation is testability: src/server.ts starts listening
+ * on import, so nothing that imports it can be a unit test. These functions
+ * take the world as arguments and return decisions; the server is left with
+ * the doing.
+ */
+import type { Schedule } from './types.js';
+import { nextRunAt } from './schedule.js';
+
+/** Default ceiling on what a project's SCHEDULED runs may cost in one calendar month. */
+export const DEFAULT_SCHEDULED_MONTHLY_CAP_USD = 25;
+
+/**
+ * What this project's scheduled runs have cost so far this calendar month.
+ * Months are local, matching the local-time cadences: an operator who says
+ * "every night at 2am" means their nights, and their month rolls over on their
+ * midnight. Only runs with a scheduleId count; a hand-started mission spends
+ * the human's attention, not the schedule's allowance.
+ */
+export function monthlyScheduledSpend(
+  runs: Array<{ projectId?: string; scheduleId?: string; createdAt: number; costUsd: number }>,
+  projectId: string,
+  now: Date,
+): number {
+  const year = now.getFullYear();
+  const month = now.getMonth();
+  let total = 0;
+  for (const run of runs) {
+    if (!run.scheduleId || run.projectId !== projectId) continue;
+    const at = new Date(run.createdAt);
+    if (at.getFullYear() !== year || at.getMonth() !== month) continue;
+    total += run.costUsd;
+  }
+  return total;
+}
+
+/**
+ * Did this scheduled run fail for the purposes of the failure pause? — status
+ * 'error', or 'interrupted' with a stopReason (budget/turns/time/tokens). An
+ * interruption with no stopReason is a server restart sweeping its orphans,
+ * not the schedule's fault, and pausing a schedule for that would mean a
+ * reboot silently switches off the operator's nightly missions.
+ */
+export function isFailedOutcome(run: { status: string; stopReason?: string | null }): boolean {
+  if (run.status === 'error') return true;
+  return run.status === 'interrupted' && !!run.stopReason;
+}
+
+/**
+ * The schedule's failure bookkeeping after one of its runs ended. Two
+ * consecutive failures pause it: once is a bad night, twice is a standing
+ * instruction that no longer works, and there is nobody awake to notice the
+ * third. A 'done' resets the count but does not un-pause — a schedule stopped
+ * for the monthly cap or by a human stays stopped until they say otherwise.
+ */
+export function afterRunOutcome(
+  schedule: Pick<Schedule, 'consecutiveFailures' | 'pausedReason'>,
+  run: { status: string; stopReason?: string | null },
+): { consecutiveFailures: number; pausedReason: Schedule['pausedReason']; pausedNow: boolean } {
+  if (!isFailedOutcome(run)) {
+    return { consecutiveFailures: 0, pausedReason: schedule.pausedReason, pausedNow: false };
+  }
+  const consecutiveFailures = schedule.consecutiveFailures + 1;
+  const pausedNow = schedule.pausedReason === null && consecutiveFailures >= 2;
+  return {
+    consecutiveFailures,
+    pausedReason: pausedNow ? 'failures' : schedule.pausedReason,
+    pausedNow,
+  };
+}
+
+export type TickAction =
+  | { kind: 'start'; scheduleId: string; at: number; nextRunAt: number | null }
+  | { kind: 'skip'; scheduleId: string; reason: string; nextRunAt: number | null }
+  | { kind: 'pause'; scheduleId: string; reason: 'monthly-cap'; spent: number; cap: number };
+
+/**
+ * What the ticker should do this pass. Pure: give it the world, it returns the
+ * decisions; the server performs them.
+ */
+export function decideTicks(input: {
+  schedules: Schedule[];
+  now: Date;
+  /** Projects that already have an active mission (reserveProject would fail). */
+  busyProjectIds: Set<string> | string[];
+  /** This month's scheduled spend per project id. */
+  monthSpend: Map<string, number> | Record<string, number>;
+  /** The project's monthly ceiling for scheduled runs. */
+  capFor: (projectId: string) => number;
+}): TickAction[] {
+  const nowMs = input.now.getTime();
+  // Copies, because a start in this pass has to be visible to the schedules
+  // decided after it.
+  const busy = new Set(input.busyProjectIds);
+  const spend = input.monthSpend instanceof Map
+    ? new Map(input.monthSpend)
+    : new Map(Object.entries(input.monthSpend));
+
+  // Earliest due first, tie-broken on createdAt, so that when two schedules in
+  // one project come due together the older one starts and the newer one is
+  // the one that waits. Without an order the array's order would decide, and a
+  // schedule could be starved every night by a later-created neighbour.
+  const due = input.schedules
+    .filter((s) => s.enabled && s.pausedReason === null && s.nextRunAt !== null && s.nextRunAt <= nowMs)
+    .sort((a, b) => (a.nextRunAt! - b.nextRunAt!) || (a.createdAt - b.createdAt) || a.id.localeCompare(b.id));
+
+  // The next firing is computed from `now`, never from the slot that was
+  // missed. That is why this function takes `now` at all: if the machine was
+  // asleep for a week, the schedule fires once on waking and then goes back to
+  // its cadence — a missed mission is missed, not queued, and catch-up happens
+  // at most once per schedule however long Foreman was down.
+  const advance = (s: Schedule): number | null => {
+    const next = nextRunAt(s.cadence, input.now);
+    return next ? next.getTime() : null;
+  };
+
+  const actions: TickAction[] = [];
+  for (const s of due) {
+    if (busy.has(s.projectId)) {
+      actions.push({ kind: 'skip', scheduleId: s.id, reason: 'project busy', nextRunAt: advance(s) });
+      continue;
+    }
+    const spent = spend.get(s.projectId) ?? 0;
+    const cap = input.capFor(s.projectId);
+    if (spent + s.budgetUsd > cap) {
+      // No advance: a paused schedule is resumed by a human, who then gets a
+      // fresh next time. Leaving nextRunAt in the past would make it fire the
+      // instant it came back.
+      actions.push({ kind: 'pause', scheduleId: s.id, reason: 'monthly-cap', spent, cap });
+      continue;
+    }
+    actions.push({ kind: 'start', scheduleId: s.id, at: nowMs, nextRunAt: advance(s) });
+    // One active mission per project: this project is now taken for the rest
+    // of the pass, and its month spend is charged straight away so a second
+    // schedule cannot slip under the ceiling by being decided in the same tick.
+    busy.add(s.projectId);
+    spend.set(s.projectId, spent + s.budgetUsd);
+  }
+  return actions;
+}