@amenophis1er/foreman 0.1.10 → 0.1.13

package/README.md

@@ -230,12 +230,34 @@ result.
 ```sh
 npm ci && npm run setup      # dependencies, then the dashboard build
 npm start                    # serves http://localhost:4177
-npm test                     # 364 tests, node:test
+npm test                     # 373 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
 ```
 
+## Use Foreman from another agent
+
+`foreman mcp` serves Foreman's tools over stdio, so a Claude Code session, Codex
+or Antigravity can watch and launch missions without a polling loop:
+
+```sh
+claude mcp add foreman -- foreman mcp
+codex mcp add foreman -- foreman mcp
+agy mcp add foreman -- foreman mcp
+```
+
+Tools: `fleet_status`, `list_runs`, `run_status` (with `wait_seconds`: one call
+that returns when the run changes), `run_transcript`, `mission_doc`,
+`project_memory`, `search_runs`, `doctor`, `link_project` (folder or Git URL),
+`start_mission`, `steer`. 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.
+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.
+
 To run a checkout beside an installed Foreman on the same machine, give it its
 own port and leave the bot to the installed one:
 

package/bin/foreman.mjs

@@ -34,6 +34,7 @@ const USAGE = `foreman ${pkg.version}
   foreman uninstall          Remove the service and the background server; keeps ~/.foreman
   foreman uninstall --purge --yes   …and delete ~/.foreman (every run's history) too
   foreman completion install Tab-completion for these commands (zsh, bash, fish); or "completion zsh" to print it
+  foreman mcp                Serve Foreman's tools to another agent over stdio (claude mcp add foreman -- foreman mcp)
   foreman --version | --help
 
 Environment:
@@ -56,7 +57,7 @@ if (command === '--help' || command === '-h' || command === 'help') {
 } else if (command === 'start') {
   register();
   await import(new URL('../src/server.ts', import.meta.url).href);
-} else if (['doctor', 'open', 'service', 'up', 'down', 'stop', 'restart', 'status', 'logs', 'uninstall', 'update', 'completion'].includes(command)) {
+} else if (['doctor', 'open', 'service', 'up', 'down', 'stop', 'restart', 'status', 'logs', 'uninstall', 'update', 'completion', 'mcp'].includes(command)) {
   register();
   const { runCli } = await import(new URL('../src/cli.ts', import.meta.url).href);
   process.exitCode = await runCli(command, rest, { version: pkg.version, bin: new URL(import.meta.url) });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amenophis1er/foreman",
-  "version": "0.1.10",
+  "version": "0.1.13",
   "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",
@@ -51,6 +51,7 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.259",
+    "@modelcontextprotocol/sdk": "1.30.0",
     "@playwright/mcp": "^0.0.80",
     "qrcode": "^1.5.4",
     "tsx": "^4.23.13",

package/skills/director/SKILL.md

@@ -5,6 +5,11 @@ description: Kick off a Foreman mission for the current project — ensures the
 
 # /director — launch a Foreman mission from this session
 
+> Prefer the MCP: `claude mcp add foreman -- foreman mcp` gives this session
+> `start_mission`, `run_status` (with a wait, so no polling) and the rest as
+> tools, with the same governance. The steps below are the curl fallback for a
+> session without it.
+
 You are the launcher only. The mission itself runs in Foreman's own director
 and worker sessions with budgets, approval cards, and MISSION.md governance;
 the human supervises from the dashboard, not from this session. Do NOT do the

package/src/cli.ts

@@ -498,6 +498,13 @@ export async function runCli(command: string, rest: string[], ctx: { version: st
     case 'uninstall': return uninstall(rest);
     case 'status': return status();
     case 'doctor': return doctor();
+    case 'mcp': {
+      // Stdio is the protocol channel: nothing else may print there.
+      const { serveMcp } = await import('./mcp.js');
+      await serveMcp();
+      await new Promise(() => {}); // until the client closes the pipe
+      return 0;
+    }
     case 'completion': {
       const { completionScript, detectShell, installCompletion } = await import('./completion.js');
       const arg = rest[0];

package/src/completion.ts

@@ -25,6 +25,7 @@ export const COMMANDS: Array<[string, string]> = [
   ['service', 'Keep Foreman running at login'],
   ['uninstall', 'Remove the service and the background server'],
   ['completion', 'Shell completion: zsh, bash, fish, or install'],
+  ['mcp', 'Serve Foreman\'s tools to another agent over stdio'],
   ['help', 'Show usage'],
   ['version', 'Print the version'],
 ];

package/src/mcp.test.ts

@@ -0,0 +1,131 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, writeFile, mkdir, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { doneWhen, eventLine, foremanTools, isForemanCheckout, waitForRunEvent } from './mcp.js';
+
+/** A Foreman server as the tools see it: routes answered from a table, requests recorded. */
+function fakeServer(routes: Record<string, unknown | ((body: unknown) => unknown)>) {
+  const calls: Array<{ method: string; path: string; body?: unknown }> = [];
+  const fetchImpl = (async (input: string | URL | Request, init?: RequestInit) => {
+    const url = new URL(String(input));
+    const key = `${init?.method ?? 'GET'} ${url.pathname}${url.search}`;
+    const keyNoQuery = `${init?.method ?? 'GET'} ${url.pathname}`;
+    const body = init?.body ? JSON.parse(String(init.body)) : undefined;
+    calls.push({ method: init?.method ?? 'GET', path: url.pathname + url.search, body });
+    const hit = key in routes ? routes[key] : routes[keyNoQuery];
+    if (hit === undefined) return new Response(JSON.stringify({ error: 'not found' }), { status: 404 });
+    const val = typeof hit === 'function' ? (hit as (b: unknown) => unknown)(body) : hit;
+    if (val instanceof Response) return val;
+    return new Response(JSON.stringify(val), { status: 200, headers: { 'content-type': 'application/json' } });
+  }) as unknown as typeof fetch;
+  return { fetchImpl, calls };
+}
+
+const run = (o: Record<string, unknown> = {}) => ({
+  id: 'r1', projectId: 'p1', mission: 'Fix the thing', title: 'Fix', status: 'running', costUsd: 1.25, budgetUsd: 5,
+  costBasis: 'priced', createdAt: 1, directorModel: 'fable', workerModel: 'opus',
+  workers: [{ id: 'worker-1', status: 'done', costUsd: 0.4, task: 'write tests' }],
+  git: { branch: 'foreman/fix-r1', base: 'main' }, ...o,
+});
+const tool = (tools: ReturnType<typeof foremanTools>, name: string) => tools.find((t) => t.name === name)!;
+
+test('fleet_status reads /projects and says what needs a human', async () => {
+  const { fetchImpl } = fakeServer({
+    'GET /projects': { version: '0.1.12', projects: [
+      { id: 'p1', name: 'app', folder: '/x/app', activeRun: run(), lastRun: null, pendingPermissions: 1, pendingQuestions: 0, git: { branch: 'main' } },
+      { id: 'p2', name: 'lib', folder: '/x/lib', activeRun: null, lastRun: { id: 'r0', mission: 'Old', status: 'done', costUsd: 2, createdAt: 1 }, pendingPermissions: 0, pendingQuestions: 0 },
+    ] },
+  });
+  const r = await tool(foremanTools({ base: 'http://f', fetchImpl }), 'fleet_status').run({});
+  assert.match(r.text, /app \(p1\).*main\n  running: r1 · running · \$1\.25 of \$5\.00/);
+  assert.match(r.text, /NEEDS YOU: 1 pending/);
+  assert.match(r.text, /lib \(p2\)[^\n]*\n  idle · last: done · \$2\.00/);
+});
+
+test('run_status: crew, DONE WHEN from the mission doc, needs, and no wait on a finished run', async () => {
+  const { fetchImpl, calls } = fakeServer({
+    'GET /runs': { runs: [run({ status: 'interrupted', stopReason: 'budget' })] },
+    'GET /projects': { projects: [{ id: 'p1', name: 'app', folder: '/x/app', activeRun: null, lastRun: null, needs: [] }] },
+    'GET /missiondoc': { doc: '# M\n## DONE WHEN\n- [x] tests pass\n- [ ] docs updated\n' },
+  });
+  const r = await tool(foremanTools({ base: 'http://f', fetchImpl }), 'run_status').run({ runId: 'r1', wait_seconds: 30 });
+  assert.match(r.text, /stopped at its budget cap/);
+  assert.match(r.text, /DONE WHEN 1\/2\n  open: docs updated/);
+  assert.match(r.text, /worker-1 · done/);
+  assert.match(r.text, /changed: no/);
+  assert.ok(!calls.some((c) => c.path.startsWith('/events')), 'a finished run is never waited on');
+});
+
+test('run_status with a wait subscribes to /events and returns on the first event for that run', async () => {
+  const sse = new ReadableStream<Uint8Array>({
+    start(c) {
+      const enc = new TextEncoder();
+      c.enqueue(enc.encode(': connected\n\n'));
+      c.enqueue(enc.encode('event: cost\ndata: {"runId":"other","projectId":"p9","data":{}}\n\n'));
+      c.enqueue(enc.encode('event: worker_started\ndata: {"runId":"r1","projectId":"p1","data":{"id":"worker-2"}}\n\n'));
+    },
+  });
+  const { fetchImpl } = fakeServer({
+    'GET /runs': { runs: [run()] },
+    'GET /projects': { projects: [{ id: 'p1', name: 'app', folder: '/x/app', activeRun: run(), needs: [{ kind: 'perm', id: 'a1', runId: 'r1', text: 'director wants Bash — rm -rf dist' }] }] },
+    'GET /missiondoc': { doc: '' },
+    'GET /events': new Response(sse, { status: 200, headers: { 'content-type': 'text/event-stream' } }),
+  });
+  const r = await tool(foremanTools({ base: 'http://f', fetchImpl }), 'run_status').run({ runId: 'r1', wait_seconds: 5 });
+  assert.match(r.text, /changed: yes/);
+  assert.match(r.text, /NEEDS YOU \(1\) — only a human can answer/);
+  assert.match(r.text, /\[perm\] director wants Bash/);
+});
+
+test('waitForRunEvent gives up at the timeout when nothing arrives for the run', async () => {
+  const quiet = new ReadableStream<Uint8Array>({ start(c) { c.enqueue(new TextEncoder().encode(': connected\n\n')); } });
+  const { fetchImpl } = fakeServer({ 'GET /events': new Response(quiet, { status: 200 }) });
+  const t0 = Date.now();
+  assert.equal(await waitForRunEvent('http://f', 'r1', 1, fetchImpl), false);
+  assert.ok(Date.now() - t0 >= 900, 'waited about the timeout');
+});
+
+test('start_mission: 409 is a fact, the run id is read back, and Foreman itself is refused', async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), 'foreman-mcp-'));
+  const self = path.join(dir, 'foreman'); await mkdir(path.join(self, 'src'), { recursive: true });
+  await writeFile(path.join(self, 'package.json'), JSON.stringify({ name: 'x', bin: { foreman: 'bin/foreman.mjs' } }));
+  assert.equal(isForemanCheckout(self), true);
+  assert.equal(isForemanCheckout(dir), false);
+  let started = false;
+  const { fetchImpl, calls } = fakeServer({
+    'GET /projects': { projects: [{ id: 'p1', name: 'app', folder: dir, activeRun: null }, { id: 'pf', name: 'foreman', folder: self, activeRun: null }] },
+    'POST /run': (b: unknown) => { started = true; return (b as { projectId: string }).projectId === 'busy' ? new Response(JSON.stringify({ error: 'busy' }), { status: 409 }) : { ok: true }; },
+    'GET /runs': () => ({ runs: started ? [run({ status: 'running', budgetUsd: 3 })] : [] }),
+  });
+  const tools = foremanTools({ base: 'http://f', fetchImpl });
+  const refused = await tool(tools, 'start_mission').run({ projectId: 'pf', brief: 'Harden the server please', budgetUsd: 3 });
+  assert.match(refused.text, /Refused: this folder is Foreman itself/);
+  assert.ok(!calls.some((c) => c.method === 'POST'), 'nothing was posted for the refused one');
+  const ok = await tool(tools, 'start_mission').run({ projectId: 'p1', brief: 'Fix the flaky test in ci', budgetUsd: 3, worker: 'sonnet' });
+  assert.match(ok.text, /Started r1 on app, cap \$3\.00/);
+  assert.deepEqual(calls.find((c) => c.method === 'POST')!.body, { projectId: 'p1', mission: 'Fix the flaky test in ci', budgetUsd: 3, workerModel: 'sonnet' });
+  await rm(dir, { recursive: true, force: true });
+});
+
+test('the tool set has no human-only actions', () => {
+  const names = foremanTools({ base: 'http://f' }).map((t) => t.name);
+  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_transcript', 'mission_doc', 'project_memory', 'search_runs', 'doctor', 'link_project', 'start_mission', 'steer']);
+});
+
+test('a server that is not there is said in one sentence with the start command', async () => {
+  const fetchImpl = (async () => { throw new Error('ECONNREFUSED'); }) as unknown as typeof fetch;
+  await assert.rejects(tool(foremanTools({ base: 'http://localhost:4177', fetchImpl }), 'fleet_status').run({}), /not answering at http:\/\/localhost:4177 .*Start it with `foreman`/);
+});
+
+test('eventLine and doneWhen condense what the transcript and the doc say', () => {
+  assert.equal(eventLine('permission_request', { agent: 'director', toolName: 'Bash', decisionReason: 'leaves the folder' }), 'NEEDS YOU — director wants Bash (leaves the folder)');
+  assert.equal(eventLine('message', { agent: 'worker-1', msg: { type: 'assistant', message: { content: [{ type: 'text', text: 'Done.\n\nAll  green.' }] } } }), 'worker-1: Done. All green.');
+  assert.equal(eventLine('message', { agent: 'w', msg: { type: 'user' } }), null);
+  assert.equal(eventLine('cost', {}), null);
+  assert.deepEqual(doneWhen('- [ ] a\n* [x] b\n- [X] c\nnot a box'), { done: ['b', 'c'], open: ['a'] });
+});

package/src/mcp.ts

@@ -0,0 +1,402 @@
+/**
+ * `foreman mcp` — Foreman for other agents.
+ *
+ * A stdio MCP server another agent starts on demand (Claude Code, Codex,
+ * Antigravity: `<client> mcp add foreman -- foreman mcp`). Deliberately thin:
+ * every tool is a call to the running Foreman server over the same REST and
+ * event stream the dashboard uses, so policy lives in one place — the server
+ * — and this file has no business logic of its own.
+ *
+ * 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.
+ *
+ * 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
+ * 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';
+
+export interface ToolResult {
+  /** What the model reads. */
+  text: string;
+  /** The same facts, structured. */
+  data?: unknown;
+}
+
+export interface ToolDef {
+  name: string;
+  description: string;
+  schema: z.ZodRawShape;
+  run: (args: Record<string, unknown>) => Promise<ToolResult>;
+}
+
+export interface ForemanClientOptions {
+  /** Where Foreman answers; `FOREMAN_URL` or http://127.0.0.1:4177. */
+  base: string;
+  fetchImpl?: typeof fetch;
+  /** Longest a `wait` may block, in seconds. */
+  maxWaitSeconds?: number;
+}
+
+const usd = (n: number) => `$${n.toFixed(2)}`;
+
+/** A folder that is Foreman itself: never a mission target (the oversight rule). */
+export function isForemanCheckout(folder: string): boolean {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(folder, 'package.json'), 'utf8')) as { bin?: Record<string, string> | string };
+    if (pkg.bin && typeof pkg.bin === 'object' && 'foreman' in pkg.bin) return true;
+  } catch { /* no package.json, or not ours */ }
+  return fs.existsSync(path.join(folder, 'src', 'orchestrator.ts')) && fs.existsSync(path.join(folder, 'src', 'policy.ts'));
+}
+
+interface RunSummary {
+  id: string; projectId?: string; mission: string; title?: string; status: string;
+  costUsd: number; budgetUsd: number; costBasis?: string; createdAt: number; endedAt?: number;
+  directorModel?: string; workerModel?: string; resumes?: number; stopReason?: string;
+  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 };
+}
+interface Need { kind: string; id: string; runId?: string; text: string; options?: string[]; toolName?: string; since?: number }
+interface ProjectCard {
+  id: string; name: string; folder: string; activeRun: RunSummary | null;
+  lastRun: { id: string; title?: string; mission: string; status: string; costUsd: number; createdAt: number } | null;
+  pendingPermissions: number; pendingQuestions: number; needs?: Need[]; git?: { branch?: string; dirty?: boolean } | null;
+}
+
+/** 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)}`;
+  return `${r.id} · ${r.status}${r.stopReason ? ` (stopped at its ${r.stopReason} cap)` : ''} · ${cost} · ${r.title || r.mission.slice(0, 80)}`;
+}
+
+/** A transcript event as one line; null for noise. */
+export function eventLine(event: string, d: Record<string, unknown>): string | null {
+  const s = (k: string) => (typeof d[k] === 'string' ? (d[k] as string) : '');
+  switch (event) {
+    case 'run_started': return 'run started';
+    case 'run_resumed': return 'run resumed';
+    case 'run_finished': return `run finished: ${s('status')}`;
+    case 'worker_started': return `${s('id')} started: ${s('task').slice(0, 120)}`;
+    case 'worker_finished': return `${s('id')} finished: ${s('status')}`;
+    case 'worker_progress': return `${s('id')}: ${d.blocked ? `BLOCKED — ${String(d.blocked)}` : s('status')}`;
+    case 'permission_request': return `NEEDS YOU — ${s('agent')} wants ${s('toolName')}${s('decisionReason') ? ` (${s('decisionReason')})` : ''}`;
+    case 'permission_resolved': return `approval ${s('behavior')}`;
+    case 'permission_timeout': return 'approval timed out (unattended default applied)';
+    case 'question': return `NEEDS YOU — director asks: ${s('question')}`;
+    case 'question_answered': return 'question answered';
+    case 'budget_alert': case 'budget_stop': case 'models_changed': case 'settings_changed': case 'mission_incomplete':
+      return s('text') || s('reason') || (Array.isArray(d.changes) ? (d.changes as string[]).join('; ') : null) || event;
+    case 'git_branch': return `on branch ${s('branch')}`;
+    case 'git_committed': return s('text') || 'branch closed';
+    case 'pull_request': return s('url') ? `pull request: ${s('url')}` : null;
+    case 'memory_updated': return 'project memory rewritten';
+    case 'steer': return `operator → ${s('to')}: ${s('text')}`;
+    case 'message': {
+      const msg = d.msg as { type?: string; message?: { content?: Array<{ type: string; text?: string; name?: string }> } } | undefined;
+      if (msg?.type !== 'assistant') return null;
+      const block = msg.message?.content?.find((c) => c.type === 'text' && c.text) ?? msg.message?.content?.find((c) => c.type === 'tool_use');
+      if (!block) return null;
+      return block.type === 'text' ? `${s('agent')}: ${(block.text ?? '').replace(/\s+/g, ' ').slice(0, 200)}` : `${s('agent')} → ${block.name}`;
+    }
+    default: return null;
+  }
+}
+
+/** DONE WHEN lines from a mission doc: ticked and unticked. */
+export function doneWhen(doc: string): { done: string[]; open: string[] } {
+  const done: string[] = []; const open: string[] = [];
+  for (const line of doc.split('\n')) {
+    const m = /^\s*[-*]\s*\[( |x|X)\]\s+(.*)$/.exec(line);
+    if (!m) continue;
+    (m[1].trim() ? done : open).push(m[2].trim());
+  }
+  return { done, open };
+}
+
+/**
+ * Waits for the next event on a run, over the server's own SSE stream. One
+ * subscription per call, filtered to the run; resolves true on the first
+ * event that names it, false at the timeout. Never polls.
+ */
+export async function waitForRunEvent(base: string, runId: string, seconds: number, fetchImpl: typeof fetch): Promise<boolean> {
+  const ctl = new AbortController();
+  let reader: ReadableStreamDefaultReader<Uint8Array> | null = null;
+  // The clock wins whatever the stream does: a fetch that ignores the abort
+  // signal, or a body that never yields, must not hold the caller past the
+  // seconds it asked for.
+  const timeout = new Promise<false>((resolve) => setTimeout(() => { ctl.abort(); void reader?.cancel().catch(() => {}); resolve(false); }, Math.max(1, seconds) * 1000));
+  const watch = (async (): Promise<boolean> => {
+    try {
+      const res = await fetchImpl(`${base}/events`, { signal: ctl.signal, headers: { accept: 'text/event-stream' } });
+      if (!res.ok || !res.body) return false;
+      reader = res.body.getReader();
+      const decoder = new TextDecoder();
+      let buf = '';
+      for (;;) {
+        const { value, done } = await reader.read();
+        if (done) return false;
+        buf += decoder.decode(value, { stream: true });
+        let nl: number;
+        while ((nl = buf.indexOf('\n')) >= 0) {
+          const line = buf.slice(0, nl).trimEnd();
+          buf = buf.slice(nl + 1);
+          if (!line.startsWith('data:')) continue;
+          try {
+            const env = JSON.parse(line.slice(5).trim()) as { runId?: string | null };
+            if (env.runId === runId) { ctl.abort(); void reader.cancel().catch(() => {}); return true; }
+          } catch { /* a comment or a partial frame */ }
+        }
+      }
+    } catch {
+      return false;
+    }
+  })();
+  return Promise.race([watch, timeout]);
+}
+
+/** The tools, as data — the MCP server registers them; the tests call them. */
+export function foremanTools(opts: ForemanClientOptions): ToolDef[] {
+  const base = opts.base.replace(/\/+$/, '');
+  const f = opts.fetchImpl ?? fetch;
+  const maxWait = opts.maxWaitSeconds ?? 300;
+
+  async function get<T>(p: string): Promise<T> {
+    let res: Response;
+    try { res = await f(`${base}${p}`); } catch (err) {
+      throw new Error(`Foreman is not answering at ${base} (${err instanceof Error ? err.message : String(err)}). Start it with \`foreman\`, or set FOREMAN_URL.`);
+    }
+    if (!res.ok) throw new Error(`${p}: HTTP ${res.status} ${(await res.text()).slice(0, 200)}`);
+    return res.json() as Promise<T>;
+  }
+  async function post<T>(p: string, body: unknown): Promise<{ ok: boolean; status: number; json: T }> {
+    let res: Response;
+    try { res = await f(`${base}${p}`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) }); } catch (err) {
+      throw new Error(`Foreman is not answering at ${base} (${err instanceof Error ? err.message : String(err)}). Start it with \`foreman\`, or set FOREMAN_URL.`);
+    }
+    const json = await res.json().catch(() => ({})) as T;
+    return { ok: res.ok, status: res.status, json };
+  }
+  async function findRun(runId: string): Promise<RunSummary> {
+    const { runs } = await get<{ runs: RunSummary[] }>('/runs');
+    const r = runs.find((x) => x.id === runId);
+    if (!r) throw new Error(`No run ${runId}. list_runs shows what exists.`);
+    return r;
+  }
+
+  const fleet: ToolDef = {
+    name: 'fleet_status',
+    description: 'Every linked project with what it is doing: the active mission (status, spend against cap, crew), what needs a human, and the last finished run. Start here.',
+    schema: {},
+    run: async () => {
+      const d = await get<{ projects: ProjectCard[]; authMode?: string; version?: string }>('/projects');
+      const lines = d.projects.map((p) => {
+        const a = p.activeRun;
+        const needs = (p.pendingPermissions ?? 0) + (p.pendingQuestions ?? 0);
+        const head = `${p.name} (${p.id}) — ${p.folder}${p.git?.branch ? ` · ${p.git.branch}` : ''}`;
+        if (a) return `${head}\n  running: ${runLine(a)}${needs ? `\n  NEEDS YOU: ${needs} pending — the human decides these on the dashboard or phone` : ''}`;
+        if (p.lastRun) return `${head}\n  idle · last: ${p.lastRun.status} · ${usd(p.lastRun.costUsd)} · ${p.lastRun.title || p.lastRun.mission.slice(0, 80)}`;
+        return `${head}\n  idle · no runs yet`;
+      });
+      return {
+        text: lines.length ? lines.join('\n') : 'No projects linked. link_project adds one.',
+        data: { version: d.version, authMode: d.authMode, projects: d.projects.map((p) => ({ id: p.id, name: p.name, folder: p.folder, branch: p.git?.branch, activeRun: p.activeRun && { id: p.activeRun.id, status: p.activeRun.status, costUsd: p.activeRun.costUsd, budgetUsd: p.activeRun.budgetUsd }, needs: p.needs ?? [], lastRun: p.lastRun })) },
+      };
+    },
+  };
+
+  const listRuns: ToolDef = {
+    name: 'list_runs',
+    description: 'Run summaries, newest first, optionally for one project.',
+    schema: { projectId: z.string().optional(), limit: z.number().int().min(1).max(100).default(20) },
+    run: async ({ projectId, limit }) => {
+      const { runs } = await get<{ runs: RunSummary[] }>(`/runs${projectId ? `?projectId=${encodeURIComponent(String(projectId))}` : ''}`);
+      const shown = runs.slice(0, Number(limit ?? 20));
+      return { text: shown.length ? shown.map(runLine).join('\n') : 'No runs.', data: { runs: shown } };
+    },
+  };
+
+  const runStatus: ToolDef = {
+    name: 'run_status',
+    description: 'One run: status, spend against cap, crew and their states, DONE WHEN ticks, what needs a human, branch and pull request. With wait_seconds > 0 it returns as soon as anything changes on that run (or at the timeout) — use it instead of polling.',
+    schema: { runId: z.string(), wait_seconds: z.number().int().min(0).max(maxWait).default(0) },
+    run: async ({ runId, wait_seconds }) => {
+      const id = String(runId);
+      let changed: boolean | undefined;
+      if (Number(wait_seconds) > 0) {
+        const before = await findRun(id);
+        if (before.status === 'running') changed = await waitForRunEvent(base, id, Number(wait_seconds), f);
+        else changed = false;
+      }
+      const r = await findRun(id);
+      const projects = (await get<{ projects: ProjectCard[] }>('/projects')).projects;
+      const card = projects.find((p) => p.activeRun?.id === id);
+      const needs = (card?.needs ?? []).filter((n) => !n.runId || n.runId === id);
+      const doc = await get<{ doc: string }>(`/missiondoc?run=${encodeURIComponent(id)}`).then((d) => d.doc).catch(() => '');
+      const dw = doneWhen(doc);
+      const workers = (r.workers ?? []).map((w) => `  ${w.id} · ${w.status} · ${usd(w.costUsd)} · ${w.task.slice(0, 80)}`);
+      const lines = [
+        runLine(r),
+        `director ${r.directorModel ?? 'default'} · workers ${r.workerModel ?? 'default'} · resumes ${r.resumes ?? 0}`,
+        r.git ? `branch ${r.git.branch} from ${r.git.base}${r.git.pr ? ` · PR ${r.git.pr}${r.git.prState ? ` (${r.git.prState})` : ''}` : ''}` : null,
+        dw.done.length + dw.open.length ? `DONE WHEN ${dw.done.length}/${dw.done.length + dw.open.length}${dw.open.length ? `\n  open: ${dw.open.join('\n  open: ')}` : ''}` : null,
+        workers.length ? `crew:\n${workers.join('\n')}` : null,
+        needs.length ? `NEEDS YOU (${needs.length}) — only a human can answer these, on the dashboard or the phone:\n${needs.map((n) => `  [${n.kind}] ${n.text}`).join('\n')}` : null,
+        changed !== undefined ? (changed ? 'changed: yes' : 'changed: no (timeout)') : null,
+      ].filter(Boolean);
+      return { text: lines.join('\n'), data: { run: r, doneWhen: dw, needs, changed } };
+    },
+  };
+
+  const transcript: ToolDef = {
+    name: 'run_transcript',
+    description: 'The run\'s recent events, one line each, oldest first. since_ts (ms) narrows to what happened after a moment you already read.',
+    schema: { runId: z.string(), since_ts: z.number().optional(), limit: z.number().int().min(1).max(500).default(50) },
+    run: async ({ runId, since_ts, limit }) => {
+      const { events } = await get<{ events: Array<{ ts: number; event: string; data: Record<string, unknown> }> }>(`/runs/${encodeURIComponent(String(runId))}/events`);
+      const lines: Array<{ ts: number; line: string }> = [];
+      for (const e of events) {
+        if (since_ts && e.ts <= Number(since_ts)) continue;
+        const line = eventLine(e.event, e.data ?? {});
+        if (line) lines.push({ ts: e.ts, line });
+      }
+      const shown = lines.slice(-Number(limit ?? 50));
+      return {
+        text: shown.length ? shown.map((l) => `${new Date(l.ts).toISOString().slice(11, 19)} ${l.line}`).join('\n') : 'Nothing yet.',
+        data: { events: shown, lastTs: shown.at(-1)?.ts ?? null },
+      };
+    },
+  };
+
+  const missionDoc: ToolDef = {
+    name: 'mission_doc',
+    description: 'The run\'s MISSION.md: DONE WHEN criteria, log, state — what the director itself keeps.',
+    schema: { runId: z.string() },
+    run: async ({ runId }) => {
+      const { doc } = await get<{ doc: string }>(`/missiondoc?run=${encodeURIComponent(String(runId))}`);
+      return { text: doc || 'MISSION.md not written yet.', data: { doc } };
+    },
+  };
+
+  const memory: ToolDef = {
+    name: 'project_memory',
+    description: 'The project\'s memory (.foreman/MEMORY.md): what earlier crews learned — how to run and test it, ports, traps.',
+    schema: { projectId: z.string() },
+    run: async ({ projectId }) => {
+      const d = await get<{ text: string; updatedAt?: number }>(`/projects/${encodeURIComponent(String(projectId))}/memory`);
+      return { text: d.text || 'No memory yet.', data: d };
+    },
+  };
+
+  const search: ToolDef = {
+    name: 'search_runs',
+    description: 'Runs across the fleet whose title, brief, project or folder match.',
+    schema: { q: z.string().min(1) },
+    run: async ({ q }) => {
+      const d = await get<{ runs: RunSummary[] }>(`/search?q=${encodeURIComponent(String(q))}`);
+      return { text: d.runs.length ? d.runs.map(runLine).join('\n') : 'No match.', data: d };
+    },
+  };
+
+  const doctor: ToolDef = {
+    name: 'doctor',
+    description: 'What this machine has for missions: credentials, providers, browser, reach — the same checks as `foreman doctor`.',
+    schema: {},
+    run: async () => {
+      const d = await get<{ checks: Array<{ name: string; status: string; detail: string; fix?: string }> }>('/doctor');
+      return { text: d.checks.map((c) => `${c.status === 'ok' ? '✓' : c.status === 'warn' ? '!' : '✗'} ${c.name}: ${c.detail}${c.fix && c.status !== 'ok' ? `\n    ${c.fix}` : ''}`).join('\n'), data: d };
+    },
+  };
+
+  const link: ToolDef = {
+    name: 'link_project',
+    description: 'Link a folder on this machine as a project (idempotent), or clone a Git URL under the projects root and link it. Returns the project id.',
+    schema: { folder: z.string().optional(), git_url: z.string().optional(), branch: z.string().optional() },
+    run: async ({ folder, git_url, branch }) => {
+      if (git_url) {
+        const started = await post<{ id?: string; dest?: string; error?: string }>('/projects/clone', { url: git_url, branch });
+        if (!started.ok) return { text: `Could not start the clone: ${started.json.error ?? started.status}` };
+        for (let i = 0; i < 600; i++) {
+          const job = await get<{ state: string; progress: string; projectId?: string; error?: string }>(`/projects/clone/${started.json.id}`);
+          if (job.state === 'done') return { text: `Cloned to ${started.json.dest} and linked as project ${job.projectId}.`, data: { projectId: job.projectId, folder: started.json.dest } };
+          if (job.state === 'error') return { text: `Clone failed: ${job.error}` };
+          await new Promise((r) => setTimeout(r, 1000));
+        }
+        return { text: 'The clone is still running; check fleet_status in a minute.' };
+      }
+      if (!folder) return { text: 'Give a folder path or a git_url.' };
+      const abs = path.resolve(String(folder));
+      const r = await post<{ project?: { id: string; name: string; folder: string }; error?: string }>('/projects', { folder: abs });
+      if (!r.ok || !r.json.project) return { text: `Could not link ${abs}: ${r.json.error ?? r.status}` };
+      return { text: `Linked ${r.json.project.name} (${r.json.project.id}) at ${r.json.project.folder}.`, data: r.json.project };
+    },
+  };
+
+  const start: ToolDef = {
+    name: 'start_mission',
+    description: 'Start a mission on a project: the brief, a dollar cap, optional director/worker models and a browser. The mission runs in Foreman under its own governance; approvals and questions go to the human on the dashboard or phone, never through this tool. Follow with run_status(wait_seconds).',
+    schema: {
+      projectId: z.string(), brief: z.string().min(10), budgetUsd: z.number().positive(),
+      director: z.string().optional(), worker: z.string().optional(), browser: z.boolean().optional(),
+    },
+    run: async ({ projectId, brief, budgetUsd, director, worker, browser }) => {
+      const pid = String(projectId);
+      const projects = (await get<{ projects: ProjectCard[] }>('/projects')).projects;
+      const p = projects.find((x) => x.id === pid);
+      if (!p) return { text: `No project ${pid}. fleet_status lists them; link_project adds one.` };
+      if (isForemanCheckout(p.folder)) return { text: 'Refused: this folder is Foreman itself, and Foreman never runs missions on its own oversight infrastructure.' };
+      const r = await post<{ ok?: boolean; error?: string }>('/run', {
+        projectId: pid, mission: brief, budgetUsd, directorModel: director, workerModel: worker, browserTools: browser === true ? true : undefined,
+      });
+      if (r.status === 409) return { text: `${p.name} already has an active mission; see fleet_status. One mission per project at a time.` };
+      if (!r.ok) return { text: `Could not start: ${r.json.error ?? r.status}` };
+      // The run id lands a moment later; read it back so the caller can watch it.
+      for (let i = 0; i < 20; i++) {
+        const { runs } = await get<{ runs: RunSummary[] }>(`/runs?projectId=${encodeURIComponent(pid)}`);
+        const live = runs.find((x) => x.status === 'running');
+        if (live) return { text: `Started ${live.id} on ${p.name}, cap ${usd(live.budgetUsd)}. Watch it with run_status(runId, wait_seconds).`, data: { runId: live.id, projectId: pid } };
+        await new Promise((res) => setTimeout(res, 250));
+      }
+      return { text: `Started on ${p.name}; the run id was not visible yet — list_runs will show it.`, data: { projectId: pid } };
+    },
+  };
+
+  const steer: ToolDef = {
+    name: 'steer',
+    description: 'Send an operator note to a running director (a hint, a priority, a correction). Relays the human; it does not approve anything.',
+    schema: { runId: z.string(), text: z.string().min(1) },
+    run: async ({ runId, text }) => {
+      const r = await post<{ ok?: boolean; error?: string }>('/steer', { runId, text });
+      return { text: r.ok ? 'Delivered to the director for its next turn.' : `Could not steer: ${r.json.error ?? r.status}` };
+    },
+  };
+
+  return [fleet, listRuns, runStatus, transcript, missionDoc, memory, 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. */
+// 127.0.0.1 rather than localhost: a stray process on the IPv6 wildcard
+// (a worker's dev server, once) answers `localhost` first in most resolvers
+// and would shadow Foreman for this client too. FOREMAN_URL overrides.
+export async function serveMcp(base = process.env.FOREMAN_URL || 'http://127.0.0.1:4177'): Promise<void> {
+  const { McpServer } = await import('@modelcontextprotocol/sdk/server/mcp.js');
+  const { StdioServerTransport } = await import('@modelcontextprotocol/sdk/server/stdio.js');
+  const server = new McpServer({ name: 'foreman', version: '1' });
+  for (const t of foremanTools({ base })) {
+    server.registerTool(t.name, { description: t.description, inputSchema: t.schema }, async (args: Record<string, unknown>) => {
+      try {
+        const r = await t.run(args ?? {});
+        return { content: [{ type: 'text' as const, text: r.text }], ...(r.data !== undefined ? { structuredContent: r.data as Record<string, unknown> } : {}) };
+      } catch (err) {
+        return { content: [{ type: 'text' as const, text: err instanceof Error ? err.message : String(err) }], isError: true };
+      }
+    });
+  }
+  await server.connect(new StdioServerTransport());
+}

package/src/provider.test.ts

@@ -364,3 +364,19 @@ test('a role provider carries the role’s model, so every alias resolves on its
   assert.equal(withRoleModel(bare, '').model, undefined);
   assert.equal(withRoleModel(bare, undefined), bare, 'no change returns the same object');
 });
