@amenophis1er/foreman 0.1.7 → 0.1.9

package/src/memory.ts

@@ -0,0 +1,107 @@
+/**
+ * Project memory: the page of notes a good contractor keeps about a site.
+ *
+ * `.foreman/MEMORY.md` — one file per project, human-readable, a page or two
+ * at most. How to run the tests, which port is taken, where the CSS lives
+ * and why, what the client hates. Read by the director, the workers and the
+ * planner at the start of every turn; written by the director at the end of
+ * a mission through one tool; visible in the rail so the human can see what
+ * their project "believes", and edit it with any text editor.
+ *
+ * Memory makes the crew better informed, never more powerful: it is prose
+ * in a prompt, and everything the crew may do is still exactly what the
+ * tool policy and the budget allow. It also never carries a secret — the
+ * server strips anything that looks like one before writing.
+ */
+import path from 'node:path';
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+
+export const MEMORY_FILE = '.foreman/MEMORY.md';
+/** Bytes kept in the file. Past this the director is asked to prune, not append. */
+export const MEMORY_CAP_BYTES = 8 * 1024;
+/** Bytes injected into a prompt; the tail is dropped with a note if the file is larger. */
+const INJECT_CAP_BYTES = 6 * 1024;
+
+export function memoryPath(folder: string): string {
+  return path.join(folder, MEMORY_FILE);
+}
+
+export async function readMemory(folder: string): Promise<{ text: string; updatedAt?: number }> {
+  const file = memoryPath(folder);
+  const text = await readFile(file, 'utf8').catch(() => '');
+  const st = text ? await stat(file).catch(() => null) : null;
+  return { text, updatedAt: st?.mtimeMs };
+}
+
+/**
+ * Things that must not live in a page of notes, whatever the model meant:
+ * API keys, tokens, private keys, and `KEY=value` lines for secret-looking
+ * names. Replaced, not dropped, so the line still reads as a line.
+ */
+const SECRET_PATTERNS: RegExp[] = [
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+  /\b(sk|rk|pk)-(?:live|test|proj|ant)?-?[A-Za-z0-9_-]{16,}\b/g,
+  /\b(?:ghp|gho|ghu|ghs|ghr|github_pat)_[A-Za-z0-9_]{20,}\b/g,
+  /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/g,
+  /\bAKIA[0-9A-Z]{16}\b/g,
+  /\bAIza[0-9A-Za-z_-]{30,}\b/g,
+  /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g,
+  /\b([A-Z0-9_]*(?:SECRET|TOKEN|PASSWORD|PASSWD|API_KEY|APIKEY|PRIVATE_KEY)[A-Z0-9_]*)\s*[=:]\s*["']?[^\s"']{8,}["']?/gi,
+  /\b(?:bearer|token|password|secret|api[_-]?key)\s*[:=]\s*["']?[A-Za-z0-9_\-./+=]{16,}["']?/gi,
+];
+
+/** Strip what looks like a credential. Returns the text and how many replacements were made. */
+export function scrubSecrets(text: string): { text: string; redacted: number } {
+  let redacted = 0;
+  let out = text;
+  for (const re of SECRET_PATTERNS) {
+    out = out.replace(re, (m, name?: string) => {
+      redacted += 1;
+      // Keep the variable name when there was one, so the line still explains itself.
+      return typeof name === 'string' && /^[A-Z0-9_]+$/.test(name) && m.startsWith(name) ? `${name}=[redacted]` : '[redacted]';
+    });
+  }
+  return { text: out, redacted };
+}
+
+/**
+ * Write the whole memory. The director hands over the full page, not a
+ * delta, because "rewrite the stale line" is the behaviour we want and
+ * append-only files only grow. Trimmed to the cap; the caller is told.
+ */
+export async function writeMemory(folder: string, text: string): Promise<{ bytes: number; redacted: number; trimmed: boolean }> {
+  const scrubbed = scrubSecrets(text.replace(/\r\n/g, '\n').trim());
+  let body = scrubbed.text;
+  let trimmed = false;
+  if (Buffer.byteLength(body, 'utf8') > MEMORY_CAP_BYTES) {
+    body = Buffer.from(body, 'utf8').subarray(0, MEMORY_CAP_BYTES).toString('utf8').replace(/[^\n]*$/, '').trimEnd();
+    trimmed = true;
+  }
+  await mkdir(path.dirname(memoryPath(folder)), { recursive: true });
+  await writeFile(memoryPath(folder), body ? `${body}\n` : '');
+  return { bytes: Buffer.byteLength(body, 'utf8'), redacted: scrubbed.redacted, trimmed };
+}
+
+/**
+ * The memory as a prompt section, for the director, the workers and the
+ * planner. Empty memory says so in one line rather than vanishing, so the
+ * crew knows the file exists to be written.
+ */
+export function memorySection(text: string, role: 'director' | 'worker' | 'planner'): string {
+  const t = text.trim();
+  if (!t) {
+    return role === 'director'
+      ? `\nPROJECT MEMORY (${MEMORY_FILE}): empty. Before you finish, write it with mcp__foreman__remember — a page at most of facts the next crew needs here.\n`
+      : '';
+  }
+  let body = t;
+  if (Buffer.byteLength(body, 'utf8') > INJECT_CAP_BYTES) {
+    body = Buffer.from(body, 'utf8').subarray(0, INJECT_CAP_BYTES).toString('utf8').replace(/[^\n]*$/, '') + '\n[… memory is longer than a page; the rest was not shown. Prune it.]';
+  }
+  const lead = role === 'director'
+    ? `PROJECT MEMORY (${MEMORY_FILE}) — what earlier crews learned about this project. Trust it over guessing; correct it when it is wrong. Before you finish, rewrite it with mcp__foreman__remember so the next crew starts where you end.`
+    : role === 'worker'
+      ? 'PROJECT MEMORY — what earlier crews learned about this project. Trust it over guessing; tell the director if it is wrong.'
+      : `PROJECT MEMORY (${MEMORY_FILE}) — what the crew learned about this project on earlier missions. Ground your advice in it, and say when a proposal would change something it records.`;
+  return `\n${lead}\n---\n${body}\n---\n`;
+}

package/src/notify/commands.ts

@@ -66,7 +66,7 @@ export const HELP_TEXT = [
   '',
   '/projects — the fleet, with what is running',
   '/status — the runs in flight and what they need',
-  '/new <name> — create a project under your projects root and link it',
+  '/new <name> — create a project under your projects root and link it; /new <git url> clones it there first',
   '/plan <project> <what you want> — talk to that project\'s planner',
   '/run <project> <brief> — skip the talk: start a mission at the project\'s default cap',
   '/stop [project] — stop the planner reply in flight',

package/src/notify/telegram.ts

@@ -94,7 +94,7 @@ export function telegramTransport(token: string, chatId: string, apiBase = TELEG
 export const BOT_COMMANDS: Array<{ command: string; description: string }> = [
   { command: 'projects', description: 'The fleet, with what is running' },
   { command: 'status', description: 'Runs in flight, spend, what needs you' },
-  { command: 'new', description: 'Create a project: /new <name>' },
+  { command: 'new', description: 'Create a project: /new <name>, or clone one: /new <git url>' },
   { command: 'plan', description: 'Talk to a planner: /plan <project> <what you want>' },
   { command: 'run', description: 'Skip the talk: /run <project> <brief>' },
   { command: 'stop', description: 'Stop the planner reply in flight' },

package/src/notify.ts

@@ -241,6 +241,11 @@ export function shape(env: Envelope, ctx: NotifyContext): Shaped | null {
     case 'mission_incomplete':
       return { key: `incomplete:${env.runId}`, gate: 'done',
         text: `${head('Not done')}${runLine}\n${esc(clip(d.text))}${foot}` };
+    case 'pull_request': {
+      if (d.error || !d.url) return null;
+      return { key: `pr:${env.runId}`, gate: 'done',
+        text: `${head(d.method === 'gh' ? 'Pull request opened' : 'Branch pushed')}${runLine}\n<a href="${esc(String(d.url))}">${esc(String(d.url))}</a>` };
+    }
     case 'service_exposed': {
       // Informational, and worth a tap: the crew put something on the air.
       const url = String(d.url ?? '');

package/src/orchestrator.test.ts

@@ -9,6 +9,7 @@ import {
   stalledWorkerReport, workerStatusBlock,
   watchRepeats, watchSilence, REPEAT_EXEMPT, observeToolUse,
   DEFAULT_ASK_TIMEOUT_MS, armAskTimeout, unattendedAnswer, unattendedDenyMessage,
+  tokenCapLabel, stopReasonOf,
 } from './orchestrator.js';
 import { makePolicy, type PendingPermission } from './policy.js';
 import type { AgentEnv } from './provider.js';
@@ -1145,3 +1146,113 @@ test('pendingAsks exposes an open question with its text and options, and forget
   await p;
   assert.deepEqual(run.pendingAsks(), []);
 });
+
+// ---------------------------------------------------------------------------
+// The token cap: the bound that holds where dollars cannot
+// ---------------------------------------------------------------------------
+
+/**
+ * A run whose usage is whatever the test says it is. Usage is read through
+ * liveUsage(), so setting `meta.usage` is enough — the confirmed half of the
+ * figure the cap actually consults.
+ */
+function cappedRun(over: Partial<RunMeta> = {}, usage?: Partial<{
+  inputTokens: number; outputTokens: number; cacheReadTokens: number; cacheWriteTokens: number;
+}>) {
+  const run = new MissionRun(
+    meta({ costBasis: 'free', ...over }), () => {}, () => {}, noopAgentEnv,
+  ) as unknown as {
+    meta: RunMeta; turns: number;
+    capReached(): string | null;
+    budgetLine(): string;
+  };
+  if (usage) {
+    run.meta.usage = {
+      inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, ...usage,
+    };
+  }
+  return run;
+}
+
+test('capReached says nothing while the token total is under the cap', () => {
+  const run = cappedRun({}, {
+    inputTokens: 1_000_000, outputTokens: 100_000,
+    cacheReadTokens: 1_000_000, cacheWriteTokens: 500_000,
+  });
+  assert.equal(run.capReached(), null);
+});
+
+test('capReached counts cache tokens too, and fires at the default 20M', () => {
+  // Under on input and output alone; over once cache is counted — which is
+  // exactly the run the cap exists for, since cache reads are most of the
+  // traffic on a long director loop.
+  const run = cappedRun({}, {
+    inputTokens: 2_000_000, outputTokens: 400_000,
+    cacheReadTokens: 16_000_000, cacheWriteTokens: 1_600_000,
+  });
+  const cap = run.capReached();
+  assert.ok(cap?.startsWith('TOKEN CAP REACHED'), `got ${cap}`);
+  assert.match(cap!, /20\.0M tokens/);
+});
+
+test('capReached: the ledger\'s largest finished missions stay under the default', () => {
+  // 15.9M tokens, done, $8.55 — a real Fable run from this machine. A cap
+  // that would have ended it is a cap set wrong.
+  const run = cappedRun({}, { inputTokens: 300_000, outputTokens: 200_000, cacheReadTokens: 15_000_000, cacheWriteTokens: 400_000 });
+  assert.equal(run.capReached(), null);
+});
+
+test('capReached honours an explicit maxTokens over the default', () => {
+  const run = cappedRun({ maxTokens: 1_000_000 }, { inputTokens: 1_200_000 });
+  assert.ok(run.capReached()?.startsWith('TOKEN CAP REACHED'));
+  const roomy = cappedRun({ maxTokens: 40_000_000 }, { inputTokens: 25_000_000 });
+  assert.equal(roomy.capReached(), null);
+});
+
+test('the turn cap still wins when turns and tokens are both past their caps', () => {
+  const run = cappedRun({ maxTurns: 10, maxTokens: 1_000 }, { inputTokens: 9_000_000 });
+  run.turns = 50;
+  assert.match(run.capReached()!, /^TURN CAP REACHED/);
+});
+
+test('the token cap binds free and unpriced runs, and never a priced one', () => {
+  for (const basis of ['free', 'unpriced'] as const) {
+    const run = cappedRun({ costBasis: basis }, { inputTokens: 25_000_000 });
+    assert.ok(run.capReached()?.startsWith('TOKEN CAP REACHED'), `basis ${basis}`);
+  }
+  // Priced: dollars are the cap. Under budget, tokens alone end nothing;
+  // over budget, it is the budget that speaks.
+  const priced = cappedRun({ costBasis: 'priced', budgetUsd: 5 }, { inputTokens: 25_000_000 });
+  priced.meta.costUsd = 1;
+  assert.equal(priced.capReached(), null);
+  priced.meta.costUsd = 5;
+  assert.match(priced.capReached()!, /^BUDGET CAP REACHED/);
+});
+
+test('budgetLine tells an unmetered director its turn AND token bounds', () => {
+  const free = cappedRun({ costBasis: 'free' }).budgetLine();
+  assert.match(free, /150 director turns and 20M tokens/);
+  const unpriced = cappedRun({ costBasis: 'unpriced' }).budgetLine();
+  assert.match(unpriced, /150 director turns and 20M tokens/);
+  // A custom cap is quoted as set, not as the default.
+  assert.match(cappedRun({ maxTokens: 2_000_000 }).budgetLine(), /2M tokens/);
+  // A priced run still speaks in dollars, and says nothing about tokens.
+  const priced = cappedRun({ costBasis: 'priced' }).budgetLine();
+  assert.match(priced, /^Budget: \$5\.00/);
+  assert.doesNotMatch(priced, /tokens/);
+});
+
+test('tokenCapLabel rounds to a figure a director can hold in mind', () => {
+  assert.equal(tokenCapLabel(20_000_000), '20M tokens');
+  assert.equal(tokenCapLabel(5_000_000), '5M tokens');
+  assert.equal(tokenCapLabel(1_500_000), '1.5M tokens');
+  assert.equal(tokenCapLabel(250_000), '250k tokens');
+  assert.equal(tokenCapLabel(400), '400 tokens');
+});
+
+test('stopReasonOf names the cap behind a capReached sentence', () => {
+  assert.equal(stopReasonOf('BUDGET CAP REACHED: $10.02 of $10.00.'), 'budget');
+  assert.equal(stopReasonOf('TURN CAP REACHED: 150 director turns.'), 'turns');
+  assert.equal(stopReasonOf('TIME CAP REACHED: 240 minutes.'), 'time');
+  assert.equal(stopReasonOf('TOKEN CAP REACHED: 20.1M tokens.'), 'tokens');
+});

package/src/orchestrator.ts

@@ -90,11 +90,13 @@ class MessageStream implements AsyncIterable<SDKUserMessage> {
   }
 }
 import { WORK_DIR, makePolicy, type PendingPermission } from './policy.js';
+import { PLAYWRIGHT_MCP_CLI } from './browser.js';
 import type { AgentEnv } from './provider.js';
 import { generateRunTitle } from './title.js';
 import { combineBasis, costBasisOf, isPriced, type CostBasis } from './types.js';
 import { priceUsage, type ModelPrice } from './prices.js';
 import { captureBaseline } from './deck.js';
+import { memorySection, readMemory, writeMemory } from './memory.js';
 import type { RunMeta, TokenUsage, WorkerMeta, WorkerProgress } from './types.js';
 
 /** A run's usage before its first `result` message. */
@@ -248,6 +250,40 @@ export async function ensureIgnoreLines(file: string, lines: readonly string[]):
 // a metered one that dollars already stop.
 const DEFAULT_MAX_TURNS = 150;
 
+/**
+ * The same idea counted in tokens, for the same reason the turn cap exists.
+ *
+ * A turn cap bounds how many times the director speaks, not how much it says,
+ * and those come apart badly on a free or unpriced run: 150 turns over a large
+ * context is millions of tokens that nothing here was watching. It binds only
+ * where dollars cannot — a priced run already has a real cap, and this one
+ * must never end it first. Sized from the ledger, not from a hunch: cache
+ * reads are most of a director loop's traffic, and finished missions on this
+ * machine have run to 8–16M tokens total (a 5M figure was first proposed and
+ * would have cut several of them short). 20M is clear of every honest run
+ * seen so far and still well inside what a runaway reaches before the clock.
+ */
+export const DEFAULT_MAX_TOKENS = 20_000_000;
+
+/** The cap behind a capReached() sentence, as the run record stores it. */
+export function stopReasonOf(cap: string): 'budget' | 'turns' | 'time' | 'tokens' {
+  if (cap.startsWith('TURN')) return 'turns';
+  if (cap.startsWith('TIME')) return 'time';
+  if (cap.startsWith('TOKEN')) return 'tokens';
+  return 'budget';
+}
+
+/**
+ * The token cap as a director should read it: "5M tokens", not "5000000".
+ * A budget is only useful if the agent it constrains can hold it in mind, and
+ * a raw seven-digit figure in a prompt is one more thing to misread.
+ */
+export function tokenCapLabel(n: number): string {
+  if (n >= 1e6) return `${Number((n / 1e6).toFixed(1))}M tokens`;
+  if (n >= 1000) return `${Number((n / 1000).toFixed(1))}k tokens`;
+  return `${n} tokens`;
+}
+
 /**
  * How long a worker may say nothing at all before it is treated as stalled.
  *
@@ -675,6 +711,12 @@ directing worker agents. Non-negotiable rules, in priority order:
    failure is an escalation, never a self-repair.
 7. When DONE WHEN is verified, update MISSION.md (all boxes ticked, final log
    entry) and end with a short summary of what was built and how you verified it.
+8. LEAVE NOTES FOR THE NEXT CREW. Before you finish, call mcp__foreman__remember
+   with the whole project memory as it should read now: how to run and test
+   the project, ports and paths that matter, conventions and the reasons
+   behind them, traps you fell into. Facts, one line each, a page at most.
+   Rewrite stale lines rather than appending; drop what no longer holds.
+   Never a secret, never anything outside this project.
 `;
 
 export const WORKER_CHARTER = `
@@ -697,9 +739,6 @@ When finished, end with a concise report of what you did and how you checked it.
 `;
 
 /** Foreman's bundled Playwright MCP server, resolved from this repo. */
-const PLAYWRIGHT_MCP_CLI = fileURLToPath(
-  new URL('../node_modules/@playwright/mcp/cli.js', import.meta.url),
-);
 
 /** Claude subscription/quota exhaustion — an external pause, not a failure. */
 const USAGE_LIMIT_RE = /out of usage credits|usage limit reached|upgrade to increase your usage/i;
@@ -756,6 +795,8 @@ export class MissionRun {
   private readonly askTimers = new Map<string, { cancel(): void }>();
   /** The director's streaming prompt; steering pushes into it. */
   private directorInput?: MessageStream;
+  /** The project's notes as a worker-prompt section, read once per start; empty when there are none. */
+  private memoryForWorkers = '';
   /** Director cost is cumulative per query; track the last figure for deltas. */
   private directorCostSeen = 0;
   private wasInterrupted = false;
@@ -834,6 +875,8 @@ export class MissionRun {
      */
     private readonly host: {
       exposeService?: (runId: string, port: number, label: string) => Promise<{ ok: true; url: string; path: string } | { ok: false; reason: string }>;
+      /** The browser channel detected at dispatch (src/browser.ts); Chrome when the host says nothing. */
+      browserChannel?: string;
     } = {},
   ) {
     this.meta = meta;
@@ -1108,9 +1151,12 @@ export class MissionRun {
         'actually complete. Keep completed work; do not rewrite files that already ' +
         'satisfy their milestone. Update the doc to match reality, then continue ' +
         'the mission to DONE WHEN. ' +
-        this.budgetNote()
+        this.gitLine() +
+        this.budgetNote() +
+        memorySection((await readMemory(this.meta.folder)).text, 'director')
       : `MISSION: ${this.meta.mission}\n\n${this.budgetLine()} ` +
-        `Working directory: ${this.meta.folder}. Begin by writing .foreman/MISSION.md, then execute the plan.`;
+        `Working directory: ${this.meta.folder}. ${this.gitLine()}Begin by writing .foreman/MISSION.md, then execute the plan.` +
+        memorySection((await readMemory(this.meta.folder)).text, 'director');
 
     try {
       // The mission doc directory ignores itself wholesale (`*`, which also
@@ -1135,6 +1181,7 @@ export class MissionRun {
         void captureBaseline(this.meta.folder, this.meta.id).catch(() => {});
       }
       await mkdir(path.join(this.meta.folder, WORK_DIR), { recursive: true }).catch(() => {});
+      this.memoryForWorkers = memorySection((await readMemory(this.meta.folder)).text, 'worker');
       // Covers a .claude/ left by an earlier run; the one this run creates is
       // handled again on the way out.
       await this.ignoreLocalSettings();
@@ -1360,9 +1407,9 @@ export class MissionRun {
         // Absolute path: the server runs with the mission folder as cwd,
         // where npx cannot resolve Foreman's own dependency.
         command: process.execPath,
-        // Chrome channel by default (the machine's own Chrome, no download);
-        // FOREMAN_BROWSER picks another channel or Playwright's Chromium.
-        args: [PLAYWRIGHT_MCP_CLI, '--headless', '--isolated', '--browser', process.env.FOREMAN_BROWSER || 'chrome'],
+        // The channel the server detected for this machine: FOREMAN_BROWSER,
+        // else its Chrome, else Playwright's own Chromium (src/browser.ts).
+        args: [PLAYWRIGHT_MCP_CLI, '--headless', '--isolated', '--browser', this.host.browserChannel ?? process.env.FOREMAN_BROWSER ?? 'chrome'],
       },
     };
   }
@@ -1441,14 +1488,6 @@ export class MissionRun {
   }
 
 
-  /**
-   * Fold in the SDK's own dollar figure for a role.
-   *
-   * Ignored outright where Foreman holds that role's real rates: the SDK
-   * prices every response with Anthropic's table, so on a gateway role its
-   * number is fiction — and adding fiction to a figure computed from the
-   * endpoint's own published rates would corrupt the one honest total.
-   */
   /**
    * `costUsd` from its parts. The upstream's own figure, once it has given
    * one, replaces the rated figure for gateway tokens rather than adding to
@@ -1475,12 +1514,6 @@ export class MissionRun {
     this.enforceBudget();
   }
 
-  /**
-   * Folds one result message's token usage into the run total and persists
-   * it. Called alongside addCost() from the same two call sites (director
-   * loop, runWorker) so usage and cost are always in step — the honest
-   * counterpart to a dollar figure that is not honest on every provider.
-   */
   /**
    * The one event that carries a run's economics. Emitted whenever either half
    * changes — dollars OR tokens — because through a gateway the SDK often
@@ -1621,6 +1654,15 @@ export class MissionRun {
     }
   }
 
+  /** The mission's branch, when it has one: stay on it, and leave merging and pushing alone. */
+  private gitLine(): string {
+    const g = this.meta.git;
+    if (!g) return '';
+    return `This mission runs on git branch ${g.branch}, created for it from ${g.base}. Stay on it: do not switch branches, ` +
+      'do not merge, do not push, do not rebase or reset. You may commit as you go; Foreman commits whatever ' +
+      'is left uncommitted when the mission ends. ';
+  }
+
   /**
    * What the director is told about its budget, in the units that are true.
    *
@@ -1633,18 +1675,19 @@ export class MissionRun {
    */
   private budgetLine(): string {
     const turns = this.meta.maxTurns ?? DEFAULT_MAX_TURNS;
+    const tokens = tokenCapLabel(this.meta.maxTokens ?? DEFAULT_MAX_TOKENS);
     switch (costBasisOf(this.meta)) {
       case 'free':
         return `This run costs nothing per token — it is served by hardware the ` +
           `operator already owns — so there is no spend cap. It is bounded by ` +
-          `${turns} director turns.`;
+          `${turns} director turns and ${tokens}.`;
       case 'unpriced':
         // Deliberately still "no spend cap", and deliberately not silent about
         // the spend. A director told only that money is being spent, with no
         // figure and no cap, invents a limit and winds itself down early.
         return `This run does draw on a paid account, but Foreman cannot price it, ` +
           `so there is no dollar cap and no figure to reason about — do not ration ` +
-          `yourself against one. It is bounded by ${turns} director turns.`;
+          `yourself against one. It is bounded by ${turns} director turns and ${tokens}.`;
       case 'priced':
         return `Budget: $${this.meta.budgetUsd.toFixed(2)} total for this run.`;
     }
@@ -1690,6 +1733,8 @@ export class MissionRun {
     const maxSeconds = this.meta.maxSeconds ?? DEFAULT_MAX_SECONDS;
     if (elapsed < maxSeconds + CAP_WATCHDOG_GRACE_MS / 1000) return;
     this.hardStopped = true;
+    this.meta.stopReason = 'time';
+    this.saveMeta(this.meta);
     this.emit('budget_stop', {
       costUsd: this.meta.costUsd,
       budgetUsd: this.meta.budgetUsd,
@@ -1714,10 +1759,21 @@ export class MissionRun {
       return `TIME CAP REACHED: ${Math.round(elapsed / 60)} minutes.`;
     }
     // Money only binds where the figure is real. Enforcing it through a
-    // gateway ends working runs over spend that never happened.
-    if (!isPriced(this.meta)) return null;
-    if (this.meta.costUsd < this.meta.budgetUsd) return null;
-    return `BUDGET CAP REACHED: $${this.meta.costUsd.toFixed(2)} of $${this.meta.budgetUsd.toFixed(2)}.`;
+    // gateway ends working runs over spend that never happened. Where it is
+    // real it is the cap, full stop: a priced run is never ended by tokens,
+    // which would cut a mission the human funded to its dollar figure.
+    if (isPriced(this.meta)) {
+      if (this.meta.costUsd < this.meta.budgetUsd) return null;
+      return `BUDGET CAP REACHED: $${this.meta.costUsd.toFixed(2)} of $${this.meta.budgetUsd.toFixed(2)}.`;
+    }
+    // Unpriced or free: tokens are the bound dollars cannot be. Live usage
+    // rather than the persisted total, so a gateway's interim tokens count too.
+    const u = this.liveUsage();
+    const total = u.inputTokens + u.outputTokens + u.cacheReadTokens + u.cacheWriteTokens;
+    if (total >= (this.meta.maxTokens ?? DEFAULT_MAX_TOKENS)) {
+      return `TOKEN CAP REACHED: ${(total / 1e6).toFixed(1)}M tokens.`;
+    }
+    return null;
   }
 
   private overBudget(): string | null {
@@ -1751,6 +1807,8 @@ export class MissionRun {
     const cap = this.capReached();
     if (!cap || this.budgetStopped) return null;
     this.budgetStopped = true;
+    this.meta.stopReason = stopReasonOf(cap);
+    this.saveMeta(this.meta);
     this.emit('budget_stop', {
       costUsd: this.meta.costUsd,
       budgetUsd: this.meta.budgetUsd,
@@ -1768,22 +1826,6 @@ export class MissionRun {
     );
   }
 
-  /**
-   * Starts a worker and returns at once; the session runs in the background.
-   *
-   * The split between this and {@link runWorker} is the asynchronous design in
-   * one place: everything the director can observe about a worker — the record
-   * in the map, `worker_started`, the `done` promise wait_for_worker races, the
-   * stored report and `worker_finished` at the end — is settled here, around a
-   * runWorker that only drives the SDK session. The promise is kept on the
-   * record rather than dropped, so a worker is never a floating promise, and
-   * the outcome is written onto the record rather than returned once, because
-   * the director now reads it back whenever it asks.
-   *
-   * Synchronous up to the point runWorker takes over: by the time this returns
-   * the record exists and `worker_started` has been emitted, which is exactly
-   * the guarantee spawn_worker's immediate reply relies on.
-   */
   /**
    * Item 6, decided as "ask": a worker on a gateway provider has stalled or
    * looped. Rather than letting the director cope alone or retrying somewhere
@@ -1860,6 +1902,22 @@ export class MissionRun {
     };
   }
 
+  /**
+   * Starts a worker and returns at once; the session runs in the background.
+   *
+   * The split between this and {@link runWorker} is the asynchronous design in
+   * one place: everything the director can observe about a worker — the record
+   * in the map, `worker_started`, the `done` promise wait_for_worker races, the
+   * stored report and `worker_finished` at the end — is settled here, around a
+   * runWorker that only drives the SDK session. The promise is kept on the
+   * record rather than dropped, so a worker is never a floating promise, and
+   * the outcome is written onto the record rather than returned once, because
+   * the director now reads it back whenever it asks.
+   *
+   * Synchronous up to the point runWorker takes over: by the time this returns
+   * the record exists and `worker_started` has been emitted, which is exactly
+   * the guarantee spawn_worker's immediate reply relies on.
+   */
   private launchWorker(workerId: string, prompt: string, resumeSessionId?: string, overrides?: WorkerOverrides): WorkerRuntime {
     const existing = this.workers.get(workerId);
     const w: WorkerRuntime = existing ?? {
@@ -2137,7 +2195,9 @@ export class MissionRun {
     const stop = this.overBudget();
     if (stop) return stop;
     const id = `worker-${++this.workerSeq}`;
-    this.launchWorker(id, task);
+    // The worker gets the project's notes with its brief: what earlier crews
+    // learned is exactly what a fresh session lacks.
+    this.launchWorker(id, this.memoryForWorkers ? `${task}\n${this.memoryForWorkers}` : task);
     return `[${id} started] status: running. It works in the background — use check_workers ` +
       `to watch it, and wait_for_worker when you need its result.`;
   }
@@ -2279,7 +2339,6 @@ export class MissionRun {
           this.pendingQuestions.set(id, resolve);
           this.armAsk(id, (afterMs) => {
             if (!this.pendingQuestions.delete(id)) return;
-        this.askMeta.delete(id);
             this.askMeta.delete(id);
             timedOut = true;
             this.emit('question_timeout', { id, afterMs });
@@ -2317,9 +2376,24 @@ export class MissionRun {
           'running while they may want to look, and put the URL in your report.' }] };
       },
     );
+    const remember = tool(
+      'remember',
+      'Rewrite the project memory (.foreman/MEMORY.md): the whole page as it should read now, ' +
+      'for the next crew. Facts about this project — how to run and test it, ports and paths, ' +
+      'conventions and why, traps — one line each, a page at most. Replace stale lines; do not ' +
+      'append forever. Never a secret; anything that looks like one is stripped.',
+      { text: z.string().max(20_000).describe('The complete memory file content, Markdown') },
+      async ({ text: body }) => {
+        const r = await writeMemory(this.meta.folder, body);
+        this.emit('memory_updated', { bytes: r.bytes, redacted: r.redacted, trimmed: r.trimmed,
+          text: `Project memory rewritten (${r.bytes} bytes${r.redacted ? `, ${r.redacted} secret-looking value${r.redacted === 1 ? '' : 's'} stripped` : ''}${r.trimmed ? ', trimmed to the cap' : ''}).` });
+        return { content: [{ type: 'text' as const, text:
+          `Memory written (${r.bytes} bytes).${r.redacted ? ` ${r.redacted} value(s) that looked like secrets were replaced with [redacted]; do not put credentials in memory.` : ''}${r.trimmed ? ' It was longer than the cap and has been cut at the end — prune it to a page.' : ''}` }] };
+      },
+    );
     return createSdkMcpServer({
       name: 'foreman',
-      tools: [spawnWorker, checkWorkers, waitForWorker, messageWorker, askHuman, exposeService],
+      tools: [spawnWorker, checkWorkers, waitForWorker, messageWorker, askHuman, exposeService, remember],
     });
   }
 }

package/src/planner.ts

@@ -29,6 +29,7 @@ import {
 } from '@anthropic-ai/claude-agent-sdk';
 import type { AgentEnv } from './provider.js';
 import type { MissionProposal } from './types.js';
+import { memorySection, readMemory } from './memory.js';
 import {
   armAskTimeout, formatAnswers, normaliseQuestions,
   type AskAnswers, type AskQuestion, type PendingAsk,
@@ -172,6 +173,8 @@ export interface PlannerModel {
   providerLabel: string;
   costBasis: 'priced' | 'free' | 'unpriced';
   note?: string;
+  /** Its track record here, from the run ledger: "here: director 4/5 done (~$0.78, ~18 min)". */
+  record?: string;
 }
 
 /**
@@ -205,7 +208,7 @@ export function pickKnownModel(
 export function modelsSection(models: PlannerModel[] | undefined): string {
   if (!models?.length) return '';
   const lines = models.map((m) =>
-    `  - ${m.id} — ${m.providerLabel} · ${m.costBasis}${m.note ? ` · ${m.note}` : ''}`);
+    `  - ${m.id} — ${m.providerLabel} · ${m.costBasis}${m.note ? ` · ${m.note}` : ''}${m.record ? ` · ${m.record}` : ''}`);
   return `\nMODELS AVAILABLE ON THIS MACHINE (use these exact ids in propose_mission):\n${lines.join('\n')}\n`;
 }
 
@@ -214,6 +217,8 @@ export interface PlanningTurn {
   projectId: string;
   /** What the machine can run, so recommendations are real ids, not guesses. */
   models?: PlannerModel[];
+  /** What missions have cost here and across the fleet, from the ledger; '' when too little history. */
+  anchor?: string;
   /** Session to resume; absent starts a fresh conversation. */
   sessionId?: string;
   folder: string;
@@ -407,7 +412,7 @@ export async function runPlanningTurn(turn: PlanningTurn): Promise<PlanningResul
         // thinking about the proposal, not discover it by asking.
         systemPrompt: {
           type: 'preset', preset: 'claude_code',
-          append: PLANNER_CHARTER + modelsSection(turn.models),
+          append: PLANNER_CHARTER + modelsSection(turn.models) + (turn.anchor ?? '') + memorySection((await readMemory(turn.folder)).text, 'planner'),
         },
         mcpServers: { foreman: createSdkMcpServer({ name: 'foreman', tools: [proposeMission, askUser] }) },
         canUseTool,