Codeman/test/respawn-analysis.md

Respawn Controller Test Analysis

Date: 2026-01-25 Analyzed Files:

• /home/arkon/default/codeman/src/respawn-controller.ts
• /home/arkon/default/codeman/src/ai-idle-checker.ts
• /home/arkon/default/codeman/src/ai-plan-checker.ts
• /home/arkon/default/codeman/test/respawn-controller.test.ts

---

1. Test Execution Results

Summary

• Total Tests: 91
• Passed: 91
• Failed: 0
• Duration: ~10 seconds

Type Check Results

• Type Errors: 0

All tests pass and the codebase is type-safe.

---

2. Code Coverage Analysis

Coverage Summary

File	Statements	Branches	Functions	Lines
respawn-controller.ts	62.51%	59.85%	74.48%	62.37%
ai-idle-checker.ts	68.91%	46.57%	75%	69.31%
ai-plan-checker.ts	57.52%	37.68%	58.33%	57.69%

Uncovered Code in respawn-controller.ts

The following areas lack test coverage:

1. Lines 2077-2151: sendClear(), sendInit(), completeCycle()

   • These functions execute during the full respawn cycle
   • Tests trigger cycles but don't mock session responses to complete them

2. Line 2162: checkIdleAndMaybeStart()

   • Called when resuming from pause while already idle
   • Only tested superficially with resume() call

3. Lines 2100-2103: Clear fallback timer path when sendInit is false

   • Edge case where /clear completes via fallback but init is disabled

---

3. Potential Bugs and Issues

Issue 1: E2BIG Error in ai-plan-checker.ts (HIGH)

File: /home/arkon/default/codeman/src/ai-plan-checker.ts Lines: 341-346 Severity: HIGH

Description: Unlike ai-idle-checker.ts, the plan checker passes the prompt directly as a shell argument rather than via a temp file. This can cause E2BIG (argument list too long) errors when the terminal buffer is large.

Code:

