@amenophis1er/foreman 0.1.15 → 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.15",
+  "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,9 @@ 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, ensureMissionBranch, gitInfo, missionBranchName, startMissionBranch, renameMissionBranch } from './gitwork.js';
+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();
 
@@ -108,3 +109,89 @@ test('renameMissionBranch takes the run title once there is one, and leaves a br
   sh(dir, 'checkout', '-q', 'main');
   assert.equal(await renameMissionBranch(dir, renamed!, 'Another title', '1788713434983-226123af'), null);
 });
+
+test('dirtyPaths names the uncommitted work a mission branch would carry', async () => {
+  const dir = await repo();
+  assert.deepEqual(await dirtyPaths(dir), [], 'a clean checkout carries nothing');
+
+  await writeFile(path.join(dir, 'README.md'), 'hello, edited\n');
+  await writeFile(path.join(dir, 'scratch.txt'), 'untracked\n');
+  const dirty = await dirtyPaths(dir);
+  assert.deepEqual(dirty.sort(), ['README.md', 'scratch.txt'], 'tracked edits and untracked files both count');
+
+  // The cap is for a message, not for the truth of it.
+  assert.equal((await dirtyPaths(dir, 1)).length, 1);
+  // Not a repository at all: nothing to report, and no throw.
+  assert.deepEqual(await dirtyPaths(os.tmpdir()), []);
+});
+
+test('a pull request targets the default branch when the mission was branched from a local-only branch', async () => {
+  const dir = await repo();
+  // A bare origin, the way a real clone has one.
+  const origin = await mkdtemp(path.join(os.tmpdir(), 'gitwork-origin-'));
+  execFileSync('git', ['init', '-q', '--bare', '-b', 'main', origin], { stdio: 'pipe' });
+  sh(dir, 'remote', 'add', 'origin', origin);
+  sh(dir, 'push', '-q', '-u', 'origin', 'main');
+
+  assert.equal(await defaultBranch(dir), 'main');
+  assert.equal(await remoteHasBranch(dir, 'main'), true);
+  assert.equal(await remoteHasBranch(dir, 'foreman/earlier-1234'), false);
+
+  // Branched from main: the base is real and is left alone.
+  assert.deepEqual(await resolvePrBase(dir, 'main'), { base: 'main', fellBack: false });
+
+  // The case from the field: the checkout was left on the previous mission's
+  // branch, so this mission recorded that as its base and it exists nowhere
+  // but here. gh would fail on it; the default branch is the honest target.
+  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 {
@@ -85,6 +86,89 @@ export function missionBranchName(mission: string, runId: string): string {
  * Uncommitted changes come along, as `checkout -b` always does. Resolves to
  * the record for the run, or to one sentence on why it could not.
  */
+/**
+ * The paths with uncommitted changes, tracked or untracked, capped for a
+ * message. `checkout -b` carries all of them onto the mission's branch, and
+ * the closing commit sweeps whatever is still uncommitted into the mission's
+ * 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);
+    return out.split('\n').map((l) => l.slice(3).trim()).filter(Boolean).slice(0, limit);
+  } catch {
+    return [];
+  }
+}
+
 export async function startMissionBranch(folder: string, mission: string, runId: string): Promise<MissionGit | { error: string }> {
   const info = await gitInfo(folder);
   if (!info.repo) return { error: 'not a git repository' };
@@ -245,6 +329,56 @@ export function pullRequestState(folder: string, url: string): Promise<{ state:
   });
 }
 
+/**
+ * The repository's default branch as origin sees it, from the remote HEAD git
+ * recorded at clone time, then from the usual names, and `main` as the last
+ * word. Local only: no network, so it works offline and cannot hang.
+ */
+export async function defaultBranch(folder: string): Promise<string> {
+  try {
+    const ref = (await git(['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], folder)).trim();
+    const name = ref.replace(/^origin\//, '');
+    if (name) return name;
+  } catch { /* no remote HEAD recorded */ }
+  for (const name of ['main', 'master']) {
+    try {
+      await git(['rev-parse', '--verify', `refs/remotes/origin/${name}`], folder);
+      return name;
+    } catch { /* not this one */ }
+  }
+  return 'main';
+}
+
+/** Does origin have this branch? Asks the remote, and says no if it cannot ask. */
+export async function remoteHasBranch(folder: string, branch: string): Promise<boolean> {
+  try {
+    const out = await git(['ls-remote', '--heads', 'origin', branch], folder, 10_000);
+    return out.trim().length > 0;
+  } catch {
+    // Offline or unauthenticated: fall back to what the last fetch recorded.
+    try {
+      await git(['rev-parse', '--verify', `refs/remotes/origin/${branch}`], folder);
+      return true;
+    } catch { return false; }
+  }
+}
+
+/**
+ * What a pull request from this mission should actually target.
+ *
+ * A finished mission leaves the checkout on its own branch, so the next
+ * mission is branched from *that* — and records it as its base. That base
+ * lives only on this machine, so `gh pr create --base foreman/…` fails and a
+ * compare URL built from it 404s. When the recorded base is not on the
+ * remote, the default branch is the honest target, and the caller says so
+ * rather than quietly retargeting the request.
+ */
+export async function resolvePrBase(folder: string, recorded: string): Promise<{ base: string; fellBack: boolean }> {
+  if (recorded && await remoteHasBranch(folder, recorded)) return { base: recorded, fellBack: false };
+  const base = await defaultBranch(folder);
+  return { base, fellBack: base !== recorded };
+}
+
 /** `gh pr create`, as the user. Resolves to the PR's URL, or to why not. */
 export function createPullRequest(folder: string, opts: { base: string; branch: string; title: string; body: string }): Promise<{ url?: string; error?: string }> {
   return new Promise((resolve) => {

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 () => {