@amenophis1er/foreman 0.1.7 → 0.1.8

package/src/server.ts

@@ -24,10 +24,17 @@
  *   POST   /runs/{id}/resume     Resume an interrupted/failed run
  *   POST   /permission           Resolve an approval {id, behavior, message?}
  *   POST   /answer               Answer a director question {id, text}
+ *   POST   /projects/clone        Clone a Git URL under the projects root and link it {url, branch?} → {id}; GET /projects/clone/{id} polls
+ *   GET    /projects/{id}/memory  The project's memory (.foreman/MEMORY.md): text, updatedAt
+ *   GET    /projects/{id}/tree    The project's files as they stand (read-only, jailed); …/artifact and …/preview as for runs
+ *   GET    /doctor                The same checks `foreman doctor` runs, for the first-run card
  *   GET    /search?q=            Runs across the fleet matching title, brief, project or folder
  *   POST   /fleet/chat           One turn with the fleet planner {text} → {text, costUsd}
  *   POST   /fleet/stop           Stop the fleet planner reply in flight
  *   DELETE /fleet/chat           Forget the fleet conversation
+ *   GET    /runs/{id}/pr         The pull request Foreman would draft for a finished run on its own branch
+ *   POST   /runs/{id}/pr         Push that branch and open the PR (gh) or hand back the compare URL {title, body}
+ *   GET    /runs/{id}/pr/state   open | merged | closed, from gh; a final answer is remembered on the run
  *   POST   /steer                Send an operator note to a running director {runId, text}
  *   POST   /interrupt            Interrupt a run {runId}
  *   GET    /runs?projectId=      Persisted run summaries, newest first
@@ -47,7 +54,7 @@
 import http from 'node:http';
 import crypto from 'node:crypto';
 import os from 'node:os';