+
+
+test('agents do not inherit the server\'s own environment: PORT and FOREMAN_* are dropped', async () => {
+  const saved = { PORT: process.env.PORT, FOREMAN_HOME: process.env.FOREMAN_HOME, FOREMAN_BIND: process.env.FOREMAN_BIND };
+  process.env.PORT = '4177'; process.env.FOREMAN_HOME = '/tmp/fh'; process.env.FOREMAN_BIND = 'all';
+  try {
+    const p = await resolveProvider({ kind: 'claude-code' }, '/tmp/foreman-test-root');
+    const env = providerEnv(p).env ?? {};
+    assert.equal(env.PORT, undefined, 'a dev server a worker starts must not bind the dashboard port');
+    assert.equal(env.FOREMAN_HOME, undefined);
+    assert.equal(env.FOREMAN_BIND, undefined);
+    assert.ok(env.PATH, 'the rest of the environment survives');
+  } finally {
+    for (const [k, v] of Object.entries(saved)) { if (v === undefined) delete process.env[k]; else process.env[k] = v; }
+  }
+});

package/src/provider.ts

@@ -427,8 +427,22 @@ export interface AgentEnv {
  * programming error rather than a user error, and the failure mode it guards
  * against is a leaked token, so it fails loudly instead of degrading.
  */
+/**
+ * The server's own knobs, which an agent must not inherit. `PORT` is the one
+ * that bit: the service sets it for the dashboard, an agent's dev server
+ * honoured it, bound Foreman's port on a wildcard address and shadowed the
+ * dashboard on localhost until it exited. The rest are Foreman's operating
+ * settings — none of them means anything to a project's own tooling, and a
+ * worker reading `FOREMAN_HOME` would only find somewhere it should not be.
+ */
+const SERVER_ONLY_VARS = [
+  'PORT', 'FOREMAN_SERVICES_PORT', 'FOREMAN_HOME', 'FOREMAN_BIND', 'FOREMAN_BROWSER',
+  'FOREMAN_AUTH_MODE', 'FOREMAN_CLAUDE_CONFIG_DIR', 'FOREMAN_CLAUDE_EXECUTABLE', 'FOREMAN_NO_TELEGRAM', 'FOREMAN_LOG',
+];
+
 export function providerEnv(p: ResolvedProvider, gatewayUrl?: string): AgentEnv {
   const env: Record<string, string | undefined> = { ...process.env };
+  for (const v of SERVER_ONLY_VARS) delete env[v];
   env.CLAUDE_CONFIG_DIR = p.configDir;
 
   if (p.wire === 'anthropic-native') {