feat: perf-constraint-tester - Resource constraint testing (hook)

[avifenesh]

Overview

Hook/utility for testing performance under resource constraints (CPU, memory limits).

Parent Issue

Part of #124 - Master performance profiling orchestrator

Implementation Type

This is primarily a HOOK, not a full agent.

Can be implemented as:

• Pre-benchmark hook that applies constraints
• Wrapper script for benchmark commands
• Simple utility called by other agents

Rationale

"try now also to cap the cores to 4"

Production environments have resource constraints. Performance issues often ONLY appear under constraint. Testing under constraint reveals:

• Thread contention issues
• Memory pressure behavior
• CPU scheduling problems
• Resource starvation patterns

Responsibilities

1. CPU Constraints

# Apply CPU core limit
taskset -c 0-3 <command>  # Limit to cores 0-3

# Or using cgroups (Linux)
cgexec -g cpu:limited <command>

2. Memory Constraints

# Apply memory limit
ulimit -v <bytes>

# Or using cgroups
cgexec -g memory:limited <command>

3. Comparison Matrix

## Standard comparison:
1. Run benchmark: unconstrained
2. Run benchmark: CPU-constrained (4 cores)
3. Run benchmark: memory-constrained
4. Compare results
5. Report differences

Hook Definition

---
name: perf-constraint-tester
type: hook  # Not a full agent
description: Applies resource constraints to benchmark runs
triggers:
  - before: benchmark
---

Usage

# Via environment variable
PERF_CPU_LIMIT=4 /perf --benchmark

# Via flag
/perf --benchmark --cpu-limit 4 --memory-limit 2048

# Via hook configuration
# .claude/perf/constraints.json
{
  "cpu_limit": 4,
  "memory_limit_mb": 2048,
  "enabled": true
}

Output Format

{
  "constraints_applied": {
    "cpu_cores": 4,
    "memory_limit_mb": 2048
  },
  "comparison": {
    "unconstrained": {
      "p50": 1.2,
      "p99": 4.5
    },
    "constrained": {
      "p50": 3.8,
      "p99": 156.2
    },
    "degradation": {
      "p50": "3.2x worse",
      "p99": "34.7x worse"
    },
    "constraint_sensitive": true
  }
}

Files to Create

• lib/perf/constraint-wrapper.sh (shell script)
• lib/perf/constraints.js (configuration)

Success Criteria

• Applies CPU constraints via taskset
• Applies memory constraints via ulimit
• Compares constrained vs unconstrained
• Reports degradation factor
• Integrates with benchmark workflow
• Simple hook, not complex agent

[avifenesh]

Implemented in v3.4.0