// ai-plan-checker.ts - PROBLEMATIC
const escapedPrompt = prompt.replace(/'/g, "'\\''");
const claudeCmd = `claude -p ${modelArg} --output-format text '${escapedPrompt}'`;

// ai-idle-checker.ts - CORRECT
writeFileSync(this.checkPromptFile, prompt);
const claudeCmd = `cat "${this.checkPromptFile}" | claude -p ${modelArg} --output-format text`;

Impact: With maxContextChars: 8000, the prompt can easily exceed shell argument limits (~128KB on most systems), causing the AI plan check to fail with a cryptic error.

Suggested Fix: Modify ai-plan-checker.ts to use the same temp file approach as ai-idle-checker.ts:

1. Add checkPromptFile instance variable
2. Write prompt to temp file
3. Use cat | claude -p pattern
4. Clean up temp file in cleanupCheck()

---

Issue 2: Missing Prompt File Cleanup on Timeout (MEDIUM)

File: /home/arkon/default/codeman/src/ai-idle-checker.ts Lines: 392-398 Severity: MEDIUM

Description: When the AI check times out, the cleanupCheck() function is called via finally. However, the prompt file deletion in cleanupCheck() may fail silently if the file is still being read by the cat command in the spawned screen.

Impact: Temp files may accumulate in /tmp if checks frequently timeout.

Suggested Fix: Add a small delay before file deletion or use a unique timestamp-based naming scheme that guarantees no collisions (already partially implemented but the shell command rm -f in the fullCmd also handles this).

---

Issue 3: Race Condition in cancel() with Promise Resolution (MEDIUM)

File: /home/arkon/default/codeman/src/ai-idle-checker.ts Lines: 265-279 Severity: MEDIUM

Description: The cancel() method resolves the pending promise and then calls cleanupCheck(). However, the interval poll timer might fire between these two operations and attempt to resolve an already-resolved promise.

Code:

cancel(): void {
  if (this._status !== 'checking') return;
  this.checkCancelled = true;
  // Race: poll timer might fire here
  if (this.checkResolve) {
    this.checkResolve({ verdict: 'ERROR', ... });
    this.checkResolve = null;
  }
  this.cleanupCheck(); // This clears the poll timer
  this._status = 'ready';
}

Impact: Could theoretically cause a double-resolve, though the guard if (this.checkCancelled) in the poll handler mitigates this.

Suggested Fix: Set checkCancelled = true and call cleanupCheck() (which clears the poll timer) before resolving the promise.

---

Issue 4: Stale Screen Name Collision (LOW)

File: /home/arkon/default/codeman/src/ai-idle-checker.ts, ai-plan-checker.ts Lines: 326-329 (idle), 333-336 (plan) Severity: LOW

Description: Screen names are generated using only sessionId.slice(0, 8), without a unique suffix. While there's a screen -X quit to kill leftover screens, two rapid checks could conflict.

Code:

this.checkScreenName = `codeman-aicheck-${shortId}`;

Impact: Very unlikely in practice since checks have cooldowns, but theoretically possible.

Suggested Fix: Already partially mitigated by the timestamp in temp file names. Could add timestamp to screen name too:

this.checkScreenName = `codeman-aicheck-${shortId}-${timestamp}`;

---

Issue 5: DetectionStatus Calculation During ai_checking State (LOW)

File: /home/arkon/default/codeman/src/respawn-controller.ts Lines: 759-762 Severity: LOW

Description: The outputSilent calculation uses config.completionConfirmMs, but when in ai_checking state, the output silence threshold should conceptually be the AI check timeout, not the completion confirm time.

Impact: UI display may show incorrect "silence" status during AI check.

---

4. Coverage Gaps

Functions Not Fully Tested

1. sendClear() - Never reaches execution in tests because the cycle is cut short
2. sendInit() - Same as above
3. completeCycle() - Tests don't allow cycles to complete fully
4. checkClearComplete() - Requires mocking prompt detection after /clear
5. checkInitComplete() - Requires mocking init completion flow
6. sendKickstart() - Not tested at all
7. checkKickstartComplete() - Not tested
8. startMonitoringInit() - Not tested
9. checkMonitoringInitIdle() - Not tested

Branches Not Tested

1. /clear fallback timer completing (line 2095-2105)
2. sendInit: false branch in various locations
3. Kickstart prompt flow when /init doesn't trigger work
4. AI checker returning WORKING verdict (only test with timeout)
5. AI plan checker PLAN_MODE verdict (real check, not just pre-filter)

Edge Cases Not Tested

1. Multiple rapid AI checks before cooldown
2. AI checker disabled mid-check
3. Session terminal buffer being undefined on start
4. Buffer trimming behavior at MAX_RESPAWN_BUFFER_SIZE
5. signalElicitation() called multiple times

---

5. Timing and Race Condition Analysis

Potential Timing Issues

1. Pre-filter timer vs AI check: If pre-filter fires while an AI check is already running, it correctly skips (line 1613).

2. Completion confirm during AI check: Output during AI check cancels it (line 1173-1188), which is correct.

3. Auto-accept during respawn cycle: Correctly guards against non-watching state (line 1741).

4. Step confirm timer: Uses same completionConfirmMs as idle confirm, which may be too short for complex operations.

Timer Cleanup

All timers appear to be properly cleaned up in clearTimers():

• idleTimer
• stepTimer
• clearFallbackTimer
• completionConfirmTimer
• stepConfirmTimer
• autoAcceptTimer
• preFilterTimer
• noOutputTimer
• detectionUpdateTimer (interval)

---

6. Recommendations (Prioritized)

Critical (Should Fix)

1. Fix E2BIG vulnerability in ai-plan-checker.ts
   • Use temp file for prompt like ai-idle-checker.ts does
   • Add checkPromptFile instance variable
   • Update cleanupCheck() to delete prompt file

High Priority

2. Add integration tests for full respawn cycle

   • Mock session to simulate prompt detection after each step
   • Test: update -> clear -> init -> back to watching
   • Test: kickstart prompt when init doesn't trigger work

3. Fix cancel() race condition in AI checkers

   • Clear poll timer before resolving promise
   • Or use a mutex/flag check in poll handler

Medium Priority

4. Add tests for AI checker WORKING verdict

   • Mock the screen process to return WORKING
   • Verify cooldown is started
   • Verify controller returns to watching

5. Add tests for plan checker PLAN_MODE verdict

   • Mock the screen process to return PLAN_MODE
   • Verify Enter is sent
   • Verify state transitions

6. Add timestamp to screen session names

   • Prevents potential collisions during rapid operations

Low Priority

7. Improve coverage of edge cases

   • Test sendInit: false and sendClear: false combinations
   • Test buffer trimming behavior
   • Test pause/resume with activity detection

8. Consider reducing step confirm timeout

   • Currently uses completionConfirmMs (10s default)
   • May want separate config for step confirmation

---

7. MockSession Limitations

The current MockSession class in tests is simplified and doesn't accurately simulate:

1. Delayed responses: Real sessions have processing time between input and output
2. State persistence: Real sessions maintain state between commands
3. Screen integration: Real sessions use GNU screen for persistence
4. Token tracking: Real sessions parse and track token usage

Consider adding a more sophisticated mock that can:

• Queue delayed responses
• Simulate multi-step workflows
• Return realistic completion messages with timing

---

8. Conclusion

The respawn controller tests are comprehensive for basic functionality but lack coverage for:

• Full respawn cycle completion
• AI checker verdicts (IDLE/WORKING/PLAN_MODE)
• Kickstart functionality
• Edge cases and error handling

The main bug found is in ai-plan-checker.ts which can fail with E2BIG errors on large terminal buffers. This should be fixed by using the temp file approach already implemented in ai-idle-checker.ts.

All 91 tests pass, and there are no type errors, indicating a stable codebase but with room for deeper integration testing.