@amenophis1er/foreman 0.1.14 → 0.1.16

package/package.json

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

package/src/gitwork.test.ts

@@ -4,7 +4,8 @@ import os from 'node:os';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { mkdtemp, writeFile } from 'node:fs/promises';
-import { closeMissionBranch, ensureMissionBranch, gitInfo, missionBranchName, startMissionBranch, renameMissionBranch } from './gitwork.js';
+import { closeMissionBranch, defaultBranch, ensureMissionBranch, gitInfo, missionBranchName, remoteHasBranch, resolvePrBase, startMissionBranch, renameMissionBranch, dirtyPaths,
+} from './gitwork.js';
 
 const sh = (cwd: string, ...args: string[]) => execFileSync('git', args, { cwd, stdio: 'pipe', env: { ...process.env, GIT_CONFIG_GLOBAL: '/dev/null' } }).toString();
 
@@ -108,3 +109,40 @@ test('renameMissionBranch takes the run title once there is one, and leaves a br
   sh(dir, 'checkout', '-q', 'main');
   assert.equal(await renameMissionBranch(dir, renamed!, 'Another title', '1788713434983-226123af'), null);
 });
+
+test('dirtyPaths names the uncommitted work a mission branch would carry', async () => {
+  const dir = await repo();
+  assert.deepEqual(await dirtyPaths(dir), [], 'a clean checkout carries nothing');
+
+  await writeFile(path.join(dir, 'README.md'), 'hello, edited\n');
+  await writeFile(path.join(dir, 'scratch.txt'), 'untracked\n');
+  const dirty = await dirtyPaths(dir);
+  assert.deepEqual(dirty.sort(), ['README.md', 'scratch.txt'], 'tracked edits and untracked files both count');
+
+  // The cap is for a message, not for the truth of it.
+  assert.equal((await dirtyPaths(dir, 1)).length, 1);
+  // Not a repository at all: nothing to report, and no throw.
+  assert.deepEqual(await dirtyPaths(os.tmpdir()), []);
+});
+
+test('a pull request targets the default branch when the mission was branched from a local-only branch', async () => {
+  const dir = await repo();
+  // A bare origin, the way a real clone has one.
+  const origin = await mkdtemp(path.join(os.tmpdir(), 'gitwork-origin-'));
+  execFileSync('git', ['init', '-q', '--bare', '-b', 'main', origin], { stdio: 'pipe' });
+  sh(dir, 'remote', 'add', 'origin', origin);
+  sh(dir, 'push', '-q', '-u', 'origin', 'main');
+
+  assert.equal(await defaultBranch(dir), 'main');
+  assert.equal(await remoteHasBranch(dir, 'main'), true);
+  assert.equal(await remoteHasBranch(dir, 'foreman/earlier-1234'), false);
+
+  // Branched from main: the base is real and is left alone.
+  assert.deepEqual(await resolvePrBase(dir, 'main'), { base: 'main', fellBack: false });
+
+  // The case from the field: the checkout was left on the previous mission's
+  // branch, so this mission recorded that as its base and it exists nowhere
+  // but here. gh would fail on it; the default branch is the honest target.
+  sh(dir, 'checkout', '-q', '-b', 'foreman/earlier-1234');
+  assert.deepEqual(await resolvePrBase(dir, 'foreman/earlier-1234'), { base: 'main', fellBack: true });
+});

package/src/gitwork.ts

@@ -85,6 +85,22 @@ export function missionBranchName(mission: string, runId: string): string {
  * Uncommitted changes come along, as `checkout -b` always does. Resolves to
  * the record for the run, or to one sentence on why it could not.
  */
+/**
+ * The paths with uncommitted changes, tracked or untracked, capped for a
+ * message. `checkout -b` carries all of them onto the mission's branch, and
+ * the closing commit sweeps whatever is still uncommitted into the mission's
+ * own commit — so this is what a human stands to have committed under a
+ * mission's name without noticing.
+ */
+export async function dirtyPaths(folder: string, limit = 8): Promise<string[]> {
+  try {
+    const out = await git(['status', '--porcelain', '--untracked-files=normal'], folder);
+    return out.split('\n').map((l) => l.slice(3).trim()).filter(Boolean).slice(0, limit);
+  } catch {
+    return [];
+  }
+}
+
 export async function startMissionBranch(folder: string, mission: string, runId: string): Promise<MissionGit | { error: string }> {
   const info = await gitInfo(folder);
   if (!info.repo) return { error: 'not a git repository' };
@@ -245,6 +261,56 @@ export function pullRequestState(folder: string, url: string): Promise<{ state:
   });
 }
 