-import { mkdir, readFile, readdir, stat } from 'node:fs/promises';
+import { mkdir, readFile, readdir, rm, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { MissionRun } from './orchestrator.js';
@@ -57,10 +64,18 @@ import {
   dropPendingAsk,
 } from './planner.js';
 import { DEFAULT_TOOL_POLICY } from './policy.js';
+import { pathPermitted, requestAllowed } from './guard.js';
+import { BodyError, bodyLimitFor, parseBody } from './http-body.js';
 import { saveAttachments } from './attachments.js';
+import { cloneRepo, looksLikeRepoUrl, parseRepoUrl } from './clone.js';
+import { readMemory } from './memory.js';
+import { budgetAnchor, modelRecords, projectRecord, recordLine } from './track-record.js';
+import { reconcileRole } from './role-provider.js';
+import { detectBrowser, installChromium } from './browser.js';
+import { closeMissionBranch, compareUrl, createPullRequest, ensureMissionBranch, ghReady, gitInfo, prDraft, pullRequestState, pushBranch, startMissionBranch, type GitInfo } from './gitwork.js';
 import { detectTailscale, tailnetUrl } from './tailscale.js';
 import { checkForUpdate, currentVersion, type UpdateInfo } from './update.js';
-import { ServiceRegistry, SVC_PREFIX, parseServicePath, portOpen, proxyToService, servicePath } from './services.js';
+import { ServiceRegistry, portOpen, servicesHandler } from './services.js';
 import { HELP_TEXT, expandHome, parseCommand, projectsRoot, slug } from './notify/commands.js';
 import {
   DEFAULT_FLEET_MODEL, FLEET_CHAT_ID, PHONE_CONTEXT_MS, phoneRoute, runFleetTurn,
@@ -229,6 +244,8 @@ interface ModelOption {
   providerLabel: string;
   cost?: number;
   note?: string;
+  /** Its track record on this machine, from the run ledger; absent until it has one. */
+  record?: string;
   /** What spending on this model is: priced, free, or real-but-unquantified. */
   costBasis: CostBasis;
   /** @deprecated Mirrors `costBasis === 'priced'` for older clients. */
@@ -249,6 +266,15 @@ async function availableModels(project: Project | null): Promise<{
   reachable: boolean;
 }> {
   const out: ModelOption[] = [];
+  // The ledger, read back: each model's record across every run on this
+  // machine, attached as one line so the picker and the planner can weigh
+  // "cheap" against "finished last time".
+  const records = modelRecords(await store.listRuns().catch(() => []));
+  const withRecord = (m: ModelOption): ModelOption => {
+    const r = records.get(m.id) ?? records.get(m.model) ?? records.get(m.label);
+    const line = recordLine(r);
+    return line ? { ...m, record: line } : m;
+  };
 
   // Anthropic, via whichever Claude Code install or key the server resolves.
   // Always offered: it is the default, and the shipped configuration.
@@ -326,7 +352,7 @@ async function availableModels(project: Project | null): Promise<{
       count: out.filter((x) => x.providerLabel === m.providerLabel).length,
     }));
 
-  return { models: out, groups, reachable: true };
+  return { models: out.map(withRecord), groups, reachable: true };
 }
 
 /**
@@ -347,6 +373,26 @@ function providerForRole(meta: RunMeta, roleProviderId?: string): ProviderRef {
   return own;
 }
 
+
+/**
+ * The one provider problem `resolveProvider` cannot see: a Claude Code
+ * provider whose install is not signed in. Resolution only names the config
+ * dir; whether anything is logged into it is a fact about the machine, read
+ * fresh here so a login done a minute ago counts. Said in Foreman's words,
+ * because the SDK's own — "Not logged in · Please run /login" — reads like a
+ * Foreman slash command and names nothing the person can do from here.
+ */
+async function signedInProblem(resolved: ResolvedProvider): Promise<string | null> {
+  if (resolved.kind !== 'claude-code') return null;
+  const signedIn = resolved.ownLogin
+    ? await dirHasCredentials(resolved.configDir)
+    : (await detectAuth()).mode !== 'none';
+  if (signedIn) return null;
+  return 'Claude Code is not signed in on this machine, so nothing can run on it yet. ' +
+    'Sign in — run `claude` in a terminal, then `/login` — and restart Foreman; ' +
+    'or give this project a provider of its own (an Anthropic API key, Codex, or an OpenAI-compatible endpoint) in Settings → Provider.';
+}
+
 /** Whether a project's provider has a key on file. Never the key itself. */
 async function providerHasKeyOf(p: Project): Promise<boolean> {
   const ref = providerOf(p);
@@ -369,7 +415,6 @@ function toPath(v: unknown): string | undefined {
   return typeof v === 'string' && v.trim() ? v.trim() : undefined;
 }
 
-/** Parses a model choice: a known alias or a full claude-* id; else inherit. */
 /**
  * A model id from any provider.
  *
@@ -420,6 +465,19 @@ async function locateFolders(name: string): Promise<string[]> {
 }
 
 const PORT = Number(process.env.PORT ?? 4177);
+/**
+ * Where the dev servers the crew exposed are proxied — a second port, and so a
+ * second origin. Those pages are written by an agent, and a browser gives a
+ * page the run of every API on its own origin: served from Foreman's port, an
+ * exposed preview could start missions, read the folder tree and spend the
+ * budget with a line of fetch(). On a port of its own the same-origin policy
+ * does that refusing for us. FOREMAN_SERVICES_PORT overrides; PORT + 1 by default.
+ */
+const SERVICES_PORT = (() => {
+  const raw = process.env.FOREMAN_SERVICES_PORT;
+  const n = Number(raw);
+  return raw && Number.isInteger(n) && n >= 1 && n <= 65535 ? n : PORT + 1;
+})();
 /**
  * Where to listen. Default: loopback, plus the tailnet address when this
  * machine is on one — never every interface, since there is no login.
@@ -452,12 +510,30 @@ const authPromise = detectAuth();
 const activeByProject = new Map<string, MissionRun | null>();
 const sseClients = new Set<http.ServerResponse>();
 
+/**
+ * A comment frame down every open stream, often enough that nothing in the
+ * middle calls the connection dead.
+ *
+ * A quiet fleet produces no events for minutes at a time, and an idle stream
+ * is exactly what proxies (`tailscale serve`, anything else in front) and
+ * phone radios reclaim — the dashboard then sits there looking live while
+ * receiving nothing. `:` starts a comment in the SSE grammar, so this costs
+ * the client nothing to parse and never reaches an event handler. Unref'd:
+ * it must not be the reason the process stays up. Clients that have gone
+ * away are dropped here rather than waiting for a real event to notice.
+ */
+setInterval(() => {
+  for (const res of sseClients) {
+    if (res.destroyed || res.writableEnded) { sseClients.delete(res); continue; }
+    try { res.write(': ping\n\n'); } catch { sseClients.delete(res); }
+  }
+}, 25_000).unref();
+
 function activeRuns(): MissionRun[] {
   // Filter out reservation placeholders (see reserveProject).
   return [...activeByProject.values()].filter((r): r is MissionRun => Boolean(r));
 }
 
-/** Broadcasts an enveloped frame to live clients and persists the bare event. */
 /**
  * What happened in the fleet lately, in one line each, for the front desk.
  *
@@ -560,10 +636,6 @@ function ledgerKeyFor(meta: RunMeta): string {
   return `${meta.id}.${meta.resumes ?? 0}`;
 }
 
-/**
- * Chat frames carry `chat: true` and no run id, so a UI following the same
- * stream can tell a planning conversation from a mission without guessing.
- */
 /**
  * A chat event for open tabs only, not the log: the log it would describe
  * is the one being thrown away. Used when a conversation is cleared, so a
@@ -736,6 +808,55 @@ async function findProject(ref: string): Promise<Project | null> {
     ?? null;
 }
 
+// ---------------------------------------------------------------------------
+// Linking a repository: clone under the projects root, then link the folder
+// ---------------------------------------------------------------------------
+
+interface CloneJob {
+  id: string; url: string; dest: string; startedAt: number;
+  state: 'running' | 'done' | 'error'; progress: string; projectId?: string; error?: string;
+}
+/** Clones in flight or recently finished, for the picker to poll. Memory only; a restart forgets them (the folder stays). */
+const cloneJobs = new Map<string, CloneJob>();
+
+interface InstallJob { id: string; what: 'chromium'; startedAt: number; state: 'running' | 'done' | 'error'; progress: string; error?: string }
+/** Browser installs started from the setup page; one at a time, polled like a clone. */
+const installJobs = new Map<string, InstallJob>();
+
+/**
+ * Where a repository lands and whether it may: under the projects root, by
+ * its own name, never over something that is already there. Returns the
+ * destination or the reason it cannot be used.
+ */
+async function cloneDestination(url: string): Promise<{ ok: true; ref: NonNullable<ReturnType<typeof parseRepoUrl>>; dest: string } | { ok: false; error: string }> {
+  const ref = parseRepoUrl(url);
+  if (!ref) return { ok: false, error: `"${url}" is not a Git URL Foreman recognises. Try https://github.com/owner/repo, git@host:owner/repo.git, or owner/repo.` };
+  const settings = await store.readSettings().catch(() => ({ global: {}, projects: {} }));
+  const root = projectsRoot((settings.global as Record<string, unknown>).projectsRoot);
+  const dest = path.join(root, ref.name);
+  if (await stat(dest).catch(() => null)) {
+    const linked = (await store.listProjects()).find((p) => p.folder === dest);
+    return { ok: false, error: linked ? `${ref.name} is already here and linked as ${linked.name}.` : `${dest} already exists. Link that folder instead, or move it aside.` };
+  }
+  await mkdir(root, { recursive: true });
+  return { ok: true, ref, dest };
+}
+
+/** Clone and link, start to finish. Used by the front desk and the phone, which wait; the picker uses the job table instead. */
+async function cloneAndLink(url: string, branch?: string, onProgress?: (line: string) => void): Promise<{ project?: Project; error?: string }> {
+  const where = await cloneDestination(url);
+  if (!where.ok) return { error: where.error };
+  const failed = await cloneRepo({ ref: where.ref, dest: where.dest, branch, onProgress });
+  if (failed) {
+    // A half-clone is worse than none: git leaves the folder on failure.
+    await rm(where.dest, { recursive: true, force: true }).catch(() => {});
+    return { error: failed };
+  }
+  const project = await store.addProject(where.dest);
+  projectsCache.set(project.id, { name: project.name });
+  return { project };
+}
+
 // ---------------------------------------------------------------------------
 // The fleet planner — the front desk
 // ---------------------------------------------------------------------------
@@ -851,6 +972,8 @@ const fleetHost: FleetHost = {
         if (words.error) lines.push(`it stopped with: ${clipText(words.error, 300)}`);
       }
     }
+    const rec = projectRecord((await store.listRuns().catch(() => [] as RunMeta[])).filter((r) => r.folder === project.folder));
+    if (rec.done >= 2 && rec.medianCostUsd !== undefined) lines.push(`track record: ${rec.done} of ${rec.runs} missions finished; a finished one here costs about $${rec.medianCostUsd.toFixed(2)}${rec.medianMinutes !== undefined ? ` and takes ~${rec.medianMinutes} min` : ''}${rec.capHits ? `; ${rec.capHits} hit the cap` : ''}`);
     const meta = await store.readChatMeta(project.id).catch(() => null);
     if (meta?.proposal) lines.push(`a proposal is waiting for Start or Discard: "${clipText(firstLine(meta.proposal.mission), 100)}" cap $${meta.proposal.budgetUsd}`);
     if (chatTurns.has(project.id)) lines.push('its planner is replying right now');
@@ -889,6 +1012,11 @@ const fleetHost: FleetHost = {
   },
 
   async linkProject(folderIn) {
+    if (looksLikeRepoUrl(folderIn)) {
+      const r = await cloneAndLink(folderIn.trim());
+      if (r.error) return r.error;
+      return `Cloned ${r.project!.name} into ${r.project!.folder} and linked it. Its planner can read it now (open_planning).`;
+    }
     const folder = expandHome(folderIn.trim());
     if (!path.isAbsolute(folder)) return `A folder to link must be an absolute path (or ~/…), not "${folderIn}".`;
     const st = await stat(folder).catch(() => null);
@@ -950,7 +1078,7 @@ async function driveFleetTurn(text: string, via: 'telegram' | 'http'): Promise<{
   try {
     const resolved = await resolveProvider(providerOf({}), store.root);
     emit('chat_turn', { state: 'thinking', model, provider: resolved.label, costBasis: resolved.costBasis });
-    const problem = providerProblem(resolved);
+    const problem = providerProblem(resolved) ?? await signedInProblem(resolved);
     if (problem) {
       emit('chat_error', { error: `provider unavailable — ${problem}` });
       return { text: '', costUsd: 0, error: `provider unavailable — ${problem}` };
@@ -964,7 +1092,7 @@ async function driveFleetTurn(text: string, via: 'telegram' | 'http'): Promise<{
     const result = await runFleetTurn({
       sessionId: meta.sessionId, text, model, cwd, host: fleetHost, via,
       news: fleetNews(since), sinceMs: Date.now() - since,
-      models: models.map((m) => ({ id: m.id, label: m.label, providerId: m.providerId, providerLabel: m.providerLabel, costBasis: m.costBasis, note: m.note })),
+      models: models.map((m) => ({ id: m.id, label: m.label, providerId: m.providerId, providerLabel: m.providerLabel, costBasis: m.costBasis, note: m.note, record: m.record })),
       agentEnv: await agentEnvFor(resolved, `chat:${FLEET_CHAT_ID}`),
       emit, abort,
     });
@@ -1068,6 +1196,13 @@ async function handlePhoneText(text: string, replyTo?: string): Promise<void> {
           return say(`<b>Running · ${live.length}</b>\n${lines.join('\n')}${planning.length ? `\n\n<b>Planning</b>\n${planning.join('\n')}` : ''}`);
         }
         case 'new': {
+          if (looksLikeRepoUrl(cmd.name)) {
+            say(`Cloning <code>${escTg(cmd.name.trim())}</code>…`);
+            const r = await cloneAndLink(cmd.name.trim());
+            if (r.error) return say(`Could not clone: ${escTg(r.error)}`);
+            lastPhonePlanning = r.project!.id; lastPhonePlanningAt = Date.now();
+            return say(`Cloned <b>${escTg(r.project!.name)}</b> into <code>${escTg(r.project!.folder)}</code> and linked it.\nTell me what it should do next — just type it.`);
+          }
           const settings = await store.readSettings().catch(() => ({ global: {}, projects: {} }));
           const root = projectsRoot((settings.global as Record<string, unknown>).projectsRoot);
           const name = slug(cmd.name);
@@ -1138,11 +1273,6 @@ async function chatMetaOf(projectId: string): Promise<ChatMeta> {
     ?? { projectId, costUsd: 0, createdAt: now, updatedAt: now };
 }
 
-/**
- * Runs one planning turn: the human's message goes into the log first (so a
- * reload mid-turn still shows what was asked), then the planner's reply
- * streams out through the same envelope machinery as a mission.
- */
 /**
  * `shown` is what the transcript records as the human's message when it
  * differs from what the planner is sent (a fork's seed). `via: 'telegram'`
@@ -1182,7 +1312,7 @@ async function driveChatTurn(project: Project, text: string, shown: string = tex
       provider: resolved.label,
       costBasis: resolved.costBasis,
     });
-    const problem = providerProblem(resolved);
+    const problem = providerProblem(resolved) ?? await signedInProblem(resolved);
     if (problem) {
       emit('chat_error', { error: `provider unavailable — ${problem}` });
       return;
@@ -1197,8 +1327,9 @@ async function driveChatTurn(project: Project, text: string, shown: string = tex
       projectId: project.id,
       models: models.map((m) => ({
         id: m.id, label: m.label, providerId: m.providerId,
-        providerLabel: m.providerLabel, costBasis: m.costBasis, note: m.note,
+        providerLabel: m.providerLabel, costBasis: m.costBasis, note: m.note, record: m.record,
       })),
+      anchor: await budgetAnchorFor(project).catch(() => ''),
       sessionId: meta.sessionId,
       folder: project.folder,
       text,
@@ -1244,18 +1375,25 @@ async function driveChatTurn(project: Project, text: string, shown: string = tex
 }
 
 /**
- * A mission has started, so the proposal that led to it is spent. Recording
- * the handoff in the conversation matters as much as clearing it: the chat is
- * the story of how this mission came to exist, and it should not simply stop
- * at the moment the work began.
+ * A mission has started, so the conversation that led to it is finished.
+ *
+ * The handoff is recorded first — the chat is the story of how this mission
+ * came to exist, and it should not simply stop at the moment the work began —
+ * and then the whole conversation is archived, not left as the project's
+ * front page. A project visited after a mission shows its runs and a blank
+ * line, not a spent planning session scrolled to the bottom; the run is the
+ * continuation, and "Plan the next step" forks a new conversation from it.
+ * Open tabs are told, so they reset without a reload.
  */
 async function consumeProposal(projectId: string, runId: string, mission: string): Promise<void> {
   const meta = await store.readChatMeta(projectId).catch(() => null);
   if (!meta) return;
-  makeChatEmitter(projectId)('mission_started', { runId, mission });
-  if (!meta.proposal) return;
-  const { proposal: _spent, ...rest } = meta;
-  await store.writeChatMeta({ ...rest, updatedAt: Date.now() }).catch(() => {});
+  const handoff = { runId, mission };
+  await store.appendChat(projectId, { ts: Date.now(), event: 'mission_started', data: handoff }).catch(() => {});
+  noteFleetEvent(projectId, 'mission_started', handoff);
+  notifyHub.handle({ event: 'mission_started', runId: null, projectId, chat: true, data: handoff, ts: Date.now() });
+  await store.archiveChat(projectId, runId).catch(() => {});
+  broadcastChat(projectId, 'chat_cleared', {});
 }
 
 /**
@@ -1269,6 +1407,28 @@ function reserveProject(projectId: string): boolean {
   return true;
 }
 
+/**
+ * Where an exposed service is reachable from, without the trailing slash — the
+ * same address the human already uses for Foreman, but on SERVICES_PORT.
+ *
+ * The starting point is the URL the dashboard hands out (Settings, else the
+ * tailnet, else localhost), because that is the one that actually reaches this
+ * machine from wherever the human reads their notifications. Only the port
+ * changes. An https URL cannot simply be re-pointed: it is `tailscale serve`
+ * terminating TLS in front of the main port, and serve fronts that port alone,
+ * so the honest answer is plain http straight at the tailnet address.
+ */
+async function servicesBase(): Promise<string> {
+  const publicUrl = (await notifySettings().catch(() => null))?.publicUrl
+    ?? (tailnet ? tailnetUrl(tailnet, PORT) : `http://localhost:${PORT}`);
+  const direct = () => `http://${tailnet ? (tailnet.dnsName ?? tailnet.ip) : 'localhost'}:${SERVICES_PORT}`;
+  let u: URL;
+  try { u = new URL(publicUrl); } catch { return direct(); }
+  if (u.protocol !== 'http:') return direct();
+  u.port = String(SERVICES_PORT);
+  return u.origin;
+}
+
 /** Runs a mission to completion. The project must already be reserved. */
 async function driveRun(
   projectId: string, meta: RunMeta, resume?: { sessionId?: string },
@@ -1279,7 +1439,7 @@ async function driveRun(
   // A run that cannot resolve a credential must not start: dispatching anyway
   // would fall back to whatever the environment happens to hold.
   const resolved = await resolveProvider(providerOf(meta), store.root);
-  const problem = providerProblem(resolved);
+  const problem = providerProblem(resolved) ?? await signedInProblem(resolved);
   if (problem) {
     meta.status = 'error';
     meta.endedAt = Date.now();
@@ -1289,6 +1449,29 @@ async function driveRun(
     activeByProject.delete(projectId);
     return;
   }
+  // Each role's provider, checked against its model before anything is
+  // resolved. Model and provider are picked together but stored apart, and
+  // a stale pair — `fable` pinned to Codex by an older settings file — fails
+  // on the first turn with an upstream 400 nobody chose. The model list is
+  // the authority; a corrected role is written back and said in the
+  // transcript, so the run reads the way it actually ran.
+  {
+    const project = await store.getProject(projectId).catch(() => null);
+    const { models } = await availableModels(project).catch(() => ({ models: [] as ModelOption[] }));
+    const known = models.map((m) => ({ id: m.id, providerId: m.providerId }));
+    const director = reconcileRole('director', meta.directorModel, meta.directorProviderId, known);
+    const worker = reconcileRole('workers', meta.workerModel, meta.workerProviderId, known);
+    const notes = [director.note, worker.note].filter((n): n is string => Boolean(n));
+    if (notes.length) {
+      meta.directorProviderId = director.providerId;
+      meta.workerProviderId = worker.providerId;
+      await store.writeMeta(meta).catch(() => {});
+      emit('models_changed', {
+        text: `Provider corrected before dispatch — ${notes.join(' ')}`,
+        directorModel: meta.directorModel, workerModel: meta.workerModel,
+      });
+    }
+  }
   let agentEnv;
   let roleBasis = resolved.costBasis;
   let prices: { director?: ModelPrice; worker?: ModelPrice } = {};
@@ -1373,11 +1556,14 @@ async function driveRun(
     // A dev server behind Foreman's address. Declared ports only, and only
     // ones something is listening on — an agent cannot reserve a path for a
     // server it has not started.
+    // Detected per dispatch, so a browser installed from the setup page
+    // serves the very next mission without a restart.
+    browserChannel: (await detectBrowser())?.channel,
     exposeService: async (runId, port, label) => {
+      if (servicesDown) return { ok: false, reason: servicesDown };
       if (!(await portOpen(port))) return { ok: false, reason: `nothing is listening on 127.0.0.1:${port} — start the server first` };
       const svc = services.register(runId, port, label);
-      const base = (await notifySettings().catch(() => null))?.publicUrl ?? (tailnet ? tailnetUrl(tailnet, PORT) : `http://localhost:${PORT}`);
-      return { ok: true, url: `${base.replace(/\/+$/, '')}${svc.path}`, path: svc.path };
+      return { ok: true, url: `${await servicesBase()}${svc.path}`, path: svc.path };
     },
   });
   activeByProject.set(projectId, run);
@@ -1409,6 +1595,23 @@ async function driveRun(
     // However the run ended, it no longer needs its gateways.
     releaseGateways(meta.id);
     if (activeByProject.get(projectId) === run) activeByProject.delete(projectId);
+    // A finished mission on its own branch closes with a commit of whatever
+    // the crew left uncommitted. Done only: an interrupted run resumes on
+    // the same branch and its tree, and an error is not a result to record.
+    if (meta.git && meta.status === 'done') {
+      const label = meta.title || meta.mission.split('\n').find((l) => l.trim())?.trim().slice(0, 72) || meta.id;
+      const closed = await closeMissionBranch(meta.folder, meta.git, `foreman: ${label}`);
+      meta.git = { branch: closed.branch, base: closed.base, baseHead: closed.baseHead, commits: closed.commits, commit: closed.commit ?? meta.git.commit };
+      await store.writeMeta(meta).catch(() => {});
+      gitInfoCache.delete(meta.folder);
+      const ahead = closed.commits ?? 0;
+      emit('git_committed', {
+        branch: closed.branch, base: closed.base, commits: ahead, commit: closed.commit, committed: closed.committed, error: closed.error,
+        text: closed.error
+          ? `Could not commit the mission's work on ${closed.branch}: ${closed.error}`
+          : `${closed.committed ? `Committed the mission's work as ${closed.commit}` : 'Nothing left to commit'} — ${closed.branch} is ${ahead} commit${ahead === 1 ? '' : 's'} ahead of ${closed.base}. Merge or open a pull request when you are ready; Foreman does neither.`,
+      });
+    }
   }
 }
 
@@ -1418,6 +1621,8 @@ async function effectiveSettings(projectId: string): Promise<{
   directorModel: ModelChoice; workerModel: ModelChoice; plannerModel: ModelChoice;
   /** Provider serving each role, when Settings pinned one with the model. */
   directorProviderId?: string; workerProviderId?: string;
+  /** In a repository, each mission runs on a branch of its own (default on). */
+  gitBranchPerMission: boolean;
 }> {
   const s = await store.readSettings()
     .catch(() => ({ global: {}, projects: {} as Record<string, object> }));
@@ -1438,9 +1643,26 @@ async function effectiveSettings(projectId: string): Promise<{
     plannerModel: modelChoice(p.plannerModel ?? g.plannerModel),
     directorProviderId: str(p.directorProviderId ?? g.directorProviderId),
     workerProviderId: str(p.workerProviderId ?? g.workerProviderId),
+    gitBranchPerMission: (p.gitBranchPerMission ?? g.gitBranchPerMission) !== false,
   };
 }
 
+/** What missions have cost in this project and across the fleet, as the planner's anchor. */
+async function budgetAnchorFor(project: Project): Promise<string> {
+  const runs = await store.listRuns();
+  return budgetAnchor(projectRecord(runs.filter((r) => r.folder === project.folder)), projectRecord(runs), project.name);
+}
+
+/** Git facts per folder, for the fleet poll — asked at most every few seconds per project. */
+const gitInfoCache = new Map<string, { at: number; value: GitInfo }>();
+async function gitInfoCached(folder: string): Promise<GitInfo> {
+  const hit = gitInfoCache.get(folder);
+  if (hit && Date.now() - hit.at < 5_000) return hit.value;
+  const value = await gitInfo(folder);
+  gitInfoCache.set(folder, { at: Date.now(), value });
+  return value;
+}
+
 async function startRun(
   projectId: string, folder: string, mission: string, budgetUsd: number,
   directorModel: ModelChoice, workerModel: ModelChoice, browserTools: boolean,
@@ -1477,6 +1699,21 @@ async function startRun(
     return;
   }
   await consumeProposal(projectId, meta.id, mission).catch(() => {});
+  // In a repository, the mission gets a branch of its own before the crew
+  // touches anything — so the deck's baseline, taken at the director's first
+  // turn, is the branch point, and the diff is exactly the mission.
+  if (settings.gitBranchPerMission) {
+    const g = await startMissionBranch(folder, mission, meta.id);
+    const emit = makeEmitter(meta.id, projectId);
+    if ('error' in g) {
+      if (g.error !== 'not a git repository') emit('git_note', { text: `Could not give this mission its own branch (${g.error}); running on the current branch.` });
+    } else {
+      meta.git = g;
+      await store.writeMeta(meta).catch(() => {});
+      gitInfoCache.delete(folder);
+      emit('git_branch', { branch: g.branch, base: g.base, text: `On branch ${g.branch}, made from ${g.base}. Foreman commits the mission's work here when it ends; merging and pushing stay yours.` });
+    }
+  }
   await driveRun(projectId, meta);
 }
 
@@ -1514,6 +1751,11 @@ async function resumeRun(projectId: string, meta: RunMeta, pick: {
   meta.status = 'running';
   meta.endedAt = undefined;
   meta.resumes = (meta.resumes ?? 0) + 1;
+  if (meta.git) {
+    const back = await ensureMissionBranch(meta.folder, meta.git.branch);
+    if (back) makeEmitter(meta.id, projectId)('git_note', { text: `Could not return to ${meta.git.branch} (${back}); the resumed mission runs on whatever is checked out.` });
+    gitInfoCache.delete(meta.folder);
+  }
   await store.writeMeta(meta).catch((err) => {
     console.error(`failed to persist resume of ${meta.id}:`, err);
   });
@@ -1558,13 +1800,52 @@ async function serveStatic(pathname: string, res: http.ServerResponse): Promise<
 // Request helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * The request body as an object, refusing to buffer more than the route's cap.
+ *
+ * Both failures throw a `BodyError`, which the handler's outer catch turns
+ * into the client's own status instead of a 500 that reads like a Foreman bug:
+ * 413 when the body outgrows the cap (see `src/http-body.ts` for why there is
+ * one), 400 when what arrived is not JSON. Content-Length is consulted first
+ * so an oversized upload is refused before a single byte is read.
+ */
 async function readBody(req: http.IncomingMessage): Promise<Record<string, unknown>> {
+  const pathname = new URL(req.url ?? '/', `http://localhost:${PORT}`).pathname;
+  const limit = bodyLimitFor(req.method, pathname);
+  const declared = Number(req.headers['content-length']);
+  if (Number.isFinite(declared) && declared > limit) throw new BodyError(413, 'request body too large');
   const chunks: Buffer[] = [];
-  for await (const c of req) chunks.push(c as Buffer);
+  let seen = 0;
+  for await (const c of req) {
+    const buf = c as Buffer;
+    seen += buf.length;
+    if (seen > limit) throw new BodyError(413, 'request body too large');
+    chunks.push(buf);
+  }
   if (!chunks.length) return {};
-  const parsed: unknown = JSON.parse(Buffer.concat(chunks).toString());
-  return typeof parsed === 'object' && parsed !== null
-    ? (parsed as Record<string, unknown>) : {};
+  return parseBody(Buffer.concat(chunks));
+}
+
+/**
+ * The folders the folder picker may look inside.
+ *
+ * `/browse` and `/mkdir` exist to let the human point at a project, and they
+ * took any absolute path — which made them a directory listing and a
+ * `mkdir -p` for the whole filesystem, reachable from a page that got past
+ * nothing but a URL. The answer is the same one the permission cards use:
+ * name the places a project could plausibly live — the home directory, the
+ * configured projects root (it may be on another volume), and every folder
+ * already linked as a project — and refuse the rest. Read afresh per request
+ * because linking a project is what widens the set.
+ */
+async function browseRoots(): Promise<string[]> {
+  const settings = await store.readSettings().catch(() => ({ global: {} as Record<string, unknown> }));
+  const roots = [
+    os.homedir(),
+    projectsRoot((settings.global as Record<string, unknown>).projectsRoot),
+  ];
+  for (const p of await store.listProjects().catch(() => [])) roots.push(p.folder);
+  return roots;
 }
 
 function json(res: http.ServerResponse, code: number, body: unknown): void {
@@ -1577,40 +1858,31 @@ function json(res: http.ServerResponse, code: number, body: unknown): void {
 // ---------------------------------------------------------------------------
 
 const server = http.createServer(async (req, res) => {
+  // Before any route, including the service proxy: is this request one we
+  // should be answering at all? Foreman has no login, so a browser that can
+  // reach the port can otherwise act as the operator — a page on any domain
+  // can point that name at 127.0.0.1 (DNS rebinding) or simply POST at
+  // localhost from whatever tab the operator has open. See src/guard.ts.
+  const verdict = requestAllowed(req, { port: PORT, tailnet, bindAll: BIND === 'all' });
+  if (!verdict.ok) { json(res, verdict.status, { error: verdict.error }); return; }
   const url = new URL(req.url ?? '/', `http://localhost:${PORT}`);
-  // Services the crew exposed: /svc/<run>/<port>/… goes to 127.0.0.1:<port>,
-  // but only for a pair a run declared. A page served this way asks for its
-  // absolute-path assets (`/app.js`) against Foreman's root; those arrive as
-  // sub-resource requests carrying the service page as Referer, and are
-  // routed to the same service. Documents never are — a typed URL is Foreman's.
-  {
-    const svc = parseServicePath(url.pathname);
-    if (svc) {
-      if (!services.has(svc.runId, svc.port)) { json(res, 404, { error: 'no such service' }); return; }
-      proxyToService(req, res, svc.port, svc.rest, url.search, servicePath(svc.runId, svc.port));
-      return;
-    }
-    const ref = req.headers.referer;
-    const dest = String(req.headers['sec-fetch-dest'] ?? '');
-    if (ref && dest && dest !== 'document' && dest !== 'empty' && !url.pathname.startsWith(SVC_PREFIX)) {
-      try {
-        const via = parseServicePath(new URL(ref).pathname);
-        if (via && services.has(via.runId, via.port)) {
-          proxyToService(req, res, via.port, url.pathname, url.search, servicePath(via.runId, via.port));
-          return;
-        }
-      } catch { /* not a URL we can read — fall through to Foreman's own routes */ }
-    }
-  }
+  // Note: /svc/… is not handled here. Exposed dev servers live on
+  // SERVICES_PORT, on their own origin — see servicesServer below.
   const runEventsMatch = url.pathname.match(/^\/runs\/([^/]+)\/events$/);
   // The deck: what a run changed and what it produced. Read-only by design —
   // a stated non-goal — and handled before the chain because it owns two paths
   // under /runs/{id}/ that nothing else claims.
-  if (await handleDeckRoute(req, res, url, async (id) => {
+  if (await handleDeckRoute(req, res, url, async (scope, id) => {
+    if (scope === 'projects') {
+      const project = await store.getProject(id).catch(() => null);
+      return project ? { folder: project.folder } : null;
+    }
     const m = await store.readMeta(id).catch(() => null);
     return m ? { folder: m.folder } : null;
   })) return;
   const runResumeMatch = url.pathname.match(/^\/runs\/([^/]+)\/resume$/);
+  const prMatch = url.pathname.match(/^\/runs\/([^/]+)\/pr$/);
+  const prStateMatch = url.pathname.match(/^\/runs\/([^/]+)\/pr\/state$/);
   const projectMatch = url.pathname.match(/^\/projects\/([^/]+)$/);
   const providerKeyMatch = url.pathname.match(/^\/providers\/([A-Za-z0-9_-]{1,64})\/key$/);
 
@@ -1632,6 +1904,57 @@ const server = http.createServer(async (req, res) => {
       sseClients.add(res);
       req.on('close', () => sseClients.delete(res));
 
+    } else if (req.method === 'GET' && url.pathname === '/doctor') {
+      // What `foreman doctor` prints, as data, for the dashboard's setup card.
+      // Computed fresh each time — the point is to reflect a login or an
+      // install the person just did. The port and dashboard checks are left
+      // out: whoever is reading this in the dashboard already knows both.
+      const [checks, auth, ollama, codexAuth, notify] = await Promise.all([
+        preflight({ port: PORT, servicesPort: SERVICES_PORT, foremanHome: store.root, distDir: DIST_DIR, tailnet }),
+        detectAuth(),
+        discoverOllama(1200),
+        readCodexAuth(codexHome()).catch(() => null),
+        notifySettings().catch(() => null),
+      ]);
+      const codexCount = codexAuth ? (await codexModels(codexHome()).catch(() => [])).length : 0;
+      json(res, 200, {
+        checks: checks.filter((c) => !c.name.startsWith('Port') && c.name !== 'Dashboard'),
+        // The same facts, shaped for the first-run pages: one object per step.
+        auth: { mode: auth.mode, source: auth.source, account: auth.account ?? null },
+        ollama: ollama ? { host: ollamaHost(), models: ollama.length, local: ollama.filter((m) => !m.remote).length } : null,
+        codex: codexAuth ? { models: codexCount } : null,
+        tailnet: tailnet ? { dnsName: tailnet.dnsName ?? null, ip: tailnet.ip, url: tailnetUrl(tailnet, PORT), https: Boolean(tailnet.httpsPort) } : null,
+        phone: notify?.telegramChatId ? { label: notify.telegramChatLabel ?? 'linked', bot: notify.telegramBot ?? null } : notify?.telegramBot ? { label: null, bot: notify.telegramBot } : null,
+        browser: checks.find((c) => c.name === 'Browser') ?? null,
+        version: currentVersion(),
+      });
+
+    } else if (req.method === 'POST' && url.pathname === '/setup/browser') {
+      // Install Playwright's Chromium, as the user, into Playwright's cache.
+      // The one install action the setup page has: no root, no system
+      // packages, and the crew's browser tool can drive the result.
+      const running = [...installJobs.values()].find((j) => j.state === 'running');
+      if (running) return json(res, 202, { id: running.id });
+      const job: InstallJob = { id: crypto.randomBytes(6).toString('hex'), what: 'chromium', startedAt: Date.now(), state: 'running', progress: 'Starting…' };
+      installJobs.set(job.id, job);
+      void installChromium((l) => { job.progress = l; }).then((failed) => {
+        if (failed) { job.state = 'error'; job.error = failed; } else { job.state = 'done'; job.progress = 'Installed'; }
+        setTimeout(() => installJobs.delete(job.id), 10 * 60_000).unref();
+      });
+      json(res, 202, { id: job.id });
+
+    } else if (req.method === 'GET' && url.pathname.startsWith('/setup/browser/')) {
+      const job = installJobs.get(url.pathname.split('/').pop()!);
+      if (!job) return json(res, 404, { error: 'no such install' });
+      json(res, 200, job);
+
+    } else if (req.method === 'POST' && url.pathname === '/setup/done') {
+      // The first-run pages were seen through (or skipped). Remembered in
+      // settings so they do not come back; `#/setup` reopens them on purpose.
+      const current = await store.readSettings();
+      await store.writeSettings({ ...current, global: { ...current.global, setupDoneAt: Date.now() } });
+      json(res, 200, { ok: true });
+
     } else if (req.method === 'GET' && url.pathname === '/settings') {
       json(res, 200, await store.readSettings());
 
@@ -1665,9 +1988,14 @@ const server = http.createServer(async (req, res) => {
       json(res, 200, await availableModels(project));
 
     } else if (req.method === 'GET' && url.pathname === '/projects') {
-      const [projects, allRuns, auth] = await Promise.all([
+      const [projects, allRuns, auth, settingsFile] = await Promise.all([
         store.listProjects(), store.listRuns(), authPromise,
+        store.readSettings().catch(() => ({ global: {} as Record<string, unknown>, projects: {} })),
       ]);
+      // A first run: nothing linked, nothing ever run, the setup pages not
+      // yet seen. An install upgraded from before the pages existed has
+      // projects, so it never sees them uninvited.
+      const firstRun = !projects.length && !allRuns.length && !(settingsFile.global as Record<string, unknown>).setupDoneAt;
       const cards = await Promise.all(projects.map(async (p) => {
         const run = activeByProject.get(p.id);
         const plannerAsk = pendingChatQuestion(p.id);
@@ -1681,6 +2009,9 @@ const server = http.createServer(async (req, res) => {
           // Whether a key is on file, never the key. Settings renders
           // "stored / not stored" from this and nothing more.
           providerHasKey: await providerHasKeyOf(p),
+          // Which branch the folder is on, and whether it is dirty — the
+          // header's pill, and what "a branch per mission" starts from.
+          git: await gitInfoCached(p.folder),
           activeRun: run ? { ...run.meta } : null,
           lastRun: lastRun && {
             id: lastRun.id,
@@ -1720,6 +2051,7 @@ const server = http.createServer(async (req, res) => {
       json(res, 200, {
         // Billing mode travels with every fleet poll so the UI can state it
         // plainly wherever money is about to be spent.
+        firstRun,
         authMode: auth.mode,
         authSource: auth.source,
         authAccount: auth.account ?? null,
@@ -2194,6 +2526,42 @@ const server = http.createServer(async (req, res) => {
       if (!ok) return json(res, 404, { error: 'no pending question with that id' });
       json(res, 200, { ok: true });
 
+    } else if (req.method === 'GET' && url.pathname === '/projects/clone/where') {
+      // Where a URL would land, before anyone clicks: the dialog shows the
+      // path as you type, and the same check refuses what the clone would.
+      const repo = (url.searchParams.get('url') ?? '').trim();
+      if (!repo) return json(res, 200, { dest: null });
+      const where = await cloneDestination(repo);
+      json(res, 200, where.ok ? { dest: where.dest, name: where.ref.name, host: where.ref.host } : { dest: null, error: where.error });
+
+    } else if (req.method === 'POST' && url.pathname === '/projects/clone') {
+      // Start a clone under the projects root; the picker polls the job.
+      const { url: repo, branch } = await readBody(req);
+      if (typeof repo !== 'string' || !repo.trim()) return json(res, 400, { error: 'url is required' });
+      const where = await cloneDestination(repo.trim());
+      if (!where.ok) return json(res, 400, { error: where.error });
+      const job: CloneJob = { id: crypto.randomBytes(6).toString('hex'), url: where.ref.url, dest: where.dest, startedAt: Date.now(), state: 'running', progress: 'Starting git…' };
+      cloneJobs.set(job.id, job);
+      void (async () => {
+        const failed = await cloneRepo({ ref: where.ref, dest: where.dest, branch: typeof branch === 'string' && branch.trim() ? branch.trim() : undefined, onProgress: (l) => { job.progress = l; } });
+        if (failed) {
+          await rm(where.dest, { recursive: true, force: true }).catch(() => {});
+          job.state = 'error'; job.error = failed;
+        } else {
+          const project = await store.addProject(where.dest);
+          projectsCache.set(project.id, { name: project.name });
+          job.state = 'done'; job.projectId = project.id; job.progress = 'Done';
+        }
+        // Finished jobs linger long enough to be read, then go.
+        setTimeout(() => cloneJobs.delete(job.id), 10 * 60_000).unref();
+      })();
+      json(res, 202, { id: job.id, dest: job.dest });
+
+    } else if (req.method === 'GET' && /^\/projects\/clone\/[a-f0-9]{12}$/.test(url.pathname)) {
+      const job = cloneJobs.get(url.pathname.split('/').pop()!);
+      if (!job) return json(res, 404, { error: 'no such clone (Foreman may have restarted; check the projects root)' });
+      json(res, 200, { state: job.state, progress: job.progress, projectId: job.projectId, error: job.error, dest: job.dest });
+
     } else if (req.method === 'GET' && url.pathname === '/search') {
       // Every run across the fleet whose title, brief, project or folder
       // says the words. Run records are small and already on disk; no index.
@@ -2235,6 +2603,72 @@ const server = http.createServer(async (req, res) => {
       broadcastChat(FLEET_CHAT_ID, 'chat_cleared', {});
       json(res, 200, { ok: true });
 
+    } else if (prStateMatch && req.method === 'GET') {
+      // What became of the run's pull request. A final answer (merged,
+      // closed) is written to the run so it is not asked again; open is.
+      const meta = await store.readMeta(prStateMatch[1]).catch(() => null);
+      if (!meta?.git?.pr) return json(res, 404, { error: 'no pull request on this run' });
+      if (meta.git.prState) return json(res, 200, { url: meta.git.pr, state: meta.git.prState, cached: true });
+      const s = await pullRequestState(meta.folder, meta.git.pr);
+      if (s && s.state !== 'open') {
+        meta.git = { ...meta.git, prState: s.state };
+        await store.writeMeta(meta).catch(() => {});
+      }
+      json(res, 200, { url: meta.git.pr, state: s?.state ?? null, mergedAt: s?.mergedAt, number: s?.number });
+
+    } else if (prMatch && req.method === 'GET') {
+      // The pull request as Foreman would draft it, for the sheet to edit.
+      const meta = await store.readMeta(prMatch[1]).catch(() => null);
+      if (!meta) return json(res, 404, { error: 'unknown run' });
+      if (!meta.git) return json(res, 409, { error: 'this run had no branch of its own' });
+      const info = await gitInfo(meta.folder);
+      if (!info.remote) return json(res, 409, { error: 'the repository has no origin remote to push to' });
+      const doc = await readFile(path.join(meta.folder, '.foreman', 'MISSION.md'), 'utf8').catch(() => null);
+      const gh = await ghReady();
+      json(res, 200, {
+        ...prDraft(meta, doc), branch: meta.git.branch, base: meta.git.base, commits: meta.git.commits ?? null,
+        remote: info.remote, compareUrl: compareUrl(info.remote, meta.git.base, meta.git.branch),
+        gh, pr: meta.git.pr ?? null, onBranch: info.branch === meta.git.branch, dirty: Boolean(info.dirty),
+      });
+
+    } else if (prMatch && req.method === 'POST') {
+      // The one outward-facing act: push the mission's branch and open the
+      // pull request — as the user, with their git and gh, on their click.
+      // Never from an agent, never from the phone.
+      const meta = await store.readMeta(prMatch[1]).catch(() => null);
+      if (!meta) return json(res, 404, { error: 'unknown run' });
+      if (!meta.git) return json(res, 409, { error: 'this run had no branch of its own' });
+      if (meta.status === 'running') return json(res, 409, { error: 'the mission is still running' });
+      const { title, body } = await readBody(req);
+      const t = typeof title === 'string' && title.trim() ? title.trim().slice(0, 200) : null;
+      if (!t) return json(res, 400, { error: 'a title is required' });
+      const b = typeof body === 'string' ? body : '';
+      const info = await gitInfo(meta.folder);
+      if (!info.remote) return json(res, 409, { error: 'the repository has no origin remote to push to' });
+      const emit = makeEmitter(meta.id, meta.projectId ?? prMatch[1]);
+      const pushed = await pushBranch(meta.folder, meta.git.branch);
+      if (pushed) {
+        emit('pull_request', { branch: meta.git.branch, error: pushed, text: `Push of ${meta.git.branch} failed: ${pushed}` });
+        return json(res, 502, { error: pushed });
+      }
+      const gh = await ghReady();
+      let url: string | undefined;
+      let method: 'gh' | 'compare' = 'compare';
+      let note: string | undefined;
+      if (gh.present && gh.authed && /github\.com/.test(info.remote)) {
+        const r = await createPullRequest(meta.folder, { base: meta.git.base, branch: meta.git.branch, title: t, body: b });
+        if (r.url) { url = r.url; method = 'gh'; } else note = r.error;
+      }
+      if (!url) url = compareUrl(info.remote, meta.git.base, meta.git.branch) ?? undefined;
+      meta.git = { ...meta.git, pr: method === 'gh' ? url : meta.git.pr };
+      await store.writeMeta(meta).catch(() => {});
+      gitInfoCache.delete(meta.folder);
+      const text = method === 'gh'
+        ? `Pushed ${meta.git.branch} and opened a pull request: ${url}`
+        : `Pushed ${meta.git.branch}.${note ? ` ${note}.` : ''} Finish the pull request in the browser: ${url ?? 'open the repository'}`;
+      emit('pull_request', { branch: meta.git.branch, base: meta.git.base, url, method, text });
+      json(res, 200, { ok: true, url, method, pushed: true, note });
+
     } else if (req.method === 'POST' && url.pathname === '/steer') {
       const { runId, text } = await readBody(req);
       const trimmed = typeof text === 'string' ? text.trim() : '';
@@ -2315,6 +2749,12 @@ const server = http.createServer(async (req, res) => {
       if (!events) return json(res, 404, { error: 'unknown run' });
       json(res, 200, { events });
 
+    } else if (req.method === 'GET' && /^\/projects\/[^/]+\/memory$/.test(url.pathname)) {
+      // What the project "believes": .foreman/MEMORY.md, read-only here.
+      const project = await store.getProject(url.pathname.split('/')[2]).catch(() => null);
+      if (!project) return json(res, 404, { error: 'unknown project' });
+      json(res, 200, await readMemory(project.folder));
+
     } else if (req.method === 'GET' && url.pathname === '/missiondoc') {
       const runId = url.searchParams.get('run');
       if (!runId) return json(res, 400, { error: 'run parameter is required' });
@@ -2327,6 +2767,9 @@ const server = http.createServer(async (req, res) => {
     } else if (req.method === 'GET' && url.pathname === '/browse') {
       const requested = url.searchParams.get('path') || os.homedir();
       const dir = path.resolve(requested);
+      if (!pathPermitted(dir, await browseRoots())) {
+        return json(res, 400, { error: 'path outside the folders Foreman may browse' });
+      }
       const st = await stat(dir).catch(() => null);
       if (!st?.isDirectory()) return json(res, 400, { error: `not a directory: ${dir}` });
       const entries = await readdir(dir, { withFileTypes: true });
@@ -2345,6 +2788,11 @@ const server = http.createServer(async (req, res) => {
       if (typeof name !== 'string' || !name.trim() || /[/\\]/.test(name) || name.trim().startsWith('.')) {
         return json(res, 400, { error: 'invalid folder name' });
       }
+      // The parent is what is being written into, so the parent is what has
+      // to be inside the allowed folders.
+      if (!pathPermitted(parent, await browseRoots())) {
+        return json(res, 400, { error: 'path outside the folders Foreman may browse' });
+      }
       const parentSt = await stat(parent).catch(() => null);
       if (!parentSt?.isDirectory()) return json(res, 400, { error: `not a directory: ${parent}` });
       const created = path.join(parent, name.trim());
@@ -2360,12 +2808,42 @@ const server = http.createServer(async (req, res) => {
       json(res, 404, { error: 'not found' });
     }
   } catch (err) {
+    if (err instanceof BodyError) {
+      // The answer goes out before the stream is torn down: destroying the
+      // request first makes the client see a connection reset instead of the
+      // 413 that explains it. `res.end` has already queued the bytes by the
+      // time `req.destroy` stops the sender from writing more.
+      json(res, err.status, { error: err.message });
+      if (!req.readableEnded) req.destroy();
+      return;
+    }
     json(res, 500, { error: String(err) });
   }
 });
 
+/**
+ * The second origin: nothing but the crew's exposed dev servers, guarded the
+ * same way as the dashboard. Kept separate so a page an agent wrote cannot
+ * reach a single Foreman route from the browser — see src/services.ts.
+ */
+const servicesServer = http.createServer(servicesHandler({
+  registry: services,
+  allowed: (req) => requestAllowed(req, { port: SERVICES_PORT, tailnet, bindAll: BIND === 'all' }),
+}));
+/**
+ * Why the services port is not listening, when it is not. A taken port must
+ * not take the dashboard down with it (an unhandled 'error' on a server is a
+ * crash): it is logged, preflight has already warned, and expose_service
+ * tells the crew plainly instead of handing out a URL that answers nothing.
+ */
+let servicesDown: string | null = null;
+servicesServer.on('error', (err: NodeJS.ErrnoException) => {
+  servicesDown = `Foreman's services port ${SERVICES_PORT} is not available (${err.code ?? err.message}); set FOREMAN_SERVICES_PORT to a free port and restart to expose dev servers`;
+  console.warn(`[services] ${servicesDown}`);
+});
+
 // Fail loudly on a misconfigured install before anything else happens.
-if (!reportPreflight(await preflight({ port: PORT, foremanHome: store.root, distDir: DIST_DIR, tailnet }))) {
+if (!reportPreflight(await preflight({ port: PORT, servicesPort: SERVICES_PORT, foremanHome: store.root, distDir: DIST_DIR, tailnet }))) {
   process.exit(1);
 }
 
@@ -2410,11 +2888,13 @@ void store.listRuns().then((runs) => {
 }).catch(() => {});
 
 if (BIND === 'all') {
-  server.listen(PORT, () => console.log(`Foreman listening on http://0.0.0.0:${PORT} (FOREMAN_BIND=all)`));
+  server.listen(PORT, () => console.log(`Foreman listening on http://0.0.0.0:${PORT} (FOREMAN_BIND=all) · services on http://0.0.0.0:${SERVICES_PORT}`));
+  servicesServer.listen(SERVICES_PORT);
 } else {
   server.listen(PORT, '127.0.0.1', () => {
-    console.log(`Foreman listening on http://localhost:${PORT}${tailnet ? ` · ${tailnetUrl(tailnet, PORT)}` : ''}`);
+    console.log(`Foreman listening on http://localhost:${PORT}${tailnet ? ` · ${tailnetUrl(tailnet, PORT)}` : ''} · services on http://localhost:${SERVICES_PORT}`);
   });
+  servicesServer.listen(SERVICES_PORT, '127.0.0.1');
   if (tailnet) {
     // A second listener on the tailnet address, feeding the same handler.
     // Not 0.0.0.0: the café Wi-Fi is not the tailnet.
@@ -2422,7 +2902,12 @@ if (BIND === 'all') {
     const viaTailnet = http.createServer(onRequest);
     viaTailnet.on('error', (err) => console.warn(`[tailscale] could not listen on ${tailnet.ip}:${PORT} — ${err.message}`));
     viaTailnet.listen(PORT, tailnet.ip);
-    for (const signal of ['SIGINT', 'SIGTERM'] as const) process.on(signal, () => viaTailnet.close());
+    // The services port needs the same reach: the human opens those previews
+    // from their phone, over the tailnet, like everything else.
+    const svcViaTailnet = http.createServer(servicesServer.listeners('request')[0] as http.RequestListener);
+    svcViaTailnet.on('error', (err) => console.warn(`[tailscale] could not listen on ${tailnet.ip}:${SERVICES_PORT} — ${err.message}`));
+    svcViaTailnet.listen(SERVICES_PORT, tailnet.ip);
+    for (const signal of ['SIGINT', 'SIGTERM'] as const) process.on(signal, () => { viaTailnet.close(); svcViaTailnet.close(); });
   }
 }