@amenophis1er/foreman 0.1.15 → 0.1.17

package/src/mcp.ts

@@ -10,17 +10,20 @@
  * What it offers is what an agent watching or launching missions needs: the
  * fleet, runs, a run's status with a `wait` (one call that returns when
  * something changes, instead of a polling loop), the transcript, the mission
- * doc and memory, linking a project, starting a mission, steering a director.
+ * doc and memory, the schedules, linking a project, starting a mission,
+ * steering a director.
  *
  * What it does not offer, on purpose: approving or denying, answering the
  * director's questions, interrupt, resume, raising a budget, opening a pull
- * request, settings and keys. Those are the moments Foreman exists to put a
+ * request, settings and keys, and any change to a schedule. Those are the
+ * moments Foreman exists to put a
  * human in; `run_status` says when a run needs one, and with what, so the
  * agent's job is to send the human to decide, not to decide.
  */
 import fs from 'node:fs';
 import path from 'node:path';
 import { z } from 'zod';
+import { describeCadence, type Cadence } from './schedule.js';
 
 export interface ToolResult {
   /** What the model reads. */
@@ -70,6 +73,45 @@ interface ProjectCard {
   pendingPermissions: number; pendingQuestions: number; needs?: Need[]; git?: { branch?: string; dirty?: boolean } | null;
 }
 
+/** A schedule as `GET /projects/{id}/schedules` reports it. */
+interface ScheduleSummary {
+  id: string; name: string; cadence: Cadence; budgetUsd: number; enabled: boolean;
+  nextRunAt: number | null; pausedReason: null | 'failures' | 'monthly-cap' | 'human';
+  consecutiveFailures?: number; lastOutcome?: string; lastRunId?: string; lastRunAt?: number; lastNote?: string;
+}
+interface SchedulePayload { schedules: ScheduleSummary[]; monthSpendUsd?: number; monthlyCapUsd?: number }
+
+/** A moment as a reader would say it: "in 15 h", "3 days ago". */
+export function relativeTime(ms: number): string {
+  const s = Math.round(ms / 1000);
+  const a = Math.abs(s);
+  const span = a < 90 ? 'a minute' : a < 5400 ? `${Math.round(a / 60)} min` : a < 172800 ? `${Math.round(a / 3600)} h` : `${Math.round(a / 86400)} days`;
+  return s >= 0 ? `in ${span}` : `${span} ago`;
+}
+
+/** Why a schedule is not going to fire, in the words that say what would undo it. */
+function pausedPhrase(s: ScheduleSummary): string {
+  switch (s.pausedReason) {
+    case 'failures': return `paused after ${s.consecutiveFailures ?? 2} failed scheduled runs in a row`;
+    case 'monthly-cap': return 'paused at the project\'s monthly cap for scheduled spend';
+    case 'human': return 'paused by hand';
+    default: return s.enabled ? 'enabled' : 'disabled';
+  }
+}
+
+/**
+ * One line for a schedule. The next run is said twice — absolutely, because a
+ * schedule is a wall-clock promise, and relatively, because "in 15 h" is what
+ * the reader actually wanted to know.
+ */
+function scheduleLine(s: ScheduleSummary): string {
+  const next = s.pausedReason || !s.enabled ? 'no next run while paused'
+    : s.nextRunAt ? `next ${new Date(s.nextRunAt).toLocaleString()} (${relativeTime(s.nextRunAt - Date.now())})`
+      : 'next never — this cadence has no future firing';
+  const last = s.lastOutcome ? `last ${s.lastOutcome}${s.lastRunId ? ` (${s.lastRunId})` : ''}${s.lastRunAt ? ` ${relativeTime(s.lastRunAt - Date.now())}` : ''}` : 'never run yet';
+  return `${s.name} · ${describeCadence(s.cadence)} · ${next} · ${pausedPhrase(s)} · ${usd(s.budgetUsd)} per run · ${last}`;
+}
+
 /** One line for a run, the way the fleet board says it. */
 function runLine(r: RunSummary): string {
   const cost = r.costBasis && r.costBasis !== 'priced' ? `${r.costBasis}` : `${usd(r.costUsd)} of ${usd(r.budgetUsd)}`;
@@ -373,6 +415,36 @@ export function foremanTools(opts: ForemanClientOptions): ToolDef[] {
     },
   };
 
+  const schedules: ToolDef = {
+    name: 'list_schedules',
+    description: 'The standing schedules: missions that start themselves in their project on a cadence. Per schedule — the project, the name, the cadence in words, the next run, enabled or paused and why, the per-run cap, and how the last firing ended with its run id. Read-only, and the only schedule tool there is: creating, editing, pausing, resuming or running one now happens on the dashboard, because a schedule is standing configuration and remote surfaces never grant standing changes. Do not look for another tool.',
+    schema: { projectId: z.string().optional() },
+    run: async ({ projectId }) => {
+      const all = (await get<{ projects: ProjectCard[] }>('/projects')).projects;
+      const ref = projectId === undefined ? '' : String(projectId).trim();
+      const wanted = ref ? all.filter((p) => p.id === ref || p.name.toLowerCase() === ref.toLowerCase()) : all;
+      if (ref && !wanted.length) return { text: `No project ${ref}. fleet_status lists them by id and name.` };
+      const blocks: string[] = [];
+      const data: Array<{ projectId: string; project: string; schedules: ScheduleSummary[]; monthSpendUsd?: number; monthlyCapUsd?: number }> = [];
+      for (const p of wanted) {
+        const d = await get<SchedulePayload>(`/projects/${encodeURIComponent(p.id)}/schedules`).catch(() => null);
+        if (!d) continue;
+        const list = d.schedules ?? [];
+        data.push({ projectId: p.id, project: p.name, schedules: list, monthSpendUsd: d.monthSpendUsd, monthlyCapUsd: d.monthlyCapUsd });
+        if (!list.length) {
+          if (ref) blocks.push(`${p.name} (${p.id}) — no schedules.`);
+          continue;
+        }
+        const month = typeof d.monthSpendUsd === 'number' && typeof d.monthlyCapUsd === 'number'
+          ? ` · scheduled this month ${usd(d.monthSpendUsd)} of ${usd(d.monthlyCapUsd)}` : '';
+        blocks.push(`${p.name} (${p.id}) — ${list.length} schedule${list.length === 1 ? '' : 's'}${month}\n${list.map((s) => `  ${scheduleLine(s)}`).join('\n')}`);
+      }
+      if (!blocks.length) return { text: 'No schedules. They are created on the dashboard, in a project\'s view.', data: { projects: data } };
+      blocks.push('Read-only here: a schedule is created, edited, paused or resumed on the dashboard.');
+      return { text: blocks.join('\n'), data: { projects: data } };
+    },
+  };
+
   const search: ToolDef = {
     name: 'search_runs',
     description: 'Runs across the fleet whose title, brief, project or folder match.',
@@ -456,7 +528,7 @@ export function foremanTools(opts: ForemanClientOptions): ToolDef[] {
     },
   };
 
-  return [fleet, listRuns, runStatus, runReport, transcript, missionDoc, memory, search, doctor, link, start, steer];
+  return [fleet, listRuns, runStatus, runReport, transcript, missionDoc, memory, schedules, search, doctor, link, start, steer];
 }
 
 /** Runs the MCP server over stdio until the client goes away. Nothing may be written to stdout but the protocol. */

