@amenophis1er/foreman 0.1.16 → 0.1.18

package/src/gitwork.test.ts

@@ -3,9 +3,10 @@ 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 { mkdir, mkdtemp, realpath, symlink, unlink, writeFile } from 'node:fs/promises';
+import { changeFingerprint, closeMissionBranch, defaultBranch, worktreeGrant, worktreeParent, ensureMissionBranch, gitInfo, missionBranchName, remoteHasBranch, resolvePrBase, startMissionBranch, renameMissionBranch, dirtyPaths,
 } from './gitwork.js';
+import type { ReviewVerdict } from './crew.js';
 
 const sh = (cwd: string, ...args: string[]) => execFileSync('git', args, { cwd, stdio: 'pipe', env: { ...process.env, GIT_CONFIG_GLOBAL: '/dev/null' } }).toString();
 
@@ -93,6 +94,26 @@ test('prDraft: the run title, the brief, the boxes as the mission left them, and
   assert.match(d.body, /## Mission\n\nAdd a footer to the page\.\nKeep it small\./);
   assert.match(d.body, /## Done when\n\n- \[x\] footer\.html exists\n- \[ \] linked from index/);
   assert.match(d.body, /branch `foreman\/add-a-footer-ab12` from `main` · spend \$0\.42/);
+  assert.ok(!/## Review/.test(d.body), 'a run nobody reviewed says nothing about review');
+});
+
+test('prDraft: the reviewers and their verdicts, with the head of the findings', async () => {
+  const { prDraft } = await import('./gitwork.js');
+  const verdict = (over: Partial<ReviewVerdict>): ReviewVerdict => ({
+    presetId: 'reviewer', name: 'Reviewer', pass: true, findings: '', diffHash: 'h', workerId: 'w1', at: 1, ...over,
+  });
+  const d = prDraft(
+    { mission: 'Add a footer.', costUsd: 1, costBasis: 'priced', git: { branch: 'b', base: 'main', baseHead: null } },
+    null,
+    [
+      verdict({ findings: '- footer.html:12 the year is hard-coded' }),
+      verdict({ presetId: 'security-review', name: 'Security review', pass: false, findings: `x${'y'.repeat(2000)}` }),
+    ],
+  );
+  assert.match(d.body, /## Review\n\n\*\*Reviewer: PASS\*\*\n\n- footer\.html:12 the year is hard-coded/);
+  assert.match(d.body, /\*\*Security review: FAIL\*\*/);
+  assert.match(d.body, /… the rest is in the run's record\./, 'a long findings list is cut, not pasted whole');
+  assert.ok(d.body.length < 2000, 'the body stays a pull request, not an archive');
 });
 
 
@@ -146,3 +167,113 @@ 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/);
+});
+
+test('the fingerprint copes with awkward filenames and with a repository that has no commit', async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), 'fingerprint-git-'));
+  sh(dir, 'init', '-q', '-b', 'main');
+  sh(dir, 'config', 'user.email', 'me@example.com');
+  sh(dir, 'config', 'user.name', 'Me');
+
+  // No commit yet: `git diff HEAD` has nothing to diff against, and a run that
+  // starts a repository from nothing is an ordinary mission.
+  await writeFile(path.join(dir, 'first.txt'), 'work\n');
+  const empty = await changeFingerprint(dir);
+  assert.ok(empty, 'a repository with no HEAD still has a fingerprint');
+
+  // A name git C-quotes in `ls-files`: a quoted path handed to hash-object
+  // fails, which used to silently drop the file's content from the hash.
+  const awkward = path.join(dir, 'répertoire "odd" name.txt');
+  await writeFile(awkward, 'one\n');
+  const withAwkward = await changeFingerprint(dir);
+  assert.ok(withAwkward);
+  assert.notEqual(withAwkward, empty);
+
+  await writeFile(awkward, 'two\n');
+  assert.notEqual(await changeFingerprint(dir), withAwkward, 'editing it moves the fingerprint');
+
+  // And once there is a commit, the same file is tracked and still counts.
+  sh(dir, 'add', '-A'); sh(dir, 'commit', '-q', '-m', 'one');
+  const committed = await changeFingerprint(dir);
+  await writeFile(awkward, 'three\n');
+  assert.notEqual(await changeFingerprint(dir), committed);
+});
+
+test('the fingerprint is scoped to the project folder, and sees a retargeted symlink', async () => {
+  // A project that is a subdirectory of a bigger repository: a sibling's
+  // changes are not this mission's, and must not invalidate its review.
+  const repoRoot = await repo();
+  const project = path.join(repoRoot, 'packages', 'app');
+  await mkdir(project, { recursive: true });
+  await writeFile(path.join(project, 'index.ts'), 'export const a = 1;\n');
+  await mkdir(path.join(repoRoot, 'packages', 'other'), { recursive: true });
+  await writeFile(path.join(repoRoot, 'packages', 'other', 'index.ts'), 'export const b = 1;\n');
+  sh(repoRoot, 'add', '-A'); sh(repoRoot, 'commit', '-q', '-m', 'two packages');
+
+  const reviewed = await changeFingerprint(project);
+  assert.ok(reviewed);
+  await writeFile(path.join(repoRoot, 'packages', 'other', 'index.ts'), 'export const b = 2;\n');
+  assert.equal(await changeFingerprint(project), reviewed, 'a sibling package is not this mission');
+  await writeFile(path.join(project, 'index.ts'), 'export const a = 2;\n');
+  assert.notEqual(await changeFingerprint(project), reviewed, 'its own change still counts');
+
+  // Non-git folder: a symlink is neither file nor directory, and retargeting
+  // one changes the project without changing any content.
+  const plain = await mkdtemp(path.join(os.tmpdir(), 'links-'));
+  await writeFile(path.join(plain, 'one.txt'), 'one\n');
+  await writeFile(path.join(plain, 'two.txt'), 'two\n');
+  await symlink('one.txt', path.join(plain, 'current'));
+  const linked = await changeFingerprint(plain);
+  assert.ok(linked);
+  await unlink(path.join(plain, 'current'));
+  await symlink('two.txt', path.join(plain, 'current'));
+  assert.notEqual(await changeFingerprint(plain), linked, 'a retargeted link moves the fingerprint');
+});

