@amenophis1er/foreman 0.1.16 → 0.1.17

package/README.md

@@ -151,6 +151,16 @@ a human's judgement is required *and* being wrong is expensive.
   temp directory is denied on the spot and redirected to `.foreman/work/`.
   A path that is knowably wrong is denied. A path only you can judge asks —
   with a default, because "no answer" is also an answer the run must survive.
+- **A worktree comes with its repository.** A mission whose folder is a git
+  worktree is given the repository it was made from, once, at the start — the
+  build config, the shared declarations and the parent's `node_modules` live
+  there, so without it the crew asks the same question all day and you learn
+  to click Allow without reading. The transcript records the grant, and
+  withdraws it in the open if the reason stops holding on a resume. Sibling
+  worktrees stay closed — and when they live *inside* the repository the
+  parent is not opened at all, because a grant is a subtree and would carry
+  them along. A parent another mission is working in stays closed too.
+  Turn it off per project with **Worktree parent** in Settings.
 - **Every ask has a deadline and a default.** An approval nobody answers is
   denied with a message that says where to go instead; a question nobody
   answers is handed back to the director with "decide and record". You set
@@ -161,6 +171,34 @@ a human's judgement is required *and* being wrong is expensive.
   phone with buttons. The default is what happens when you truly cannot
   answer, not what happens because you never knew.
 
+## Schedules
+
+A schedule is a mission that starts itself. It lives in Foreman, not in the
+repository: a name, a brief, a cadence — daily, weekly, every N hours, or a
+five-field cron expression — and its own budget. When it fires, the mission
+runs in the project's folder on its own branch and leaves a run you cannot
+tell apart from one you started by hand: same transcript, same files, same
+report, same place in the fleet.
+
+Standing spend is the thing that can hurt you while you are away, so three
+guards bound it, all in the server, none of them the agent's to interpret:
+
+- **The per-run cap**, the same budget every mission has.
+- **A monthly ceiling on scheduled spend, per project** —
+  `scheduledMonthlyCapUsd`, $25 by default. Foreman pauses the schedule
+  *before* the run that would cross it, rather than stopping one halfway.
+- **Two failed scheduled runs in a row pause it.** A schedule that has started
+  failing keeps failing, and it should stop costing money until someone reads
+  why.
+
+A paused schedule says which of the three paused it, and what would undo it.
+
+Schedules are created and edited in the dashboard's project view. The phone
+and `foreman mcp` list them — cadence, next run, whether they are paused and
+why — and can do nothing else: resuming a paused schedule is a decision at the
+desk, because a schedule is standing configuration, and Foreman grants no
+standing changes from a remote surface.
+
 ## From your phone
 
 With the Telegram bot linked (Settings → Notifications, scan the QR):
@@ -230,7 +268,7 @@ result.
 ```sh
 npm ci && npm run setup      # dependencies, then the dashboard build
 npm start                    # serves http://localhost:4177
-npm test                     # 379 tests, node:test
+npm test                     # 424 tests, node:test
 npm run typecheck            # server and dashboard
 npm run dev                  # API + Vite together
 scripts/dev-restart.sh       # restarts the server only when nothing would be lost
@@ -251,12 +289,14 @@ Tools: `fleet_status`, `list_runs`, `run_status` (with `wait_seconds` and
 `until`: one call that blocks until the run changes, finishes, or needs you),
 `run_report` (a finished run in one call: the director's report, DONE WHEN,
 changed files, branch and pull request), `run_transcript`, `mission_doc`,
-`project_memory`, `search_runs`, `doctor`, `link_project` (folder or Git URL),
+`project_memory`, `list_schedules` (read-only: what starts itself and when),
+`search_runs`, `doctor`, `link_project` (folder or Git URL),
 `start_mission`, `steer`. Start, wait until finished, read the report: three calls. It talks to the running server at `FOREMAN_URL`
 (default `http://localhost:4177`) and has no logic of its own.
 
 Deliberately absent: approving or denying, answering the director's questions,
