claude-yes 1.165.0 → 1.167.0

package/ts/spawnGate.spec.ts

@@ -0,0 +1,155 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import path from "path";
+import {
+  memAvailableMb,
+  spawnGateEnabled,
+  spawnRejectionReason,
+  waitForSpawnCapacity,
+} from "./spawnGate.ts";
+
+// Build a minimal live pid record. Using the test runner's own pid guarantees
+// `isProcessAlive` (process.kill(pid, 0)) succeeds, so the record counts as live.
+const liveRecord = (pid: number) =>
+  JSON.stringify({
+    pid,
+    cli: "claude",
+    prompt: null,
+    cwd: "/tmp",
+    log_file: null,
+    status: "active",
+    exit_code: null,
+    exit_reason: null,
+    started_at: 0,
+  });
+
+describe("spawnGate", () => {
+  let original: string | undefined;
+  let tmp: string;
+  const writePids = (lines: string[]) =>
+    writeFileSync(path.join(tmp, "pids.jsonl"), lines.join("\n") + "\n");
+
+  beforeEach(() => {
+    original = process.env.AGENT_YES_HOME;
+    tmp = mkdtempSync(path.join(tmpdir(), "ay-gate-"));
+    process.env.AGENT_YES_HOME = tmp;
+  });
+  afterEach(() => {
+    if (original === undefined) delete process.env.AGENT_YES_HOME;
+    else process.env.AGENT_YES_HOME = original;
+    delete process.env.AGENT_YES_MAX_AGENTS;
+    delete process.env.AGENT_YES_MIN_FREE_MB;
+    delete process.env.AGENT_YES_SPAWN_WAIT_MS;
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  describe("memAvailableMb", () => {
+    it("returns a positive number on this host", async () => {
+      const mb = await memAvailableMb();
+      expect(mb).not.toBeNull();
+      expect(mb!).toBeGreaterThan(0);
+    });
+  });
+
+  describe("spawnGateEnabled", () => {
+    it("is false when nothing is configured", () => {
+      expect(spawnGateEnabled()).toBe(false);
+    });
+    it("is true when a cap or floor is set", () => {
+      process.env.AGENT_YES_MAX_AGENTS = "5";
+      expect(spawnGateEnabled()).toBe(true);
+    });
+  });
+
+  describe("spawnRejectionReason", () => {
+    it("returns null when no limits are configured", async () => {
+      expect(await spawnRejectionReason()).toBeNull();
+    });
+
+    it("rejects when live agents reach the cap", async () => {
+      writePids([liveRecord(process.pid)]);
+      process.env.AGENT_YES_MAX_AGENTS = "1";
+      expect(await spawnRejectionReason()).toMatch(/too many agents running \(1\/1\)/);
+    });
+
+    it("admits when live agents are under the cap", async () => {
+      writePids([liveRecord(process.pid)]);
+      process.env.AGENT_YES_MAX_AGENTS = "5";
+      expect(await spawnRejectionReason()).toBeNull();
+    });
+
+    it("ignores dead pids when counting live agents", async () => {
+      // pid 2^31-1 is effectively never a live process → not counted.
+      writePids([liveRecord(2147483646)]);
+      process.env.AGENT_YES_MAX_AGENTS = "1";
+      expect(await spawnRejectionReason()).toBeNull();
+    });
+
+    it("rejects when free memory is below the floor", async () => {
+      process.env.AGENT_YES_MIN_FREE_MB = String(Number.MAX_SAFE_INTEGER);
+      expect(await spawnRejectionReason()).toMatch(/host is low on memory/);
+    });
+
+    it("admits when free memory is above the floor", async () => {
+      process.env.AGENT_YES_MIN_FREE_MB = "1";
+      expect(await spawnRejectionReason()).toBeNull();
+    });
+  });
+
+  describe("waitForSpawnCapacity", () => {
+    it("returns immediately (no sleep) when the gate is disabled", async () => {
+      const sleeps: number[] = [];
+      await waitForSpawnCapacity({ sleep: async (ms) => void sleeps.push(ms) });
+      expect(sleeps).toEqual([]);
+    });
+
+    it("backs off with φ growth and fails open at the deadline", async () => {
+      writePids([liveRecord(process.pid)]);
+      process.env.AGENT_YES_MAX_AGENTS = "1"; // always over → never admits
+
+      let t = 0;
+      const sleeps: number[] = [];
+      let proceededAfter: number | null = null;
+      await waitForSpawnCapacity({
+        maxWaitMs: 5000,
+        now: () => t,
+        sleep: async (ms) => {
+          sleeps.push(ms);
+          t += ms;
+        },
+        onProceedAnyway: (_r, waited) => {
+          proceededAfter = waited;
+        },
+      });
+
+      // 1000, then ×φ (1618), then clamped to the remaining 2382ms before deadline.
+      expect(sleeps[0]).toBe(1000);
+      expect(sleeps[1]).toBe(1618);
+      expect(sleeps.reduce((a, b) => a + b, 0)).toBe(5000);
+      expect(proceededAfter).toBe(5000);
+    });
+
+    it("admits as soon as capacity frees, without proceeding-anyway", async () => {
+      writePids([liveRecord(process.pid)]);
+      process.env.AGENT_YES_MAX_AGENTS = "1";
+
+      const sleeps: number[] = [];
+      let proceeded = false;
+      await waitForSpawnCapacity({
+        maxWaitMs: 600_000,
+        sleep: async (ms) => {
+          sleeps.push(ms);
+          // free up capacity after two backoff cycles
+          if (sleeps.length >= 2) process.env.AGENT_YES_MAX_AGENTS = "10";
+        },
+        onProceedAnyway: () => {
+          proceeded = true;
+        },
+      });
+
+      expect(sleeps.length).toBe(2);
+      expect(proceeded).toBe(false);
+    });
+  });
+});

package/ts/spawnGate.ts

@@ -0,0 +1,123 @@
+/**
+ * Spawn admission control — keep an unbounded fan-out of agents from exhausting
+ * host RAM and tripping the kernel OOM-killer (which, on a box with no cgroup
+ * memory limit, hangs the whole machine). Two opt-in limits:
+ *   - {@link getMaxAgents}  — max concurrently-live agents
+ *   - {@link getMinFreeMb}  — minimum free memory before admitting a spawn
+ *
+ * Two entry points share one instantaneous check ({@link spawnRejectionReason}):
+ *   - the `ay serve` daemon HARD-REJECTS (`/api/spawn` → 429) so the caller retries;
+ *   - the CLI path BLOCKS-AND-WAITS ({@link waitForSpawnCapacity}) with φ-backoff,
+ *     failing open after a timeout so recursive `ay <cli>` spawns get spaced out
+ *     (the actual cause of the burst storms) without ever deadlocking a workflow.
+ */
+import { readFile } from "fs/promises";
+import { readGlobalPids } from "./globalPidIndex.ts";
+import { getMaxAgents, getMinFreeMb, getSpawnWaitMs } from "./workspaceConfig.ts";
+
+/**
+ * System available memory in MB. Prefers Linux `/proc/meminfo` `MemAvailable`
+ * (the kernel's own estimate of what's reclaimable without swapping — far more
+ * accurate than free RAM), falling back to `os.freemem()` on other platforms or
+ * if the file can't be parsed. Returns null when nothing usable is available.
+ */
+export async function memAvailableMb(): Promise<number | null> {
+  try {
+    const txt = await readFile("/proc/meminfo", "utf-8");
+    const m = /^MemAvailable:\s+(\d+)\s*kB/m.exec(txt);
+    if (m) return Math.floor(Number(m[1]) / 1024);
+  } catch {
+    /* not Linux / unreadable — fall through */
+  }
+  try {
+    const { freemem } = await import("os");
+    return Math.floor(freemem() / (1024 * 1024));
+  } catch {
+    return null;
+  }
+}
+
+/** True when at least one spawn limit is configured (else the gate is a no-op). */
+export function spawnGateEnabled(): boolean {
+  return getMaxAgents() !== undefined || getMinFreeMb() !== undefined;
+}
+
+/**
+ * Instantaneous capacity check. Returns a human-readable reason string when a
+ * new spawn should be held back (cap reached / memory too low), or null when
+ * there's capacity. Both limits are opt-in — unset means no check.
+ *
+ * NOTE — the `maxAgents` count is BEST-EFFORT, not a hard barrier: the check is
+ * non-atomic (check here → register in `pids.jsonl` later, in another process),
+ * so a simultaneous burst can briefly overshoot the cap before the new wrappers
+ * appear in the live count. That's acceptable because (a) the CLI path's
+ * φ-backoff desynchronizes retries, spreading a burst out, and (b) `minFreeMb`
+ * is the HARD OOM guard — it's re-evaluated against live `/proc/meminfo` on every
+ * attempt, so once RAM actually drops, further spawns are held regardless of the
+ * count. Exact admission would need a cross-process reservation+lock (a TTL'd
+ * reservation file); deliberately deferred to avoid stale reservations wedging
+ * spawns, which would be worse than a transient overshoot.
+ */
+export async function spawnRejectionReason(): Promise<string | null> {
+  const maxAgents = getMaxAgents();
+  if (maxAgents !== undefined) {
+    // Live agents already running (this wrapper hasn't registered itself yet),
+    // so "live >= cap" admits exactly `maxAgents` concurrent agents.
+    const live = (await readGlobalPids({ liveOnly: true })).length;
+    if (live >= maxAgents)
+      // Phrased for the end user who clicked "Spawn" (the console shows this
+      // string verbatim), with a host-admin hint appended in parentheses.
+      return `too many agents running (${live}/${maxAgents}) — this agent wasn't started. Please wait for one to finish and try again. (host: raise "maxAgents" in ~/.agent-yes/config.json or AGENT_YES_MAX_AGENTS)`;
+  }
+  const minFreeMb = getMinFreeMb();
+  if (minFreeMb !== undefined) {
+    const avail = await memAvailableMb();
+    if (avail !== null && avail < minFreeMb)
+      return `the host is low on memory (${avail}MB free, needs ${minFreeMb}MB) — this agent wasn't started, to avoid crashing the machine. Please try again in a moment. (host: adjust "minFreeMb" in ~/.agent-yes/config.json or AGENT_YES_MIN_FREE_MB)`;
+  }
+  return null;
+}
+
+const PHI = 1.618; // golden-ratio backoff base (snomiao global pref)
+const BACKOFF_CAP_MS = 60_000;
+const BACKOFF_BASE_MS = 1_000;
+
+/**
+ * Block until there's spawn capacity, polling with φ-backoff (1s × φⁿ, capped at
+ * 60s — there is no OS event for "memory freed", so polling is unavoidable here).
+ * Fails open after {@link getSpawnWaitMs} ms (default 10 min): on timeout it logs
+ * and proceeds, so a set of mutually-waiting recursive spawns can never deadlock
+ * permanently. A no-op (returns immediately) when no limit is configured, so it
+ * adds ~zero overhead to the spawn hot path for users who haven't opted in.
+ *
+ * `sleep`/`now` are injectable for tests. `onWait` fires once per backoff cycle.
+ */
+export async function waitForSpawnCapacity(opts?: {
+  maxWaitMs?: number;
+  onWait?: (reason: string, waitedMs: number) => void;
+  onProceedAnyway?: (reason: string, waitedMs: number) => void;
+  sleep?: (ms: number) => Promise<void>;
+  now?: () => number;
+}): Promise<void> {
+  if (!spawnGateEnabled()) return; // fast path: nothing configured
+  const maxWaitMs = opts?.maxWaitMs ?? getSpawnWaitMs();
+  // Monotonic clock for the deadline — `Date.now()` can step backward (NTP /
+  // suspend) and stretch the fail-open wait far past `maxWaitMs`.
+  const now = opts?.now ?? (() => performance.now());
+  const sleep = opts?.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
+  const start = now();
+  let delay = BACKOFF_BASE_MS;
+  for (;;) {
+    const reason = await spawnRejectionReason();
+    if (!reason) return; // capacity available — admit
+    const waited = now() - start;
+    if (waited >= maxWaitMs) {
+      opts?.onProceedAnyway?.(reason, waited);
+      return; // fail open — never deadlock a workflow
+    }
+    opts?.onWait?.(reason, waited);
+    // Don't oversleep past the deadline.
+    await sleep(Math.min(delay, BACKOFF_CAP_MS, maxWaitMs - waited));
+    delay = Math.min(delay * PHI, BACKOFF_CAP_MS);
+  }
+}

package/ts/subcommands.spec.ts

@@ -113,25 +113,134 @@ describe("subcommands.isSubcommand", () => {
 });
 
 describe("subcommands.cmdHelp", () => {
-  it("hides the manager-only `setup` line for cli-bound aliases", async () => {
+  const capture = async (managerCommands?: boolean) => {
     const { cmdHelp } = await loadModule();
-    const capture = (managerCommands?: boolean) => {
-      let out = "";
-      const spy = vi.spyOn(process.stdout, "write").mockImplementation((s: unknown) => {
-        out += String(s);
-        return true;
-      });
-      try {
-        cmdHelp(managerCommands);
-      } finally {
-        spy.mockRestore();
-      }
-      return out;
-    };
-    expect(capture(true)).toContain("ay setup"); // manager
-    expect(capture()).toContain("ay setup"); // default = manager
-    expect(capture(false)).not.toContain("ay setup"); // cli-bound alias (cy)
-    expect(capture(false)).toContain("ay ls"); // universal commands still shown
+    let out = "";
+    const spy = vi.spyOn(process.stdout, "write").mockImplementation((s: unknown) => {
+      out += String(s);
+      return true;
+    });
+    try {
+      await cmdHelp(managerCommands);
+    } finally {
+      spy.mockRestore();
+    }
+    return out;
+  };
+
+  it("hides the manager-only `setup` line for cli-bound aliases", async () => {
+    expect(await capture(true)).toContain("ay setup"); // manager
+    expect(await capture()).toContain("ay setup"); // default = manager
+    expect(await capture(false)).not.toContain("ay setup"); // cli-bound alias (cy)
+    expect(await capture(false)).toContain("ay ls"); // universal commands still shown
+  });
+
+  it("stays plain for a human shell (no AGENT_YES_PID)", async () => {
+    const out = await capture();
+    expect(out).not.toContain("You are running inside an agent");
+  });
+
+  it("prints self + parent identity and sub-agent guidance when nested in an agent", async () => {
+    const { appendGlobalPid } = await import("./globalPidIndex.ts");
+    const parentWrapperPid = 555001;
+    const selfWrapperPid = 555002;
+    await appendGlobalPid({
+      pid: 900001,
+      cli: "codex",
+      prompt: "orchestrate the migration",
+      cwd: "/work/parent",
+      log_file: null,
+      fifo_file: null,
+      status: "active",
+      exit_code: null,
+      exit_reason: null,
+      started_at: Date.now(),
+      wrapper_pid: parentWrapperPid,
+    });
+    await appendGlobalPid({
+      pid: process.pid,
+      cli: "claude",
+      prompt: "fix the failing test",
+      cwd: "/work/parent/child",
+      log_file: null,
+      fifo_file: null,
+      status: "active",
+      exit_code: null,
+      exit_reason: null,
+      started_at: Date.now(),
+      wrapper_pid: selfWrapperPid,
+      parent_pid: parentWrapperPid,
+    });
+    const saved = process.env.AGENT_YES_PID;
+    process.env.AGENT_YES_PID = String(selfWrapperPid);
+    try {
+      const out = await capture();
+      expect(out).toContain("You are running inside an agent");
+      expect(out).toContain(`You are agent pid ${process.pid} (claude)`);
+      expect(out).toContain(`Spawned by agent pid 900001 (codex)`);
+      expect(out).toContain("Spawn a sub-agent");
+      expect(out).toContain(`ay ls --cwd /work/parent/child`);
+      expect(out).toContain(`ay ls --watch --cwd /work/parent/child`);
+    } finally {
+      if (saved === undefined) delete process.env.AGENT_YES_PID;
+      else process.env.AGENT_YES_PID = saved;
+    }
+  });
+
+  it("reports a nested-but-unresolved parent distinctly from top-level", async () => {
+    const { appendGlobalPid } = await import("./globalPidIndex.ts");
+    const selfWrapperPid = 555004;
+    await appendGlobalPid({
+      pid: process.pid,
+      cli: "claude",
+      prompt: null,
+      cwd: process.cwd(),
+      log_file: null,
+      fifo_file: null,
+      status: "active",
+      exit_code: null,
+      exit_reason: null,
+      started_at: Date.now(),
+      wrapper_pid: selfWrapperPid,
+      parent_pid: 999999999, // no record ever registered for this wrapper pid
+    });
+    const saved = process.env.AGENT_YES_PID;
+    process.env.AGENT_YES_PID = String(selfWrapperPid);
+    try {
+      const out = await capture();
+      expect(out).not.toContain("Top-level agent");
+      expect(out).toContain("Nested under a parent (wrapper pid 999999999)");
+    } finally {
+      if (saved === undefined) delete process.env.AGENT_YES_PID;
+      else process.env.AGENT_YES_PID = saved;
+    }
+  });
+
+  it("reports top-level (no parent) when parent_pid is absent", async () => {
+    const { appendGlobalPid } = await import("./globalPidIndex.ts");
+    const selfWrapperPid = 555003;
+    await appendGlobalPid({
+      pid: process.pid,
+      cli: "claude",
+      prompt: null,
+      cwd: process.cwd(),
+      log_file: null,
+      fifo_file: null,
+      status: "active",
+      exit_code: null,
+      exit_reason: null,
+      started_at: Date.now(),
+      wrapper_pid: selfWrapperPid,
+    });
+    const saved = process.env.AGENT_YES_PID;
+    process.env.AGENT_YES_PID = String(selfWrapperPid);
+    try {
+      const out = await capture();
+      expect(out).toContain("Top-level agent");
+    } finally {
+      if (saved === undefined) delete process.env.AGENT_YES_PID;
+      else process.env.AGENT_YES_PID = saved;
+    }
   });
 });
 

package/ts/subcommands.ts

@@ -387,14 +387,77 @@ export async function runSubcommand(argv: string[]): Promise<number | null> {
 // ay help
 // ---------------------------------------------------------------------------
 
-export function cmdHelp(managerCommands = true): number {
+/**
+ * The banner shown by `ay help` / `ay -h` when this process is itself running
+ * inside an agent (`AGENT_YES_PID` set — see resolveSender). Answers the three
+ * things a nested agent actually needs: who am I, who spawned me, and how do I
+ * drive sub-agents of my own — so it doesn't have to rediscover the fan-out
+ * primitives (spawn / ay ls forest / ay ls --watch) from scratch every session.
+ */
+async function buildAgentContextSection(self: GlobalPidRecord): Promise<string> {
+  const hasParentPid = typeof self.parent_pid === "number" && self.parent_pid > 0;
+  const parent = hasParentPid
+    ? (
+        await listRecords(undefined, {
+          all: true,
+          active: false,
+          json: false,
+          latest: false,
+          cwdScope: null,
+        })
+      ).find((r) => r.wrapper_pid === self.parent_pid)
+    : undefined;
+
+  const whoAmI = `You are agent pid ${self.pid} (${self.cli}) in ${shortenPath(self.cwd)}.`;
+  // Three distinct states: no parent at all (top-level); a parent_pid whose
+  // record we can resolve; or a parent_pid we can't resolve (its record aged
+  // out / lives on a remote) — that last case is still nested, just unknown,
+  // so it must not collapse into the "top-level" line.
+  const parentLine = !hasParentPid
+    ? `Top-level agent — no parent (started from a human shell or scheduler).`
+    : parent
+      ? `Spawned by agent pid ${parent.pid} (${parent.cli}) in ${shortenPath(parent.cwd)}.`
+      : `Nested under a parent (wrapper pid ${self.parent_pid}) whose record isn't in the local registry.`;
+
+  return (
+    `You are running inside an agent:\n` +
+    `  ${whoAmI}\n` +
+    `  ${parentLine}\n` +
+    `\n` +
+    `As an agent, you can:\n` +
+    `  Spawn a sub-agent:\n` +
+    `    ay <cli> -- "<prompt>"                                  auto-links as your child\n` +
+    `    ay claude --model sonnet --advisor opus -- "<prompt>"   routine task\n` +
+    `    ay claude --model opus --advisor fable -- "<prompt>"    complex task\n` +
+    `    (pick --model by task complexity so easy tasks don't cost like hard ones;\n` +
+    `     --advisor is a claude-cli flag — only takes effect for claude/cy)\n` +
+    `  List agents (your children nest under your own pid in the tree):\n` +
+    `    ay ls --cwd ${shortenPath(self.cwd)}\n` +
+    `  Watch agent state changes, scoped to your workspace:\n` +
+    `    ay ls --watch --cwd ${shortenPath(self.cwd)}\n` +
+    `    (NDJSON stream of state changes across every matched agent — one watcher\n` +
+    `     for the whole fan-out instead of N \`ay status --watch\`es)\n` +
+    `  Read one sub-agent's output:\n` +
+    `    ay tail -f <pid>                        follow live output (no single command tails\n` +
+    `                                              many agents' content at once yet — loop\n` +
+    `                                              \`ay ls --json\` pids into per-pid \`ay tail\`)\n` +
+    `\n`
+  );
+}
+
+export async function cmdHelp(managerCommands = true): Promise<number> {
   // `setup` is manager-only — hide it when invoked through a cli-bound alias
   // (cy/claude-yes/…), where `cy setup` runs the agent instead of managing the host.
   const setupLine = managerCommands
     ? `  ay setup                            guided setup: pick a workspace, share to agent-yes.com\n`
     : ``;
+  // Only agents carry AGENT_YES_PID — a human shell never sets it — so this
+  // section is skipped entirely (no async work at all) for interactive use.
+  const self = process.env.AGENT_YES_PID ? await resolveSender() : null;
+  const agentSection = self ? await buildAgentContextSection(self) : "";
   process.stdout.write(
-    `ay - agent-yes CLI\n` +
+    agentSection +
+      `ay - agent-yes CLI\n` +
       `\n` +
       `Management:\n` +
       `  ay ls [keyword]                     list running agents\n` +

package/ts/workspaceConfig.spec.ts

@@ -4,6 +4,9 @@ import { homedir, tmpdir } from "os";
 import path from "path";
 import {
   expandTilde,
+  getMaxAgents,
+  getMinFreeMb,
+  getSpawnWaitMs,
   getProvisionAllowlist,
   getProvisionRoot,
   getSpawnHook,
@@ -28,6 +31,9 @@ describe("workspaceConfig", () => {
     delete process.env.CODEHOST_WS_ROOT;
     delete process.env.CODEHOST_PROVISION_ALLOWLIST;
     delete process.env.AGENT_YES_SPAWN_HOOK;
+    delete process.env.AGENT_YES_MAX_AGENTS;
+    delete process.env.AGENT_YES_MIN_FREE_MB;
+    delete process.env.AGENT_YES_SPAWN_WAIT_MS;
     rmSync(tmp, { recursive: true, force: true });
   });
 
@@ -146,6 +152,85 @@ describe("workspaceConfig", () => {
     });
   });
 
+  describe("getMaxAgents", () => {
+    it("is undefined (unlimited) when neither env nor config is set", () => {
+      expect(getMaxAgents()).toBeUndefined();
+    });
+
+    it("reads a positive integer from config", () => {
+      writeConfig({ maxAgents: 8 });
+      expect(getMaxAgents()).toBe(8);
+    });
+
+    it("env AGENT_YES_MAX_AGENTS overrides config", () => {
+      writeConfig({ maxAgents: 8 });
+      process.env.AGENT_YES_MAX_AGENTS = "3";
+      expect(getMaxAgents()).toBe(3);
+    });
+
+    it("floors a fractional value", () => {
+      process.env.AGENT_YES_MAX_AGENTS = "4.9";
+      expect(getMaxAgents()).toBe(4);
+    });
+
+    it("treats 0, negative, and garbage as unlimited (undefined)", () => {
+      writeConfig({ maxAgents: 0 });
+      expect(getMaxAgents()).toBeUndefined();
+      process.env.AGENT_YES_MAX_AGENTS = "-5";
+      expect(getMaxAgents()).toBeUndefined();
+      process.env.AGENT_YES_MAX_AGENTS = "lots";
+      expect(getMaxAgents()).toBeUndefined();
+    });
+
+    it("treats a fractional value < 1 as unlimited, not a 0 hard-cap", () => {
+      // Regression: 0.5 must NOT floor to 0 (which would reject every spawn).
+      process.env.AGENT_YES_MAX_AGENTS = "0.5";
+      expect(getMaxAgents()).toBeUndefined();
+    });
+  });
+
+  describe("getMinFreeMb", () => {
+    it("is undefined (no floor) when unset", () => {
+      expect(getMinFreeMb()).toBeUndefined();
+    });
+
+    it("reads config and lets env override", () => {
+      writeConfig({ minFreeMb: 1024 });
+      expect(getMinFreeMb()).toBe(1024);
+      process.env.AGENT_YES_MIN_FREE_MB = "2048";
+      expect(getMinFreeMb()).toBe(2048);
+    });
+
+    it("treats non-positive/garbage/sub-1 as no floor", () => {
+      process.env.AGENT_YES_MIN_FREE_MB = "0";
+      expect(getMinFreeMb()).toBeUndefined();
+      process.env.AGENT_YES_MIN_FREE_MB = "nope";
+      expect(getMinFreeMb()).toBeUndefined();
+      process.env.AGENT_YES_MIN_FREE_MB = "0.5";
+      expect(getMinFreeMb()).toBeUndefined();
+    });
+  });
+
+  describe("getSpawnWaitMs", () => {
+    it("defaults to 10 minutes when unset", () => {
+      expect(getSpawnWaitMs()).toBe(600_000);
+    });
+
+    it("reads config and lets env override; allows 0 (don't wait)", () => {
+      writeConfig({ spawnWaitMs: 5000 });
+      expect(getSpawnWaitMs()).toBe(5000);
+      process.env.AGENT_YES_SPAWN_WAIT_MS = "0";
+      expect(getSpawnWaitMs()).toBe(0);
+    });
+
+    it("falls back to the default on negative/garbage", () => {
+      process.env.AGENT_YES_SPAWN_WAIT_MS = "-1";
+      expect(getSpawnWaitMs()).toBe(600_000);
+      process.env.AGENT_YES_SPAWN_WAIT_MS = "soon";
+      expect(getSpawnWaitMs()).toBe(600_000);
+    });
+  });
+
   describe("getSpawnHook / hasSpawnHook", () => {
     const isPosix = process.platform !== "win32";