package/src/gitwork.ts

@@ -8,7 +8,11 @@
  * 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 { readdir, readFile, readlink, stat } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
 import { execFile } from 'node:child_process';
+import type { ReviewVerdict } from './crew.js';
 
 export interface GitInfo {
   repo: boolean;
@@ -92,6 +96,183 @@ 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 };
+}
+
+/**
+ * A fingerprint of everything this checkout has changed, for pinning a
+ * reviewer's PASS to the code it actually read.
+ *
+ * Deliberately not computed from the deck: the deck is a *view* — it stops at
+ * 200 files and carries no binary content — so a change to the 201st file, or
+ * a swapped image, would leave a deck-derived hash identical and a stale PASS
+ * looking current. This asks git instead: the full diff against HEAD including
+ * binary deltas, plus the blob hash of every untracked file. Null when the
+ * folder is not a repository or git will not answer, which callers must treat
+ * as "cannot verify", never as "nothing changed".
+ */
+/** git's empty tree, for diffing a repository that has no commit yet. */
+const EMPTY_TREE = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
+const FINGERPRINT_FILE_CAP = 20_000;
+const FINGERPRINT_HASH_MAX_BYTES = 1024 * 1024;
+const FINGERPRINT_SKIP = new Set(['.git', '.foreman', 'node_modules']);
+
+/**
+ * The same fingerprint for a folder that is not a repository — Foreman links
+ * plain folders too, and a gate that only worked in git would make every
+ * mission in one impossible to finish.
+ *
+ * Content-hashed up to a megabyte a file, size and mtime beyond that, since
+ * reading a large binary on every gate check costs more than it proves.
+ * Dependency trees and Foreman's own directory are skipped: they are not the
+ * work under review. Null past the file cap, which the caller reads as
+ * "cannot verify" — the honest answer for a tree too large to pin.
+ */
+async function walkFingerprint(folder: string): Promise<string | null> {
+  const parts: string[] = [];
+  const walk = async (dir: string, rel: string): Promise<boolean> => {
+    const entries = await readdir(dir, { withFileTypes: true }).catch(() => null);
+    // A directory we cannot read may be where the change is. Failing open
+    // would let a PASS stand over work nobody could see.
+    if (!entries) return false;
+    for (const e of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
+      if (FINGERPRINT_SKIP.has(e.name)) continue;
+      const full = path.join(dir, e.name);
+      const here = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) {
+        if (!await walk(full, here)) return false;
+        continue;
+      }
+      // A symlink is neither a file nor a directory to readdir, and retargeting
+      // one changes what the project is without touching a byte of content.
+      if (e.isSymbolicLink()) {
+        const target = await readlink(full).catch(() => null);
+        if (target === null) return false;
+        parts.push(`${here}\0link\0${target}`);
+        continue;
+      }
+      if (!e.isFile()) continue;
+      if (parts.length >= FINGERPRINT_FILE_CAP) return false;
+      const st = await stat(full).catch(() => null);
+      if (!st) continue;
+      if (st.size <= FINGERPRINT_HASH_MAX_BYTES) {
+        const buf = await readFile(full).catch(() => null);
+        parts.push(`${here}\0${st.size}\0${buf ? createHash('sha256').update(buf).digest('hex') : 'unreadable'}`);
+      } else {
+        parts.push(`${here}\0${st.size}\0${st.mtimeMs}`);
+      }
+    }
+    return true;
+  };
+  if (!await walk(folder, '')) return null;
+  return createHash('sha256').update(parts.join('\n')).digest('hex');
+}
+
+export async function changeFingerprint(folder: string): Promise<string | null> {
+  try {
+    const inside = await git(['rev-parse', '--is-inside-work-tree'], folder).catch(() => '');
+    if (inside.trim() !== 'true') return walkFingerprint(folder);
+    // HEAD is part of the fingerprint, not just the dirty tree: a director
+    // that commits its work after a PASS leaves `git diff HEAD` empty, and a
+    // fingerprint of the diff alone would call the new commit unchanged and
+    // let the old PASS stand.
+    // A repository with no commit yet has no HEAD to diff against, and a
+    // mission that starts one is ordinary — so the comparison falls back to
+    // git's empty tree rather than failing, which would make every run with a
+    // required reviewer impossible to finish until someone committed.
+    const head = (await git(['rev-parse', 'HEAD'], folder).catch(() => '')).trim();
+    // Scoped to this folder, like the deck: a project linked as a subdirectory
+    // of a bigger repository must not have its review invalidated because a
+    // sibling project changed. `ls-files` below is already limited to the cwd.
+    const tracked = await git(
+      ['diff', head || EMPTY_TREE, '--binary', '--no-color', '--no-ext-diff', '--', '.'], folder, 60_000,
+    );
+    // -z, because `ls-files` C-quotes any path with a quote, a tab or a
+    // non-ASCII character, and a quoted path handed back to `hash-object`
+    // fails — which used to leave those files with no content in the hash at
+    // all, so edits to them were invisible to the gate.
+    const untracked = (await git(['ls-files', '--others', '--exclude-standard', '-z'], folder))
+      .split('\0')
+      // The mission doc and the crew's scratch space are Foreman's own and
+      // change constantly; they are not the work under review.
+      .filter((p) => p && !p.startsWith('.foreman/'));
+    const parts: string[] = [`HEAD\0${head || 'none'}`, tracked];
+    for (const p of untracked.sort()) {
+      // No catch: a file whose hash cannot be read is a fingerprint that
+      // cannot be trusted, and the honest answer is "cannot verify".
+      const blob = await git(['hash-object', '--', p], folder);
+      parts.push(`${p}\0${blob.trim()}`);
+    }
+    return createHash('sha256').update(parts.join('\n')).digest('hex');
+  } catch {
+    return null;
+  }
+}
+
 export async function dirtyPaths(folder: string, limit = 8): Promise<string[]> {
   try {
     const out = await git(['status', '--porcelain', '--untracked-files=normal'], folder);
@@ -207,8 +388,22 @@ export function compareUrl(remote: string | undefined, base: string, branch: str
   return `${r.web}`;
 }
 
-/** The pull request as Foreman drafts it: the run's title, and a body a reviewer can read without opening Foreman. */
-export function prDraft(run: { title?: string; mission: string; costUsd: number; costBasis?: string; git?: MissionGit }, missionDoc: string | null): { title: string; body: string } {
+/** How much of a reviewer's findings go in the body; the rest is in the run's record. */
+const FINDINGS_HEAD = 800;
+
+/**
+ * The pull request as Foreman drafts it: the run's title, and a body a reviewer
+ * can read without opening Foreman.
+ *
+ * `reviews` is passed in rather than read from the run's record here, because
+ * this module knows about git and nothing else — and because the caller is the
+ * only one that knows which verdicts are the ones this branch was judged by.
+ */
+export function prDraft(
+  run: { title?: string; mission: string; costUsd: number; costBasis?: string; git?: MissionGit },
+  missionDoc: string | null,
+  reviews?: readonly ReviewVerdict[],
+): { title: string; body: string } {
   const first = run.mission.split('\n').find((l) => l.trim())?.trim() ?? 'Mission';
   const title = (run.title || first).slice(0, 120);
   const boxes = (missionDoc ?? '').split('\n').filter((l) => /^\s*[-*] \[[ xX]\]/.test(l)).map((l) => l.trim());
@@ -217,6 +412,20 @@ export function prDraft(run: { title?: string; mission: string; costUsd: number;
     '## Mission', '', run.mission.trim(), '',
   ];
   if (boxes.length) parts.push('## Done when', '', ...boxes, '');
+  // Who reviewed this before it was offered to a human, and what they said.
+  // The whole point of the reviewer gate is that the answer travels with the
+  // work; a PASS nobody outside Foreman can see is worth nothing on a branch.
+  if (reviews?.length) {
+    parts.push('## Review', '');
+    for (const v of reviews) {
+      parts.push(`**${v.name}: ${v.pass ? 'PASS' : 'FAIL'}**`);
+      const head = v.findings.trim();
+      if (head) {
+        parts.push('', head.length > FINDINGS_HEAD ? `${head.slice(0, FINDINGS_HEAD).trimEnd()}\n\n… the rest is in the run's record.` : head);
+      }
+      parts.push('');
+    }
+  }
   parts.push('---', `Run by [Foreman](https://github.com/amenophis1er/foreman) on branch \`${run.git?.branch ?? ''}\` from \`${run.git?.base ?? ''}\` · spend ${spend}.`);
   return { title, body: parts.join('\n') };
 }

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,22 @@
  * 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';
+import type { CrewPreset, ReviewVerdict } from './crew.js';
+import { reviewReportLines } from './run-crew.js';
 
 export interface ToolResult {
   /** What the model reads. */
@@ -62,6 +67,9 @@ interface RunSummary {
   workers?: Array<{ id: string; status: string; costUsd: number; task: string }>;
   git?: { branch: string; base: string; commits?: number; pr?: string; prState?: string };
   usage?: { inputTokens: number; outputTokens: number };
+  /** Frozen at dispatch; read here only to say who was meant to review. */
+  crew?: CrewPreset[];
+  reviews?: ReviewVerdict[];
 }
 interface Need { kind: string; id: string; runId?: string; text: string; options?: string[]; toolName?: string; since?: number }
 interface ProjectCard {
@@ -70,6 +78,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)}`;
@@ -297,7 +344,7 @@ export function foremanTools(opts: ForemanClientOptions): ToolDef[] {
 
   const runReport: ToolDef = {
     name: 'run_report',
-    description: 'What a finished run produced, in one call: the director\'s final report, DONE WHEN ticks, the files it changed with +/− counts, the branch, commit and pull request, spend and crew. For a running run it reports the state so far.',
+    description: 'What a finished run produced, in one call: the director\'s final report, DONE WHEN ticks, the files it changed with +/− counts, the branch, commit and pull request, spend, crew and any review verdicts. For a running run it reports the state so far.',
     schema: { runId: z.string() },
     run: async ({ runId }) => {
       const id = String(runId);
@@ -327,9 +374,13 @@ export function foremanTools(opts: ForemanClientOptions): ToolDef[] {
         deck ? `changed: ${own.length} file${own.length === 1 ? '' : 's'} · +${deck.totals.additions} −${deck.totals.deletions}${images ? ` · ${images} screenshot${images === 1 ? '' : 's'}` : ''}${files.length > own.length ? ` · ${files.length - own.length} already dirty before the run` : ''}` : null,
         fileLines.length ? fileLines.join('\n') + (own.length > 40 ? `\n  … ${own.length - 40} more` : '') : null,
         `crew: ${(r.workers ?? []).length} worker${(r.workers ?? []).length === 1 ? '' : 's'} · ${(r.workers ?? []).filter((w) => w.status === 'done').length} done`,
+        // The verdicts, and any required reviewer standing between this run and
+        // done. Read-only, like everything else here: presets are configuration
+        // and configuration is edited on the dashboard.
+        ...reviewReportLines(r.crew, r.reviews),
         report ? `\nDirector's report:\n${report.slice(0, 4000)}` : '\nNo final report from the director yet.',
       ].filter(Boolean);
-      return { text: lines.join('\n'), data: { run: r, doneWhen: dw, files: own, totals: deck?.totals, report } };
+      return { text: lines.join('\n'), data: { run: r, doneWhen: dw, files: own, totals: deck?.totals, report, reviews: r.reviews ?? [] } };
     },
   };
 
@@ -373,6 +424,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 +537,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' },
 ];