@pitboss/cli 0.4.3 → 0.4.5

package/dist/cli.js

@@ -10864,7 +10864,7 @@ var require_lib2 = __commonJS({
       return matches;
     };
     exports.analyse = analyse;
-    var detectFile = (filepath, opts = {}) => new Promise((resolve7, reject) => {
+    var detectFile = (filepath, opts = {}) => new Promise((resolve8, reject) => {
       let fd;
       const fs = (0, node_1.default)();
       const handler = (err, buffer) => {
@@ -10874,7 +10874,7 @@ var require_lib2 = __commonJS({
         if (err) {
           reject(err);
         } else if (buffer) {
-          resolve7((0, exports.detect)(buffer));
+          resolve8((0, exports.detect)(buffer));
         } else {
           reject(new Error("No error and no buffer received"));
         }
@@ -17281,13 +17281,13 @@ var PromisePolyfill = class extends Promise {
   // Available starting from Node 22
   // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/withResolvers
   static withResolver() {
-    let resolve7;
+    let resolve8;
     let reject;
     const promise = new Promise((res, rej) => {
-      resolve7 = res;
+      resolve8 = res;
       reject = rej;
     });
-    return { promise, resolve: resolve7, reject };
+    return { promise, resolve: resolve8, reject };
   }
 };
 
@@ -17324,7 +17324,7 @@ function createPrompt(view) {
     });
     output.mute();
     const screen = new ScreenManager(rl);
-    const { promise, resolve: resolve7, reject } = PromisePolyfill.withResolver();
+    const { promise, resolve: resolve8, reject } = PromisePolyfill.withResolver();
     const cancel = () => reject(new CancelPromptError());
     if (signal) {
       const abort = () => reject(new AbortPromptError({ cause: signal.reason }));
@@ -17355,7 +17355,7 @@ function createPrompt(view) {
           try {
             const nextView = view(config, (value) => {
               if (effectsSettled) {
-                resolve7(value);
+                resolve8(value);
               } else {
                 pendingDone = { value };
               }
@@ -17378,7 +17378,7 @@ function createPrompt(view) {
           if (pendingDone !== null) {
             const { value } = pendingDone;
             pendingDone = null;
-            resolve7(value);
+            resolve8(value);
           }
         });
       };
@@ -17463,28 +17463,28 @@ var RemoveFileError = class extends Error {
 
 // ../../node_modules/.pnpm/@inquirer+external-editor@3.0.4_@types+node@22.19.17/node_modules/@inquirer/external-editor/dist/parse-editor-command.js
 function parseEditorCommand(editor) {
-  let bin2;
+  let bin3;
   let rest;
   if (editor.startsWith('"')) {
     const closeQuote = editor.indexOf('"', 1);
     if (closeQuote === -1) {
-      bin2 = editor.slice(1);
+      bin3 = editor.slice(1);
       rest = "";
     } else {
-      bin2 = editor.substring(1, closeQuote);
+      bin3 = editor.substring(1, closeQuote);
       rest = editor.substring(closeQuote + 1).trim();
     }
   } else {
     const firstSpace = editor.indexOf(" ");
     if (firstSpace === -1) {
-      bin2 = editor;
+      bin3 = editor;
       rest = "";
     } else {
-      bin2 = editor.substring(0, firstSpace);
+      bin3 = editor.substring(0, firstSpace);
       rest = editor.substring(firstSpace + 1).trim();
     }
   }
-  return { bin: bin2, args: rest ? rest.split(/\s+/) : [] };
+  return { bin: bin3, args: rest ? rest.split(/\s+/) : [] };
 }
 
 // ../../node_modules/.pnpm/@inquirer+external-editor@3.0.4_@types+node@22.19.17/node_modules/@inquirer/external-editor/dist/index.js
@@ -17533,7 +17533,7 @@ var ExternalEditor = class {
   }
   runAsync(callback) {
     this.createTempFile();
-    const promise = new Promise((resolve7, reject) => {
+    const promise = new Promise((resolve8, reject) => {
       try {
         const editorProcess = spawn(this.editor.bin, this.editorArgs(), {
           shell: false,
@@ -17544,7 +17544,7 @@ var ExternalEditor = class {
         });
         editorProcess.once("exit", (code) => {
           this.lastExitStatus = code ?? 0;
-          resolve7();
+          resolve8();
         });
       } catch (launchError) {
         reject(new LaunchEditorError(launchError));
@@ -18343,7 +18343,7 @@ async function taskCreateCommand(options) {
   if (options.reviewBy) {
     verifyKind = "reviewer_agent";
   } else if (options.verifyKind) {
-    if (!["shell", "file_exists", "thread_concluded", "reviewer_agent", "human_approval"].includes(options.verifyKind)) {
+    if (!["shell", "file_exists", "thread_concluded", "reviewer_agent", "human_approval", "ci_passed"].includes(options.verifyKind)) {
       console.error(source_default.red(`Invalid --verify-kind "${options.verifyKind}".`));
       process.exit(1);
     }
@@ -18357,6 +18357,9 @@ async function taskCreateCommand(options) {
       process.exit(1);
     }
     verifyReviewerId = await resolveAgentRef(client, config.repoId, reviewerRef);
+  } else if (verifyKind === "ci_passed" && !options.verifyPath) {
+    console.error(source_default.red("--verify-kind ci_passed requires --verify-path <sha>."));
+    process.exit(1);
   } else if (options.verifyReviewer) {
     console.error(source_default.red("--verify-reviewer is only valid with --verify-kind reviewer_agent."));
     process.exit(1);
@@ -18957,10 +18960,10 @@ async function readWake(stream, { idleMs = 1e3, stallMs = 75e3 } = {}) {
       }
       if (next.done) return wake;
       buffer += decoder.decode(next.value, { stream: true });
-      let sep2;
-      while ((sep2 = buffer.indexOf("\n\n")) !== -1) {
-        const { id, event } = parseFrame(buffer.slice(0, sep2));
-        buffer = buffer.slice(sep2 + 2);
+      let sep3;
+      while ((sep3 = buffer.indexOf("\n\n")) !== -1) {
+        const { id, event } = parseFrame(buffer.slice(0, sep3));
+        buffer = buffer.slice(sep3 + 2);
         if (id && EVENT_ID.test(id)) wake.lastId = id;
         if (event?.kind === "replay.truncated" && !wake.first) {
           wake.truncated = true;
@@ -19104,6 +19107,7 @@ function isWorkerType(value) {
   return typeof value === "string" && WORKER_TYPES.includes(value);
 }
 var DEFAULT_UNSTARTED_AFTER_MS = 4 * 60 * 60 * 1e3;
+var POOL_STOPPED_REASON = "pool member stopped by pitboss node";
 
 // src/lib/runtimes.ts
 var RUNTIMES2 = RUNTIMES.map((r) => r.value);
@@ -20340,10 +20344,10 @@ async function consumeEventStream(stream, onEvent) {
     const { done, value } = await reader.read();
     if (done) break;
     buffer += decoder.decode(value, { stream: true });
-    let sep2;
-    while ((sep2 = buffer.indexOf("\n\n")) !== -1) {
-      const event = parseSseFrame(buffer.slice(0, sep2));
-      buffer = buffer.slice(sep2 + 2);
+    let sep3;
+    while ((sep3 = buffer.indexOf("\n\n")) !== -1) {
+      const event = parseSseFrame(buffer.slice(0, sep3));
+      buffer = buffer.slice(sep3 + 2);
       if (event) onEvent(event);
     }
   }
@@ -20596,13 +20600,13 @@ function hookCursorPromptCommand(opts) {
 }
 
 // src/commands/node.ts
-import { execFileSync as execFileSync6, spawn as spawnChild } from "node:child_process";
-import { closeSync, existsSync as existsSync10, mkdirSync as mkdirSync7, openSync, readFileSync as readFileSync12, realpathSync as realpathSync4 } from "node:fs";
-import { dirname as dirname10, resolve as resolve6 } from "node:path";
+import { execFileSync as execFileSync7, spawn as spawnChild } from "node:child_process";
+import { closeSync, existsSync as existsSync11, mkdirSync as mkdirSync8, openSync, readFileSync as readFileSync12, realpathSync as realpathSync5 } from "node:fs";
+import { dirname as dirname11, resolve as resolve7 } from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 
 // src/node/spec.ts
-import { resolve as resolve4 } from "node:path";
+import { join as join14, resolve as resolve4, sep as sep2 } from "node:path";
 
 // ../claude-worker/src/session.ts
 import { spawn as spawn2 } from "child_process";
@@ -20754,7 +20758,7 @@ var HANDOFF_RULES = `## Handoff discipline
   relevant paths, branch name, and what you did or found. The next session has the
   thread, not your head.
 - \`mcp__relai__create_task\` only when a human explicitly asks you to file a **new**
-  piece of work. Say in the description that it is a proposal an orchestrator must
+  piece of work, or when you hold an order's planning task (see Factory orders below). Say in the description that it is a proposal an orchestrator must
   commit. Do not attach roundNumber or parentTaskId bookkeeping, and do not use it
   to chain reviewer/writer/tester/devops work.`;
 function specializationBlock(spec) {
@@ -20870,6 +20874,78 @@ Handle CI/CD, infrastructure, build/deploy configuration.
       throw new Error(`Unknown specialization "${spec}" \u2014 valid values: reviewer, architect, writer, tester, devops`);
   }
 }
+var ORDER_RULES = `## Factory orders
+
+An order is a feature request the system builds end to end. Its tasks carry
+\`metadata.orderId\` and \`metadata.orderRole\`. For a task with \`metadata.orderRole\`, the
+instructions below override your role rules and the branch rules above. Read the order with
+\`mcp__relai__get_order\` (id = \`metadata.orderId\`). The order branch is \`order/<orderId>\`.
+Find the default branch with \`git remote show origin\`.
+
+**orderRole "planning"** (you are the order's planner):
+1. Read the order's \`feature\` and \`acceptance\`, and read the repo enough to plan it. If the order
+   has no \`title\`, give it a short one (a few words) with \`mcp__relai__update_order\`.
+2. Create the branch and PR:
+   \`git fetch origin && git checkout -B order/<orderId> origin/<default>\`,
+   \`git commit --allow-empty -m "Start order <orderId>"\`, \`git push -u origin order/<orderId>\`,
+   then \`gh pr create --draft --base <default> --head order/<orderId> --title "<feature>" --body "Order <orderId>"\`.
+   Record both with \`mcp__relai__update_order\` (\`branch\`, \`prUrl\`).
+3. Build tasks: \`mcp__relai__create_task\` for each piece of work, with \`epicId\` = the order's
+   \`epicId\`, \`assignedTo: "@auto"\`, and
+   \`metadata: { orderId, orderRole: "build", branchName: "order/<orderId>" }\`. Set
+   \`specialization\` or \`domains\` only to values agents in \`mcp__relai__list_agents\` declare:
+   the router never hands out a task whose tag no agent matches. When the repo has \`writer\` agents, set
+   \`specialization: "writer"\` on build tasks, so they wait for a writer instead of going to a reviewer.
+   Never name a build task's assignee as the goal's reviewer; the API refuses it. Make them small
+   and independently testable so several agents can work at once. Use \`blockedBy\` only where
+   one task truly needs another's result. Each description is self-contained: what to change,
+   which files, how to test it, and the acceptance criteria.
+4. Gate tasks, blocked by every build task, \`assignedTo: "@auto"\`,
+   \`metadata: { orderId, orderRole: "gate" }\`:
+   - \`human_approval\` in acceptance: a task "Approve: <feature>" with \`verifyKind: "human_approval"\`.
+   - \`reviewer_agent\` in acceptance: a task "Review: <feature>" with \`verifyKind: "reviewer_agent"\`
+     and \`verifyReviewerId\` set to a reviewer from \`mcp__relai__list_agents\`.
+   - \`ci_passed\` gets no gate task: the merge task checks CI. Say so on the planning task's thread.
+5. One merge task, blocked by every gate task (or every build task when there are no gates),
+   \`assignedTo: "@auto"\`, \`metadata: { orderId, orderRole: "merge", prUrl }\`.
+6. Write the plan into the PR body so a reader of the PR sees how it will be built: the
+   feature, the acceptance gates, and a table of every task (id, title, role, blockedBy).
+   Write it to a file and run \`gh pr edit <prUrl> --body-file <file>\`. Post the same plan on
+   the planning task's thread and complete it.
+
+**orderRole "build"**:
+- \`git fetch origin && git checkout -B order/<orderId> origin/order/<orderId>\`, then implement,
+  test and commit. Do not create another branch or PR.
+- Push with \`git pull --rebase origin order/<orderId> && git push origin HEAD:order/<orderId>\`,
+  repeating up to 5 times if the push is rejected. Never force-push.
+- If you drop or change any part of what the goal asked for, even for a good reason, record each one
+  with \`mcp__relai__update_task_status\` metadata \`deviations: [{ "item": "<what the goal asked>",
+  "reason": "<why>" }]\` and say so in your handoff. The owner decides whether to accept it.
+- Hand off on the task's thread with the commit sha and what you tested, then complete.
+
+**orderRole "gate"**:
+- Check every build task in the order's Epic is completed, then post the PR link on the task's
+  thread, listing every \`metadata.deviations\` entry from the build tasks, and complete it. The gate decides from there: the owner approves a \`human_approval\`
+  gate on the dashboard and the named reviewer decides a \`reviewer_agent\` gate.
+- As the reviewer of an order, check each thing the goal asked for. Anything dropped or changed is
+  the owner's call, not yours: if it is recorded in \`metadata.deviations\`, mention it and judge
+  the rest; if it is not recorded, reject and name it so the builder records it. The owner decides
+  on deviations in the approval gate.
+
+**orderRole "merge"**:
+1. \`gh pr ready <prUrl>\`, then \`gh pr checks <prUrl> --watch --fail-fast\`.
+   Before merging, replace the PR body with a run report built from
+   \`mcp__relai__list_all_tasks\` filtered to the order's Epic: the feature, the workflow
+   (planning, build, gates, merge), each task with its assignee, status, and created and
+   completed times, the number of distinct agents that worked on it, the total elapsed time
+   from the planning task's creation, and the CI checks that ran. Use \`gh pr edit <prUrl> --body-file <file>\`.
+2. Every check passed: \`gh pr merge <prUrl> --squash --match-head-commit <head sha from
+   gh pr view --json headRefOid>\`. Then update the run report: mark the merge task completed with
+   the merge commit and time, and recompute the elapsed time to the merge, with
+   \`gh pr edit <prUrl> --body-file <file>\` (a merged PR still accepts an edit). Post the merge commit
+   on the thread, and complete.
+3. A check failed: fix it on \`order/<orderId>\` as a build task would, push, and go back to step 1.
+   After 3 failed rounds, block the task with \`blockedReason\` naming the failing checks.`;
 function buildPrompt(config) {
   return [
     BASE_TASK_LOOP(config.agentId, config.repoPath),
@@ -20878,7 +20954,9 @@ function buildPrompt(config) {
     "",
     SAME_TASK_RULES(config.maxTaskRounds),
     "",
-    HANDOFF_RULES
+    HANDOFF_RULES,
+    "",
+    ORDER_RULES
   ].join("\n");
 }
 
@@ -21020,7 +21098,7 @@ function mcpServerLaunch(here = fileURLToPath2(import.meta.url), exists = exists
   if (exists(bundled)) return { command: execPath, args: [bundled] };
   return { command: execPath, args: [mcpServerTsxCli(), mcpServerEntry()] };
 }
-function writeMcpConfig(config) {
+function writeMcpConfig(config, prefix = "claude-worker") {
   const { command, args } = mcpServerLaunch();
   const mcpConfig = {
     mcpServers: {
@@ -21036,7 +21114,7 @@ function writeMcpConfig(config) {
       }
     }
   };
-  const path3 = join12(tmpdir(), `claude-worker-${config.agentId}-${Date.now()}.json`);
+  const path3 = join12(tmpdir(), `${prefix}-${config.agentId}-${Date.now()}.json`);
   writeFileSync6(path3, JSON.stringify(mcpConfig), { mode: 384 });
   return path3;
 }
@@ -21045,7 +21123,7 @@ async function runClaudeSession(config) {
   const mcpConfigPath = writeMcpConfig(config);
   const taskIdsPromise = listSessionTaskIds(config, "[claude-worker]");
   try {
-    return await new Promise((resolve7, reject) => {
+    return await new Promise((resolve8, reject) => {
       const args = [
         "--print",
         "--mcp-config",
@@ -21125,7 +21203,7 @@ async function runClaudeSession(config) {
             const detail = (resultError || stderrOutput || "").trim();
             reject(new Error(`claude exited with ${signal ?? `code ${code}`}${detail ? `: ${detail}` : ""}`));
           } else {
-            resolve7(unique);
+            resolve8(unique);
           }
         };
         finish.then(settle, settle);
@@ -21205,7 +21283,7 @@ async function runCursorSession(config) {
   const args = cursorArgs(config.repoPath, buildPrompt(config));
   console.log(`[cursor-worker] Spawning: ${bin()} ${args.slice(0, 5).join(" ")} ...`);
   const taskIdsPromise = listSessionTaskIds(config, "[cursor-worker]");
-  return new Promise((resolve7, reject) => {
+  return new Promise((resolve8, reject) => {
     const proc = spawn3(bin(), args, { cwd: config.repoPath, env: process.env, stdio: ["ignore", "pipe", "pipe"] });
     console.log(`[cursor-worker] Process PID: ${proc.pid}`);
     const toolsUsed = [];
@@ -21244,7 +21322,7 @@ async function runCursorSession(config) {
           const detail = (resultError || stderrOutput).trim();
           reject(new Error(`cursor-agent exited with ${signal ?? `code ${code}`}${detail ? `: ${detail}` : ""}`));
         } else {
-          resolve7([...new Set(toolsUsed)]);
+          resolve8([...new Set(toolsUsed)]);
         }
       };
       finish.then(settle, settle);
@@ -21275,9 +21353,111 @@ var claudeAdapter = {
   classifyError: classifySessionError
 };
 
+// ../claude-worker/src/adapters/copilot.ts
+import { spawn as spawn4 } from "child_process";
+import { unlinkSync as unlinkSync2 } from "fs";
+var bin2 = () => process.env.COPILOT_BIN ?? "copilot";
+var POLICY_BLOCKS = [/access denied by policy/i, /third-party mcp servers are disabled/i];
+var QUOTA = [/premium request/i, /monthly (?:limit|allowance|quota)/i];
+function copilotArgs(repoPath, prompt, mcpConfigPath) {
+  return [
+    "-p",
+    prompt,
+    "--allow-all-tools",
+    "--output-format",
+    "json",
+    "--no-color",
+    "-C",
+    repoPath,
+    "--additional-mcp-config",
+    `@${mcpConfigPath}`,
+    "--disable-builtin-mcps"
+  ];
+}
+function readCopilotEvent(line) {
+  let event;
+  try {
+    event = JSON.parse(line);
+  } catch {
+    return {};
+  }
+  const type = typeof event.type === "string" ? event.type : "";
+  const data = event.data ?? {};
+  const message = typeof data.message === "string" ? data.message : "";
+  if (/^tool\..*start/.test(type) && typeof data.toolName === "string") return { tool: data.toolName };
+  if (type === "session.error") return { error: message || "copilot session error" };
+  if (type === "result" && typeof event.exitCode === "number" && event.exitCode !== 0) return { error: `copilot finished with exit code ${event.exitCode}` };
+  if (type === "session.warning" && POLICY_BLOCKS.some((re) => re.test(message))) return { error: message };
+  return {};
+}
+async function runCopilotSession(config) {
+  const mcpConfigPath = writeMcpConfig(config, "copilot-worker");
+  const args = copilotArgs(config.repoPath, buildPrompt(config), mcpConfigPath);
+  console.log(`[copilot-worker] Spawning: ${bin2()} -p <prompt> ${args.slice(2, 6).join(" ")} ...`);
+  return new Promise((resolve8, reject) => {
+    const proc = spawn4(bin2(), args, { cwd: config.repoPath, env: process.env, stdio: ["ignore", "pipe", "pipe"] });
+    console.log(`[copilot-worker] Process PID: ${proc.pid}`);
+    const toolsUsed = [];
+    let buffer = "";
+    let sessionError = "";
+    let stderrOutput = "";
+    proc.stdout.on("data", (chunk) => {
+      buffer += chunk.toString();
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+      for (const line of lines) {
+        const { tool, error } = readCopilotEvent(line);
+        if (tool) {
+          toolsUsed.push(tool);
+          process.stdout.write(`  \u2699  ${tool}
+`);
+        }
+        if (error) {
+          sessionError = error;
+          console.error(`[copilot-worker] Session failed: ${error}`);
+        }
+      }
+    });
+    proc.stderr.on("data", (chunk) => {
+      stderrOutput += chunk.toString();
+    });
+    proc.on("close", (code, signal) => {
+      try {
+        unlinkSync2(mcpConfigPath);
+      } catch {
+      }
+      console.log(`[copilot-worker] Done \u2014 tools used: ${toolsUsed.length ? [...new Set(toolsUsed)].join(", ") : "none"}`);
+      if (sessionError || signal || code !== 0 && code !== null) {
+        const detail = (sessionError || stderrOutput).trim();
+        reject(new Error(`copilot exited with ${signal ?? `code ${code}`}${detail ? `: ${detail}` : ""}`));
+      } else {
+        resolve8([...new Set(toolsUsed)]);
+      }
+    });
+    proc.on("error", (err) => {
+      try {
+        unlinkSync2(mcpConfigPath);
+      } catch {
+      }
+      reject(err);
+    });
+  });
+}
+var copilotAdapter = {
+  runtime: "copilot",
+  prepare() {
+  },
+  runSession: runCopilotSession,
+  classifyError: (text) => {
+    if (POLICY_BLOCKS.some((re) => re.test(text))) return "credentials";
+    if (QUOTA.some((re) => re.test(text))) return "quota";
+    return classifySessionError(text);
+  }
+};
+
 // ../claude-worker/src/adapters/index.ts
-var RUNTIMES3 = ["claude", "cursor"];
-var ADAPTERS = { claude: claudeAdapter, cursor: cursorAdapter };
+var RUNTIMES3 = ["claude", "cursor", "copilot"];
+var ADAPTERS = { claude: claudeAdapter, cursor: cursorAdapter, copilot: copilotAdapter };
 function getAdapter(runtime) {
   const adapter = ADAPTERS[runtime];
   if (!adapter) throw new Error(`no adapter for runtime "${runtime}"`);
@@ -21292,10 +21472,53 @@ var VALID_SPECIALIZATIONS = ["reviewer", "architect", "writer", "tester", "devop
 
 // src/node/spec.ts
 var DEFAULT_API2 = "https://api.pitboss.dev";
+var MAX_POOL_SIZE = 32;
 var NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/;
+var POOL_NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,59}$/;
 function inviteEnvKey(name) {
   return `PITBOSS_NODE_INVITE_${name.toUpperCase().replace(/[.-]/g, "_")}`;
 }
+var isWithin = (path3, dir) => path3 === dir || path3.startsWith(dir.endsWith(sep2) ? dir : dir + sep2);
+function poolMembers(pool) {
+  return Array.from({ length: pool.max }, (_, i) => {
+    const name = `${pool.pool}-${i + 1}`;
+    return { name, runtime: pool.runtime, worktree: join14(pool.worktreeRoot, name), specialization: pool.specialization };
+  });
+}
+var allAgents = (spec) => [...spec.agents, ...spec.pools.flatMap(poolMembers)];
+function runtimeOf(a, i) {
+  if (!RUNTIMES3.includes(a.runtime)) {
+    throw new Error(`agents[${i}]: runtime "${String(a.runtime)}" is not supported (have: ${RUNTIMES3.join(", ")})`);
+  }
+  return a.runtime;
+}
+function specializationOf(a, i) {
+  const specialization = a.specialization === void 0 ? "writer" : a.specialization;
+  if (!VALID_SPECIALIZATIONS.includes(specialization)) {
+    throw new Error(`agents[${i}]: specialization "${String(specialization)}" is not one of ${VALID_SPECIALIZATIONS.join(", ")}`);
+  }
+  return specialization;
+}
+function parsePool(a, i, specDir) {
+  if (a.name !== void 0 || a.worktree !== void 0) throw new Error(`agents[${i}] must have either name or pool, not both`);
+  if (typeof a.pool !== "string" || !POOL_NAME.test(a.pool)) throw new Error(`agents[${i}].pool must be letters, digits, '.', '_' or '-' (at most 60)`);
+  if (typeof a.base !== "string" || !a.base) throw new Error(`agents[${i}].base is required: the clone pool worktrees are created from`);
+  if (typeof a.worktreeRoot !== "string" || !a.worktreeRoot) throw new Error(`agents[${i}].worktreeRoot is required`);
+  const runtime = runtimeOf(a, i);
+  const specialization = specializationOf(a, i);
+  const max = a.max;
+  if (typeof max !== "number" || !Number.isInteger(max) || max < 1 || max > MAX_POOL_SIZE) {
+    throw new Error(`agents[${i}].max must be an integer from 1 to ${MAX_POOL_SIZE}`);
+  }
+  const min = a.min === void 0 ? 0 : a.min;
+  if (typeof min !== "number" || !Number.isInteger(min) || min < 0 || min > max) {
+    throw new Error(`agents[${i}].min must be an integer from 0 to max`);
+  }
+  const base2 = resolve4(specDir, a.base);
+  const worktreeRoot = resolve4(specDir, a.worktreeRoot);
+  if (isWithin(worktreeRoot, base2)) throw new Error(`agents[${i}].worktreeRoot ${worktreeRoot} is inside base ${base2}; pool worktrees never go inside your checkout`);
+  return { pool: a.pool, runtime, base: base2, worktreeRoot, specialization, min, max };
+}
 function parseSpec(text, specDir) {
   let raw;
   try {
@@ -21309,23 +21532,30 @@ function parseSpec(text, specDir) {
     throw new Error("api must be https (plain http only for localhost)");
   }
   if (!Array.isArray(body.agents) || body.agents.length === 0) throw new Error("spec needs at least one agent");
-  const agents = body.agents.map((entry, i) => {
+  const agents = [];
+  const pools = [];
+  body.agents.forEach((entry, i) => {
     const a = entry ?? {};
+    if (a.pool !== void 0) {
+      pools.push(parsePool(a, i, specDir));
+      return;
+    }
     if (typeof a.name !== "string" || !NAME.test(a.name)) throw new Error(`agents[${i}].name must be letters, digits, '.', '_' or '-'`);
     if (typeof a.worktree !== "string" || !a.worktree) throw new Error(`agents[${i}].worktree is required`);
-    if (!RUNTIMES3.includes(a.runtime)) {
-      throw new Error(`agents[${i}]: runtime "${String(a.runtime)}" is not supported (have: ${RUNTIMES3.join(", ")})`);
-    }
-    const specialization = a.specialization === void 0 ? "writer" : a.specialization;
-    if (!VALID_SPECIALIZATIONS.includes(specialization)) {
-      throw new Error(`agents[${i}]: specialization "${String(specialization)}" is not one of ${VALID_SPECIALIZATIONS.join(", ")}`);
-    }
-    return { name: a.name, runtime: a.runtime, worktree: resolve4(specDir, a.worktree), specialization };
+    const runtime = runtimeOf(a, i);
+    agents.push({ name: a.name, runtime, worktree: resolve4(specDir, a.worktree), specialization: specializationOf(a, i) });
   });
+  for (const p of pools) {
+    for (const a of agents) {
+      if (isWithin(p.worktreeRoot, a.worktree)) {
+        throw new Error(`pool "${p.pool}" worktreeRoot ${p.worktreeRoot} is inside agent "${a.name}"'s worktree`);
+      }
+    }
+  }
   const names = /* @__PURE__ */ new Set();
   const worktrees = /* @__PURE__ */ new Map();
   const envKeys = /* @__PURE__ */ new Map();
-  for (const a of agents) {
+  for (const a of allAgents({ api, agents, pools })) {
     if (names.has(a.name.toLowerCase())) throw new Error(`agent name "${a.name}" appears twice`);
     names.add(a.name.toLowerCase());
     const envKey = inviteEnvKey(a.name);
@@ -21336,17 +21566,17 @@ function parseSpec(text, specDir) {
     if (other) throw new Error(`agents "${other}" and "${a.name}" share the worktree ${a.worktree}; each needs its own`);
     worktrees.set(a.worktree, a.name);
   }
-  return { api: api.replace(/\/+$/, ""), agents };
+  return { api: api.replace(/\/+$/, ""), agents, pools };
 }
 
 // src/node/store.ts
 import { existsSync as existsSync8, mkdirSync as mkdirSync6, readdirSync as readdirSync2, readFileSync as readFileSync11, renameSync as renameSync4, rmSync as rmSync4, writeFileSync as writeFileSync7 } from "node:fs";
-import { dirname as dirname8, join as join14 } from "node:path";
+import { dirname as dirname8, join as join15 } from "node:path";
 import { randomBytes as randomBytes4 } from "node:crypto";
-var nodeDir = () => join14(configDir(), "node");
-var credsPath = (name) => join14(nodeDir(), "agents", `${name}.json`);
-var statePath2 = () => join14(nodeDir(), "state.json");
-var logPath = (name) => join14(nodeDir(), "logs", `${name}.log`);
+var nodeDir = () => join15(configDir(), "node");
+var credsPath = (name) => join15(nodeDir(), "agents", `${name}.json`);
+var statePath2 = () => join15(nodeDir(), "state.json");
+var logPath = (name) => join15(nodeDir(), "logs", `${name}.log`);
 function writePrivate(path3, value) {
   mkdirSync6(dirname8(path3), { recursive: true, mode: 448 });
   const tmp = `${path3}.relai-${randomBytes4(8).toString("hex")}`;
@@ -21364,7 +21594,7 @@ var removeCreds = (name) => {
   if (existsSync8(path3)) rmSync4(path3);
 };
 var listStoredAgentNames = () => {
-  const dir = join14(nodeDir(), "agents");
+  const dir = join15(nodeDir(), "agents");
   if (!existsSync8(dir)) return [];
   return readdirSync2(dir).filter((n) => n.endsWith(".json")).map((n) => n.slice(0, -".json".length)).sort();
 };
@@ -21577,14 +21807,45 @@ var Supervisor = class {
       failures: 0,
       startedMs: 0,
       timer: null,
-      state: { pid: null, status: "starting", restarts: 0, startedAt: null, lastExit: null, nextStartAt: null }
+      held: spec.onDemand === true,
+      state: { pid: null, status: spec.onDemand ? "stopped" : "starting", restarts: 0, startedAt: null, lastExit: null, nextStartAt: null }
     }));
   }
   opts;
   slots;
   stopping = false;
   start() {
-    for (const slot of this.slots) this.launch(slot);
+    for (const slot of this.slots) if (!slot.held) this.launch(slot);
+  }
+  isActive(name) {
+    return this.slot(name).held === false;
+  }
+  startAgent(name) {
+    const slot = this.slot(name);
+    if (!slot.held || this.stopping) return;
+    slot.held = false;
+    slot.failures = 0;
+    this.launch(slot);
+  }
+  async stopAgent(name) {
+    const slot = this.slot(name);
+    slot.held = true;
+    if (slot.timer) clearTimeout(slot.timer);
+    slot.timer = null;
+    const child = slot.child;
+    if (!child) {
+      slot.state = { ...slot.state, pid: null, status: "stopped", nextStartAt: null };
+      this.emit();
+      return;
+    }
+    const exited = new Promise((done) => child.on("exit", () => done()));
+    child.kill("SIGTERM");
+    await exited;
+  }
+  slot(name) {
+    const slot = this.slots.find((s) => s.spec.name === name);
+    if (!slot) throw new Error(`no agent named ${name}`);
+    return slot;
   }
   snapshot() {
     return Object.fromEntries(this.slots.map((s) => [s.spec.name, { ...s.state }]));
@@ -21634,8 +21895,9 @@ var Supervisor = class {
     slot.child = null;
     const at = (/* @__PURE__ */ new Date()).toISOString();
     const lastExit = { code, signal, at, ...error ? { error } : {} };
-    if (this.stopping) {
+    if (this.stopping || slot.held) {
       slot.state = { ...slot.state, pid: null, status: "stopped", lastExit, nextStartAt: null };
+      if (slot.held && !this.stopping) this.emit();
       return;
     }
     slot.failures = slot.startedMs && Date.now() - slot.startedMs >= this.opts.stableMs ? 1 : slot.failures + 1;
@@ -21658,27 +21920,27 @@ var Supervisor = class {
 
 // src/node/entries.ts
 import { existsSync as existsSync9 } from "node:fs";
-import { dirname as dirname9, join as join15, resolve as resolve5 } from "node:path";
+import { dirname as dirname9, join as join16, resolve as resolve5 } from "node:path";
 var MISSING_WORKER = "event-worker not found next to this CLI. Run node from a pitboss checkout, or set PITBOSS_EVENT_WORKER to packages/event-worker.";
 function checkoutWorker(dir) {
   return {
-    command: join15(dir, "node_modules", ".bin", "tsx"),
-    args: [join15(dir, "src", "index.ts")]
+    command: join16(dir, "node_modules", ".bin", "tsx"),
+    args: [join16(dir, "src", "index.ts")]
   };
 }
 function checkoutMcp(dir, execPath) {
   return {
     command: execPath,
     args: [
-      join15(dir, "node_modules", "tsx", "dist", "cli.mjs"),
-      join15(dir, "src", "index.ts")
+      join16(dir, "node_modules", "tsx", "dist", "cli.mjs"),
+      join16(dir, "src", "index.ts")
     ]
   };
 }
 function walkFor(here, packageName, exists) {
   for (let dir = dirname9(here); dirname9(dir) !== dir; dir = dirname9(dir)) {
-    const candidate = join15(dir, packageName);
-    if (exists(join15(candidate, "src", "index.ts"))) return candidate;
+    const candidate = join16(dir, packageName);
+    if (exists(join16(candidate, "src", "index.ts"))) return candidate;
   }
   return null;
 }
@@ -21690,10 +21952,10 @@ function resolveEventWorker(opts) {
   if (override) {
     const resolved = resolve5(override);
     if (resolved.endsWith(".js") && exists(resolved)) return { command: execPath, args: [resolved] };
-    if (exists(join15(resolved, "src", "index.ts"))) return checkoutWorker(resolved);
+    if (exists(join16(resolved, "src", "index.ts"))) return checkoutWorker(resolved);
     throw new Error(MISSING_WORKER);
   }
-  const bundled = join15(dirname9(opts.here), "event-worker.js");
+  const bundled = join16(dirname9(opts.here), "event-worker.js");
   if (exists(bundled)) return { command: execPath, args: [bundled] };
   const dir = walkFor(opts.here, "event-worker", exists);
   if (dir) return checkoutWorker(dir);
@@ -21702,7 +21964,7 @@ function resolveEventWorker(opts) {
 function resolveMcpServer(opts) {
   const execPath = opts.execPath ?? process.execPath;
   const exists = opts.exists ?? existsSync9;
-  const bundled = join15(dirname9(opts.here), "mcp.js");
+  const bundled = join16(dirname9(opts.here), "mcp.js");
   if (exists(bundled)) return { command: execPath, args: [bundled] };
   const dir = walkFor(opts.here, "mcp-server", exists);
   if (dir) return checkoutMcp(dir, execPath);
@@ -21722,7 +21984,19 @@ function describeState(state, alive = isAlive) {
     const lastExit = a.lastExit ? a.lastExit.signal ? `signal ${a.lastExit.signal}` : a.lastExit.error ?? `code ${a.lastExit.code}` : null;
     return { name, status, pid: a.pid, restarts: a.restarts, lastExit };
   });
-  return { supervised, agents };
+  const byName = new Map(agents.map((a) => [a.name, a]));
+  const pools = Object.entries(state.pools ?? {}).map(([name, p]) => ({
+    name,
+    members: p.members,
+    min: p.min,
+    max: p.max,
+    ready: p.ready,
+    checkedAt: p.checkedAt,
+    desiredMax: p.desiredMax ?? null,
+    error: p.error ?? null,
+    running: p.members.filter((m) => byName.get(m)?.status === "running").length
+  }));
+  return { supervised, agents, pools };
 }
 function orphanedWorkers(state, alive, inspect) {
   if (alive(state.supervisorPid)) return [];
@@ -21798,18 +22072,183 @@ function loadPruneTargets(names) {
   });
 }
 
+// src/node/pool.ts
+import { execFileSync as execFileSync6 } from "node:child_process";
+import { existsSync as existsSync10, lstatSync as lstatSync3, mkdirSync as mkdirSync7, realpathSync as realpathSync4 } from "node:fs";
+import { basename as basename2, dirname as dirname10, join as join17, resolve as resolve6 } from "node:path";
+var IDLE_STOP_MS = 10 * 6e4;
+var RECONCILE_MS = 15e3;
+var UNAVAILABLE_FOR_MS = 7 * 24 * 60 * 6e4 - 6e4;
+var REMARK_AFTER_MS = 24 * 60 * 6e4;
+function positiveMs(raw, fallback2) {
+  const n = Number(raw);
+  return raw && Number.isInteger(n) && n > 0 ? n : fallback2;
+}
+function poolTimings(env2 = process.env) {
+  return {
+    reconcileMs: positiveMs(env2.PITBOSS_POOL_RECONCILE_MS, RECONCILE_MS),
+    idleStopMs: positiveMs(env2.PITBOSS_POOL_IDLE_STOP_MS, IDLE_STOP_MS)
+  };
+}
+function effectiveBounds(spec, desired) {
+  if (!desired) return { min: spec.min, max: spec.max, desiredMax: null, capped: false };
+  const max = Math.min(desired.max, spec.max);
+  return { min: Math.min(desired.min, max), max, desiredMax: desired.max, capped: desired.max > spec.max };
+}
+function reconcilePool({ pending, members, min, max, idleStopMs }) {
+  const isIdle = (m) => m.assigned === 0 && m.inProgress === 0;
+  const running = members.filter((m) => m.running);
+  const stopped = members.filter((m) => !m.running);
+  let count = running.length;
+  const start = [];
+  const take = (m) => {
+    start.push(m.name);
+    count++;
+  };
+  for (const m of stopped) {
+    if (count >= max) break;
+    if (m.inProgress > 0 || m.readyAssigned > 0) take(m);
+  }
+  const spare = () => stopped.filter((m) => !start.includes(m.name)).sort((a, b) => Number(isIdle(b)) - Number(isIdle(a)));
+  let demand = pending - running.filter(isIdle).length;
+  for (const m of spare()) {
+    if (demand <= 0 || count >= max) break;
+    take(m);
+    demand--;
+  }
+  for (const m of spare()) {
+    if (count >= min || count >= max) break;
+    take(m);
+  }
+  if (start.length > 0) return { start, stop: [] };
+  const stop = [];
+  let surplus = running.filter(isIdle).length - pending;
+  const eligible = running.filter((m) => isIdle(m) && m.idleMs >= idleStopMs).sort((a, b) => b.idleMs - a.idleMs);
+  for (const m of eligible) {
+    if (surplus <= 0 || count <= min) break;
+    stop.push(m.name);
+    count--;
+    surplus--;
+  }
+  return { start, stop };
+}
+function summarizeTasks(ready, held, members) {
+  const nameOf = new Map(members.map((m) => [m.agentId, m.name]));
+  const counts = Object.fromEntries(
+    members.map((m) => [m.name, { assigned: 0, inProgress: 0, readyAssigned: 0 }])
+  );
+  const pending = ready.filter((t) => t.status === "pending" && t.autoAssign).length;
+  let readyAssigned = 0;
+  for (const t of ready) {
+    const name = t.status === "assigned" && t.assignedTo ? nameOf.get(t.assignedTo) : void 0;
+    if (!name) continue;
+    counts[name].readyAssigned++;
+    readyAssigned++;
+  }
+  for (const t of held) {
+    const name = t.assignedTo ? nameOf.get(t.assignedTo) : void 0;
+    if (!name) continue;
+    if (t.status === "assigned") counts[name].assigned++;
+    if (t.status === "in_progress") counts[name].inProgress++;
+  }
+  return { pending, ready: pending + readyAssigned, members: counts };
+}
+function poolRootProblem(root, protectedPaths) {
+  for (const p of protectedPaths) {
+    if (isWithin(root, p.path)) return `worktreeRoot ${root} is inside ${p.label} ${p.path}; pool worktrees never go inside a checkout`;
+  }
+  return null;
+}
+function memberPathProblem(s) {
+  if (s.symlink) return `${s.path} is a symlink; refusing to use it as a pool worktree`;
+  if (s.exists && s.commonDir !== s.baseCommonDir) return `${s.path} exists and is not a worktree of the pool's base clone`;
+  if (!s.exists && s.tracked) return `${s.path} is tracked by git; refusing to create a pool worktree there`;
+  return null;
+}
+function realpathAllowMissing(path3) {
+  const abs = resolve6(path3);
+  if (existsSync10(abs)) return realpathSync4.native(abs);
+  return join17(realpathAllowMissing(dirname10(abs)), basename2(abs));
+}
+function run2(cwd, args) {
+  try {
+    return execFileSync6("git", args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+  } catch (err) {
+    const stderr = err.stderr?.toString().trim();
+    throw new Error(`git ${args.join(" ")} in ${cwd} failed${stderr ? `: ${stderr}` : ""}`);
+  }
+}
+var commonDir = (cwd) => {
+  const dir = git(["rev-parse", "--path-format=absolute", "--git-common-dir"], cwd);
+  return dir ? realpathSync4.native(dir) : null;
+};
+function defaultBranch(cwd) {
+  const head = () => git(["symbolic-ref", "--short", "refs/remotes/origin/HEAD"], cwd);
+  let ref = head();
+  if (!ref) {
+    git(["remote", "set-head", "origin", "--auto"], cwd);
+    ref = head();
+  }
+  if (!ref || !ref.startsWith("origin/")) throw new Error(`${cwd}: cannot tell origin's default branch; run git remote set-head origin --auto`);
+  return ref.slice("origin/".length);
+}
+function ensurePoolWorktrees(pool, otherWorktrees = []) {
+  if (!existsSync10(pool.base)) throw new Error(`pool ${pool.pool}: base ${pool.base} does not exist`);
+  const baseTop = git(["rev-parse", "--show-toplevel"], pool.base);
+  const baseCommon = commonDir(pool.base);
+  if (!baseTop || !baseCommon) throw new Error(`pool ${pool.pool}: base ${pool.base} is not a git clone`);
+  const root = realpathAllowMissing(pool.worktreeRoot);
+  const rootProblem = poolRootProblem(root, [{ label: "base", path: realpathSync4.native(baseTop) }, ...otherWorktrees]);
+  if (rootProblem) throw new Error(`pool ${pool.pool}: ${rootProblem}`);
+  const members = poolMembers({ ...pool, worktreeRoot: root });
+  for (const m of members) {
+    let symlink = false;
+    try {
+      symlink = lstatSync3(m.worktree).isSymbolicLink();
+    } catch {
+      symlink = false;
+    }
+    const exists = !symlink && existsSync10(m.worktree);
+    const problem = memberPathProblem({
+      path: m.worktree,
+      symlink,
+      exists,
+      baseCommonDir: baseCommon,
+      commonDir: exists ? commonDir(m.worktree) : null,
+      tracked: !exists && !symlink && isTracked(m.worktree)
+    });
+    if (problem) throw new Error(`pool ${pool.pool}: ${problem}`);
+  }
+  const missing = members.filter((m) => !existsSync10(m.worktree));
+  if (missing.length > 0) {
+    mkdirSync7(root, { recursive: true });
+    run2(pool.base, ["fetch", "-q", "origin"]);
+    const branch = defaultBranch(pool.base);
+    run2(pool.base, ["worktree", "prune"]);
+    for (const m of missing) run2(pool.base, ["worktree", "add", "-q", "--detach", m.worktree, `origin/${branch}`]);
+  }
+  return members.map((m) => realpathSync4.native(m.worktree));
+}
+function resetWorktree(worktree) {
+  run2(worktree, ["fetch", "-q", "--prune", "origin"]);
+  const target = `origin/${defaultBranch(worktree)}`;
+  run2(worktree, ["checkout", "-q", "--detach", "--force", target]);
+  run2(worktree, ["reset", "-q", "--hard", target]);
+  run2(worktree, ["clean", "-fdq"]);
+}
+
 // src/commands/node.ts
 var HERE = fileURLToPath3(import.meta.url);
 function inspectProcess(pid) {
   try {
-    const out = execFileSync6("ps", ["-o", "pgid=,command=", "-p", String(pid)], { encoding: "utf-8" }).trim();
+    const out = execFileSync7("ps", ["-o", "pgid=,command=", "-p", String(pid)], { encoding: "utf-8" }).trim();
     const match = /^(\d+)\s+(.*)$/.exec(out);
     return match ? { pgid: Number(match[1]), command: match[2] } : null;
   } catch {
     return null;
   }
 }
-function childSpec(agent, creds, worker) {
+function childSpec(agent, creds, worker, onDemand = false) {
   const { ANTHROPIC_API_KEY: _key, ANTHROPIC_AUTH_TOKEN: _tok, ...inherited } = process.env;
   return {
     name: agent.name,
@@ -21817,6 +22256,7 @@ function childSpec(agent, creds, worker) {
     args: worker.args,
     cwd: agent.worktree,
     logPath: logPath(agent.name),
+    onDemand,
     env: {
       ...inherited,
       API_URL: creds.api,
@@ -21840,13 +22280,13 @@ function prepareAgent(agent, creds, mcp) {
       writeMergedJson(target, (existing) => mergeMcpServer(existing, name, entry), root);
       excludeIfUntracked(root, target);
     },
-    run(bin2, args, cwd) {
-      execFileSync6(bin2, args, { cwd, stdio: "ignore" });
+    run(bin3, args, cwd) {
+      execFileSync7(bin3, args, { cwd, stdio: "ignore" });
     }
   });
 }
 function spawnWorker(spec) {
-  mkdirSync7(dirname10(spec.logPath), { recursive: true, mode: 448 });
+  mkdirSync8(dirname11(spec.logPath), { recursive: true, mode: 448 });
   const log = openSync(spec.logPath, "a", 384);
   try {
     const child = spawnChild(spec.command, spec.args, { cwd: spec.cwd, env: spec.env, stdio: ["ignore", log, log], detached: true });
@@ -21865,19 +22305,138 @@ function spawnWorker(spec) {
     closeSync(log);
   }
 }
+async function fetchTasks(creds, query) {
+  const res = await getJson(`${creds.api}/tasks?repoId=${encodeURIComponent(creds.repoId)}&${query}`, creds.token);
+  if (res.status !== 200 || !Array.isArray(res.payload.data)) throw new Error(`GET /tasks?${query} returned HTTP ${res.status}`);
+  return res.payload.data;
+}
+async function fetchPoolSize(creds, name) {
+  const res = await getJson(`${creds.api}/repos/${encodeURIComponent(creds.repoId)}/pools`, creds.token);
+  if (res.status !== 200 || !Array.isArray(res.payload.data)) return void 0;
+  const row = res.payload.data.find((p) => p.name === name);
+  return row ? { min: row.min, max: row.max } : void 0;
+}
+async function setAvailable(creds, available) {
+  const body = available ? { until: null } : { until: new Date(Date.now() + UNAVAILABLE_FOR_MS).toISOString(), reason: POOL_STOPPED_REASON };
+  const res = await fetch(`${creds.api}/agents/${encodeURIComponent(creds.agentId)}/unavailable`, {
+    method: "PUT",
+    headers: { Authorization: `Bearer ${creds.token}`, "Content-Type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  if (!res.ok) throw new Error(`PUT /agents/${creds.agentId}/unavailable returned HTTP ${res.status}`);
+}
+async function reportScale(creds, event) {
+  const res = await fetch(`${creds.api}/agents/${encodeURIComponent(creds.agentId)}/pool-events`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${creds.token}`, "Content-Type": "application/json" },
+    body: JSON.stringify(event)
+  });
+  if (!res.ok) throw new Error(`POST /agents/${creds.agentId}/pool-events returned HTTP ${res.status}`);
+}
+function startPoolLoop(run3, sup, record) {
+  const { pool, members } = run3;
+  const { reconcileMs, idleStopMs } = poolTimings();
+  const lastBusy = /* @__PURE__ */ new Map();
+  const markedAt = /* @__PURE__ */ new Map();
+  const state = { members: members.map((m) => m.agent.name), min: pool.min, max: pool.max, ready: null, checkedAt: null };
+  const log = (line) => console.log(`${(/* @__PURE__ */ new Date()).toISOString()}  pool ${pool.pool}: ${line}`);
+  let busy = false;
+  const markStopped = async (member) => {
+    try {
+      await setAvailable(member.creds, false);
+      markedAt.set(member.agent.name, Date.now());
+    } catch (err) {
+      log(`could not mark ${member.agent.name} unavailable: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  };
+  const report = async (member, action, reason, ready) => {
+    const running = members.filter((m) => sup.isActive(m.agent.name)).length;
+    try {
+      await reportScale(member.creds, { pool: pool.pool, action, reason, ready, running, max: pool.max });
+    } catch (err) {
+      log(`could not report ${action} ${member.agent.name}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  };
+  const tick = async () => {
+    if (busy) return;
+    busy = true;
+    try {
+      for (const m of members) {
+        if (!sup.isActive(m.agent.name) && Date.now() - (markedAt.get(m.agent.name) ?? 0) >= REMARK_AFTER_MS) await markStopped(m);
+      }
+      const reader = members.find((m) => sup.isActive(m.agent.name)) ?? members[0];
+      const [ready, held] = await Promise.all([
+        fetchTasks(reader.creds, "ready=true"),
+        fetchTasks(reader.creds, "status=assigned,in_progress")
+      ]);
+      const summary = summarizeTasks(ready, held, members.map((m) => ({ name: m.agent.name, agentId: m.creds.agentId })));
+      const now = Date.now();
+      const views = members.map(({ agent }) => {
+        const counts = summary.members[agent.name];
+        if (counts.assigned + counts.inProgress > 0) lastBusy.set(agent.name, now);
+        return { name: agent.name, running: sup.isActive(agent.name), ...counts, idleMs: now - (lastBusy.get(agent.name) ?? now) };
+      });
+      const bounds = effectiveBounds(pool, await fetchPoolSize(reader.creds, pool.pool));
+      if (bounds.max !== state.max || bounds.min !== state.min) {
+        log(`size min ${bounds.min} max ${bounds.max}${bounds.capped ? ` (API asks for ${bounds.desiredMax}, capped at the ${pool.max} provisioned members)` : ""}`);
+      }
+      Object.assign(state, { min: bounds.min, max: bounds.max, desiredMax: bounds.desiredMax });
+      const decision = reconcilePool({ pending: summary.pending, members: views, min: bounds.min, max: bounds.max, idleStopMs });
+      for (const name of decision.start) {
+        const member = members.find((m) => m.agent.name === name);
+        try {
+          if (summary.members[name].inProgress === 0) resetWorktree(member.agent.worktree);
+          await setAvailable(member.creds, true);
+          markedAt.delete(name);
+        } catch (err) {
+          log(`not starting ${name}: ${err instanceof Error ? err.message : String(err)}`);
+          continue;
+        }
+        lastBusy.set(name, Date.now());
+        sup.startAgent(name);
+        log(`started ${name} (ready ${summary.ready})`);
+        await report(member, "started", `ready ${summary.ready}`, summary.ready);
+      }
+      for (const name of decision.stop) {
+        const member = members.find((m) => m.agent.name === name);
+        await sup.stopAgent(name);
+        await markStopped(member);
+        log(`stopped ${name} after ${Math.round(idleStopMs / 1e3)}s idle`);
+        await report(member, "stopped", `idle ${Math.round(idleStopMs / 1e3)}s`, summary.ready);
+      }
+      Object.assign(state, { ready: summary.ready, checkedAt: (/* @__PURE__ */ new Date()).toISOString(), error: void 0 });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (state.error !== message) log(message);
+      Object.assign(state, { checkedAt: (/* @__PURE__ */ new Date()).toISOString(), error: message });
+    } finally {
+      record(pool.pool, { ...state });
+      busy = false;
+    }
+  };
+  void tick();
+  const timer = setInterval(() => void tick(), reconcileMs);
+  return () => clearInterval(timer);
+}
 async function nodeUpCommand(specFile, opts = {}) {
   try {
-    const specPath = resolve6(specFile);
-    const specRealpath = realpathSync4.native(specPath);
-    const parsed = parseSpec(readFileSync12(specPath, "utf-8"), dirname10(specPath));
+    const specPath = resolve7(specFile);
+    const specRealpath = realpathSync5.native(specPath);
+    const parsed = parseSpec(readFileSync12(specPath, "utf-8"), dirname11(specPath));
     const previous = readState();
     if (previous && previous.supervisorPid !== process.pid && isAlive(previous.supervisorPid)) {
       throw new Error(`a node is already running (pid ${previous.supervisorPid}, ${previous.specPath}). Stop it first.`);
     }
     for (const a of parsed.agents) {
-      if (!existsSync10(a.worktree)) throw new Error(`${a.name}: worktree ${a.worktree} does not exist`);
+      if (!existsSync11(a.worktree)) throw new Error(`${a.name}: worktree ${a.worktree} does not exist`);
     }
-    const spec = { ...parsed, agents: parsed.agents.map((a) => ({ ...a, worktree: realpathSync4.native(a.worktree) })) };
+    const plain = parsed.agents.map((a) => ({ ...a, worktree: realpathSync5.native(a.worktree) }));
+    const pools = parsed.pools.map((pool) => {
+      const paths = ensurePoolWorktrees(pool, plain.map((a) => ({ label: `agent ${a.name}'s worktree`, path: a.worktree })));
+      return { pool, members: poolMembers(pool).map((m, i) => ({ ...m, worktree: paths[i] })) };
+    });
+    const spec = { ...parsed, agents: [...plain, ...pools.flatMap((p) => p.members)] };
+    const pooled = new Set(pools.flatMap((p) => p.members.map((m) => m.name)));
     const seen = /* @__PURE__ */ new Map();
     for (const a of spec.agents) {
       const other = seen.get(a.worktree);
@@ -21894,6 +22453,7 @@ async function nodeUpCommand(specFile, opts = {}) {
         }
       }
     }
+    const poolStates = {};
     writeState({ ...base2, agents: {} });
     logStoredOrphans(spec.agents.map((a) => a.name), specRealpath);
     const worker = resolveEventWorker({ here: HERE });
@@ -21904,13 +22464,13 @@ async function nodeUpCommand(specFile, opts = {}) {
     const mcp = resolveMcpServer({ here: HERE });
     for (const a of runnable) prepareAgent(a, creds.get(a.name), mcp);
     const last = /* @__PURE__ */ new Map();
-    const sup = new Supervisor(runnable.map((a) => childSpec(a, creds.get(a.name), worker)), {
+    const sup = new Supervisor(runnable.map((a) => childSpec(a, creds.get(a.name), worker, pooled.has(a.name))), {
       spawn: spawnWorker,
       baseMs: 1e3,
       maxMs: 6e4,
       stableMs: 6e4,
       onChange: (agents) => {
-        writeState({ ...base2, agents });
+        writeState({ ...base2, agents, pools: poolStates });
         for (const [name, s] of Object.entries(agents)) {
           const line = s.status === "running" ? `running pid ${s.pid}` : s.status === "backoff" ? `exited (${s.lastExit?.signal ?? s.lastExit?.error ?? `code ${s.lastExit?.code}`}), restart ${s.restarts} at ${s.nextStartAt}` : s.status;
           if (last.get(name) === line) continue;
@@ -21919,13 +22479,17 @@ async function nodeUpCommand(specFile, opts = {}) {
         }
       }
     });
+    const plainCount = runnable.filter((a) => !pooled.has(a.name)).length;
+    const poolNote = pools.length > 0 ? `, ${pools.length} pool(s)` : "";
     console.log(source_default.bold(`
-  pitboss node: ${runnable.length} agent(s)`) + source_default.dim(`  state ${statePath2()}
+  pitboss node: ${plainCount} agent(s)${poolNote}`) + source_default.dim(`  state ${statePath2()}
 `));
+    const stopLoops = [];
     let stopping = false;
     const shutdown = async () => {
       if (stopping) return;
       stopping = true;
+      for (const stopLoop of stopLoops) stopLoop();
       console.log(source_default.dim("\n  stopping agents\u2026"));
       await sup.stop();
       process.exit(0);
@@ -21934,6 +22498,18 @@ async function nodeUpCommand(specFile, opts = {}) {
     process.on("SIGTERM", shutdown);
     process.on("SIGHUP", shutdown);
     sup.start();
+    for (const { pool, members } of pools) {
+      const ready = members.filter((m) => creds.has(m.name)).map((agent) => ({ agent, creds: creds.get(agent.name) }));
+      if (ready.length === 0) {
+        console.log(source_default.yellow(`  ! pool ${pool.pool}: no member has credentials; it will not scale`));
+        continue;
+      }
+      poolStates[pool.pool] = { members: ready.map((m) => m.agent.name), min: pool.min, max: pool.max, ready: null, checkedAt: null };
+      stopLoops.push(startPoolLoop({ pool, members: ready }, sup, (name, state) => {
+        poolStates[name] = state;
+        writeState({ ...base2, agents: sup.snapshot(), pools: poolStates });
+      }));
+    }
   } catch (err) {
     console.error(source_default.red(`
   ${err instanceof Error ? err.message : String(err)}`));
@@ -21942,10 +22518,10 @@ async function nodeUpCommand(specFile, opts = {}) {
 }
 async function nodePruneCommand(specFile, opts = {}) {
   try {
-    const specPath = resolve6(specFile);
-    const specRealpath = realpathSync4.native(specPath);
-    const spec = parseSpec(readFileSync12(specPath, "utf-8"), dirname10(specPath));
-    const { orphans: names, unattributed } = classifyStored(spec.agents.map((a) => a.name), specRealpath);
+    const specPath = resolve7(specFile);
+    const specRealpath = realpathSync5.native(specPath);
+    const spec = parseSpec(readFileSync12(specPath, "utf-8"), dirname11(specPath));
+    const { orphans: names, unattributed } = classifyStored(allAgents(spec).map((a) => a.name), specRealpath);
     if (names.length === 0) {
       console.log("No stored credentials are missing from the spec.");
       if (unattributed.length > 0) console.log(`unattributed, not pruned: ${unattributed.join(", ")}`);
@@ -21989,9 +22565,9 @@ function nodeStatusCommand(opts) {
     console.log("No node has run on this machine.");
     return;
   }
-  const { supervised, agents } = describeState(state);
+  const { supervised, agents, pools } = describeState(state);
   if (opts.json) {
-    console.log(JSON.stringify({ supervisorPid: state.supervisorPid, supervised, specPath: state.specPath, agents }, null, 2));
+    console.log(JSON.stringify({ supervisorPid: state.supervisorPid, supervised, specPath: state.specPath, agents, pools }, null, 2));
     return;
   }
   console.log(`${supervised ? source_default.green("supervisor up") : source_default.red("supervisor down")}  pid ${state.supervisorPid}  ${source_default.dim(state.specPath)}`);
@@ -21999,6 +22575,10 @@ function nodeStatusCommand(opts) {
     const color = a.status === "running" ? source_default.green : a.status === "backoff" ? source_default.yellow : source_default.red;
     console.log(`  ${a.name.padEnd(16)} ${color(a.status.padEnd(12))} pid ${String(a.pid ?? "-").padEnd(7)} restarts ${a.restarts}${a.lastExit ? source_default.dim(`  last exit ${a.lastExit}`) : ""}`);
   }
+  for (const p of pools) {
+    const ready = p.ready === null ? "-" : String(p.ready);
+    console.log(`  pool ${p.name.padEnd(11)} running ${p.running}/${p.max} (min ${p.min})${p.desiredMax !== null && p.desiredMax > p.max ? source_default.yellow(` desired ${p.desiredMax}, capped`) : ""}  ready ${ready}  members ${p.members.join(", ")}${p.error ? source_default.red(`  ${p.error}`) : ""}`);
+  }
 }
 
 // src/index.ts
@@ -22018,7 +22598,7 @@ hook.command("cursor-stop").description("Cursor stop hook").option("--dir <path>
 hook.command("cursor-prompt").description("Cursor beforeSubmitPrompt hook").option("--dir <path>", "The agent's folder").action(hookCursorPromptCommand);
 program2.command("tasks").description("List tasks assigned to you (default: assigned + in_progress)").option("-a, --all", "Show all tasks in the project, not just yours").option("-s, --status <status>", "Filter by status (comma-separated: pending,assigned,in_progress,pending_verification,completed,blocked)").action(tasksCommand);
 var task = program2.command("task").description("Create or update a task");
-task.command("create").description("Create a new task").option("-t, --title <title>", "Task title").option("-d, --description <description>", "Task description").option("-p, --priority <priority>", "low|normal|high|urgent").option("--to <agent>", "Assign to an agent (id or name)").option("--domains <list>", "Comma-separated domain tags").option("--specialization <s>", "Required specialization").option("-v, --verify <cmd>", "Shell command that must exit 0 to gate the `completed` transition (API must set ALLOW_SHELL_VERIFY=1)").option("--verify-cwd <path>", "Working directory for --verify (defaults to API server cwd)").option("--verify-kind <kind>", "Verifier kind: shell|file_exists|thread_concluded|reviewer_agent|human_approval").option("--verify-path <path>", "Path that must exist (--verify-kind file_exists)").option("--verify-thread <id>", "Thread that must be concluded (--verify-kind thread_concluded)").option("--verify-reviewer <agent>", "Agent (id or name) who must approve (--verify-kind reviewer_agent)").option("--review-by <agent>", "Shorthand for --verify-kind reviewer_agent --verify-reviewer <agent>").action(taskCreateCommand);
+task.command("create").description("Create a new task").option("-t, --title <title>", "Task title").option("-d, --description <description>", "Task description").option("-p, --priority <priority>", "low|normal|high|urgent").option("--to <agent>", "Assign to an agent (id or name)").option("--domains <list>", "Comma-separated domain tags").option("--specialization <s>", "Required specialization").option("-v, --verify <cmd>", "Shell command that must exit 0 to gate the `completed` transition (API must set ALLOW_SHELL_VERIFY=1)").option("--verify-cwd <path>", "Working directory for --verify (defaults to API server cwd)").option("--verify-kind <kind>", "Verifier kind: shell|file_exists|thread_concluded|reviewer_agent|human_approval|ci_passed").option("--verify-path <path>", "Path that must exist (--verify-kind file_exists) or commit sha (--verify-kind ci_passed)").option("--verify-thread <id>", "Thread that must be concluded (--verify-kind thread_concluded)").option("--verify-reviewer <agent>", "Agent (id or name) who must approve (--verify-kind reviewer_agent)").option("--review-by <agent>", "Shorthand for --verify-kind reviewer_agent --verify-reviewer <agent>").action(taskCreateCommand);
 task.command("start <id>").description("Mark a task as in_progress").option("-n, --note <note>", "Optional note to attach").action((id, options) => taskUpdateCommand(id, "in_progress", options));
 task.command("done <id>").description("Mark a task as completed").option("-n, --note <note>", "Optional note to attach").action((id, options) => taskUpdateCommand(id, "completed", options));
 task.command("block <id>").description("Mark a task as blocked").option("-n, --note <note>", "Describe what's blocking you").action((id, options) => taskUpdateCommand(id, "blocked", options));