@amenophis1er/foreman 0.1.13 → 0.1.15

package/src/server.ts

@@ -72,7 +72,8 @@ 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 { 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 { detectTailscale, tailnetUrl } from './tailscale.js';
 import { checkForUpdate, currentVersion, type UpdateInfo } from './update.js';
 import { ServiceRegistry, portOpen, servicesHandler } from './services.js';
@@ -593,6 +594,21 @@ function makeEmitter(runId: string, projectId: string) {
       runLabelCache.set(runId, { ...runLabelCache.get(runId), mission: String(d.mission ?? '') });
     } else if (event === 'run_titled') {
       runLabelCache.set(runId, { ...runLabelCache.get(runId), title: String(d.title ?? '') });
+      // The branch was named from the brief before the title existed; now it
+      // can carry the title. Only while it is still the brief-derived name and
+      // nothing is committed on it — the mission's first turns.
+      const run = activeRuns().find((r) => r.meta.id === runId);
+      const title = String(d.title ?? '').trim();
+      if (run?.meta.git && title && run.meta.git.branch === missionBranchName(run.meta.mission, runId) && !(run.meta.git.commits)) {
+        void renameMissionBranch(run.meta.folder, run.meta.git.branch, title, runId).then(async (renamed) => {
+          if (!renamed || !run.meta.git) return;
+          const was = run.meta.git.branch;
+          run.meta.git = { ...run.meta.git, branch: renamed };
+          await store.writeMeta(run.meta).catch(() => {});
+          gitInfoCache.delete(run.meta.folder);
+          makeEmitter(runId, projectId)('git_branch', { branch: renamed, base: run.meta.git.base, text: `Branch renamed to ${renamed} (was ${was}) now that the run has a title.` });
+        });
+      }
     }
     if (!projectsCache.has(projectId)) {
       void store.getProject(projectId).then((p) => { if (p) projectsCache.set(projectId, { name: p.name }); });
@@ -1595,6 +1611,15 @@ async function driveRun(
     // However the run ended, it no longer needs its gateways.
     releaseGateways(meta.id);
     if (activeByProject.get(projectId) === run) activeByProject.delete(projectId);
+    // Freeze the record: the mission doc and the deck as they stand at this
+    // moment, beside the run's meta and log. Done first, before the branch
+    // closes, so the record is what the crew left — a later mission in the
+    // same folder rewrites MISSION.md and the live diff, never this copy.
+    const frozen = await snapshotRun(store.runDirectory(meta.id), meta.folder, meta.id);
+    if (frozen.doc || frozen.deck) {
+      meta.snapshotAt = Date.now();
+      await store.writeMeta(meta).catch(() => {});
+    }
     // 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.
@@ -1623,6 +1648,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> }));
@@ -1644,6 +1671,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 : 80;
+    })(),
   };
 }
 
