@amenophis1er/foreman 0.1.14 → 0.1.15

package/package.json

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

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

package/src/orchestrator.test.ts

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

package/src/orchestrator.ts

@@ -266,6 +266,31 @@ const DEFAULT_MAX_TURNS = 150;
 export const DEFAULT_MAX_TOKENS = 20_000_000;
 
 /** The cap behind a capReached() sentence, as the run record stores it. */
+/**
+ * Is it time to tell the director to start winding down? True once spend
+ * crosses the warn threshold and while it is still under the cap — past the
+ * cap the wind-down order takes over, and a warning then would be noise.
+ */
+export function budgetWarnDue(costUsd: number, budgetUsd: number, warnAt: number | undefined): boolean {
+  if (!Number.isFinite(warnAt as number) || (warnAt as number) <= 0 || (warnAt as number) >= 100) return false;
+  if (!(budgetUsd > 0)) return false;
+  return costUsd >= budgetUsd * ((warnAt as number) / 100) && costUsd < budgetUsd;
+}
+
+/**
+ * A run the budget stopped, whose own DONE WHEN criteria are all ticked, is
+ * done: it reached its criteria and then reached its limit, in that order.
+ * Only for the budget — a human interrupt or a usage limit says nothing
+ * about the work — and only when the doc actually had criteria to tick.
+ */
+export function doneAtCap(
+  flags: { budgetStopped: boolean; wasInterrupted: boolean; usageLimited: boolean },
+  unmet: string[] | null,
+): boolean {
+  if (!flags.budgetStopped || flags.wasInterrupted || flags.usageLimited) return false;
+  return Array.isArray(unmet) && unmet.length === 0;
+}
+
 export function stopReasonOf(cap: string): 'budget' | 'turns' | 'time' | 'tokens' {
   if (cap.startsWith('TURN')) return 'turns';
   if (cap.startsWith('TIME')) return 'time';
@@ -1080,6 +1105,7 @@ export class MissionRun {
         // overrun quiet.
         this.budgetNoticeSent = false;
         this.budgetKillSent = false;
+        this.budgetWarnSent = false;
         this.budgetStopped = false;
       }
     }
@@ -1332,6 +1358,23 @@ export class MissionRun {
       // the one lie a mission runner cannot afford. Downgrading to
       // 'interrupted' is also the useful answer: it is what makes the run
       // resumable rather than closed.
+      // A mission whose own record says every criterion is verified is done,
+      // even if the cap ended the turn it was writing its report in. Calling
+      // that 'interrupted' told the fleet a finished mission had failed, and
+      // invited a resume that spent more to rewrite a report already on disk.
+      // The stop reason stays on the record, so nothing is hidden.
+      if (this.meta.status === 'interrupted' && this.budgetStopped
+          && !this.wasInterrupted && !this.usageLimited) {
+        const unmet = await this.unmetCriteria();
+        if (doneAtCap({ budgetStopped: this.budgetStopped, wasInterrupted: this.wasInterrupted, usageLimited: this.usageLimited }, unmet)) {
+          this.meta.status = 'done';
+          this.emit('mission_done_at_cap', {
+            costUsd: this.meta.costUsd, budgetUsd: this.meta.budgetUsd, reason: this.meta.stopReason,
+            text: 'Every DONE WHEN criterion was verified before the cap ended the run, so this mission is done. ' +
+              'It stopped at its limit rather than finishing under it — the report may be shorter than usual.',
+          });
+        }
+      }
       if (this.meta.status === 'done') {
         const unmet = await this.unmetCriteria();
         if (unmet?.length) {
@@ -1482,6 +1525,7 @@ export class MissionRun {
 
   private budgetNoticeSent = false;
   private budgetKillSent = false;
+  private budgetWarnSent = false;
 
   /**
    * Keeps an "always allow" grant out of `git status`.
@@ -1652,6 +1696,26 @@ export class MissionRun {
       void this.interrupt();
       return;
     }
+    // Before the fence, a nudge. A director that only learns of the cap when
+    // it hits it does its verification and its report inside the one turn it
+    // has left — which is how two missions that had finished their work were
+    // cut mid-report and read as failures. Warn while there is still room to
+    // wind down deliberately.
+    if (!this.budgetWarnSent && budgetWarnDue(costUsd, budgetUsd, this.meta.budgetWarnAt)) {
+      this.budgetWarnSent = true;
+      const pct = Math.round((costUsd / budgetUsd) * 100);
+      this.emit('budget_alert', {
+        level: 'warn', costUsd, budgetUsd,
+        text: `${pct}% of the budget spent ($${costUsd.toFixed(2)} of $${budgetUsd.toFixed(2)}) — director told to start verifying.`,
+      });
+      this.directorInput?.push(
+        '[BUDGET — automated notice]\n' +
+        `You have spent $${costUsd.toFixed(2)} of the $${budgetUsd.toFixed(2)} cap (${pct}%). ` +
+        'Start winding down now: finish or stop the work in flight, do not begin anything you ' +
+        'cannot complete and verify within what is left, and get your verification and MISSION.md ' +
+        'up to date. At the cap you get one final turn, and at 125% the run is interrupted.',
+      );
+    }
     if (!this.budgetNoticeSent && costUsd >= budgetUsd) {
       this.budgetNoticeSent = true;
       this.emit('budget_alert', {

package/src/server.ts

@@ -1648,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> }));
@@ -1669,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;
+    })(),
   };
 }
 
@@ -1708,6 +1714,7 @@ async function startRun(
     workerProviderId: roleProviders.worker ?? settings.workerProviderId,
     ownerPid: process.pid,
     browserTools: browserTools || undefined,
+    budgetWarnAt: settings.budgetWarnAt,
     toolPolicy: settings.toolPolicy,
     autoAllowReadOnly: settings.autoAllowReadOnly,
     // Frozen at dispatch: a later change to the project or the server default

package/src/types.ts

@@ -330,6 +330,11 @@ 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;