package/src/notify/commands.test.ts

@@ -11,6 +11,8 @@ test('parseCommand: one shape per command, bot suffix tolerated, junk is null',
   assert.deepEqual(parseCommand('/run lp1 ship it'), { cmd: 'run', project: 'lp1', text: 'ship it' });
   assert.deepEqual(parseCommand('/stop'), { cmd: 'stop' });
   assert.deepEqual(parseCommand('/stop lp1'), { cmd: 'stop', project: 'lp1' });
+  assert.deepEqual(parseCommand('/schedules'), { cmd: 'schedules' });
+  assert.deepEqual(parseCommand('/schedules@ForemanBot lp1'), { cmd: 'schedules', project: 'lp1' });
   assert.equal(parseCommand('/plan test-4'), null);
   assert.equal(parseCommand('/new'), null);
   assert.equal(parseCommand('/dance'), null);

package/src/notify/commands.ts

@@ -17,6 +17,8 @@ export type Command =
   | { cmd: 'plan'; project: string; text: string }
   | { cmd: 'run'; project: string; text: string }
   | { cmd: 'stop'; project?: string }
+  /** Read-only: what stands, for one project or the whole fleet. */
+  | { cmd: 'schedules'; project?: string }
   | { cmd: 'fleet'; text: string };
 
 /** `/plan@ForemanBot test-4 add a footer` → { cmd: 'plan', project: 'test-4', text: 'add a footer' }. */
@@ -37,6 +39,9 @@ export function parseCommand(text: string): Command | null {
     case 'plan': { const [project, t] = split(); return project && t ? { cmd: 'plan', project, text: t } : null; }
     case 'run': { const [project, t] = split(); return project && t ? { cmd: 'run', project, text: t } : null; }
     case 'stop': return { cmd: 'stop', ...(rest ? { project: rest } : {}) };
+    // Listing only. A schedule is standing configuration, and remote surfaces
+    // never grant standing changes — see the reply in server.ts.
+    case 'schedules': return { cmd: 'schedules', ...(rest ? { project: rest } : {}) };
     case 'fleet': case 'f': return { cmd: 'fleet', text: rest };
     default: return null;
   }
@@ -70,6 +75,7 @@ export const HELP_TEXT = [
   '/plan <project> <what you want> — talk to that project\'s planner',
   '/run <project> <brief> — skip the talk: start a mission at the project\'s default cap',
   '/stop [project] — stop the planner reply in flight',
+  '/schedules [project] — the standing schedules and when they next run (reading only; they are changed in the dashboard)',
   '/fleet [anything] — the front desk: ask how things are going, or say what you want started where',
   '',
   'Anything else you type answers the open question, continues the planning conversation you were just in, or goes to the front desk.',

package/src/notify/telegram.ts

@@ -98,6 +98,7 @@ export const BOT_COMMANDS: Array<{ command: string; description: string }> = [
   { command: 'plan', description: 'Talk to a planner: /plan <project> <what you want>' },
   { command: 'run', description: 'Skip the talk: /run <project> <brief>' },
   { command: 'stop', description: 'Stop the planner reply in flight' },
+  { command: 'schedules', description: 'Standing schedules and when they next run (read-only)' },
   { command: 'fleet', description: 'The front desk: /fleet how is everything going?' },
   { command: 'help', description: 'What you can say here' },
 ];

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/orchestrator.ts

@@ -644,6 +644,14 @@ export type Emitter = (event: string, data: unknown) => void;
 /** Persists updated run metadata (fire-and-forget from the run's viewpoint). */
 export type MetaSink = (meta: RunMeta) => void;
 
+/**
+ * Turns a worker gets before the SDK stops it. Raised from 60: five workers
+ * in four missions hit the cap mid-task on legitimate, brief-sized work
+ * (a hundred TypeScript errors in one package; a test-suite port), and each
+ * time the director paid to respawn one that re-read the same files.
+ */
+const WORKER_MAX_TURNS = 100;
+
 export const DIRECTOR_CHARTER = `
 You are the FOREMAN DIRECTOR. You run a mission autonomously inside one folder by
 directing worker agents. Non-negotiable rules, in priority order:
@@ -720,6 +728,16 @@ directing worker agents. Non-negotiable rules, in priority order:
    (a dev server, a static preview), call mcp__foreman__expose_service with
    its port and put the URL it returns in your report — the human can open
    it from their phone. Keep that server up until the mission ends.
+   CLEAN UP WHAT YOU STARTED: before you finish, stop every server, watcher or
+   background process the crew started that you are not deliberately leaving
+   for the human, and name in your report any you left up and on which port.
+   A process that outlives the mission holds its port until somebody hunts it
+   down by hand.
+   SIZE THE TASK TO THE WORKER: a worker is stopped after ${WORKER_MAX_TURNS}
+   turns of its own. It gets one continuation to finish what it was doing, and
+   after that the task comes back to you half-done. So give a worker a task it
+   can finish in that many steps — split the big ones — rather than one brief
+   that has to be rescued twice.
 4. REPORT WHAT YOU SEE. Judge the work as a competent professional would, not
    only against the letter of the acceptance criteria. If you observe a defect
    the criteria did not name — tap targets too small to use, unreadable
@@ -773,13 +791,6 @@ const USAGE_LIMIT_RE = /out of usage credits|usage limit reached|upgrade to incr
 /** One worker's outcome, as runWorker hands it back. */
 interface WorkerOutcome { report: string; isError: boolean }
 
-/**
- * Turns a worker gets before the SDK stops it. Raised from 60: five workers
- * in four missions hit the cap mid-task on legitimate, brief-sized work
- * (a hundred TypeScript errors in one package; a test-suite port), and each
- * time the director paid to respawn one that re-read the same files.
- */
-const WORKER_MAX_TURNS = 100;
 /** What a worker stopped by the cap is told when its session is picked back up. */
 const WORKER_CONTINUE_PROMPT =
   'You were stopped by the turn cap, not by a failure. Your session and your files are as you left them; ' +
@@ -914,7 +925,7 @@ export class MissionRun {
      * has no `expose_service` to offer.
      */
     private readonly host: {
-      exposeService?: (runId: string, port: number, label: string) => Promise<{ ok: true; url: string; path: string } | { ok: false; reason: string }>;
+      exposeService?: (runId: string, port: number, label: string) => Promise<{ ok: true; url: string; path: string; pid?: number } | { ok: false; reason: string }>;
       /** The browser channel detected at dispatch (src/browser.ts); Chrome when the host says nothing. */
       browserChannel?: string;
     } = {},
@@ -2457,7 +2468,7 @@ export class MissionRun {
         if (!fn) return { content: [{ type: 'text' as const, text: 'Exposing services is not available in this run.' }] };
         const r = await fn(this.meta.id, port, (label ?? '').trim() || `port ${port}`);
         if (!r.ok) return { content: [{ type: 'text' as const, text: `Not exposed: ${r.reason}` }] };
-        const entry = { port, label: (label ?? '').trim() || `port ${port}`, path: r.path, since: Date.now() };
+        const entry = { port, label: (label ?? '').trim() || `port ${port}`, path: r.path, since: Date.now(), pid: r.pid };
         this.meta.services = [...(this.meta.services ?? []).filter((s) => s.port !== port), entry];
         this.saveMeta(this.meta);
         this.emit('service_exposed', { ...entry, url: r.url });

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']);
+});