@amenophis1er/foreman 0.1.13 → 0.1.14

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

@@ -331,6 +331,15 @@ export interface RunMeta {
    * a resume clears it. Absent when the run ended for any other reason.
    */
   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;