feat(cli): add --agent-timeout flag for execution time limit (#1242)

* feat(cli): add --agent-timeout flag for execution time limit

Adds --agent-timeout flag that sets a maximum execution time (in minutes)
for the agent command. When the timeout is reached, the container is
gracefully stopped and AWF exits with code 124 (matching coreutils
timeout convention). This helps large projects like nushell, Dapper,
and Polly that need more than 20 minutes for builds/tests.

Fixes #948

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* test: add unit tests for agent timeout in runAgentCommand

Cover the timeout branch (exit code 124) and normal completion
with timeout set to fix coverage regression.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* test: add parseAgentTimeout tests to fix coverage regression

Extract inline timeout validation into exported parseAgentTimeout()
function and add 7 unit tests covering valid integers, zero, negative,
non-numeric, empty string, and large values.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: resolve rebase conflicts and remove duplicate --tty flag

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* test: extract applyAgentTimeout for testable coverage

Move agent timeout validation from inline action handler to a
standalone exported function, enabling direct unit test coverage
for all branches (undefined, valid, invalid paths).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* test: add formatItem tests to fix coverage regression

Add unit tests for the formatItem help formatter function to offset
the minor branch coverage regression (-0.01%) from the agent timeout
feature. Tests cover all three branches: term fits with description,
term wraps to next line, and term without description.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: clear timeout timer and use stricter validation

- Clear setTimeout when docker wait wins the race to prevent event
  loop hang
- Use regex validation (^[1-9]\d*$) instead of parseInt to reject
  values like "30m" or "1.5" that parseInt would silently accept
- Add tests for stricter validation edge cases

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: Mossaka

.specify/progress.txt

@@ -1 +1,4 @@
 2026-03-05: Task 002 - Fix minimatch ReDoS vulnerability. Ran `npm audit fix` to update minimatch from 10.2.1 to 10.2.4 and ajv to patched version. Build, tests (821 passed), and lint all pass. npm audit shows 0 vulnerabilities. Branch: fix/002-minimatch-redos-vuln.
+PRIORITY: PR #1242 (task 025 - agent timeout) needs immediate attention. Has merge conflicts AND 3 Copilot review comments to address: (1) setTimeout not cleared/unrefed when docker wait completes normally - memory/timer leak, (2) parseInt accepts floats/negatives but flag is documented as 'positive integer' - needs stricter validation, (3) Missing test coverage for new timeout behavior in docker-manager.test.ts. Rebase onto main, resolve conflicts, fix all 3 review issues, then push.
+PRIORITY: PR #1244 (task 055 - secure_getenv bypass) has integration test failures: Test Chroot Package Managers and agent smoke test. Investigate and fix.
+PRIORITY: PR #1245 (task 103 - predownload images) has merge conflicts. Rebase onto main, resolve conflicts, push.

docs/usage.md

@@ -21,6 +21,7 @@ Options:
                                comma-separated, supports # comments)
   --log-level <level>          Log level: debug, info, warn, error (default: info)
   -k, --keep-containers        Keep containers running after command exits (default: false)
+  --agent-timeout <minutes>    Maximum time in minutes for the agent command to run (default: no limit)
   --tty                        Allocate a pseudo-TTY for the container (required for interactive
                                tools like Claude Code) (default: false)
   --work-dir <dir>             Working directory for temporary files

src/cli-workflow.test.ts

@@ -63,6 +63,52 @@ describe('runMainWorkflow', () => {
     expect(logger.warn).not.toHaveBeenCalled();
   });
 
+  it('passes agentTimeout to runAgentCommand', async () => {
+    const configWithTimeout: WrapperConfig = {
+      ...baseConfig,
+      agentTimeout: 30,
+    };
+    const dependencies: WorkflowDependencies = {
+      ensureFirewallNetwork: jest.fn().mockResolvedValue({ squidIp: '172.30.0.10' }),
+      setupHostIptables: jest.fn().mockResolvedValue(undefined),
+      writeConfigs: jest.fn().mockResolvedValue(undefined),
+      startContainers: jest.fn().mockResolvedValue(undefined),
+      runAgentCommand: jest.fn().mockResolvedValue({ exitCode: 0 }),
+    };
+    const performCleanup = jest.fn().mockResolvedValue(undefined);
+    const logger = createLogger();
+
+    await runMainWorkflow(configWithTimeout, dependencies, { logger, performCleanup });
+
+    expect(dependencies.runAgentCommand).toHaveBeenCalledWith(
+      configWithTimeout.workDir,
+      configWithTimeout.allowedDomains,
+      undefined,
+      30
+    );
+  });
+
+  it('passes undefined agentTimeout when not set', async () => {
+    const dependencies: WorkflowDependencies = {
+      ensureFirewallNetwork: jest.fn().mockResolvedValue({ squidIp: '172.30.0.10' }),
+      setupHostIptables: jest.fn().mockResolvedValue(undefined),
+      writeConfigs: jest.fn().mockResolvedValue(undefined),
+      startContainers: jest.fn().mockResolvedValue(undefined),
+      runAgentCommand: jest.fn().mockResolvedValue({ exitCode: 0 }),
+    };
+    const performCleanup = jest.fn().mockResolvedValue(undefined);
+    const logger = createLogger();
+
+    await runMainWorkflow(baseConfig, dependencies, { logger, performCleanup });
+
+    expect(dependencies.runAgentCommand).toHaveBeenCalledWith(
+      baseConfig.workDir,
+      baseConfig.allowedDomains,
+      undefined,
+      undefined
+    );
+  });
+
   it('logs warning with exit code when command fails', async () => {
     const callOrder: string[] = [];
     const dependencies: WorkflowDependencies = {

src/cli-workflow.ts

@@ -8,7 +8,8 @@ export interface WorkflowDependencies {
   runAgentCommand: (
     workDir: string,
     allowedDomains: string[],
-    proxyLogsDir?: string
+    proxyLogsDir?: string,
+    agentTimeoutMinutes?: number
   ) => Promise<{ exitCode: number }>;
 }
 
@@ -58,7 +59,7 @@ export async function runMainWorkflow(
   onContainersStarted?.();
 
   // Step 3: Wait for agent to complete
-  const result = await dependencies.runAgentCommand(config.workDir, config.allowedDomains, config.proxyLogsDir);
+  const result = await dependencies.runAgentCommand(config.workDir, config.allowedDomains, config.proxyLogsDir, config.agentTimeout);
 
   // Step 4: Cleanup (logs will be preserved automatically if they exist)
   await performCleanup();

src/cli.test.ts

@@ -1,5 +1,5 @@
 import { Command } from 'commander';
-import { parseEnvironmentVariables, parseDomains, parseDomainsFile, escapeShellArg, joinShellArgs, parseVolumeMounts, isValidIPv4, isValidIPv6, parseDnsServers, validateAgentImage, isAgentImagePreset, AGENT_IMAGE_PRESETS, processAgentImageOption, processLocalhostKeyword, validateSkipPullWithBuildLocal, validateAllowHostPorts, parseMemoryLimit, validateFormat, validateApiProxyConfig, buildRateLimitConfig, validateRateLimitFlags, validateApiTargetInAllowedDomains, DEFAULT_OPENAI_API_TARGET, DEFAULT_ANTHROPIC_API_TARGET, emitApiProxyTargetWarnings, formatItem, program } from './cli';
+import { parseEnvironmentVariables, parseDomains, parseDomainsFile, escapeShellArg, joinShellArgs, parseVolumeMounts, isValidIPv4, isValidIPv6, parseDnsServers, validateAgentImage, isAgentImagePreset, AGENT_IMAGE_PRESETS, processAgentImageOption, processLocalhostKeyword, validateSkipPullWithBuildLocal, validateAllowHostPorts, parseMemoryLimit, validateFormat, validateApiProxyConfig, buildRateLimitConfig, validateRateLimitFlags, validateApiTargetInAllowedDomains, DEFAULT_OPENAI_API_TARGET, DEFAULT_ANTHROPIC_API_TARGET, emitApiProxyTargetWarnings, formatItem, program, parseAgentTimeout, applyAgentTimeout } from './cli';
 import { redactSecrets } from './redact-secrets';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -1783,4 +1783,102 @@ describe('cli', () => {
     });
   });
 
+  describe('parseAgentTimeout', () => {
+    it('should parse a valid positive integer', () => {
+      const result = parseAgentTimeout('30');
+      expect(result).toEqual({ minutes: 30 });
+    });
+
+    it('should parse single minute timeout', () => {
+      const result = parseAgentTimeout('1');
+      expect(result).toEqual({ minutes: 1 });
+    });
+
+    it('should return error for zero', () => {
+      const result = parseAgentTimeout('0');
+      expect(result).toEqual({ error: '--agent-timeout must be a positive integer (minutes)' });
+    });
+
+    it('should return error for negative value', () => {
+      const result = parseAgentTimeout('-5');
+      expect(result).toEqual({ error: '--agent-timeout must be a positive integer (minutes)' });
+    });
+
+    it('should return error for non-numeric string', () => {
+      const result = parseAgentTimeout('abc');
+      expect(result).toEqual({ error: '--agent-timeout must be a positive integer (minutes)' });
+    });
+
+    it('should return error for empty string', () => {
+      const result = parseAgentTimeout('');
+      expect(result).toEqual({ error: '--agent-timeout must be a positive integer (minutes)' });
+    });
+
+    it('should parse large timeout values', () => {
+      const result = parseAgentTimeout('1440');
+      expect(result).toEqual({ minutes: 1440 });
+    });
+
+    it('should return error for value with trailing non-numeric characters', () => {
+      const result = parseAgentTimeout('30m');
+      expect(result).toEqual({ error: '--agent-timeout must be a positive integer (minutes)' });
+    });
+
+    it('should return error for decimal value', () => {
+      const result = parseAgentTimeout('1.5');
+      expect(result).toEqual({ error: '--agent-timeout must be a positive integer (minutes)' });
+    });
+
+    it('should return error for value with leading zero', () => {
+      const result = parseAgentTimeout('030');
+      expect(result).toEqual({ error: '--agent-timeout must be a positive integer (minutes)' });
+    });
+  });
+
+  describe('applyAgentTimeout', () => {
+    it('should do nothing when agentTimeout is undefined', () => {
+      const config: any = {};
+      const logger = { error: jest.fn(), info: jest.fn() };
+      applyAgentTimeout(undefined, config, logger);
+      expect(config.agentTimeout).toBeUndefined();
+      expect(logger.info).not.toHaveBeenCalled();
+      expect(logger.error).not.toHaveBeenCalled();
+    });
+
+    it('should set agentTimeout on config for valid value', () => {
+      const config: any = {};
+      const logger = { error: jest.fn(), info: jest.fn() };
+      applyAgentTimeout('30', config, logger);
+      expect(config.agentTimeout).toBe(30);
+      expect(logger.info).toHaveBeenCalledWith('Agent timeout set to 30 minutes');
+    });
+
+    it('should call process.exit for invalid value', () => {
+      const config: any = {};
+      const logger = { error: jest.fn(), info: jest.fn() };
+      const mockExit = jest.spyOn(process, 'exit').mockImplementation((() => {}) as any);
+      applyAgentTimeout('abc', config, logger);
+      expect(logger.error).toHaveBeenCalledWith('--agent-timeout must be a positive integer (minutes)');
+      expect(mockExit).toHaveBeenCalledWith(1);
+      mockExit.mockRestore();
+    });
+  });
+
+  describe('formatItem', () => {
+    it('should format term with description when term fits within width', () => {
+      const result = formatItem('--flag', 'Description text', 20, 2, 2, 80);
+      expect(result).toBe('  --flag                Description text');
+    });
+
+    it('should wrap description to next line when term exceeds width', () => {
+      const result = formatItem('--very-long-flag-name-that-exceeds-width', 'Description', 10, 2, 2, 80);
+      expect(result).toContain('--very-long-flag-name-that-exceeds-width\n');
+      expect(result).toContain('Description');
+    });
+
+    it('should format term without description', () => {
+      const result = formatItem('--flag', '', 20, 2, 2, 80);
+      expect(result).toBe('  --flag');
+    });
+  });
 });

src/cli.ts

@@ -509,6 +509,38 @@ export function parseMemoryLimit(input: string): { value: string; error?: undefi
   return { value: input.toLowerCase() };
 }
 
+/**
+ * Parses and validates the --agent-timeout option
+ * @param value - The raw string value from the CLI option
+ * @returns The parsed timeout in minutes, or an error
+ */
+export function parseAgentTimeout(value: string): { minutes: number } | { error: string } {
+  if (!/^[1-9]\d*$/.test(value)) {
+    return { error: '--agent-timeout must be a positive integer (minutes)' };
+  }
+  const timeoutMinutes = parseInt(value, 10);
+  return { minutes: timeoutMinutes };
+}
+
+/**
+ * Applies the --agent-timeout option to the config if present.
+ * Exits with code 1 if the value is invalid.
+ */
+export function applyAgentTimeout(
+  agentTimeout: string | undefined,
+  config: WrapperConfig,
+  logger: { error: (msg: string) => void; info: (msg: string) => void }
+): void {
+  if (agentTimeout === undefined) return;
+  const result = parseAgentTimeout(agentTimeout);
+  if ('error' in result) {
+    logger.error(result.error);
+    process.exit(1);
+  }
+  config.agentTimeout = result.minutes;
+  logger.info(`Agent timeout set to ${result.minutes} minutes`);
+}
+
 /**
  * Parses and validates DNS servers from a comma-separated string
  * @param input - Comma-separated DNS server string (e.g., "8.8.8.8,1.1.1.1")
@@ -1019,6 +1051,10 @@ program
     'Keep containers running after command exits',
     false
   )
+  .option(
+    '--agent-timeout <minutes>',
+    'Maximum time in minutes for the agent command to run (default: no limit)',
+  )
   .option(
     '--work-dir <dir>',
     'Working directory for temporary files',
@@ -1305,6 +1341,9 @@ program
       anthropicApiTarget: options.anthropicApiTarget || process.env.ANTHROPIC_API_TARGET,
     };
 
+    // Parse and validate --agent-timeout
+    applyAgentTimeout(options.agentTimeout, config, logger);
+
     // Build rate limit config when API proxy is enabled
     if (config.enableApiProxy) {
       const rateLimitResult = buildRateLimitConfig(options);

src/docker-manager.test.ts

@@ -2564,6 +2564,52 @@ describe('docker-manager', () => {
       expect(result.exitCode).toBe(0);
       expect(result.blockedDomains).toEqual([]);
     });
+
+    it('should return exit code 124 when agent times out', async () => {
+      jest.useFakeTimers();
+
+      // Mock docker logs -f
+      mockExecaFn.mockResolvedValueOnce({ stdout: '', stderr: '', exitCode: 0 } as any);
+      // Mock docker wait - never resolves (simulates long-running command)
+      mockExecaFn.mockReturnValueOnce(new Promise(() => {}));
+      // Mock docker stop
+      mockExecaFn.mockResolvedValueOnce({ stdout: '', stderr: '', exitCode: 0 } as any);
+
+      const resultPromise = runAgentCommand(testDir, ['github.com'], undefined, 1);
+
+      // Use advanceTimersByTimeAsync to flush microtasks between timer advances
+      // This handles the 60s timeout AND the subsequent 500ms log flush delay
+      await jest.advanceTimersByTimeAsync(60 * 1000 + 1000);
+
+      const result = await resultPromise;
+
+      expect(result.exitCode).toBe(124);
+      // Verify docker stop was called
+      expect(mockExecaFn).toHaveBeenCalledWith('docker', ['stop', '-t', '10', 'awf-agent'], { reject: false });
+
+      jest.useRealTimers();
+    });
+
+    it('should return normal exit code when agent completes before timeout', async () => {
+      jest.useFakeTimers();
+
+      // Mock docker logs -f
+      mockExecaFn.mockResolvedValueOnce({ stdout: '', stderr: '', exitCode: 0 } as any);
+      // Mock docker wait - resolves immediately with exit code 0
+      mockExecaFn.mockResolvedValueOnce({ stdout: '0', stderr: '', exitCode: 0 } as any);
+
+      const resultPromise = runAgentCommand(testDir, ['github.com'], undefined, 30);
+
+      // Advance past the 500ms log flush delay
+      await jest.advanceTimersByTimeAsync(1000);
+
+      const result = await resultPromise;
+
+      expect(result.exitCode).toBe(0);
+      expect(result.blockedDomains).toEqual([]);
+
+      jest.useRealTimers();
+    });
   });
 
   describe('cleanup', () => {

src/docker-manager.ts

@@ -1513,7 +1513,7 @@ export async function startContainers(workDir: string, allowedDomains: string[],
 /**
  * Runs the agent command in the container and reports any blocked domains
  */
-export async function runAgentCommand(workDir: string, allowedDomains: string[], proxyLogsDir?: string): Promise<{ exitCode: number; blockedDomains: string[] }> {
+export async function runAgentCommand(workDir: string, allowedDomains: string[], proxyLogsDir?: string, agentTimeoutMinutes?: number): Promise<{ exitCode: number; blockedDomains: string[] }> {
   logger.info('Executing agent command...');
 
   try {
@@ -1524,13 +1524,40 @@ export async function runAgentCommand(workDir: string, allowedDomains: string[],
       reject: false,
     });
 
-    // Wait for the container to exit (this will run concurrently with log streaming)
-    const { stdout: exitCodeStr } = await execa('docker', [
-      'wait',
-      'awf-agent',
-    ]);
+    let exitCode: number;
+
+    if (agentTimeoutMinutes) {
+      const timeoutMs = agentTimeoutMinutes * 60 * 1000;
+      logger.info(`Agent timeout: ${agentTimeoutMinutes} minutes`);
+
+      // Race docker wait against a timeout
+      const waitPromise = execa('docker', ['wait', 'awf-agent']).then(result => ({
+        type: 'completed' as const,
+        exitCodeStr: result.stdout,
+      }));
+
+      let timeoutTimer: ReturnType<typeof setTimeout>;
+      const timeoutPromise = new Promise<{ type: 'timeout' }>(resolve => {
+        timeoutTimer = setTimeout(() => resolve({ type: 'timeout' }), timeoutMs);
+      });
 
-    const exitCode = parseInt(exitCodeStr.trim(), 10);
+      const raceResult = await Promise.race([waitPromise, timeoutPromise]);
+
+      if (raceResult.type === 'timeout') {
+        logger.warn(`Agent command timed out after ${agentTimeoutMinutes} minutes, stopping container...`);
+        // Stop the container gracefully (10 second grace period before SIGKILL)
+        await execa('docker', ['stop', '-t', '10', 'awf-agent'], { reject: false });
+        exitCode = 124; // Standard timeout exit code (same as coreutils timeout)
+      } else {
+        // Clear the timeout timer so it doesn't keep the event loop alive
+        clearTimeout(timeoutTimer!);
+        exitCode = parseInt(raceResult.exitCodeStr.trim(), 10);
+      }
+    } else {
+      // No timeout - wait indefinitely
+      const { stdout: exitCodeStr } = await execa('docker', ['wait', 'awf-agent']);
+      exitCode = parseInt(exitCodeStr.trim(), 10);
+    }
 
     // Wait for the logs process to finish (it should exit automatically when container stops)
     await logsProcess;

src/types.ts

@@ -550,6 +550,22 @@ export interface WrapperConfig {
    * ```
    */
   anthropicApiTarget?: string;
+
+  /**
+   * Maximum time in minutes to allow the agent command to run
+   *
+   * When specified, the agent container is forcibly stopped after this many
+   * minutes. Useful for large projects where builds or tests may exceed
+   * default CI timeouts.
+   *
+   * When not specified, the agent runs indefinitely until the command completes
+   * or the process is externally terminated.
+   *
+   * @default undefined (no timeout)
+   * @example 30
+   * @example 45
+   */
+  agentTimeout?: number;
 }
 
 /**