@amenophis1er/foreman 0.1.16 → 0.1.18

package/src/run-crew.test.ts

@@ -0,0 +1,99 @@
+/**
+ * The run side of crew presets: what dispatch freezes onto a record, and what
+ * a report says about the verdicts it collected.
+ *
+ * The freeze test is the one that matters. It runs the server's own pipeline —
+ * a settings blob, the overlay, the chosen ids — and then does the thing the
+ * whole design exists to survive: it edits the preset afterwards.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { crewPresetsFrom, type CrewPreset, type ReviewVerdict } from './crew.js';
+import { frozenCrewFor, reviewReportLines } from './run-crew.js';
+
+/** What store.readSettings() hands effectiveSettings(), for one project. */
+function settings(): { global: Record<string, unknown>; project: Record<string, unknown> } {
+  return {
+    global: {
+      crewPresets: [
+        { id: 'reviewer', name: 'Reviewer', kind: 'reviewer', brief: 'Review it.', requiredForDone: true, model: 'opus' },
+        { id: 'perf', name: 'Performance', kind: 'reviewer', brief: 'Look at the hot paths.', requiredForDone: false },
+      ],
+    },
+    project: {},
+  };
+}
+
+test('the freeze holds: editing a preset afterwards does not change a past run', () => {
+  const s = settings();
+  // What the server does at dispatch, in the order it does it.
+  const presets = crewPresetsFrom(s.global, s.project);
+  const run: { crew?: CrewPreset[] } = {};
+  const crew = frozenCrewFor(presets, ['reviewer']);
+  if (crew) run.crew = crew;
+  assert.deepEqual(run.crew, [{ id: 'reviewer', name: 'Reviewer', kind: 'reviewer', brief: 'Review it.', requiredForDone: true, model: 'opus' }]);
+
+  // Next week, the human edits the preset in Settings: a different brief, and
+  // the reviewer no longer blocks a run.
+  const source = (s.global.crewPresets as Array<Record<string, unknown>>)[0];
+  source.brief = 'Something else entirely.';
+  source.requiredForDone = false;
+  source.name = 'Renamed';
+  // And the list handed out after the edit is a different list, mutated too.
+  for (const p of presets) { p.brief = 'mutated'; p.requiredForDone = false; }
+
+  assert.equal(run.crew![0].brief, 'Review it.', 'the run keeps the brief it was reviewed against');
+  assert.equal(run.crew![0].requiredForDone, true, 'and the gate it started under');
+  assert.equal(run.crew![0].name, 'Reviewer');
+});
+
+test('crewPresetsFrom overlay: the project replaces the global list whole', () => {
+  const s = settings();
+  s.project.crewPresets = [{ id: 'local', name: 'House reviewer', kind: 'reviewer', brief: 'ours', requiredForDone: true }];
+  assert.deepEqual(crewPresetsFrom(s.global, s.project).map((p) => p.id), ['local']);
+  assert.deepEqual(crewPresetsFrom(s.global, {}).map((p) => p.id), ['reviewer', 'perf']);
+  // The human emptied the project's list: no crew here, not the global one back.
+  assert.deepEqual(crewPresetsFrom(s.global, { crewPresets: [] }), []);
+});
+
+test('frozenCrewFor: nothing chosen leaves the field absent', () => {
+  const presets = crewPresetsFrom(settings().global, {});
+  assert.equal(frozenCrewFor(presets, undefined), undefined);
+  assert.equal(frozenCrewFor(presets, []), undefined);
+  // Only ids nobody has a preset for: still nothing to freeze.
+  assert.equal(frozenCrewFor(presets, ['ghost', '  ']), undefined);
+  assert.deepEqual(frozenCrewFor(presets, ['perf', 'ghost'])?.map((p) => p.id), ['perf']);
+});
+
+const verdict = (over: Partial<ReviewVerdict>): ReviewVerdict => ({
+  presetId: 'reviewer', name: 'Reviewer', pass: true, findings: '', diffHash: 'h1', workerId: 'w1', at: 1, ...over,
+});
+const required = (over: Partial<CrewPreset> = {}): CrewPreset =>
+  ({ id: 'reviewer', name: 'Reviewer', kind: 'reviewer', brief: '', requiredForDone: true, ...over });
+
+test('reviewReportLines: the verdicts, priced when the run was', () => {
+  assert.deepEqual(reviewReportLines([required()], [verdict({ costUsd: 0.42 })]), ['reviews: Reviewer PASS · $0.42']);
+  assert.deepEqual(
+    reviewReportLines([required()], [verdict({ pass: false })]),
+    ['reviews: Reviewer FAIL', '  Reviewer is required for this run to be done and returned FAIL.'],
+  );
+  // Nothing to say about a run that had no crew and collected no verdicts.
+  assert.deepEqual(reviewReportLines(undefined, undefined), []);
+});
+
+test('reviewReportLines: a required reviewer that never ran is named', () => {
+  assert.deepEqual(reviewReportLines([required(), { ...required({ id: 'perf', name: 'Performance' }), requiredForDone: false }], []),
+    ['  Reviewer is required for this run to be done and has not reviewed it.']);
+});
+
+test('reviewReportLines: staleness is claimed only where the diff hash is known', () => {
+  const crew = [required()];
+  const passed = [verdict({ diffHash: 'old' })];
+  // No hash: the report says what the record holds and claims nothing more.
+  assert.deepEqual(reviewReportLines(crew, passed), ['reviews: Reviewer PASS']);
+  assert.deepEqual(reviewReportLines(crew, passed, 'new'), [
+    'reviews: Reviewer PASS',
+    '  Reviewer passed an earlier version of the diff; the code changed after it.',
+  ]);
+  assert.deepEqual(reviewReportLines(crew, passed, 'old'), ['reviews: Reviewer PASS']);
+});

