@synergenius/flow-weaver-pack-weaver 0.9.151 → 0.9.153

package/src/bot/capability-registry.ts

@@ -48,30 +48,28 @@ const CAP_ROLE_ORCHESTRATOR: CapabilityDefinition = {
 You DECOMPOSE and ASSIGN. You never write code or create files directly.
 
 Your job:
-1. Analyze the objective and understand the project scope
-2. Create a PROJECT BRIEF (a concise description of what we're building, how pieces connect, conventions to follow)
-3. Break the objective into focused subtasks using task_create. Set parentId to YOUR Task ID (provided in the prompt) on every subtask so they appear as children.
-4. ALWAYS set assignedProfile on every subtask to one of these three:
-   - "developer" → code writing, file creation, implementation
-   - "reviewer" → code review, quality checks, security audit
-   - "ops" → project setup, dependencies, config, infrastructure
-   NEVER set assignedProfile to "orchestrator". You are the orchestrator — assigning to yourself creates an infinite loop. Only "developer", "reviewer", or "ops".
-5. Set dependencies so tasks execute in the right order
-   Use the EXACT title of a previous subtask as the dependsOn value. The system resolves titles to real task IDs at execution time. Example: dependsOn: ["Setup: Initialize project structure"]
-6. Include the project brief in every subtask's description
-
-CRITICAL: You do NOT have write_file, patch_file, or run_shell. You cannot execute code — only plan and delegate to developer/reviewer/ops.
-
-### Project Brief Format
-Include this at the TOP of every subtask description:
-"PROJECT: [what we're building]. STRUCTURE: [file layout]. CONVENTIONS: [naming, patterns, exports]."
+1. Analyze the objective
+2. Break it into focused subtasks via task_create. Set parentId to "@self" on every subtask.
+3. ALWAYS set assignedProfile: "developer", "reviewer", or "ops".
+   NEVER set assignedProfile to "orchestrator" — assigning to yourself creates an infinite loop.
+4. Use the EXACT title of a previous subtask as dependsOn. The system resolves titles to real task IDs.
+5. Include a project brief in every subtask: "PROJECT: [what]. FILES: [exact paths from workspace root]. CONVENTIONS: [patterns]."
+
+CRITICAL: You do NOT have write_file, patch_file, or run_shell. Only plan and delegate.
+
+### Design Phase (MANDATORY)
+Your FIRST subtask MUST be a design task assigned to ops that creates a .design.md file in the project root. This is the single source of truth. It must contain:
+- Module map, TypeScript interfaces (copy-paste ready), export contracts (function signatures)
+- Dependency graph, conventions (naming, error handling, patterns)
+Every subsequent developer task MUST read .design.md before writing code.
 
 ### Subtask Quality
-Each subtask must be:
-- Focused (one file or one concern)
-- Self-contained (has enough context to execute independently)
-- Properly routed (assignedProfile is set)
-- Ordered (dependsOn reflects real dependencies)`,
+Each subtask: focused (one concern), self-contained, properly routed, ordered by dependsOn.
+
+### Example
+{ operation: "task_create", args: { title: "Design: Create project contract", parentId: "@self", assignedProfile: "ops", complexity: "complex", description: "Create todo-app/.design.md with module map, TypeScript interfaces, export contracts.", dependsOn: [] } }
+{ operation: "task_create", args: { title: "Setup project", parentId: "@self", assignedProfile: "ops", dependsOn: ["Design: Create project contract"] } }
+{ operation: "task_create", args: { title: "Write code", parentId: "@self", assignedProfile: "developer", dependsOn: ["Setup project"] } }`,
 };
 
 const CAP_ROLE_DEVELOPER: CapabilityDefinition = {
@@ -81,17 +79,28 @@ const CAP_ROLE_DEVELOPER: CapabilityDefinition = {
 You WRITE CODE. Execute the task directly using write_file, patch_file, and run_shell.
 
 Your job:
-1. Read the task description (including the project brief)
-2. Create a plan with CONCRETE file operations (write_file, patch_file, run_shell)
-3. Execute every step — produce actual files on disk
-4. Verify your work compiles and is correct
+1. Read .design.md in the project root to understand interfaces and contracts
+2. Read files created by previous tasks (your dependencies are done — their files are on disk)
+3. Write code that MATCHES the contracts in .design.md exactly — same types, same function signatures, same exports
+4. Verify your imports resolve to real exports in existing files
 
 You do NOT have task_create. You cannot create subtasks or delegate.
 If the task seems too large, do your best — the orchestrator already decomposed it for you.
 
+### File Paths
+All paths in write_file/patch_file are RELATIVE TO THE WORKSPACE ROOT. If the task says "inside todo-app/", your paths MUST start with todo-app/ (e.g., todo-app/src/cli.ts, NOT src/cli.ts).
+
+### Code Quality
+- Write COMPLETE, WORKING code. No TODOs, no placeholders, no empty function bodies, no "// implement later".
+- Every function must be fully implemented with real logic.
+- Use proper TypeScript types. Use strict mode patterns.
+- Export everything that other files will import.
+- Handle edge cases (empty input, file not found, invalid args).
+- Use ESM-compatible patterns: import.meta.url instead of __dirname, import.meta.filename instead of __filename. Use fileURLToPath(import.meta.url) for path resolution.
+
 ### Output Requirements
 Your plan MUST include at least one write_file, patch_file, or run_shell step.
-A plan with only "respond" steps is a FAILURE — you must produce artifacts.`,
+A plan with only read_file, list_files, or respond steps is a FAILURE — you must produce artifacts.`,
 };
 
 const CAP_ROLE_REVIEWER: CapabilityDefinition = {
@@ -117,10 +126,19 @@ const CAP_ROLE_OPS: CapabilityDefinition = {
 You SET UP infrastructure — package.json, tsconfig.json, directory structure, dependencies.
 
 Your job:
-1. Initialize project structure (create config files, directories)
-2. Install dependencies with run_shell
-3. Ensure the project builds and tests can run
+1. Create the project directory first: run_shell with mkdir -p <project>/src
+2. Write config files (package.json, tsconfig.json) using write_file
+3. Install dependencies with run_shell (npm install)
+4. Ensure the project structure is ready for developers
+
+### File Paths
+All paths are RELATIVE TO THE WORKSPACE ROOT. If the project is in a subfolder (e.g., todo-app/), ALL your paths must include that prefix: todo-app/package.json, todo-app/tsconfig.json, todo-app/src/.
 
+### Design Tasks
+When the task is a Design task, create a .design.md file with detailed TypeScript interfaces, module exports, and dependency graph. This file must contain copy-paste ready interface definitions that developers will implement exactly.
+
+### Output Requirements
+Your plan MUST include write_file and/or run_shell steps that create real files.
 You do NOT have task_create. You execute infrastructure tasks directly.`,
 };
 

package/src/bot/file-validator.ts

@@ -1,3 +1,6 @@
+import { execFile } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
 import { checkDesignQuality, type DesignReport } from './design-checker.js';
 import { fwValidate } from './fw-api.js';
 
@@ -17,6 +20,18 @@ export async function validateFiles(
 
   for (const file of files) {
     if (!file.endsWith('.ts')) continue;
+
+    // Only run FW validation on files that contain @flowWeaver annotations.
+    // Plain TypeScript files (like server.ts) should not be FW-validated.
+    const absFile = path.isAbsolute(file) ? file : path.resolve(projectDir, file);
+    let hasFwAnnotation = false;
+    try {
+      const content = fs.readFileSync(absFile, 'utf-8');
+      hasFwAnnotation = content.includes('@flowWeaver') || content.includes('@flow-weaver');
+    } catch { /* file read failed — skip FW validation */ }
+
+    if (!hasFwAnnotation) continue;
+
     try {
       const { valid, errors, warnings, ast } = await fwValidate(file);
 
@@ -39,3 +54,85 @@ export async function validateFiles(
 
   return results;
 }
+
+export interface TscValidationResult {
+  valid: boolean;
+  errors: string[];
+}
+
+/**
+ * Find the tsc binary: prefer the project's own node_modules/.bin/tsc,
+ * then walk up parent directories, then fall back to a bare 'tsc' (PATH lookup).
+ */
+function findTscBin(projectDir: string): string | null {
+  let dir = projectDir;
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    const candidate = path.join(dir, 'node_modules', '.bin', 'tsc');
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null; // caller will try bare 'tsc'
+}
+
+// Strip ANSI escape codes from tsc output
+function stripAnsi(str: string): string {
+  // eslint-disable-next-line no-control-regex
+  return str.replace(/\x1b\[[0-9;]*m/g, '');
+}
+
+export async function validateTypeScript(
+  projectDir: string,
+  opts?: { timeoutMs?: number },
+): Promise<TscValidationResult> {
+  const timeoutMs = opts?.timeoutMs ?? 30_000;
+
+  // Check for tsconfig.json
+  const tsconfigPath = path.join(projectDir, 'tsconfig.json');
+  if (!fs.existsSync(tsconfigPath)) {
+    return { valid: true, errors: [] };
+  }
+
+  const tscBin = findTscBin(projectDir) ?? 'tsc';
+
+  return new Promise<TscValidationResult>((resolve) => {
+    try {
+      const child = execFile(
+        tscBin,
+        ['--noEmit', '--pretty', 'false'],
+        { cwd: projectDir, timeout: timeoutMs, env: { ...process.env } },
+        (error, stdout, stderr) => {
+          if (!error) {
+            return resolve({ valid: true, errors: [] });
+          }
+
+          // If the process was killed (timeout) or spawn failed, graceful fallback
+          if (error.killed || (error as NodeJS.ErrnoException).code === 'ENOENT') {
+            return resolve({ valid: true, errors: [] });
+          }
+
+          // tsc exits with code 2 on type errors; parse stdout for error lines
+          const output = stripAnsi((stdout || '') + (stderr || ''));
+          const lines = output.split('\n').filter((l) => l.trim().length > 0);
+          if (lines.length === 0) {
+            return resolve({ valid: true, errors: [] });
+          }
+
+          // Strip absolute projectDir prefix so errors use relative paths
+          const cleaned = lines.map(l => l.replaceAll(projectDir + '/', ''));
+          return resolve({ valid: false, errors: cleaned });
+        },
+      );
+
+      // Extra safety: if the child can't even spawn
+      child.on('error', () => {
+        resolve({ valid: true, errors: [] });
+      });
+    } catch {
+      // execFile itself threw (e.g. bad args) — graceful fallback
+      resolve({ valid: true, errors: [] });
+    }
+  });
+}

package/src/bot/instance-manager.ts

@@ -1,6 +1,10 @@
 /**
- * InstanceManager — manages in-memory bot instances (workers) per profile.
- * Instances represent running workers that don't survive process restart.
+ * InstanceManager — manages a dynamic pool of generic worker slots.
+ *
+ * Workers are profile-agnostic: any worker can run any profile's task.
+ * The profile is loaded per-task at execution time, not per-worker.
+ *
+ * Worker naming: `worker-0`, `worker-1`, ... (no per-profile instances).
  */
 
 import type { BotProfile, BotInstance } from './profile-types.js';
@@ -8,7 +12,61 @@ import type { BotProfile, BotInstance } from './profile-types.js';
 export class InstanceManager {
   private instances = new Map<string, BotInstance>();
 
-  /** Spawn a new instance for the given profile. Throws if maxInstances reached. */
+  // -----------------------------------------------------------------------
+  // Worker pool API (new)
+  // -----------------------------------------------------------------------
+
+  /** Spawn a single generic worker slot at the given index. */
+  spawnWorker(index: number): BotInstance {
+    const instanceId = `worker-${index}`;
+    if (this.instances.has(instanceId)) {
+      throw new Error(`Worker already exists: ${instanceId}`);
+    }
+
+    const instance: BotInstance = {
+      instanceId,
+      profileId: '',  // No profile until a task is assigned
+      index,
+      status: 'idle',
+      tokensUsed: 0,
+      cost: 0,
+      tasksCompleted: 0,
+      tasksFailed: 0,
+    };
+
+    this.instances.set(instanceId, instance);
+    return { ...instance };
+  }
+
+  /** Spawn a pool of N generic workers (worker-0 through worker-N-1). */
+  spawnPool(size: number): BotInstance[] {
+    const spawned: BotInstance[] = [];
+    for (let i = 0; i < size; i++) {
+      spawned.push(this.spawnWorker(i));
+    }
+    return spawned;
+  }
+
+  /** Find any idle worker (profile-agnostic). Returns a copy or null. */
+  findIdleWorker(): BotInstance | null {
+    for (const inst of this.instances.values()) {
+      if (inst.status === 'idle') return { ...inst };
+    }
+    return null;
+  }
+
+  /** Return all idle workers. */
+  findIdleWorkers(): BotInstance[] {
+    return [...this.instances.values()]
+      .filter((i) => i.status === 'idle')
+      .map((i) => ({ ...i }));
+  }
+
+  // -----------------------------------------------------------------------
+  // Legacy per-profile API (kept for backward compat, used by tests)
+  // -----------------------------------------------------------------------
+
+  /** @deprecated Use spawnWorker/spawnPool instead. Spawn a profile-bound instance. */
   spawn(profile: BotProfile): BotInstance {
     const existing = this.listByProfile(profile.id);
     if (existing.length >= profile.maxInstances) {
@@ -36,6 +94,10 @@ export class InstanceManager {
     return { ...instance };
   }
 
+  // -----------------------------------------------------------------------
+  // Shared API
+  // -----------------------------------------------------------------------
+
   /** Get instance by ID (returns a copy), or null if not found. */
   get(instanceId: string): BotInstance | null {
     const inst = this.instances.get(instanceId);
@@ -61,17 +123,23 @@ export class InstanceManager {
       .map((i) => ({ ...i }));
   }
 
-  /** Mark an instance as executing a specific task/run. */
-  markExecuting(instanceId: string, taskId: string, runId: string): void {
+  /**
+   * Mark a worker as executing a specific task/run.
+   * @param profileId — the profile being loaded for this task execution.
+   */
+  markExecuting(instanceId: string, taskId: string, runId: string, profileId?: string): void {
     const inst = this.instances.get(instanceId);
     if (!inst) throw new Error(`Instance not found: ${instanceId}`);
     inst.status = 'executing';
     inst.currentTaskId = taskId;
     inst.currentRunId = runId;
     inst.startedAt = new Date().toISOString();
+    if (profileId !== undefined) {
+      inst.profileId = profileId;
+    }
   }
 
-  /** Mark an instance as idle after task completion/failure. */
+  /** Mark a worker as idle after task completion/failure. Clears profile association. */
   markIdle(instanceId: string, success: boolean): void {
     const inst = this.instances.get(instanceId);
     if (!inst) throw new Error(`Instance not found: ${instanceId}`);
@@ -79,6 +147,8 @@ export class InstanceManager {
     inst.currentTaskId = undefined;
     inst.currentRunId = undefined;
     inst.startedAt = undefined;
+    // Clear profile — worker is generic again
+    inst.profileId = '';
     if (success) {
       inst.tasksCompleted++;
     } else {
@@ -104,7 +174,7 @@ export class InstanceManager {
     this.instances.clear();
   }
 
-  /** Scale instances for a profile to the target count. Clamps to [0, maxInstances]. */
+  /** @deprecated No longer needed in pool model. Kept for backward compat. */
   scaleTo(profile: BotProfile, target: number): void {
     const clamped = Math.max(0, Math.min(target, profile.maxInstances));
     const current = this.listByProfile(profile.id);

package/src/bot/orchestrator.ts

@@ -1,8 +1,12 @@
 /**
- * Orchestrator — the routing brain that decides which tasks go to which bot instances.
+ * Orchestrator — the routing brain that decides which tasks go to which workers.
  *
- * Pure routing logic: no side-effects beyond decision logging.
- * Fast-path cascade: exact-match → single-eligible → ai-routed → round-robin.
+ * In the worker pool model, workers are generic slots. The orchestrator:
+ * 1. Finds the profile for each task (via assignedProfile).
+ * 2. Assigns the task to any idle worker.
+ *
+ * Simplified cascade: exact-match profile → any idle worker.
+ * No more per-profile instance matching or scale-up actions.
  */
 
 import type {
@@ -15,7 +19,6 @@ import type {
 
 type Task = OrchestratorInput['pendingTasks'][number];
 type Assignment = OrchestratorOutput['assignments'][number];
-type ScaleAction = OrchestratorOutput['scaleActions'][number];
 
 // ---------------------------------------------------------------------------
 // AI Router types
@@ -50,11 +53,10 @@ export class Orchestrator {
 
   async route(input: OrchestratorInput): Promise<OrchestratorOutput> {
     const assignments: Assignment[] = [];
-    const scaleActions: ScaleAction[] = [];
     const skippedTasks: OrchestratorOutput['skippedTasks'] = [];
 
-    // Track instances claimed during this routing cycle to avoid double-assignment.
-    const claimedInstanceIds = new Set<string>();
+    // Track workers claimed during this routing cycle to avoid double-assignment.
+    const claimedWorkerIds = new Set<string>();
 
     // Sort tasks by priority DESC (higher number = higher priority).
     const sorted = [...input.pendingTasks].sort((a, b) => b.priority - a.priority);
@@ -66,50 +68,43 @@ export class Orchestrator {
         continue;
       }
 
-      const eligible = this._findEligible(task, input.profiles);
-
-      if (eligible.length === 0) {
+      // Resolve profile for this task (includes routing method)
+      const resolution = await this._resolveProfile(task, input.profiles);
+      if (!resolution) {
         skippedTasks.push({ taskId: task.id, reason: 'no-eligible-profile' });
         continue;
       }
 
-      const result = await this._selectInstance(task, eligible, input.instances, claimedInstanceIds);
-
-      if (result) {
-        claimedInstanceIds.add(result.instanceId);
-        assignments.push({
-          taskId: task.id,
-          profileId: result.profileId,
-          instanceId: result.instanceId,
-          reason: result.reason,
-          method: result.method,
-          confidence: result.confidence,
-        });
-        this._recordDecision(task, result, eligible);
-      } else {
-        // No idle instance available — request scale-up if possible.
-        const scaleProfile = eligible[0];
-        const currentCount = input.instances.filter(
-          (i) => i.profileId === scaleProfile.id,
-        ).length;
-
-        if (currentCount < scaleProfile.maxInstances) {
-          // Only add one scale-up action per profile.
-          if (!scaleActions.some((sa) => sa.profileId === scaleProfile.id)) {
-            scaleActions.push({
-              profileId: scaleProfile.id,
-              action: 'scale-up',
-              targetInstances: currentCount + 1,
-              reason: `idle instances exhausted for profile ${scaleProfile.id}`,
-            });
-          }
-        }
-
-        skippedTasks.push({ taskId: task.id, reason: 'no-idle-instance' });
+      // Find any idle worker
+      const idleWorker = this._findIdleWorker(input.instances, claimedWorkerIds);
+      if (!idleWorker) {
+        skippedTasks.push({ taskId: task.id, reason: 'no-idle-worker' });
+        continue;
       }
+
+      claimedWorkerIds.add(idleWorker.instanceId);
+
+      const reason = `${resolution.method}: ${resolution.profileId} → ${idleWorker.instanceId}`;
+      assignments.push({
+        taskId: task.id,
+        profileId: resolution.profileId,
+        instanceId: idleWorker.instanceId,
+        reason,
+        method: resolution.method,
+        confidence: resolution.confidence,
+      });
+
+      this._recordDecision(task, {
+        profileId: resolution.profileId,
+        instanceId: idleWorker.instanceId,
+        method: resolution.method,
+        reason,
+        confidence: resolution.confidence,
+      }, input.profiles.filter(p => p.id === resolution.profileId));
     }
 
-    return { assignments, scaleActions, skippedTasks };
+    // No scale actions in pool model — pool size is fixed at maxConcurrent
+    return { assignments, scaleActions: [], skippedTasks };
   }
 
   getDecisionLog(limit?: number): OrchestratorDecision[] {
@@ -126,106 +121,48 @@ export class Orchestrator {
   // Internal
   // ---------------------------------------------------------------------------
 
-  /** Find profiles eligible for a task. */
-  private _findEligible(task: Task, profiles: BotProfile[]): BotProfile[] {
+  /** Resolve which profileId should handle this task, including routing method. */
+  private async _resolveProfile(
+    task: Task,
+    profiles: BotProfile[],
+  ): Promise<{ profileId: string; method: OrchestratorDecision['method']; confidence?: number } | null> {
+    // Exact match: task has assignedProfile
     if (task.assignedProfile) {
-      const match = profiles.filter(p => p.id === task.assignedProfile);
-      if (match.length > 0) return match;
-      // Assigned profile doesn't exist — return empty to skip this task
-      // rather than falling through to all profiles (silent mis-routing).
+      const match = profiles.find(p => p.id === task.assignedProfile);
+      if (match) return { profileId: match.id, method: 'exact-match' };
       console.warn(
         `[orchestrator] Task "${task.id}" assigned to profile "${task.assignedProfile}" which does not exist — skipping`,
       );
-      return [];
+      return null;
     }
-    return profiles;
-  }
 
-  /** Select the best instance for a task from eligible profiles. */
-  private async _selectInstance(
-    task: Task,
-    eligible: BotProfile[],
-    instances: BotInstance[],
-    claimed: Set<string>,
-  ): Promise<{ profileId: string; instanceId: string; method: OrchestratorDecision['method']; reason: string; confidence?: number } | null> {
-    // Determine routing method
-    let method = this._routingMethod(task, eligible);
-
-    if (eligible.length === 1) {
-      const profile = eligible[0];
-      const idle = instances.find(
-        (i) => i.profileId === profile.id && i.status === 'idle' && !claimed.has(i.instanceId),
-      );
-      if (!idle) return null;
-      return {
-        profileId: profile.id,
-        instanceId: idle.instanceId,
-        method,
-        reason: `${method}: ${profile.id}`,
-      };
+    // Single eligible profile
+    if (profiles.length === 1) {
+      return { profileId: profiles[0].id, method: 'single-eligible' };
     }
 
-    // AI routing: when multiple eligible profiles and AI router is provided
-    if (this._aiRouter && eligible.length > 1) {
+    // Multiple eligible profiles — try AI routing
+    if (this._aiRouter && profiles.length > 1) {
       try {
-        const aiResult = await this._aiRouter.route(task, eligible);
-        const aiProfile = eligible.find((p) => p.id === aiResult.profileId);
+        const aiResult = await this._aiRouter.route(task, profiles);
+        const aiProfile = profiles.find(p => p.id === aiResult.profileId);
         if (aiProfile) {
-          const idle = instances.find(
-            (i) => i.profileId === aiProfile.id && i.status === 'idle' && !claimed.has(i.instanceId),
-          );
-          if (idle) {
-            return {
-              profileId: aiProfile.id,
-              instanceId: idle.instanceId,
-              method: 'ai-routed',
-              reason: `ai-routed: ${aiProfile.id} — ${aiResult.reason}`,
-              confidence: aiResult.confidence,
-            };
-          }
-          // AI chose a profile but no idle instance — fall through to round-robin
+          return { profileId: aiProfile.id, method: 'ai-routed', confidence: aiResult.confidence };
         }
-        // AI returned unknown profile — fall through to round-robin
       } catch {
         // AI call failed — fall through to round-robin
       }
     }
 
-    // Round-robin: pick profile with most idle instances
-    method = 'round-robin';
-    let bestProfile: BotProfile | null = null;
-    let bestIdleCount = -1;
-    let bestInstance: BotInstance | null = null;
-
-    for (const profile of eligible) {
-      const idleInstances = instances.filter(
-        (i) => i.profileId === profile.id && i.status === 'idle' && !claimed.has(i.instanceId),
-      );
-      if (idleInstances.length > bestIdleCount) {
-        bestIdleCount = idleInstances.length;
-        bestProfile = profile;
-        bestInstance = idleInstances[0] ?? null;
-      }
-    }
-
-    if (!bestProfile || !bestInstance) return null;
-
-    return {
-      profileId: bestProfile.id,
-      instanceId: bestInstance.instanceId,
-      method,
-      reason: `${method}: ${bestProfile.id}`,
-    };
+    // Fallback: round-robin (first profile)
+    return profiles.length > 0 ? { profileId: profiles[0].id, method: 'round-robin' } : null;
   }
 
-  /** Determine which routing method was used. */
-  private _routingMethod(
-    task: Task,
-    eligible: BotProfile[],
-  ): OrchestratorDecision['method'] {
-    if (task.assignedProfile) return 'exact-match';
-    if (eligible.length === 1) return 'single-eligible';
-    return 'round-robin';
+  /** Find any idle worker that hasn't been claimed this cycle. */
+  private _findIdleWorker(instances: BotInstance[], claimed: Set<string>): BotInstance | null {
+    return instances.find(
+      (i) => i.status === 'idle' && !claimed.has(i.instanceId),
+    ) ?? null;
   }
 
   /** Record a decision in the log. */