+/**
+ * The repository's default branch as origin sees it, from the remote HEAD git
+ * recorded at clone time, then from the usual names, and `main` as the last
+ * word. Local only: no network, so it works offline and cannot hang.
+ */
+export async function defaultBranch(folder: string): Promise<string> {
+  try {
+    const ref = (await git(['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], folder)).trim();
+    const name = ref.replace(/^origin\//, '');
+    if (name) return name;
+  } catch { /* no remote HEAD recorded */ }
+  for (const name of ['main', 'master']) {
+    try {
+      await git(['rev-parse', '--verify', `refs/remotes/origin/${name}`], folder);
+      return name;
+    } catch { /* not this one */ }
+  }
+  return 'main';
+}
+
+/** Does origin have this branch? Asks the remote, and says no if it cannot ask. */
+export async function remoteHasBranch(folder: string, branch: string): Promise<boolean> {
+  try {
+    const out = await git(['ls-remote', '--heads', 'origin', branch], folder, 10_000);
+    return out.trim().length > 0;
+  } catch {
+    // Offline or unauthenticated: fall back to what the last fetch recorded.
+    try {
+      await git(['rev-parse', '--verify', `refs/remotes/origin/${branch}`], folder);
+      return true;
+    } catch { return false; }
+  }
+}
+
+/**
+ * What a pull request from this mission should actually target.
+ *
+ * A finished mission leaves the checkout on its own branch, so the next
+ * mission is branched from *that* — and records it as its base. That base
+ * lives only on this machine, so `gh pr create --base foreman/…` fails and a
+ * compare URL built from it 404s. When the recorded base is not on the
+ * remote, the default branch is the honest target, and the caller says so
+ * rather than quietly retargeting the request.
+ */
+export async function resolvePrBase(folder: string, recorded: string): Promise<{ base: string; fellBack: boolean }> {
+  if (recorded && await remoteHasBranch(folder, recorded)) return { base: recorded, fellBack: false };
+  const base = await defaultBranch(folder);
+  return { base, fellBack: base !== recorded };
+}
+
 /** `gh pr create`, as the user. Resolves to the PR's URL, or to why not. */
 export function createPullRequest(folder: string, opts: { base: string; branch: string; title: string; body: string }): Promise<{ url?: string; error?: string }> {
   return new Promise((resolve) => {

package/src/notify.ts

@@ -234,10 +234,14 @@ export function shape(env: Envelope, ctx: NotifyContext): Shaped | null {
     // --- money and completion -----------------------------------------
     case 'budget_alert':
       return { key: `budget:${env.runId}:${d.level}`, gate: 'budget',
-        text: `${head(d.level === 'exceeded' ? 'Budget exceeded — run interrupted' : 'Budget cap reached')}${runLine}\n${esc(clip(d.text))}${foot}` };
+        text: `${head(d.level === 'exceeded' ? 'Budget exceeded — run interrupted'
+          : d.level === 'warn' ? 'Budget warning — winding down' : 'Budget cap reached')}${runLine}\n${esc(clip(d.text))}${foot}` };
     case 'budget_stop':
       return { key: `stop:${env.runId}`, gate: 'budget',
         text: `${head('Run winding down')}${runLine}\n${esc(clip(d.reason))}${foot}` };
+    case 'mission_done_at_cap':
+      return { key: `donecap:${env.runId}`, gate: 'done',
+        text: `${head('Done, at the cap')}${runLine}\n${esc(clip(d.text))}${foot}` };
     case 'mission_incomplete':
       return { key: `incomplete:${env.runId}`, gate: 'done',
         text: `${head('Not done')}${runLine}\n${esc(clip(d.text))}${foot}` };

package/src/orchestrator.test.ts

@@ -9,7 +9,7 @@ import {
   stalledWorkerReport, workerStatusBlock,
   watchRepeats, watchSilence, REPEAT_EXEMPT, observeToolUse,
   DEFAULT_ASK_TIMEOUT_MS, armAskTimeout, unattendedAnswer, unattendedDenyMessage,
-  tokenCapLabel, stopReasonOf,
+  tokenCapLabel, stopReasonOf, budgetWarnDue, doneAtCap,
 } from './orchestrator.js';
 import { makePolicy, type PendingPermission } from './policy.js';
 import type { AgentEnv } from './provider.js';
@@ -1256,3 +1256,27 @@ test('stopReasonOf names the cap behind a capReached sentence', () => {
   assert.equal(stopReasonOf('TIME CAP REACHED: 240 minutes.'), 'time');
   assert.equal(stopReasonOf('TOKEN CAP REACHED: 20.1M tokens.'), 'tokens');
 });
+
+test('budgetWarnDue: once past the threshold, and only while still under the cap', () => {
+  assert.equal(budgetWarnDue(7.9, 10, 80), false);
+  assert.equal(budgetWarnDue(8, 10, 80), true);
+  assert.equal(budgetWarnDue(9.99, 10, 80), true);
+  // At and past the cap the wind-down order speaks instead.
+  assert.equal(budgetWarnDue(10, 10, 80), false);
+  assert.equal(budgetWarnDue(12, 10, 80), false);
+  // No threshold, a nonsensical one, or no cap: nothing to warn about.
+  assert.equal(budgetWarnDue(9, 10, undefined), false);
+  assert.equal(budgetWarnDue(9, 10, 0), false);
+  assert.equal(budgetWarnDue(9, 10, 100), false);
+  assert.equal(budgetWarnDue(9, 0, 80), false);
+});
+
+test('doneAtCap: budget-stopped with every criterion ticked is done, and nothing else is', () => {
+  const budget = { budgetStopped: true, wasInterrupted: false, usageLimited: false };
+  assert.equal(doneAtCap(budget, []), true);
+  assert.equal(doneAtCap(budget, ['screenshots saved']), false, 'an unticked box is not done');
+  assert.equal(doneAtCap(budget, null), false, 'no DONE WHEN section says nothing either way');
+  assert.equal(doneAtCap({ ...budget, wasInterrupted: true }, []), false, 'a human stop is not a finish');
+  assert.equal(doneAtCap({ ...budget, usageLimited: true }, []), false, 'a usage limit is not a finish');
+  assert.equal(doneAtCap({ ...budget, budgetStopped: false }, []), false);
+});

package/src/orchestrator.ts

@@ -266,6 +266,31 @@ const DEFAULT_MAX_TURNS = 150;
 export const DEFAULT_MAX_TOKENS = 20_000_000;
 
 /** The cap behind a capReached() sentence, as the run record stores it. */
+/**
+ * Is it time to tell the director to start winding down? True once spend
+ * crosses the warn threshold and while it is still under the cap — past the
+ * cap the wind-down order takes over, and a warning then would be noise.
+ */
+export function budgetWarnDue(costUsd: number, budgetUsd: number, warnAt: number | undefined): boolean {
+  if (!Number.isFinite(warnAt as number) || (warnAt as number) <= 0 || (warnAt as number) >= 100) return false;
+  if (!(budgetUsd > 0)) return false;
+  return costUsd >= budgetUsd * ((warnAt as number) / 100) && costUsd < budgetUsd;
+}
+
+/**
+ * A run the budget stopped, whose own DONE WHEN criteria are all ticked, is
+ * done: it reached its criteria and then reached its limit, in that order.
+ * Only for the budget — a human interrupt or a usage limit says nothing
+ * about the work — and only when the doc actually had criteria to tick.
+ */
+export function doneAtCap(
+  flags: { budgetStopped: boolean; wasInterrupted: boolean; usageLimited: boolean },
+  unmet: string[] | null,
+): boolean {
+  if (!flags.budgetStopped || flags.wasInterrupted || flags.usageLimited) return false;
+  return Array.isArray(unmet) && unmet.length === 0;
+}
+
 export function stopReasonOf(cap: string): 'budget' | 'turns' | 'time' | 'tokens' {
   if (cap.startsWith('TURN')) return 'turns';
   if (cap.startsWith('TIME')) return 'time';
@@ -619,6 +644,14 @@ export type Emitter = (event: string, data: unknown) => void;
 /** Persists updated run metadata (fire-and-forget from the run's viewpoint). */
 export type MetaSink = (meta: RunMeta) => void;
 
+/**
+ * Turns a worker gets before the SDK stops it. Raised from 60: five workers
+ * in four missions hit the cap mid-task on legitimate, brief-sized work
+ * (a hundred TypeScript errors in one package; a test-suite port), and each
+ * time the director paid to respawn one that re-read the same files.
+ */
+const WORKER_MAX_TURNS = 100;
+
 export const DIRECTOR_CHARTER = `
 You are the FOREMAN DIRECTOR. You run a mission autonomously inside one folder by
 directing worker agents. Non-negotiable rules, in priority order:
@@ -695,6 +728,16 @@ directing worker agents. Non-negotiable rules, in priority order:
    (a dev server, a static preview), call mcp__foreman__expose_service with
    its port and put the URL it returns in your report — the human can open
    it from their phone. Keep that server up until the mission ends.
+   CLEAN UP WHAT YOU STARTED: before you finish, stop every server, watcher or
+   background process the crew started that you are not deliberately leaving
+   for the human, and name in your report any you left up and on which port.
+   A process that outlives the mission holds its port until somebody hunts it
+   down by hand.
+   SIZE THE TASK TO THE WORKER: a worker is stopped after ${WORKER_MAX_TURNS}
+   turns of its own. It gets one continuation to finish what it was doing, and
+   after that the task comes back to you half-done. So give a worker a task it
+   can finish in that many steps — split the big ones — rather than one brief
+   that has to be rescued twice.
 4. REPORT WHAT YOU SEE. Judge the work as a competent professional would, not
    only against the letter of the acceptance criteria. If you observe a defect
    the criteria did not name — tap targets too small to use, unreadable
@@ -748,13 +791,6 @@ const USAGE_LIMIT_RE = /out of usage credits|usage limit reached|upgrade to incr
 /** One worker's outcome, as runWorker hands it back. */
 interface WorkerOutcome { report: string; isError: boolean }
 
-/**
- * Turns a worker gets before the SDK stops it. Raised from 60: five workers
- * in four missions hit the cap mid-task on legitimate, brief-sized work
- * (a hundred TypeScript errors in one package; a test-suite port), and each
- * time the director paid to respawn one that re-read the same files.
- */
-const WORKER_MAX_TURNS = 100;
 /** What a worker stopped by the cap is told when its session is picked back up. */
 const WORKER_CONTINUE_PROMPT =
   'You were stopped by the turn cap, not by a failure. Your session and your files are as you left them; ' +
@@ -889,7 +925,7 @@ export class MissionRun {
      * has no `expose_service` to offer.
      */
     private readonly host: {
-      exposeService?: (runId: string, port: number, label: string) => Promise<{ ok: true; url: string; path: string } | { ok: false; reason: string }>;
+      exposeService?: (runId: string, port: number, label: string) => Promise<{ ok: true; url: string; path: string; pid?: number } | { ok: false; reason: string }>;
       /** The browser channel detected at dispatch (src/browser.ts); Chrome when the host says nothing. */
       browserChannel?: string;
     } = {},
@@ -1080,6 +1116,7 @@ export class MissionRun {
         // overrun quiet.
         this.budgetNoticeSent = false;
         this.budgetKillSent = false;
+        this.budgetWarnSent = false;
         this.budgetStopped = false;
       }
     }
@@ -1332,6 +1369,23 @@ export class MissionRun {
       // the one lie a mission runner cannot afford. Downgrading to
       // 'interrupted' is also the useful answer: it is what makes the run
       // resumable rather than closed.
+      // A mission whose own record says every criterion is verified is done,
+      // even if the cap ended the turn it was writing its report in. Calling
+      // that 'interrupted' told the fleet a finished mission had failed, and
+      // invited a resume that spent more to rewrite a report already on disk.
+      // The stop reason stays on the record, so nothing is hidden.
+      if (this.meta.status === 'interrupted' && this.budgetStopped
+          && !this.wasInterrupted && !this.usageLimited) {
+        const unmet = await this.unmetCriteria();
+        if (doneAtCap({ budgetStopped: this.budgetStopped, wasInterrupted: this.wasInterrupted, usageLimited: this.usageLimited }, unmet)) {
+          this.meta.status = 'done';
+          this.emit('mission_done_at_cap', {
+            costUsd: this.meta.costUsd, budgetUsd: this.meta.budgetUsd, reason: this.meta.stopReason,
+            text: 'Every DONE WHEN criterion was verified before the cap ended the run, so this mission is done. ' +
+              'It stopped at its limit rather than finishing under it — the report may be shorter than usual.',
+          });
+        }
+      }
       if (this.meta.status === 'done') {
         const unmet = await this.unmetCriteria();
         if (unmet?.length) {
@@ -1482,6 +1536,7 @@ export class MissionRun {
 
   private budgetNoticeSent = false;
   private budgetKillSent = false;
+  private budgetWarnSent = false;
 
   /**
    * Keeps an "always allow" grant out of `git status`.
@@ -1652,6 +1707,26 @@ export class MissionRun {
       void this.interrupt();
       return;
     }
+    // Before the fence, a nudge. A director that only learns of the cap when
+    // it hits it does its verification and its report inside the one turn it
+    // has left — which is how two missions that had finished their work were
+    // cut mid-report and read as failures. Warn while there is still room to
+    // wind down deliberately.
+    if (!this.budgetWarnSent && budgetWarnDue(costUsd, budgetUsd, this.meta.budgetWarnAt)) {
+      this.budgetWarnSent = true;
+      const pct = Math.round((costUsd / budgetUsd) * 100);
+      this.emit('budget_alert', {
+        level: 'warn', costUsd, budgetUsd,
+        text: `${pct}% of the budget spent ($${costUsd.toFixed(2)} of $${budgetUsd.toFixed(2)}) — director told to start verifying.`,
+      });
+      this.directorInput?.push(
+        '[BUDGET — automated notice]\n' +
+        `You have spent $${costUsd.toFixed(2)} of the $${budgetUsd.toFixed(2)} cap (${pct}%). ` +
+        'Start winding down now: finish or stop the work in flight, do not begin anything you ' +
+        'cannot complete and verify within what is left, and get your verification and MISSION.md ' +
+        'up to date. At the cap you get one final turn, and at 125% the run is interrupted.',
+      );
+    }
     if (!this.budgetNoticeSent && costUsd >= budgetUsd) {
       this.budgetNoticeSent = true;
       this.emit('budget_alert', {
@@ -2393,7 +2468,7 @@ export class MissionRun {
         if (!fn) return { content: [{ type: 'text' as const, text: 'Exposing services is not available in this run.' }] };
         const r = await fn(this.meta.id, port, (label ?? '').trim() || `port ${port}`);
         if (!r.ok) return { content: [{ type: 'text' as const, text: `Not exposed: ${r.reason}` }] };
-        const entry = { port, label: (label ?? '').trim() || `port ${port}`, path: r.path, since: Date.now() };
+        const entry = { port, label: (label ?? '').trim() || `port ${port}`, path: r.path, since: Date.now(), pid: r.pid };
         this.meta.services = [...(this.meta.services ?? []).filter((s) => s.port !== port), entry];
         this.saveMeta(this.meta);
         this.emit('service_exposed', { ...entry, url: r.url });

package/src/server.ts

@@ -73,10 +73,10 @@ import { budgetAnchor, modelRecords, projectRecord, recordLine } from './track-r
 import { reconcileRole } from './role-provider.js';
 import { detectBrowser, installChromium } from './browser.js';
 import { frozenDeck, frozenMissionDoc, parkMissionDoc, restoreMissionDoc, snapshotRun } from './snapshot.js';
-import { closeMissionBranch, compareUrl, createPullRequest, ensureMissionBranch, ghReady, gitInfo, missionBranchName, prDraft, pullRequestState, pushBranch, renameMissionBranch, startMissionBranch, type GitInfo } from './gitwork.js';
+import { closeMissionBranch, compareUrl, createPullRequest, dirtyPaths, ensureMissionBranch, ghReady, gitInfo, resolvePrBase, missionBranchName, prDraft, pullRequestState, pushBranch, renameMissionBranch, startMissionBranch, type GitInfo } from './gitwork.js';
 import { detectTailscale, tailnetUrl } from './tailscale.js';
 import { checkForUpdate, currentVersion, type UpdateInfo } from './update.js';
-import { ServiceRegistry, portOpen, servicesHandler } from './services.js';
+import { ServiceRegistry, listeningPid, portOpen, servicesHandler, stopService } 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,
@@ -1578,8 +1578,11 @@ async function driveRun(
     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);
-      return { ok: true, url: `${await servicesBase()}${svc.path}`, path: svc.path };
+      // Whoever holds the port right now is what the crew just started, and
+      // the only process a later stop is allowed to touch.
+      const pid = await listeningPid(port);
+      const svc = services.register(runId, port, label, pid ?? undefined);
+      return { ok: true, url: `${await servicesBase()}${svc.path}`, path: svc.path, pid: pid ?? undefined };
     },
   });
   activeByProject.set(projectId, run);
@@ -1648,6 +1651,8 @@ async function effectiveSettings(projectId: string): Promise<{
   directorProviderId?: string; workerProviderId?: string;
   /** In a repository, each mission runs on a branch of its own (default on). */
   gitBranchPerMission: boolean;
+  /** Percent of the cap at which the director is told to start verifying (default 80). */
+  budgetWarnAt: number;
 }> {
   const s = await store.readSettings()
     .catch(() => ({ global: {}, projects: {} as Record<string, object> }));
@@ -1669,6 +1674,10 @@ async function effectiveSettings(projectId: string): Promise<{
     directorProviderId: str(p.directorProviderId ?? g.directorProviderId),
     workerProviderId: str(p.workerProviderId ?? g.workerProviderId),
     gitBranchPerMission: (p.gitBranchPerMission ?? g.gitBranchPerMission) !== false,
+    budgetWarnAt: (() => {
+      const raw = Number(p.budgetWarnAt ?? g.budgetWarnAt);
+      return Number.isFinite(raw) && raw > 0 && raw < 100 ? raw : 60;
+    })(),
   };
 }
 
@@ -1708,6 +1717,7 @@ async function startRun(
     workerProviderId: roleProviders.worker ?? settings.workerProviderId,
     ownerPid: process.pid,
     browserTools: browserTools || undefined,
+    budgetWarnAt: settings.budgetWarnAt,
     toolPolicy: settings.toolPolicy,
     autoAllowReadOnly: settings.autoAllowReadOnly,
     // Frozen at dispatch: a later change to the project or the server default
@@ -1737,6 +1747,7 @@ async function startRun(
   // 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 carried = await dirtyPaths(folder);
     const g = await startMissionBranch(folder, mission, meta.id);
     const emit = makeEmitter(meta.id, projectId);
     if ('error' in g) {
@@ -1746,6 +1757,14 @@ async function startRun(
       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.` });
+      // Whoever started this may not have been at the keyboard to be asked.
+      if (carried.length) {
+        emit('git_note', {
+          text: `The checkout had uncommitted changes when this mission started, and they came along to ${g.branch}: `
+            + `${carried.slice(0, 5).join(', ')}${carried.length > 5 ? `, and ${carried.length - 5} more` : ''}. `
+            + "They will be part of the mission's closing commit unless you take them off the branch first.",
+        });
+      }
     }
   }
   await driveRun(projectId, meta);
@@ -1946,6 +1965,8 @@ const server = http.createServer(async (req, res) => {
   const runResumeMatch = url.pathname.match(/^\/runs\/([^/]+)\/resume$/);
   const prMatch = url.pathname.match(/^\/runs\/([^/]+)\/pr$/);
   const prStateMatch = url.pathname.match(/^\/runs\/([^/]+)\/pr\/state$/);
+  const runServicesMatch = url.pathname.match(/^\/runs\/([^/]+)\/services$/);
+  const stopServiceMatch = url.pathname.match(/^\/runs\/([^/]+)\/services\/(\d{1,5})\/stop$/);
   const projectMatch = url.pathname.match(/^\/projects\/([^/]+)$/);
   const providerKeyMatch = url.pathname.match(/^\/providers\/([A-Za-z0-9_-]{1,64})\/key$/);
 
@@ -2231,7 +2252,7 @@ const server = http.createServer(async (req, res) => {
     } else if (req.method === 'POST' && url.pathname === '/run') {
       const {
         projectId, mission, budgetUsd, directorModel, workerModel, browserTools,
-        directorProviderId, workerProviderId,
+        directorProviderId, workerProviderId, allowDirty,
       } = await readBody(req);
       if (typeof projectId !== 'string' || typeof mission !== 'string' || !mission.trim()) {
         return json(res, 400, { error: 'projectId and mission are required' });
@@ -2239,6 +2260,29 @@ const server = http.createServer(async (req, res) => {
       const project = await store.getProject(projectId);
       if (!project) return json(res, 404, { error: 'unknown project' });
       await mkdir(project.folder, { recursive: true });
+      // A mission on its own branch takes the working tree with it: `checkout
+      // -b` carries uncommitted work onto the mission branch, and the closing
+      // commit sweeps whatever is left into the mission's own commit, under
+      // the mission's name. So a dirty checkout is refused here rather than
+      // quietly absorbed — with an override, because it is the human's tree
+      // and their call. Only this route refuses: a mission started from the
+      // phone has nobody standing at the keyboard to answer, and gets the
+      // warning in its transcript instead.
+      {
+        const s = await effectiveSettings(projectId);
+        if (s.gitBranchPerMission && allowDirty !== true) {
+          const info = await gitInfo(project.folder);
+          if (info.repo && info.dirty) {
+            const files = await dirtyPaths(project.folder);
+            return json(res, 409, {
+              error: `This checkout has uncommitted changes on ${info.branch ?? 'HEAD'}. `
+                + 'They would follow the mission onto its branch and be committed with its work. '
+                + 'Commit or stash them first, or start anyway.',
+              code: 'dirty-checkout', branch: info.branch ?? null, files,
+            });
+          }
+        }
+      }
       // Reservation is the last step before dispatch — no awaits in between.
       if (!reserveProject(projectId)) {
         return json(res, 409, { error: 'this project already has an active mission' });
@@ -2666,6 +2710,33 @@ const server = http.createServer(async (req, res) => {
       broadcastChat(FLEET_CHAT_ID, 'chat_cleared', {});
       json(res, 200, { ok: true });
 
+    } else if (runServicesMatch && req.method === 'GET') {
+      // What this run exposed, and what of it is still up. Asked after a run
+      // ends as much as during it: a finished mission leaves no agent behind
+      // to tidy, so the human needs somewhere to see the leftovers.
+      const meta = await store.readMeta(runServicesMatch[1]).catch(() => null);
+      if (!meta) return json(res, 404, { error: 'unknown run' });
+      const list = await Promise.all((meta.services ?? []).map(async (s) => {
+        const holder = await listeningPid(s.port);
+        return {
+          port: s.port, label: s.label, since: s.since, path: s.path,
+          listening: holder !== null,
+          // Only a process Foreman watched start is one it will offer to stop.
+          ours: holder !== null && s.pid !== undefined && holder === s.pid,
+        };
+      }));
+      json(res, 200, { runId: meta.id, status: meta.status, services: list });
+
+    } else if (stopServiceMatch && req.method === 'POST') {
+      const meta = await store.readMeta(stopServiceMatch[1]).catch(() => null);
+      if (!meta) return json(res, 404, { error: 'unknown run' });
+      const port = Number(stopServiceMatch[2]);
+      const svc = (meta.services ?? []).find((s) => s.port === port);
+      if (!svc) return json(res, 404, { error: 'this run did not expose that port' });
+      const r = await stopService(port, svc.pid);
+      if (!r.ok) return json(res, 409, { error: r.reason });
+      json(res, 200, { ok: true, how: r.how });
+
     } 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.
@@ -2688,9 +2759,13 @@ const server = http.createServer(async (req, res) => {
       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();
+      // Where the request can actually go, which is not always where the
+      // mission was branched from — see resolvePrBase.
+      const target = await resolvePrBase(meta.folder, meta.git.base);
       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),
+        ...prDraft(meta, doc), branch: meta.git.branch, base: target.base, commits: meta.git.commits ?? null,
+        branchedFrom: meta.git.base, baseFellBack: target.fellBack,
+        remote: info.remote, compareUrl: compareUrl(info.remote, target.base, meta.git.branch),
         gh, pr: meta.git.pr ?? null, onBranch: info.branch === meta.git.branch, dirty: Boolean(info.dirty),
       });
 
@@ -2718,18 +2793,24 @@ const server = http.createServer(async (req, res) => {
       let url: string | undefined;
       let method: 'gh' | 'compare' = 'compare';
       let note: string | undefined;
+      const target = await resolvePrBase(meta.folder, meta.git.base);
       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 });
+        const r = await createPullRequest(meta.folder, { base: target.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;
+      if (!url) url = compareUrl(info.remote, target.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 });
+      emit('pull_request', {
+        branch: meta.git.branch, base: target.base, url, method,
+        text: target.fellBack
+          ? `${text} (targeting ${target.base}: this mission was branched from ${meta.git.base}, which is not on the remote)`
+          : text,
+      });
       json(res, 200, { ok: true, url, method, pushed: true, note });
 
     } else if (req.method === 'POST' && url.pathname === '/steer') {
@@ -2951,7 +3032,7 @@ void closeOrphanedChatTurns().then((ids) => {
 // Services declared by earlier runs are still worth proxying if their
 // processes outlived the run; the registry is rebuilt from what was saved.
 void store.listRuns().then((runs) => {
-  for (const r of runs) for (const s of (r as { services?: Array<{ port: number; label: string }> }).services ?? []) services.register(r.id, s.port, s.label);
+  for (const r of runs) for (const s of (r as { services?: Array<{ port: number; label: string; pid?: number }> }).services ?? []) services.register(r.id, s.port, s.label, s.pid);
 }).catch(() => {});
 
 if (BIND === 'all') {

package/src/services.test.ts

@@ -1,7 +1,8 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import http from 'node:http';
-import { ServiceRegistry, parseServicePath, portOpen, proxyToService, servicePath, servicesHandler } from './services.js';
+import { ServiceRegistry, listeningPid, parseServicePath, portOpen, proxyToService, servicePath, servicesHandler, stopService } from './services.js';
+import { spawn } from 'node:child_process';
 import { requestAllowed } from './guard.js';
 
 test('service paths round-trip and reject junk', () => {
@@ -86,3 +87,47 @@ test('the services port serves only /svc/ — everything else is a 404', async (
     server.close();
   }
 });
+
+/** A child process holding a port, the way a crew's dev server does. */
+async function server(): Promise<{ pid: number; port: number; kill: () => void }> {
+  const child = spawn(process.execPath, ['-e',
+    "const s=require('http').createServer((_,r)=>r.end('ok'));s.listen(0,'127.0.0.1',()=>console.log(s.address().port));"],
+    { stdio: ['ignore', 'pipe', 'ignore'] });
+  const port = await new Promise<number>((resolve, reject) => {
+    child.stdout.once('data', (b) => resolve(Number(String(b).trim())));
+    child.once('error', reject);
+    setTimeout(() => reject(new Error('the test server never reported a port')), 5000);
+  });
+  return { pid: child.pid as number, port, kill: () => { try { child.kill('SIGKILL'); } catch { /* gone */ } } };
+}
+
+test('listeningPid names the process holding a port, and nobody for a free one', async () => {
+  const s = await server();
+  try {
+    assert.equal(await listeningPid(s.port), s.pid);
+  } finally { s.kill(); }
+  // Once it is gone the port is nobody's.
+  await new Promise((r) => setTimeout(r, 300));
+  assert.equal(await listeningPid(s.port), null);
+});
+
+test('stopService stops the recorded process, and refuses every other case', async () => {
+  const s = await server();
+  try {
+    assert.deepEqual(await stopService(s.port, undefined), {
+      ok: false, reason: 'Foreman did not record which process this was, so it will not kill anything.',
+    }, 'no recorded pid means no killing');
+
+    const wrong = await stopService(s.port, s.pid + 100000);
+    assert.equal(wrong.ok, false, 'a port held by someone else is left alone');
+    assert.match((wrong as { reason: string }).reason, /not the/);
+    assert.equal(await portOpen(s.port), true, 'and the refusal really did leave it running');
+
+    const stopped = await stopService(s.port, s.pid);
+    assert.equal(stopped.ok, true);
+    assert.equal(await portOpen(s.port), false);
+
+    const gone = await stopService(s.port, s.pid);
+    assert.equal(gone.ok, false, 'stopping twice is not an error worth pretending about');
+  } finally { s.kill(); }
+});