package/src/run-crew.ts

@@ -0,0 +1,101 @@
+/**
+ * The crew as a *run* sees it: what gets frozen onto the record at dispatch,
+ * and how the verdicts it collected read back in a report.
+ *
+ * Both halves are here rather than in crew.ts because crew.ts is the rules —
+ * what a preset is, and what blocks a run — while these are the two places
+ * Foreman's own surfaces touch them: server.ts freezing at dispatch, and
+ * server.ts and mcp.ts writing the same lines to the phone and to MCP. Two
+ * surfaces printing verdicts two different ways is how "PASS" comes to mean
+ * something slightly different depending on where you read it.
+ */
+import { freezeCrew, reviewBlockers, type CrewPreset, type ReviewVerdict } from './crew.js';
+
+/**
+ * The crew to freeze onto a new run, or undefined when there is none.
+ *
+ * undefined rather than [] on purpose: an absent field is how every run
+ * recorded before presets existed reads, and a run dispatched with no crew is
+ * that same run. Unknown ids fall away silently — freezeCrew resolves against
+ * the presets actually in force, so an id from a preset the human has since
+ * deleted cannot conjure a reviewer that no longer exists.
+ */
+export function frozenCrewFor(
+  presets: readonly CrewPreset[],
+  ids: readonly string[] | undefined,
+): CrewPreset[] | undefined {
+  if (!Array.isArray(ids) || ids.length === 0) return undefined;
+  const clean = ids.filter((id): id is string => typeof id === 'string' && id.trim() !== '');
+  const crew = freezeCrew(clean, presets);
+  return crew.length ? crew : undefined;
+}
+
+/**
+ * The reviewers whose PASS this finished run is entitled to wear, or [] .
+ *
+ * Derived here and sent as a name list rather than shipping `reviews` into the
+ * fleet's projection, because that projection exists to stay small: it is
+ * re-polled every few seconds for every project, and a verdict's findings run
+ * to thousands of characters that a tile never renders. The tile asks one
+ * question — "did the required reviewers pass?" — so it is handed the answer.
+ *
+ * Only a run Foreman actually recorded `done` qualifies, and that is what
+ * makes staleness answerable from a record alone: the end-of-run gate refuses
+ * `done` unless every required PASS was pinned to the diff the run ended with,
+ * so a `done` run with all its required verdicts passing was current when it
+ * mattered. Anything else gets no mark rather than a mark that might be a lie.
+ */
+export function reviewedByNames(run: {
+  status: string;
+  crew?: readonly CrewPreset[];
+  reviews?: readonly ReviewVerdict[];
+}): string[] {
+  if (run.status !== 'done') return [];
+  const required = (run.crew ?? []).filter((p) => p.requiredForDone);
+  if (!required.length) return [];
+  const names: string[] = [];
+  for (const p of required) {
+    const passed = (run.reviews ?? []).filter((v) => v.presetId === p.id && v.pass);
+    if (!passed.length) return [];
+    names.push(p.name);
+  }
+  return names;
+}
+
+/** `$0.42` when the run's provider priced it, nothing when it did not. */
+function cost(v: ReviewVerdict): string {
+  return typeof v.costUsd === 'number' && v.costUsd > 0 ? ` · $${v.costUsd.toFixed(2)}` : '';
+}
+
+/**
+ * The `reviews:` block for a run report, or [] when the run collected none.
+ *
+ * `currentDiffHash` is optional because most surfaces cannot honestly compute
+ * it: a report reads a frozen deck whose diffs are capped, so hashing it would
+ * call a perfectly good PASS stale. Without it, staleness is simply not
+ * claimed — the end-of-run gate is the one place that judges it — and the
+ * other two blockers, a required reviewer that never ran and one that said
+ * FAIL, are facts the record already holds.
+ */
+export function reviewReportLines(
+  crew: readonly CrewPreset[] | undefined,
+  reviews: readonly ReviewVerdict[] | undefined,
+  currentDiffHash?: string,
+): string[] {
+  const verdicts = reviews ?? [];
+  if (!verdicts.length && !(crew ?? []).length) return [];
+  const lines: string[] = [];
+  if (verdicts.length) {
+    lines.push(`reviews: ${verdicts.map((v) => `${v.name} ${v.pass ? 'PASS' : 'FAIL'}${cost(v)}`).join(', ')}`);
+  }
+  const blockers = reviewBlockers(crew, verdicts, currentDiffHash ?? '')
+    .filter((b) => (currentDiffHash === undefined ? b.reason !== 'stale' : true));
+  for (const b of blockers) {
+    lines.push(b.reason === 'missing'
+      ? `  ${b.name} is required for this run to be done and has not reviewed it.`
+      : b.reason === 'fail'
+        ? `  ${b.name} is required for this run to be done and returned FAIL.`
+        : `  ${b.name} passed an earlier version of the diff; the code changed after it.`);
+  }
+  return lines;
+}

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;
+}