@amenophis1er/foreman 0.1.8 → 0.1.10

package/README.md

@@ -230,7 +230,7 @@ result.
 ```sh
 npm ci && npm run setup      # dependencies, then the dashboard build
 npm start                    # serves http://localhost:4177
-npm test                     # 360 tests, node:test
+npm test                     # 364 tests, node:test
 npm run typecheck            # server and dashboard
 npm run dev                  # API + Vite together
 scripts/dev-restart.sh       # restarts the server only when nothing would be lost

package/package.json

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

@@ -9,7 +9,7 @@ import {
   stalledWorkerReport, workerStatusBlock,
   watchRepeats, watchSilence, REPEAT_EXEMPT, observeToolUse,
   DEFAULT_ASK_TIMEOUT_MS, armAskTimeout, unattendedAnswer, unattendedDenyMessage,
-  tokenCapLabel,
+  tokenCapLabel, stopReasonOf,
 } from './orchestrator.js';
 import { makePolicy, type PendingPermission } from './policy.js';
 import type { AgentEnv } from './provider.js';
@@ -1249,3 +1249,10 @@ test('tokenCapLabel rounds to a figure a director can hold in mind', () => {
   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

@@ -265,6 +265,14 @@ 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. */
+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
@@ -1725,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,
@@ -1797,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,

package/src/policy.test.ts

@@ -149,6 +149,46 @@ test('a file write under the root does not escape', () => {
   assert.ok(bashEscapesFolder('echo hi > /tmp/out.txt', FOLDER, [ROOT]), 'outside the root still prompts');
 });
 
+test('operators inside quotes are text: a perl program with => is not a redirect', () => {
+  // The exact shape that put an approval card in front of an in-folder edit:
+  // `=>/` inside the single-quoted program read as `>` + the path `/…`.
+  assert.equal(bashEscapesFolder(`perl -0pi -e 's/\\.filter\\(\\(\\[a, b\\]\\) =>/.filter(([a]) =>/' ${ROOT}/x.tsx`, FOLDER, [ROOT]), null);
+  assert.equal(bashEscapesFolder(`set -e; D=src/f; perl -0pi -e 's/ a,\\n b,/ a,/' $D/one.tsx; perl -0pi -e 's/x =>/y/' $D/two.tsx`, FOLDER, [ROOT]), null);
+  assert.equal(bashEscapesFolder('echo "a > b; c | d & e" && echo \'x>/etc/passwd\'', FOLDER, [ROOT]), null);
+  assert.equal(bashEscapesFolder(`git commit -m "fix: handle a > b" ${ROOT}`, FOLDER, [ROOT]), null);
+  // A real redirect next to a quoted one is still seen, with its real text.
+  assert.deepEqual(bashEscape('echo "x > y" > /tmp/out.txt', FOLDER), {
+    reason: 'echo "x > y" > /tmp/out.txt — redirects output outside the mission folder', path: '/tmp/out.txt', grant: '/tmp',
+  });
+  // Quoted paths still resolve: the mask touches operators, not text.
+  assert.ok(bashEscapesFolder('rm -rf "/opt/homebrew"', FOLDER, [ROOT]));
+  // A quoted path with spaces is one token now, so it resolves and is judged.
+  assert.equal(bashEscape(`echo hi > "/tmp/o u t.txt"`, FOLDER)!.path, '/tmp/o u t.txt');
+  assert.equal(bashEscapesFolder(`echo hi > "${ROOT}/o u t.txt"`, FOLDER, [ROOT]), null);
+});
+
+test('the shell keeps its cwd between commands: a cd in one call places the next', () => {
+  const shell = { cwd: FOLDER };
+  assert.equal(bashEscape('cd examples/demo', FOLDER, [], shell), null);
+  assert.equal(shell.cwd, path.join(FOLDER, 'examples/demo'));
+  // The exact shape from a real mission: a log two levels up is inside the folder.
+  assert.equal(bashEscape('(npx tsx server.ts > ../../.foreman/work/demo/run1.log 2>&1 &) ; sleep 1', FOLDER, [], shell), null);
+  // A cd inside a subshell does not move the shell.
+  assert.equal(bashEscape('(cd .. && ls) && echo ok', FOLDER, [], shell), null);
+  assert.equal(shell.cwd, path.join(FOLDER, 'examples/demo'));
+  // From there, three levels up is out, and says so.
+  assert.match(bashEscape('touch ../../../x', FOLDER, [], shell)!.reason, /outside the mission folder/);
+  // Without a shell, the analysis starts at the folder as before.
+  assert.match(bashEscape('echo hi > ../../.foreman/work/demo/run1.log', FOLDER)!.reason, /redirects output outside/);
+});
+
+test('a shell -c body is analysed as a command, so quoting cannot hide a cd', () => {
+  assert.ok(bashEscapesFolder(`sh -c 'cd /tmp && npm install'`, FOLDER, [ROOT]));
+  assert.match(bashEscapesFolder(`bash -c "mkdir -p /tmp/x/y"`, FOLDER, [ROOT])!, /creates a path outside/);
+  assert.equal(bashEscapesFolder(`sh -c 'npm test && echo ok'`, FOLDER, [ROOT]), null);
+  assert.equal(bashEscape(`bash -c 'cd /tmp/x'`, FOLDER)!.grant, '/tmp/x');
+});
+
 test('bashEscape carries the offending path and the directory to grant', () => {
   // Directory-ish targets: the path itself is the grant.
   assert.deepEqual(bashEscape('cd /tmp/x && ls', FOLDER), {

package/src/policy.ts

@@ -153,15 +153,52 @@ const WRITE_VERBS: Record<string, { mode: ArgMode; opts?: string[]; does: string
 const FILE_OPTS = new Set(['-o', '--output', '-O', '--output-document']);
 /** Prefixes that merely wrap the real verb (`sudo rm`, `env FOO=1 mkdir`). */
 const WRAPPERS = new Set(['sudo', 'env', 'command', 'exec', 'nohup', 'time', 'nice', 'builtin']);
+/** Shells whose `-c` argument is a command in its own right. */
+const SHELLS = new Set(['sh', 'bash', 'zsh', 'dash']);
 /** Pseudo-devices: writing to them touches nothing on disk. */
 const DEV_SINKS = new Set(['/dev/null', '/dev/stdout', '/dev/stderr', '/dev/tty']);
 const URL_RE = /^[a-z][a-z0-9+.-]*:\/\//i;
 /** `> f`, `>> f`, `2> f`, `&> f` — but not `2>&1` / `>&2` (fd duplication). */
 const REDIRECT_RE = /(?:&>>?|\d*>>?)(?!&)\s*(\S+)/g;
 
+/**
+ * Shell operators inside quotes are text, not operators. The redirect scan
+ * and the segment split below work on the raw string, so a perl program in
+ * single quotes — `perl -pi -e 's/x =>/y/' f` — read as `>` followed by the
+ * path `/y/`, which resolved to the filesystem root and put an approval card
+ * in front of an ordinary in-folder edit. Operators inside a quoted region
+ * are swapped for private-use characters before the scan and swapped back by
+ * `bare()`, so tokens still carry their real text. Spaces inside quotes are
+ * masked too, so a quoted string is one token: `sh -c '…'` bodies and paths
+ * with spaces both come through whole. Quoting rules followed:
+ * single quotes take everything literally; double quotes honour backslash;
+ * a backslash outside quotes escapes the next character.
+ */
+const MASK: Record<string, string> = { '>': '\uE001', '<': '\uE002', '|': '\uE003', ';': '\uE004', '&': '\uE005', '\n': '\uE006', ' ': '\uE007', '\t': '\uE008' };
+const UNMASK_RE = /[\uE001-\uE008]/g;
+const UNMASK: Record<string, string> = Object.fromEntries(Object.entries(MASK).map(([k, v]) => [v, k]));
+function maskQuoted(command: string): string {
+  let out = '';
+  let quote: '"' | "'" | null = null;
+  for (let i = 0; i < command.length; i++) {
+    const c = command[i];
+    if (quote === null) {
+      if (c === '\\' && i + 1 < command.length) { out += c + command[++i]; continue; }
+      if (c === '"' || c === "'") quote = c;
+      out += c;
+      continue;
+    }
+    if (quote === '"' && c === '\\' && i + 1 < command.length) { out += c + command[++i]; continue; }
+    if (c === quote) { quote = null; out += c; continue; }
+    out += MASK[c] ?? c;
+  }
+  return out;
+}
+const unmask = (s: string): string => s.replace(UNMASK_RE, (ch) => UNMASK[ch] ?? ch);
+
 /** Strips one layer of matching quotes and shell grouping punctuation. */
 function bare(token: string): string {
-  let t = token.replace(/^[(\\]+|[)]+$/g, '');
+  let t = unmask(token).replace(/^[(\\]+|[)]+$/g, '');
   if ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'"))) t = t.slice(1, -1);
   return t;
 }
@@ -260,22 +297,31 @@ export interface BashEscape {
  */
 export function bashEscape(
   command: string, folder: string, extraRoots: Iterable<string> = [],
+  shell?: { cwd?: string },
 ): BashEscape | null {
   const root = path.resolve(folder);
   // Snapshot the grants once per call: the caller's set is mutable and may be
   // appended to while we walk, and one command must see one consistent view.
   const roots = [root, ...extraRoots];
   const outside = (p: string): boolean => !DEV_SINKS.has(p) && !underAnyRoot(p, roots);
-  const label = (seg: string): string => (seg.length > 80 ? seg.slice(0, 77) + '…' : seg);
+  const label = (raw: string): string => { const seg = unmask(raw); return seg.length > 80 ? seg.slice(0, 77) + '…' : seg; };
   const hit = (segment: string, does: string, p: string, isDir: boolean): BashEscape => ({
     reason: `${label(segment)} — ${does} outside the mission folder`,
     path: p,
     grant: isDir ? p : path.dirname(p),
   });
 
-  let cwd = root; // virtual cwd, so `cd sub && rm -rf ../../x` resolves correctly
-
-  const segments = command
+  // The virtual cwd, so `cd sub && rm -rf ../../x` resolves correctly. It
+  // starts where the agent's shell actually is: Claude Code's Bash tool keeps
+  // its working directory between commands, so a director that ran
+  // `cd examples/demo` one call ago and now writes `../../.foreman/work/x.log`
+  // is writing inside the folder — read from the root that looked like two
+  // levels out, and put an approval card in front of an in-folder log.
+  let cwd = shell?.cwd ? path.resolve(shell.cwd) : root;
+  // `cd` inside a subshell does not outlive it; only top-level moves persist.
+  let depth = 0;
+
+  const segments = maskQuoted(command)
     .split(/&&|\|\||;|\n|\|(?!\|)|(?<![&>\d])&(?![&>])/)
     .map((s) => s.trim())
     .filter(Boolean);
@@ -286,7 +332,13 @@ export function bashEscape(
       const p = asPath(m[1], cwd);
       if (p !== null && outside(p)) return hit(segment, 'redirects output', p, false);
     }
+    const opens = (segment.match(/\(/g) ?? []).length;
+    const closes = (segment.match(/\)/g) ?? []).length;
     const words = segment.replace(REDIRECT_RE, ' ').split(/\s+/).filter(Boolean).map(bare);
+    // Depth as seen at this segment's verb: an opening paren on the segment
+    // itself puts its `cd` inside the subshell.
+    const depthHere = depth + (segment.trimStart().startsWith('(') ? 1 : 0);
+    depth = Math.max(0, depth + opens - closes);
     // Peel wrappers and leading VAR=value assignments to reach the real verb.
     let i = 0;
     while (i < words.length && (WRAPPERS.has(words[i]) || /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i]))) i++;
@@ -295,6 +347,19 @@ export function bashEscape(
     const args = words.slice(i + 1);
     const flagless = args.filter((a) => !a.startsWith('-'));
 
+    // `sh -c '…'`: the quoted body is a command of its own, run from the
+    // current virtual cwd. Analysed as one, so quoting cannot hide a `cd /tmp`
+    // — masking made the body opaque to the split above, and this is where it
+    // is looked at instead.
+    if (SHELLS.has(verb)) {
+      const c = args.indexOf('-c');
+      if (c >= 0 && c + 1 < args.length) {
+        const inner = bashEscape(args[c + 1], cwd, roots);
+        if (inner) return { ...inner, reason: `${label(segment)} — ${inner.reason.replace(/^.*? — /, '')}` };
+      }
+      continue;
+    }
+
     if (verb === 'cd' || verb === 'pushd') {
       const target = flagless[0] ?? '~'; // bare `cd` goes home
       const p = asPath(target, cwd) ?? path.resolve(cwd, target);
@@ -302,6 +367,7 @@ export function bashEscape(
       // Enough on its own: whatever follows (relative writes, `npm install`,
       // `git init`) lands there, so we need not look at later segments.
       if (outside(p)) return hit(segment, 'writes after this land', p, true);
+      if (depthHere === 0 && shell) shell.cwd = p;
       continue;
     }
 
@@ -482,6 +548,10 @@ export function makePolicy(
   const foremanDir = path.join(folder, '.foreman') + path.sep;
   const toolPolicy = { ...DEFAULT_TOOL_POLICY, ...settings?.toolPolicy };
   const autoReadOnly = settings?.autoAllowReadOnly !== false;
+  // Where this agent's shell is. One policy per agent session, and the SDK's
+  // Bash keeps its cwd across calls, so a top-level `cd` in an allowed
+  // command is where the next command starts. Reset only with the session.
+  const shell: { cwd?: string } = { cwd: folder };
 
   return async (toolName, input, opts) => {
     // An explicit grant (Settings policy or the human's "Always" click) is a
@@ -507,10 +577,15 @@ export function makePolicy(
     // The shell is the other door out of the job site: a command that would
     // write outside the folder prompts under the same rule, so a blanket
     // `Bash: allow` (or an "Always" click) cannot quietly `cd /tmp && npm i`.
+    // Analysed from the shell's current directory; the walk records where a
+    // top-level `cd` leaves it. A command that escapes is not run unless the
+    // human allows it, so its `cd` is remembered only after an allow below.
+    const shellAfter = { cwd: shell.cwd };
     const escape =
       toolName === 'Bash' && typeof input.command === 'string'
-        ? bashEscape(input.command, folder, allowedRoots)
+        ? bashEscape(input.command, folder, allowedRoots, shellAfter)
         : null;
+    const rememberCwd = () => { if (toolName === 'Bash') shell.cwd = shellAfter.cwd; };
     const leavesFolder = outsideFolder || escape !== null;
     // What "always" on this card grants — see `PendingPermission.escapedPath`.
     // For a file tool the parent directory: the worker that wrote
@@ -540,6 +615,7 @@ export function makePolicy(
     ) {
       // Carry the reason through so the log shows what was waved past.
       hooks.onAutoAllow(agent, toolName, opts.decisionReason);
+      rememberCwd();
       return { behavior: 'allow' };
     }
 
@@ -582,13 +658,21 @@ export function makePolicy(
       input,
       title,
       description,
-      decisionReason: opts.decisionReason ??
-        (leavesFolder ? `Path is outside the mission folder (${folder})` : undefined),
+      // The card's one warning line. When the folder boundary is the reason,
+      // say that — the SDK's own heuristic ("contains shell syntax (&) that
+      // cannot be statically analyzed") is true of most real commands and
+      // tells the reader nothing about why THIS one stopped.
+      decisionReason: leavesFolder
+        ? (escape?.reason ?? `${filePath} is outside the mission folder`)
+        : opts.decisionReason,
       escapedPath,
     });
 
     return new Promise<PermissionResult>((resolve) => {
-      hooks.register(id, { resolve, toolName, suggestions: opts.suggestions, escapedPath });
+      hooks.register(id, {
+        resolve: (r) => { if (r.behavior === 'allow') rememberCwd(); resolve(r); },
+        toolName, suggestions: opts.suggestions, escapedPath,
+      });
       opts.signal.addEventListener('abort', () => {
         if (hooks.unregister(id)) {
           resolve({ behavior: 'deny', message: 'Run was interrupted.' });

package/src/server.ts

@@ -1724,6 +1724,8 @@ async function startRun(
  */
 async function resumeRun(projectId: string, meta: RunMeta, pick: {
   directorModel?: string; directorProviderId?: string; workerModel?: string; workerProviderId?: string;
+  /** A new cap for the resumed attempt — the answer to "stopped at its budget". */
+  budgetUsd?: number;
 } = {}): Promise<void> {
   const sessionId = meta.directorSessionId;
   // Resume re-reads Settings for tool policy and auto-allow, so a policy
@@ -1748,9 +1750,24 @@ async function resumeRun(projectId: string, meta: RunMeta, pick: {
   if (workerChanged) { meta.workerModel = modelChoice(pick.workerModel); meta.workerProviderId = pick.workerProviderId; }
   meta.toolPolicy = settings.toolPolicy;
   meta.autoAllowReadOnly = settings.autoAllowReadOnly;
+  // A raised cap rides the resume: the run that stopped at $10 continues
+  // under $15, and the transcript says who moved it and from where. Written
+  // to the log as a settings change, which is what it is.
+  const budgetWas = meta.budgetUsd;
+  if (typeof pick.budgetUsd === 'number' && Number.isFinite(pick.budgetUsd) && pick.budgetUsd > 0 && pick.budgetUsd !== meta.budgetUsd) {
+    meta.budgetUsd = pick.budgetUsd;
+  }
+  const stoppedAt = meta.stopReason;
+  meta.stopReason = undefined;
   meta.status = 'running';
   meta.endedAt = undefined;
   meta.resumes = (meta.resumes ?? 0) + 1;
+  if (meta.budgetUsd !== budgetWas) {
+    makeEmitter(meta.id, projectId)('settings_changed', {
+      budgetUsd: meta.budgetUsd,
+      changes: [`Budget ${meta.budgetUsd > budgetWas ? 'raised' : 'lowered'} to $${meta.budgetUsd.toFixed(2)} (was $${budgetWas.toFixed(2)}) before resume${stoppedAt === 'budget' ? ' — the last attempt stopped at its cap' : ''}.`],
+    });
+  }
   if (meta.git) {
     const back = await ensureMissionBranch(meta.folder, meta.git.branch);
     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.` });
@@ -2740,6 +2757,8 @@ const server = http.createServer(async (req, res) => {
       const overrides = {
         directorModel: str(resumeBody.directorModel), directorProviderId: str(resumeBody.directorProviderId),
         workerModel: str(resumeBody.workerModel), workerProviderId: str(resumeBody.workerProviderId),
+        budgetUsd: typeof resumeBody.budgetUsd === 'number' && Number.isFinite(resumeBody.budgetUsd) && resumeBody.budgetUsd > 0
+          ? Math.round(resumeBody.budgetUsd * 100) / 100 : undefined,
       };
       void resumeRun(meta.projectId, meta, overrides);
       json(res, 200, { ok: true });

package/src/types.ts

@@ -325,6 +325,12 @@ export interface RunMeta {
   askTimeoutMs?: number;
   /** Give agents a headless Playwright browser (navigate, click, screenshot). */
   browserTools?: boolean;
+  /**
+   * Which cap ended the last attempt, when one did. The dashboard reads it
+   * 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.
+   */
+  stopReason?: 'budget' | 'turns' | 'time' | 'tokens';
   folder: string;
   mission: string;
   budgetUsd: number;