feat: add mock engine and --engine CLI flag for zero-cost E2E testing

Mock engine simulates agent work (file creation, git commit, RETRO_JSON output)
without calling any LLM. Also fixes sprintNumber not being passed to agent config,
which prevented retro comments from being submitted.

Author: recuu-pfeg

src/cli.ts

@@ -15,6 +15,7 @@
  */
 
 import { AgentRunner, type AgentRunnerOptions } from "./runner.js";
+import type { AgentType } from "./types.js";
 import {
   createApiClient,
   type Task,
@@ -49,6 +50,7 @@ interface CliArgs {
   noDocker: boolean;
   wsPort: number;
   debug: boolean;
+  engine: AgentType;
 }
 
 function printUsage(): void {
@@ -72,6 +74,7 @@ Options:
   --model <model>       AI model for manager chat (default: claude-sonnet-4-20250514)
   --llm-base-url <url>  OpenAI-compatible API base URL (or LLM_BASE_URL env)
   --llm-api-key <key>   LLM provider API key (or LLM_API_KEY env)
+  --engine <type>       Agent engine: claude, codex, gemini, mock, custom (default: claude)
   --no-docker           Disable Docker isolation (run agents directly on host)
   --ws-port <port>      WebSocket server port for direct chat (default: 4000, 0=auto)
   --push                Push the sprint tag to origin (sprint complete only)
@@ -139,6 +142,7 @@ function parseArgs(argv: string[]): CliArgs {
     noDocker: args.includes("--no-docker"),
     wsPort: parseInt(getFlag("--ws-port") ?? "4000", 10),
     debug: args.includes("--debug") || process.env.DEBUG === "1",
+    engine: (getFlag("--engine") ?? "claude") as AgentType,
   };
 }
 
@@ -532,14 +536,15 @@ async function runLoop(cliArgs: CliArgs, runner: AgentRunner): Promise<void> {
 
       const agentConfig = {
         name: `${cliArgs.agentName}-${task.id.slice(0, 8)}`,
-        type: "claude" as const,
+        type: cliArgs.engine,
         taskId: task.id,
         workingDir: taskWorkingDir,
         branch: cliArgs.baseBranch,
         apiKey: cliArgs.apiKey,
         apiUrl: cliArgs.apiUrl,
         prompt,
         parentAgent: cliArgs.agentName,
+        sprintNumber: sprintData?.sprint.number,
         ...(Object.keys(secrets).length > 0 ? { secrets } : {}),
       };
 

src/command-builder.ts

@@ -5,6 +5,36 @@ export interface CommandSpec {
   args: string[];
 }
 
+/**
+ * Build a mock agent command that simulates work without calling an LLM.
+ * Creates a small file, commits it, and outputs a retro comment.
+ * Token cost: zero.
+ */
+function buildMockCommand(config: AgentConfig): CommandSpec {
+  const taskId = config.taskId.slice(0, 8);
+  const name = config.name;
+  const script = `
+echo "[mock] Agent ${name} starting task ${taskId}..."
+sleep 2
+echo "[mock] Analyzing task requirements..."
+sleep 1
+echo "[mock] Implementing changes..."
+mkdir -p .mock-output
+echo "Mock output for task ${taskId} by ${name} at $(date -u +%Y-%m-%dT%H:%M:%SZ)" > .mock-output/${taskId}.txt
+git add .mock-output/${taskId}.txt 2>/dev/null
+git commit -m "mock: simulated work for task ${taskId}" --allow-empty 2>/dev/null || true
+echo "[mock] Changes committed."
+sleep 1
+echo "[mock] Task complete."
+echo 'RETRO_JSON:{"went_well":"Mock agent completed successfully","to_improve":"This was a simulated run","suggested_tasks":[]}'
+`.trim();
+
+  return {
+    cmd: "bash",
+    args: ["-c", script],
+  };
+}
+
 /**
  * Build the command and args for a given agent config.
  * If commandTemplate is set (from provider config), it takes precedence.
@@ -94,6 +124,9 @@ export function buildCommand(config: AgentConfig): CommandSpec {
         ],
       };
 
+    case "mock":
+      return buildMockCommand(config);
+
     case "custom":
       if (!config.command) {
         throw new Error("Custom agent type requires a command");

src/types.ts

@@ -1,4 +1,4 @@
-export type AgentType = "claude" | "cursor" | "codex" | "gemini" | "custom";
+export type AgentType = "claude" | "cursor" | "codex" | "gemini" | "mock" | "custom";
 
 export interface AgentConfig {
   /** Agent display name */