@amenophis1er/foreman 0.1.15 → 0.1.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amenophis1er/foreman",
-  "version": "0.1.15",
+  "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/orchestrator.ts

@@ -644,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:
@@ -720,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
@@ -773,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; ' +
@@ -914,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;
     } = {},
@@ -2457,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);
@@ -1673,7 +1676,7 @@ async function effectiveSettings(projectId: string): Promise<{
     gitBranchPerMission: (p.gitBranchPerMission ?? g.gitBranchPerMission) !== false,
     budgetWarnAt: (() => {
       const raw = Number(p.budgetWarnAt ?? g.budgetWarnAt);
-      return Number.isFinite(raw) && raw > 0 && raw < 100 ? raw : 80;
+      return Number.isFinite(raw) && raw > 0 && raw < 100 ? raw : 60;
     })(),
   };
 }
@@ -1744,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) {
@@ -1753,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);
@@ -1953,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$/);
 
@@ -2238,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' });
@@ -2246,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' });
@@ -2673,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.
@@ -2695,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),
       });
 
@@ -2725,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') {
@@ -2958,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(); }
+});

package/src/services.ts

@@ -16,11 +16,18 @@
  */
 import http from 'node:http';
 import net from 'node:net';
+import { execFile } from 'node:child_process';
 import type { GuardVerdict } from './guard.js';
 
 export interface ExposedService {
   port: number;
   label: string;
+  /**
+   * The process listening on the port when the crew exposed it. Recorded so a
+   * stop later can prove it is still the same process — a port is a slot
+   * anyone can take, and Foreman must never kill something it did not start.
+   */
+  pid?: number;
   /** `/svc/<runId>/<port>/` — the path under the services origin, not Foreman's. */
   path: string;
   since: number;
@@ -53,14 +60,66 @@ export function portOpen(port: number, timeoutMs = 800): Promise<boolean> {
   });
 }
 
+/**
+ * The pid of whatever is listening on a local port, via lsof. Null when
+ * nothing is, or when lsof is unavailable — in which case Foreman simply
+ * never offers to stop the service, which is the safe direction.
+ */
+export async function listeningPid(port: number): Promise<number | null> {
+  return new Promise((resolve) => {
+    execFile('lsof', ['-nP', '-t', `-iTCP:${port}`, '-sTCP:LISTEN'], { timeout: 3000 }, (err, stdout) => {
+      if (err) return resolve(null);
+      const pid = Number(String(stdout).split('\n')[0]?.trim());
+      resolve(Number.isInteger(pid) && pid > 0 ? pid : null);
+    });
+  });
+}
+
+/** Is this process still alive? Signal 0 asks without sending anything. */
+function alive(pid: number): boolean {
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+export type StopResult =
+  | { ok: true; how: 'term' | 'kill' }
+  | { ok: false; reason: string };
+
+/**
+ * Stops a service the crew started, and only that one. The pid recorded when
+ * it was exposed must still be the process holding the port: if something
+ * else took the port since, or the recorded process is gone, this refuses
+ * rather than guessing. SIGTERM first, so a dev server gets to clean up.
+ */
+export async function stopService(port: number, expectedPid: number | undefined, graceMs = 4000): Promise<StopResult> {
+  if (!expectedPid) return { ok: false, reason: 'Foreman did not record which process this was, so it will not kill anything.' };
+  const holder = await listeningPid(port);
+  if (holder === null) return { ok: false, reason: `nothing is listening on 127.0.0.1:${port} any more` };
+  if (holder !== expectedPid) {
+    return { ok: false, reason: `port ${port} is held by process ${holder} now, not the ${expectedPid} this run started — leaving it alone` };
+  }
+  try { process.kill(expectedPid, 'SIGTERM'); } catch (err) {
+    return { ok: false, reason: err instanceof Error ? err.message : String(err) };
+  }
+  const deadline = Date.now() + graceMs;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 150));
+    if (!alive(expectedPid)) return { ok: true, how: 'term' };
+  }
+  try { process.kill(expectedPid, 'SIGKILL'); } catch { /* already gone */ }
+  await new Promise((r) => setTimeout(r, 200));
+  return alive(expectedPid)
+    ? { ok: false, reason: `process ${expectedPid} did not stop` }
+    : { ok: true, how: 'kill' };
+}
+
 export class ServiceRegistry {
   private byRun = new Map<string, ExposedService[]>();
 
-  register(runId: string, port: number, label: string): ExposedService {
+  register(runId: string, port: number, label: string, pid?: number): ExposedService {
     const list = this.byRun.get(runId) ?? [];
     const existing = list.find((s) => s.port === port);
-    if (existing) { existing.label = label || existing.label; return existing; }
-    const svc: ExposedService = { port, label: label || `port ${port}`, path: servicePath(runId, port), since: Date.now() };
+    if (existing) { existing.label = label || existing.label; if (pid) existing.pid = pid; return existing; }
+    const svc: ExposedService = { port, label: label || `port ${port}`, path: servicePath(runId, port), since: Date.now(), pid };
     this.byRun.set(runId, [...list, svc]);
     return svc;
   }

package/src/types.ts

@@ -315,7 +315,7 @@ export interface RunMeta {
    */
   allowedRoots?: string[];
   /** Dev servers the crew exposed through Foreman's proxy (see services.ts). */
-  services?: Array<{ port: number; label: string; path: string; since: number }>;
+  services?: Array<{ port: number; label: string; path: string; since: number; pid?: number }>;
   /**
    * How long an approval card or director question may wait for the human
    * before it is resolved with its unattended default (deny / "decide