-interrupt, resume, raising a budget, opening a pull request, settings and keys.
+interrupt, resume, raising a budget, opening a pull 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 you to decide.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amenophis1er/foreman",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "description": "Autonomous mission runner on the Claude Agent SDK: a director plans, delegates to workers, verifies, and reports — from one dashboard, your phone, or the CLI.",
   "keywords": [
     "claude",

package/src/fleet-planner.test.ts

@@ -1,6 +1,7 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { FLEET_CHAT_ID, PHONE_CONTEXT_MS, fleetSummary, phoneRoute, situation } from './fleet-planner.js';
+import { FLEET_CHAT_ID, PHONE_CONTEXT_MS, fleetSummary, phoneRoute, scheduleSummary, scheduleTools, situation, type FleetHost, type FleetScheduleView } from './fleet-planner.js';
+import type { Schedule } from './types.js';
 
 test('plain phone text goes to the fleet planner when no project conversation is open', () => {
   assert.equal(phoneRoute(null), 'fleet');
@@ -41,6 +42,43 @@ test('fleetSummary says what is running, what is waiting, and what finished last
   assert.equal(fleetSummary([]), 'No projects are linked yet.');
 });
 
+const schedule = (o: Partial<Schedule> = {}): Schedule => ({
+  id: 's1', projectId: 'a', name: 'nightly deps', brief: 'Update the dependencies',
+  cadence: { kind: 'daily', at: '07:30' }, budgetUsd: 3, enabled: true, createdAt: 0,
+  nextRunAt: null, consecutiveFailures: 0, pausedReason: null, ...o,
+});
+
+test('scheduleSummary says the cadence in words, the next run both ways, and why one is paused', () => {
+  const now = 1_700_000_000_000;
+  const views: FleetScheduleView[] = [
+    { projectName: 'P5', monthSpendUsd: 4.2, monthlyCapUsd: 25, schedule: schedule({ nextRunAt: now + 15 * 3_600_000, lastOutcome: 'done', lastRunId: 'r9', lastRunAt: now - 9 * 3_600_000 }) },
+    { projectName: 'P7', schedule: schedule({ id: 's2', name: 'audit', cadence: { kind: 'interval', everyMinutes: 360 }, budgetUsd: 2, enabled: false, pausedReason: 'failures', consecutiveFailures: 2 }) },
+    { projectName: 'P7', schedule: schedule({ id: 's3', name: 'weekly report', cadence: { kind: 'weekly', day: 1, at: '09:00' }, enabled: false, pausedReason: 'monthly-cap' }) },
+  ];
+  const text = scheduleSummary(views, now);
+  assert.match(text, /- P5: "nightly deps" · daily 07:30 · next .* \(in 15 h\)\n  enabled · \$3\.00 per run · last done \(r9\) 9 h ago\n  scheduled spend this month: \$4\.20 of \$25\.00/);
+  assert.match(text, /- P7: "audit" · every 6 hours · no next run while paused\n  paused after 2 failed scheduled runs in a row · \$2\.00 per run · never run yet/);
+  assert.match(text, /- P7: "weekly report" · every Monday 09:00 .*\n  paused at the project's monthly cap for scheduled spend/);
+  assert.match(text, /read-only from here: created, edited, paused and resumed on the dashboard/);
+  assert.match(scheduleSummary([]), /No schedules\. They are created on the dashboard/);
+});
+
+test('the front desk reads schedules and has no tool that changes one', async () => {
+  const asked: Array<string | undefined> = [];
+  const host = {
+    listSchedules: async (ref?: string) => { asked.push(ref); return [{ projectName: 'P5', schedule: schedule({ nextRunAt: Date.now() + 3_600_000 }) }]; },
+  } as unknown as FleetHost;
+  const tools = scheduleTools(host);
+  assert.deepEqual(tools.map((t) => t.name), ['list_schedules']);
+  assert.match(tools[0].description, /Read-only.*dashboard/s);
+  const out = await tools[0].handler({ project: 'P5' } as never, undefined);
+  assert.deepEqual(asked, ['P5']);
+  assert.match(String((out.content as Array<{ text: string }>)[0].text), /"nightly deps" · daily 07:30/);
+  // A host from before schedules existed says so instead of guessing.
+  const bare = await scheduleTools({} as FleetHost)[0].handler({} as never, undefined);
+  assert.match(String((bare.content as Array<{ text: string }>)[0].text), /cannot list schedules/);
+});
+
 test('situation carries the clock, the channel, and the news since the last message', () => {
   const now = new Date(2026, 8, 6, 14, 5);
   const s = situation({ via: 'telegram', sinceMs: 12 * 60_000, news: ['13:58 P7 — mission ended: done ($0.78)'] }, now);

package/src/fleet-planner.ts

@@ -14,8 +14,9 @@
  *  - **No resident process.** A message resumes a stored session, runs one
  *    turn, exits. Continuity is the session id on disk.
  *  - **Read-only, always.** Its tools are the fleet's verbs — list, inspect,
- *    create or link a project, open a planning conversation, propose, steer.
- *    No shell, no file access, no starting missions.
+ *    create or link a project, open a planning conversation, propose, steer,
+ *    read the schedules. No shell, no file access, no starting missions — and
+ *    no change to a schedule, which is standing configuration.
  *  - **It never answers for the human.** Open approvals and questions are
  *    described, not resolved. The buttons on the card are the human's, and an
  *    agent that presses them is a hole through `canUseTool`.
@@ -27,7 +28,8 @@ import {
 } from '@anthropic-ai/claude-agent-sdk';
 import type { AgentEnv } from './provider.js';
 import { modelsSection, needsBrowser, pickKnownModel, type PlannerModel } from './planner.js';
-import type { MissionProposal } from './types.js';
+import { describeCadence } from './schedule.js';
+import type { MissionProposal, Schedule } from './types.js';
 
 /** Where the fleet conversation is stored, beside the project chats. The underscore keeps it out of project listings. */
 export const FLEET_CHAT_ID = '_fleet';
@@ -85,6 +87,9 @@ const ago = (ms: number): string => {
   return h < 48 ? `${h} h ago` : `${Math.round(h / 24)} days ago`;
 };
 
+/** The same distance, forwards: "in 15 h". */
+const ahead = (ms: number): string => (ms < 60_000 ? 'in under a minute' : `in ${ago(ms).replace(/ ago$/, '')}`);
+
 /** The fleet in plain lines, as the list_projects tool returns it. */
 export function fleetSummary(views: FleetProjectView[], now = Date.now()): string {
   if (!views.length) return 'No projects are linked yet.';
@@ -104,6 +109,68 @@ export function fleetSummary(views: FleetProjectView[], now = Date.now()): strin
   }).join('\n');
 }
 
+/** One schedule as the front desk sees it: the record, plus whose it is. */
+export interface FleetScheduleView {
+  projectName: string;
+  schedule: Schedule;
+  /** Scheduled spend this month against the project's ceiling, when the host knows it. */
+  monthSpendUsd?: number;
+  monthlyCapUsd?: number;
+}
+
+/** Why a schedule is not going to fire, in the words that say what would undo it. */
+function pausedPhrase(s: Schedule): 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';
+  }
+}
+
+/**
+ * The schedules in plain lines, as the list_schedules tool returns them. The
+ * next run is said absolutely and relatively both: a schedule is a wall-clock
+ * promise, and "in 15 h" is what the person on the phone actually asked.
+ */
+export function scheduleSummary(views: FleetScheduleView[], now = Date.now()): string {
+  if (!views.length) return 'No schedules. They are created on the dashboard, in a project\'s view.';
+  const lines = views.map((v) => {
+    const s = v.schedule;
+    const next = s.pausedReason || !s.enabled ? 'no next run while paused'
+      : s.nextRunAt ? `next ${new Date(s.nextRunAt).toLocaleString()} (${ahead(s.nextRunAt - now)})`
+        : 'next never — this cadence has no future firing';
+    const last = s.lastOutcome
+      ? `last ${s.lastOutcome}${s.lastRunId ? ` (${s.lastRunId})` : ''}${s.lastRunAt ? ` ${ago(now - s.lastRunAt)}` : ''}`
+      : 'never run yet';
+    const month = typeof v.monthSpendUsd === 'number' && typeof v.monthlyCapUsd === 'number'
+      ? `\n  scheduled spend this month: $${v.monthSpendUsd.toFixed(2)} of $${v.monthlyCapUsd.toFixed(2)}` : '';
+    return `- ${v.projectName}: "${s.name}" · ${describeCadence(s.cadence)} · ${next}\n  ${pausedPhrase(s)} · $${s.budgetUsd.toFixed(2)} per run · ${last}${month}`;
+  });
+  lines.push('Schedules are read-only from here: created, edited, paused and resumed on the dashboard.');
+  return lines.join('\n');
+}
+
+/**
+ * The front desk's one schedule verb. Listing only, and there is no sibling:
+ * a schedule is standing configuration, and the phone never grants standing
+ * changes — the same rule that keeps "always allow" off the buttons.
+ */
+export function scheduleTools(host: FleetHost) {
+  return [
+    tool('list_schedules', 'The standing schedules — missions that start themselves on a cadence — for the whole fleet or one project: the cadence in words, the next run, enabled or paused and why, the per-run cap, and how the last firing ended. Read-only, and the only schedule tool: creating, editing, pausing, resuming or running one now is done on the dashboard, never from here.',
+      { project: z.string().optional().describe('Project name, id, or folder name; omit for the whole fleet') },
+      async ({ project }) => {
+        if (!host.listSchedules) return text('This Foreman cannot list schedules.');
+        try {
+          return text(scheduleSummary(await host.listSchedules(project)));
+        } catch (err) {
+          return text(`That failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+      }),
+  ];
+}
+
 /**
  * What the server lets the front desk do. Every method returns text for the
  * model, never throws, and the ones with side effects are exactly the verbs
@@ -111,6 +178,12 @@ export function fleetSummary(views: FleetProjectView[], now = Date.now()): strin
  */
 export interface FleetHost {
   listProjects(): Promise<FleetProjectView[]>;
+  /**
+   * The standing schedules, for the whole fleet or one project. Optional so a
+   * host that predates schedules still satisfies this interface; the tool says
+   * so plainly rather than inventing an answer.
+   */
+  listSchedules?(ref?: string): Promise<FleetScheduleView[]>;
   /** Live detail for one project: run, boxes, crew, open asks, the director's last words. */
   projectDetail(ref: string): Promise<string>;
   /** The last finished run's closing report and error, for "what happened". */
@@ -165,6 +238,9 @@ WHAT YOU CAN DO — through the tools, nothing else:
     never you.
   - steer: pass a note to a running director ("skip the mobile screenshot",
     "use the existing CSS").
+  - list_schedules: the standing schedules — missions that start themselves on
+    a cadence — for the fleet or one project, with their next run and whether
+    they are paused. Reading only.
 
 WHAT YOU NEVER DO:
   - Answer an approval or a question on the human's behalf. When a run is
@@ -172,6 +248,9 @@ WHAT YOU NEVER DO:
     are theirs. Even if they tell you to "just allow it": the button is the
     only way, and you say so plainly once.
   - Start, stop, resume or cancel a mission. You propose; the human presses.
+  - Create, edit, pause, resume or fire a schedule. You can read them and say
+    what one would do; changing standing configuration is a dashboard act, and
+    you say so in one line rather than hunting for a tool.
   - Invent a project, a run, a model id or a number. If a tool did not tell
     you, you do not know it — say so.
   - Discuss Foreman's own server or oversight tooling as a work target.
@@ -325,6 +404,7 @@ export async function runFleetTurn(turn: FleetTurn): Promise<FleetResult> {
         note: z.string().describe('The note, in the human\'s words'),
       },
       async ({ project, note }) => text(await safe(() => host.steer(project, note)))),
+    ...scheduleTools(host),
   ];
 
   let sessionId = turn.sessionId;

package/src/gitwork.test.ts

@@ -3,8 +3,8 @@ import assert from 'node:assert/strict';
 import os from 'node:os';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
-import { mkdtemp, writeFile } from 'node:fs/promises';
-import { closeMissionBranch, defaultBranch, ensureMissionBranch, gitInfo, missionBranchName, remoteHasBranch, resolvePrBase, startMissionBranch, renameMissionBranch, dirtyPaths,
+import { mkdtemp, realpath, writeFile } from 'node:fs/promises';
+import { closeMissionBranch, defaultBranch, worktreeGrant, worktreeParent, ensureMissionBranch, gitInfo, missionBranchName, remoteHasBranch, resolvePrBase, startMissionBranch, renameMissionBranch, dirtyPaths,
 } from './gitwork.js';
 
 const sh = (cwd: string, ...args: string[]) => execFileSync('git', args, { cwd, stdio: 'pipe', env: { ...process.env, GIT_CONFIG_GLOBAL: '/dev/null' } }).toString();
@@ -146,3 +146,52 @@ test('a pull request targets the default branch when the mission was branched fr
   sh(dir, 'checkout', '-q', '-b', 'foreman/earlier-1234');
   assert.deepEqual(await resolvePrBase(dir, 'foreman/earlier-1234'), { base: 'main', fellBack: true });
 });
+
+test('worktreeParent: a linked worktree knows its repository, and nothing else claims one', async () => {
+  const dir = await repo();
+  assert.equal(await worktreeParent(dir), null, 'the main worktree has no parent');
+  assert.equal(await worktreeParent(os.tmpdir()), null, 'a plain directory is not a worktree');
+
+  const wt = path.join(await mkdtemp(path.join(os.tmpdir(), 'gitwork-wt-')), 'feature');
+  sh(dir, 'worktree', 'add', '-q', '-b', 'feature', wt);
+  const shape = await worktreeParent(wt);
+  assert.equal(shape && await realpath(shape.parent), await realpath(dir), 'the linked worktree points back at the repository');
+  assert.deepEqual(shape?.siblings, [], 'and it is the only linked worktree');
+  assert.equal(await worktreeParent(dir), null, 'and the main worktree still has none');
+});
+
+test('worktreeGrant opens the parent unless a live run is working in it', () => {
+  const shape = (siblings: string[] = []) => ({ parent: '/repos/app', siblings });
+  assert.deepEqual(worktreeGrant(shape(), []), { grant: '/repos/app' });
+  assert.deepEqual(worktreeGrant(shape(['/elsewhere/wt-a']), ['/repos/other']), { grant: '/repos/app' },
+    'a sibling outside the parent is not opened by opening the parent');
+  // Two crews in one checkout is the thing the dirty-checkout guard exists to
+  // prevent; opening the parent into a live mission would arrange it.
+  assert.deepEqual(worktreeGrant(shape(), ['/repos/app']), {
+    grant: null, reason: 'its parent repository /repos/app is held by another running mission',
+  });
+  // A grant is a subtree: worktrees kept inside the repository would ride
+  // along with it, so the parent is not opened at all.
+  const nested = worktreeGrant(shape(['/repos/app/.worktrees/a', '/repos/app/.worktrees/b']), []);
+  assert.equal(nested.grant, null);
+  assert.match(nested.reason ?? '', /would also open 2 other worktrees inside it/);
+  assert.deepEqual(worktreeGrant(null, []), { grant: null }, 'not a worktree: nothing to say');
+});
+
+test('a worktree kept inside the repository is not opened by opening the repository', async () => {
+  const dir = await repo();
+  // The common layout codex flagged: linked worktrees under the main checkout.
+  const inside = path.join(dir, '.worktrees', 'a');
+  sh(dir, 'worktree', 'add', '-q', '-b', 'inside-a', inside);
+  const other = path.join(dir, '.worktrees', 'b');
+  sh(dir, 'worktree', 'add', '-q', '-b', 'inside-b', other);
+
+  const shape = await worktreeParent(inside);
+  assert.ok(shape, 'it is a linked worktree');
+  assert.equal(await realpath(shape.parent), await realpath(dir));
+  assert.ok(shape.siblings.some((s) => s.endsWith(path.join('.worktrees', 'b'))), 'and it can see its sibling');
+
+  const decision = worktreeGrant(shape, []);
+  assert.equal(decision.grant, null, 'so the parent is not opened automatically');
+  assert.match(decision.reason ?? '', /would also open/);
+});

package/src/gitwork.ts

@@ -8,6 +8,7 @@
  * commits on it. It never merges, and it pushes only when the human presses
  * the button that says so — once, for that branch, to open the pull request.
  */
+import path from 'node:path';
 import { execFile } from 'node:child_process';
 
 export interface GitInfo {
@@ -92,6 +93,73 @@ export function missionBranchName(mission: string, runId: string): string {
  * own commit — so this is what a human stands to have committed under a
  * mission's name without noticing.
  */
+/**
+ * When this folder is a linked git worktree, the repository it was made from:
+ * the main worktree's root. Null when the folder is that main worktree, is
+ * not a repository, or git is too old to say.
+ *
+ * Worktrees are the reason a mission asks the human the same question all
+ * day. A worktree holds a branch's files but not the repository's shared
+ * scaffolding — the build config, the type declarations, the parent package's
+ * node_modules — so a crew working in one steps up to the parent constantly,
+ * and every step is a boundary crossing.
+ */
+export interface WorktreeShape {
+  /** The main worktree's root: the repository this folder was made from. */
+  parent: string;
+  /** Every other worktree of the same repository, this folder excluded. */
+  siblings: string[];
+}
+
+export async function worktreeParent(folder: string): Promise<WorktreeShape | null> {
+  try {
+    const out = await git(['worktree', 'list', '--porcelain'], folder);
+    // The first entry is always the main worktree; the rest are the linked ones.
+    const roots = out.split('\n').filter((l) => l.startsWith('worktree '))
+      .map((l) => path.resolve(l.slice('worktree '.length).trim()));
+    const main = roots[0];
+    if (!main || roots.length < 2) return null;
+    const here = (await git(['rev-parse', '--show-toplevel'], folder)).trim();
+    if (!here || path.resolve(here) === main) return null;
+    return { parent: main, siblings: roots.slice(1).filter((r) => r !== path.resolve(here)) };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Should this run be given its parent repository, and why not when not.
+ * Pure so the rule is testable: the parent is opened unless another live run
+ * is working in it, because two crews in one checkout is the situation the
+ * dirty-checkout guard exists to prevent.
+ */
+export function worktreeGrant(
+  shape: WorktreeShape | null,
+  busyFolders: Iterable<string>,
+): { grant: string | null; reason?: string } {
+  if (!shape) return { grant: null };
+  const { parent, siblings } = shape;
+  for (const f of busyFolders) {
+    if (path.resolve(f) === parent) {
+      return { grant: null, reason: `its parent repository ${parent} is held by another running mission` };
+    }
+  }
+  // A grant is a subtree, so a worktree that lives *inside* the repository
+  // (the common `/repo/.worktrees/x` layout) would be opened along with the
+  // parent — and one of those may be another mission's workspace. The promise
+  // that siblings stay closed cannot be kept by granting the parent here, so
+  // the grant is declined and the human keeps deciding, one command at a time.
+  const nested = siblings.filter((s) => s === parent || s.startsWith(parent + path.sep));
+  if (nested.length) {
+    return {
+      grant: null,
+      reason: `opening ${parent} would also open ${nested.length} other worktree${nested.length === 1 ? '' : 's'} inside it `
+        + `(${nested.slice(0, 2).map((s) => path.basename(s)).join(', ')}${nested.length > 2 ? ', …' : ''})`,
+    };
+  }
+  return { grant: parent };
+}
+
 export async function dirtyPaths(folder: string, limit = 8): Promise<string[]> {
   try {
     const out = await git(['status', '--porcelain', '--untracked-files=normal'], folder);

package/src/mcp.test.ts

@@ -164,7 +164,44 @@ test('the tool set has no human-only actions', () => {
   for (const forbidden of ['approve', 'deny', 'permission', 'answer', 'interrupt', 'resume', 'budget', 'pull_request', 'open_pr', 'settings', 'key']) {
     assert.ok(!names.some((n) => n.split('_').includes(forbidden) || n === forbidden), `${forbidden} must not be a tool`);
   }
-  assert.deepEqual(names, ['fleet_status', 'list_runs', 'run_status', 'run_report', 'run_transcript', 'mission_doc', 'project_memory', 'search_runs', 'doctor', 'link_project', 'start_mission', 'steer']);
+  assert.deepEqual(names, ['fleet_status', 'list_runs', 'run_status', 'run_report', 'run_transcript', 'mission_doc', 'project_memory', 'list_schedules', 'search_runs', 'doctor', 'link_project', 'start_mission', 'steer']);
+});
+
+test('list_schedules says the cadence in words, the next run both ways, and why one is paused', async () => {
+  const now = Date.now();
+  const { fetchImpl } = fakeServer({
+    'GET /projects': { projects: [
+      { id: 'p1', name: 'app', folder: '/x/app', activeRun: null, lastRun: null, pendingPermissions: 0, pendingQuestions: 0 },
+      { id: 'p2', name: 'lib', folder: '/x/lib', activeRun: null, lastRun: null, pendingPermissions: 0, pendingQuestions: 0 },
+    ] },
+    'GET /projects/p1/schedules': { monthSpendUsd: 4.2, monthlyCapUsd: 25, schedules: [
+      { id: 's1', name: 'nightly deps', cadence: { kind: 'daily', at: '07:30' }, budgetUsd: 3, enabled: true, nextRunAt: now + 15 * 3_600_000, pausedReason: null, consecutiveFailures: 0, lastOutcome: 'done', lastRunId: 'r9', lastRunAt: now - 9 * 3_600_000 },
+      { id: 's2', name: 'weekly audit', cadence: { kind: 'interval', everyMinutes: 360 }, budgetUsd: 2, enabled: false, nextRunAt: null, pausedReason: 'failures', consecutiveFailures: 2 },
+    ] },
+    'GET /projects/p2/schedules': { monthSpendUsd: 0, monthlyCapUsd: 25, schedules: [] },
+  });
+  const r = await tool(foremanTools({ base: 'http://f', fetchImpl }), 'list_schedules').run({});
+  assert.match(r.text, /app \(p1\) — 2 schedules · scheduled this month \$4\.20 of \$25\.00/);
+  assert.match(r.text, /nightly deps · daily 07:30 · next .* \(in 15 h\) · enabled · \$3\.00 per run · last done \(r9\) 9 h ago/);
+  assert.match(r.text, /weekly audit · every 6 hours · no next run while paused · paused after 2 failed scheduled runs in a row/);
+  assert.ok(!r.text.includes('lib'), 'a project with no schedules is not listed when the whole fleet was asked');
+  assert.match(r.text, /created, edited, paused or resumed on the dashboard/);
+});
+
+test('list_schedules takes a project by id or name, and no tool changes a schedule', async () => {
+  const { fetchImpl, calls } = fakeServer({
+    'GET /projects': { projects: [{ id: 'p1', name: 'app', folder: '/x/app', activeRun: null, lastRun: null, pendingPermissions: 0, pendingQuestions: 0 }] },
+    'GET /projects/p1/schedules': { schedules: [] },
+  });
+  const tools = foremanTools({ base: 'http://f', fetchImpl });
+  assert.match((await tool(tools, 'list_schedules').run({ projectId: 'App' })).text, /app \(p1\) — no schedules/);
+  assert.match((await tool(tools, 'list_schedules').run({ projectId: 'nope' })).text, /No project nope\./);
+  assert.ok(!calls.some((c) => c.method !== 'GET'), 'listing schedules only reads');
+  const names = tools.map((t) => t.name);
+  for (const forbidden of ['create_schedule', 'edit_schedule', 'update_schedule', 'pause_schedule', 'resume_schedule', 'run_schedule', 'run_schedule_now', 'delete_schedule']) {
+    assert.ok(!names.includes(forbidden), `${forbidden} must not be a tool`);
+  }
+  assert.match(tool(tools, 'list_schedules').description, /dashboard/);
 });
 
 test('a server that is not there is said in one sentence with the start command', async () => {

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