@@ -1681,7 +1712,9 @@ async function startRun(
     // choosing a model chooses where that role runs.
     directorProviderId: roleProviders.director ?? settings.directorProviderId,
     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
@@ -1699,6 +1732,14 @@ async function startRun(
     return;
   }
   await consumeProposal(projectId, meta.id, mission).catch(() => {});
+  // The folder's MISSION.md belongs to whichever run wrote it. Parked into
+  // that run's record (when it lacks one) and cleared, so this run's status
+  // reads empty until its own director writes the plan — not 13/14 done.
+  {
+    const previous = (await store.listRuns().catch(() => [] as RunMeta[]))
+      .find((r) => r.projectId === projectId && r.id !== meta.id && r.status !== 'running');
+    await parkMissionDoc(folder, previous ? store.runDirectory(previous.id) : null).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.
@@ -1761,6 +1802,7 @@ async function resumeRun(projectId: string, meta: RunMeta, pick: {
   meta.stopReason = undefined;
   meta.status = 'running';
   meta.endedAt = undefined;
+  meta.ownerPid = process.pid;
   meta.resumes = (meta.resumes ?? 0) + 1;
   if (meta.budgetUsd !== budgetWas) {
     makeEmitter(meta.id, projectId)('settings_changed', {
@@ -1773,6 +1815,15 @@ async function resumeRun(projectId: string, meta: RunMeta, pick: {
     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);
   }
+  // The director resumes from MISSION.md. If another mission ran here since,
+  // the folder's copy is that mission's; this run's own goes back first.
+  const restored = await restoreMissionDoc(store.runDirectory(meta.id), meta.folder).catch(() => 'none' as const);
+  if (restored === 'restored') {
+    const emit = makeEmitter(meta.id, projectId);
+    emit('mission_doc_restored', {
+      text: 'Restored this run\'s own MISSION.md into the folder before resuming; a later mission had overwritten it.',
+    });
+  }
   await store.writeMeta(meta).catch((err) => {
     console.error(`failed to persist resume of ${meta.id}:`, err);
   });
@@ -1895,7 +1946,9 @@ const server = http.createServer(async (req, res) => {
       return project ? { folder: project.folder } : null;
     }
     const m = await store.readMeta(id).catch(() => null);
-    return m ? { folder: m.folder } : null;
+    if (!m) return null;
+    const frozen = m.status !== 'running' ? await frozenDeck(store.runDirectory(m.id)) : null;
+    return { folder: m.folder, ...(frozen ? { deck: frozen } : {}) };
   })) return;
   const runResumeMatch = url.pathname.match(/^\/runs\/([^/]+)\/resume$/);
   const prMatch = url.pathname.match(/^\/runs\/([^/]+)\/pr$/);
@@ -2779,9 +2832,11 @@ const server = http.createServer(async (req, res) => {
       if (!runId) return json(res, 400, { error: 'run parameter is required' });
       const meta = await store.readMeta(runId);
       if (!meta) return json(res, 404, { error: 'unknown run' });
-      const doc = await readFile(path.join(meta.folder, '.foreman', 'MISSION.md'), 'utf8')
-        .catch(() => null);
-      json(res, 200, { doc });
+      // A finished run answers with the doc as it ended; only a running run
+      // reads the folder, which is the one mission running there right now.
+      const frozen = meta.status !== 'running' ? await frozenMissionDoc(store.runDirectory(meta.id)) : null;
+      const doc = frozen ?? await readFile(path.join(meta.folder, '.foreman', 'MISSION.md'), 'utf8').catch(() => null);
+      json(res, 200, { doc, frozen: frozen !== null });
 
     } else if (req.method === 'GET' && url.pathname === '/browse') {
       const requested = url.searchParams.get('path') || os.homedir();

package/src/snapshot.test.ts

@@ -0,0 +1,68 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { frozenDeck, frozenMissionDoc, hasSnapshot, parkMissionDoc, restoreMissionDoc, snapshotRun } from './snapshot.js';
+
+async function site() {
+  const root = await mkdtemp(path.join(os.tmpdir(), 'foreman-snap-'));
+  const folder = path.join(root, 'proj'); const runDir = path.join(root, 'runs', 'r1');
+  await mkdir(path.join(folder, '.foreman'), { recursive: true });
+  await mkdir(runDir, { recursive: true });
+  return { root, folder, runDir };
+}
+
+test('snapshotRun freezes the mission doc and a deck beside the run, and reads them back', async () => {
+  const { root, folder, runDir } = await site();
+  await writeFile(path.join(folder, '.foreman', 'MISSION.md'), '# Mission A\n- [x] done\n');
+  await writeFile(path.join(folder, 'a.txt'), 'hello\n');
+  const r = await snapshotRun(runDir, folder, 'r1', 1234);
+  assert.deepEqual(r, { doc: true, deck: true });
+  assert.equal(await frozenMissionDoc(runDir), '# Mission A\n- [x] done\n');
+  const deck = await frozenDeck(runDir);
+  assert.equal(deck?.frozenAt, 1234);
+  assert.match(deck?.note ?? '', /As the folder stood when the run ended/);
+  assert.equal(await hasSnapshot(runDir), true);
+  // A later mission overwrites the folder's doc; the record does not move.
+  await writeFile(path.join(folder, '.foreman', 'MISSION.md'), '# Mission B\n');
+  assert.equal(await frozenMissionDoc(runDir), '# Mission A\n- [x] done\n');
+  await rm(root, { recursive: true, force: true });
+});
+
+test('restoreMissionDoc puts the run\'s own doc back, and says whether it had to', async () => {
+  const { root, folder, runDir } = await site();
+  assert.equal(await restoreMissionDoc(runDir, folder), 'none', 'no record yet');
+  await writeFile(path.join(runDir, 'MISSION.md'), '# Mission A\n');
+  await writeFile(path.join(folder, '.foreman', 'MISSION.md'), '# Mission B\n');
+  assert.equal(await restoreMissionDoc(runDir, folder), 'restored');
+  assert.equal(await readFile(path.join(folder, '.foreman', 'MISSION.md'), 'utf8'), '# Mission A\n');
+  assert.equal(await restoreMissionDoc(runDir, folder), 'same');
+  await rm(root, { recursive: true, force: true });
+});
+
+test('a run with no mission doc still freezes its deck; a missing folder freezes nothing and does not throw', async () => {
+  const { root, folder, runDir } = await site();
+  const r = await snapshotRun(runDir, folder, 'r1');
+  assert.equal(r.doc, false);
+  assert.equal(await hasSnapshot(runDir), r.deck);
+  const gone = await snapshotRun(path.join(root, 'runs', 'r2'), path.join(root, 'nowhere'), 'r2');
+  assert.equal(gone.doc, false);
+  assert.equal(await hasSnapshot(path.join(root, 'runs', 'r2')), gone.deck);
+  await rm(root, { recursive: true, force: true });
+});
+
+
+test('parkMissionDoc clears the folder for a new run and keeps the old doc with the run that wrote it', async () => {
+  const { root, folder, runDir } = await site();
+  assert.equal(await parkMissionDoc(folder, runDir), 'none', 'nothing to park');
+  await writeFile(path.join(folder, '.foreman', 'MISSION.md'), '# Old mission\n- [x] all done\n');
+  assert.equal(await parkMissionDoc(folder, runDir), 'parked');
+  assert.equal(await readFile(path.join(folder, '.foreman', 'MISSION.md'), 'utf8').catch(() => null), null, 'the folder starts clean');
+  assert.equal(await frozenMissionDoc(runDir), '# Old mission\n- [x] all done\n', 'kept with the previous run');
+  // A previous run that already has its own copy is not overwritten by a later folder state.
+  await writeFile(path.join(folder, '.foreman', 'MISSION.md'), '# Something else\n');
+  await parkMissionDoc(folder, runDir);
+  assert.equal(await frozenMissionDoc(runDir), '# Old mission\n- [x] all done\n');
+  await rm(root, { recursive: true, force: true });
+});

package/src/snapshot.ts

@@ -0,0 +1,116 @@
+/**
+ * What a finished run said, kept with the run.
+ *
+ * `.foreman/MISSION.md` is one file per project folder and every mission
+ * writes it, and the deck is a live diff of the folder against the run's
+ * baseline. Both were read fresh whenever a run was looked at — so the moment
+ * a newer mission started in the same project, every older run's page, its
+ * `run_report` and its resume were reading the new mission's doc and a diff
+ * that kept growing with later work. A resume of an older interrupted run
+ * handed its director the wrong mission outright.
+ *
+ * So a run's record freezes when the run ends: its MISSION.md and a summary
+ * of its deck are copied into `~/.foreman/runs/<id>/`. Finished runs are read
+ * from the copy; a running run still reads the live folder. On resume the
+ * copy goes back into the folder first, so the director picks up its own
+ * mission. Diffs in the frozen deck are capped so a record stays a record,
+ * not an archive of the repository.
+ */
+import path from 'node:path';
+import { mkdir, readFile, writeFile, rename, stat, unlink } from 'node:fs/promises';
+import crypto from 'node:crypto';
+import { deckFor, type Deck } from './deck.js';
+
+export const SNAPSHOT_DOC = 'MISSION.md';
+export const SNAPSHOT_DECK = 'deck.json';
+/** A single file's diff kept in the frozen deck; longer ones are cut with a note. */
+const DIFF_CAP = 20_000;
+
+export interface FrozenDeck extends Deck {
+  /** When the run ended and this was taken. */
+  frozenAt: number;
+}
+
+const missionDocPath = (folder: string) => path.join(folder, '.foreman', 'MISSION.md');
+
+async function writeAtomic(file: string, body: string): Promise<void> {
+  await mkdir(path.dirname(file), { recursive: true });
+  const tmp = path.join(path.dirname(file), `.${path.basename(file)}.${crypto.randomBytes(4).toString('hex')}.tmp`);
+  await writeFile(tmp, body);
+  await rename(tmp, file);
+}
+
+/** Copies the run's mission doc and deck into `runDir`. Never throws; a missing doc is simply not copied. */
+export async function snapshotRun(runDir: string, folder: string, runId: string, now = Date.now()): Promise<{ doc: boolean; deck: boolean }> {
+  let doc = false; let deck = false;
+  const text = await readFile(missionDocPath(folder), 'utf8').catch(() => null);
+  if (text !== null) {
+    await writeAtomic(path.join(runDir, SNAPSHOT_DOC), text).then(() => { doc = true; }).catch(() => {});
+  }
+  const live = await deckFor(folder, runId).catch(() => null);
+  if (live) {
+    const frozen: FrozenDeck = {
+      ...live,
+      frozenAt: now,
+      files: live.files.map((f) => (f.diff && f.diff.length > DIFF_CAP
+        ? { ...f, diff: `${f.diff.slice(0, DIFF_CAP)}\n… diff cut at ${DIFF_CAP} characters in the run's record`, truncated: true }
+        : f)),
+      note: [live.note, 'As the folder stood when the run ended.'].filter(Boolean).join(' '),
+    };
+    await writeAtomic(path.join(runDir, SNAPSHOT_DECK), JSON.stringify(frozen)).then(() => { deck = true; }).catch(() => {});
+  }
+  return { doc, deck };
+}
+
+/** The frozen doc, or null when this run has none (older runs, or nothing was written). */
+export async function frozenMissionDoc(runDir: string): Promise<string | null> {
+  return readFile(path.join(runDir, SNAPSHOT_DOC), 'utf8').catch(() => null);
+}
+
+/** The frozen deck, or null. */
+export async function frozenDeck(runDir: string): Promise<FrozenDeck | null> {
+  const raw = await readFile(path.join(runDir, SNAPSHOT_DECK), 'utf8').catch(() => null);
+  if (!raw) return null;
+  try { return JSON.parse(raw) as FrozenDeck; } catch { return null; }
+}
+
+/**
+ * Puts the run's own mission doc back into the folder before a resume, so the
+ * director reads its mission and not whichever one ran last. Returns what
+ * happened, for the transcript: `restored` when the folder's doc differed,
+ * `same` when it already matched, `none` when this run has no copy.
+ */
+export async function restoreMissionDoc(runDir: string, folder: string): Promise<'restored' | 'same' | 'none'> {
+  const frozen = await frozenMissionDoc(runDir);
+  if (frozen === null) return 'none';
+  const current = await readFile(missionDocPath(folder), 'utf8').catch(() => null);
+  if (current === frozen) return 'same';
+  await writeAtomic(missionDocPath(folder), frozen);
+  return 'restored';
+}
+
+/**
+ * A new run starts with no mission doc in the folder. The previous run's
+ * MISSION.md would otherwise sit there until the new director rewrites it,
+ * and everything reading the folder — run_status, the fleet card, the rail —
+ * showed the old DONE WHEN, ticked, on a run that had just begun. The old doc
+ * is kept: copied into the previous run's record when that run has no copy
+ * yet (runs from before records were frozen), then removed from the folder.
+ */
+export async function parkMissionDoc(folder: string, previousRunDir: string | null): Promise<'parked' | 'none'> {
+  const file = missionDocPath(folder);
+  const text = await readFile(file, 'utf8').catch(() => null);
+  if (text === null) return 'none';
+  if (previousRunDir && (await frozenMissionDoc(previousRunDir)) === null) {
+    await writeAtomic(path.join(previousRunDir, SNAPSHOT_DOC), text).catch(() => {});
+  }
+  await unlink(file).catch(() => {});
+  return 'parked';
+}
+
+/** Does the run have a frozen record at all? */
+export async function hasSnapshot(runDir: string): Promise<boolean> {
+  const doc = await stat(path.join(runDir, SNAPSHOT_DOC)).then(() => true, () => false);
+  if (doc) return true;
+  return stat(path.join(runDir, SNAPSHOT_DECK)).then(() => true, () => false);
+}

package/src/store.test.ts

@@ -135,3 +135,19 @@ test('archiveChat retires a conversation: gone from the project, kept on disk, a
   await store.archiveChat('p-abc', 'again');
   await rm(root, { recursive: true, force: true });
 });
+
+
+test('sweepOrphans leaves a running run alone while another live process owns it', async () => {
+  const { store, root } = await tmpStore();
+  const mine = newRunId(1000); const theirs = newRunId(2000); const dead = newRunId(3000);
+  await store.createRun(meta(mine, { ownerPid: process.pid }));
+  // The test runner's parent is alive and is not us.
+  await store.createRun(meta(theirs, { ownerPid: process.ppid }));
+  await store.createRun(meta(dead, { ownerPid: 2 ** 22 - 7 }));
+  const swept = await store.sweepOrphans();
+  assert.ok(swept.includes(mine), 'our own record from a previous life is swept');
+  assert.ok(swept.includes(dead), 'a dead owner is an orphan');
+  assert.ok(!swept.includes(theirs), 'a live foreign owner keeps its run');
+  assert.equal((await store.readMeta(theirs))!.status, 'running');
+  await rm(root, { recursive: true, force: true });
+});

package/src/store.ts

@@ -34,6 +34,14 @@ export function newRunId(now = Date.now()): string {
   return `${String(now).padStart(13, '0')}-${crypto.randomBytes(4).toString('hex')}`;
 }
 
+/** Is a process with this pid alive? Signal 0 checks without sending anything. */
+export function processAlive(pid: number): boolean {
+  try { process.kill(pid, 0); return true; } catch (err) {
+    // EPERM means it exists but is not ours to signal — still alive.
+    return (err as NodeJS.ErrnoException).code === 'EPERM';
+  }
+}
+
 export class RunStore {
   /** Absolute data root; exposed so startup checks can report and test it. */
   readonly root: string;
@@ -182,6 +190,11 @@ export class RunStore {
     return path.join(this.runsDir, runId);
   }
 
+  /** The run's own directory, for the record a run keeps beside its meta and log (see snapshot.ts). */
+  runDirectory(runId: string): string {
+    return this.runDir(runId);
+  }
+
   /** Creates the run directory and writes initial metadata. */
   async createRun(meta: RunMeta): Promise<void> {
     await mkdir(this.runDir(meta.id), { recursive: true });
@@ -351,6 +364,10 @@ export class RunStore {
     const swept: string[] = [];
     for (const meta of await this.listRuns()) {
       if (meta.status !== 'running') continue;
+      // Another Foreman may be driving this run right now — the installed
+      // service while a dev server starts on the same data directory. Its
+      // record is not ours to close; only a run whose owner is gone is orphaned.
+      if (meta.ownerPid && meta.ownerPid !== process.pid && processAlive(meta.ownerPid)) continue;
       const ended: RunMeta = { ...meta, status: 'interrupted', endedAt: Date.now() };
       await this.append(meta.id, {
         ts: Date.now(),

package/src/types.ts

@@ -330,7 +330,21 @@ export interface RunMeta {
    * to offer the one action that helps — raise the budget and resume — and
    * a resume clears it. Absent when the run ended for any other reason.
    */
+  /**
+   * Percent of the cap at which the director is told to start winding down,
+   * frozen at dispatch like the cap itself. Absent means the default.
+   */
+  budgetWarnAt?: number;
   stopReason?: 'budget' | 'turns' | 'time' | 'tokens';
+  /** When the run's record was frozen (MISSION.md and deck copied beside it); absent on older runs. */
+  snapshotAt?: number;
+  /**
+   * The server process driving this run. The startup sweep that marks
+   * abandoned runs interrupted leaves a run alone while its owner is alive —
+   * a second Foreman on the same data directory (a dev server beside the
+   * installed one) once swept a live mission's record out from under it.
+   */
+  ownerPid?: number;
   folder: string;
   mission: string;
   budgetUsd: number;