feat: send loop nudge message to agent when loop is detected

[avoidwork]

Description

When the agent enters a repetitive loop, the system detects it via turn hash tracking but only displays a UI nudge ("You're looping.") to the user. The agent itself never receives feedback that it is stuck, so it continues looping. This change injects a configurable nudge message into the conversation when a loop is detected, allowing the agent to see it and try a different approach.

Type of Change

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactor (no functional changes)
• Performance improvement
• CI / build / tooling

Testing

Unit tests added for:

• Config schema validation of loopMsg and loopLimit
• Default nudge message when config is not set
• Configured nudge message when config is set
• Nudge injection when loop is detected and limit not reached
• Nudge not injected when limit is reached
• Nudge count reset on session clear
• Nudge message being a user type
• Nudge not counting as agent turn

All tests pass with npm run test.

Coverage

• Line coverage maintained

Checklist

• npm run lint passes
• Tests pass with maintained line coverage (verified after implementation)
• No forbidden patterns used
• Conventional Commit style applied

Implementation Tasks

This change implements the OpenSpec proposal at openspec/changes/loop-nudge-message/:

• Config schema updates (src/config/schemas.js, config.yaml)
• Loop nudge injection logic in src/agent/react.js
• Session state management for nudge count tracking
• Full test coverage for all requirements

[avoidwork]

Final Audit Results: Loop Nudge Message

Goal Fulfillment

All detailed goals have been satisfied:

• ✅ Goal 1: Send loop nudge message to agent when loop is detected
  • Nudge message is injected into the conversation when a loop is detected
  • The nudge is a user message (HumanMessage) so the agent sees it as conversation input
  • The nudge message content is configurable via agent.loopMsg / AGENT_LOOP_MSG
  • A maximum nudge count is enforced via agent.loopLimit / AGENT_LOOP_LIMIT (default: 5)
  • After the limit is reached, no more nudges are injected but loop detection continues
  • The existing UI nudge ("You're looping.") continues to work unchanged

Spec Compliance

The implementation matches the requirements in the spec documents:

• ✅ Requirement: System injects nudge message when loop is detected — Implemented in src/agent/react.js via the checkTurnHash function
• ✅ Requirement: System enforces maximum nudge count — nudgeCount is tracked and compared against nudgeLimit
• ✅ Requirement: Nudge message is visible to the agent — Nudge is injected as a HumanMessage (user type)
• ✅ Requirement: Existing UI nudge continues to work — TUI handling in src/tui/app.js is unchanged

Task Completion

All tasks in tasks.md have been implemented:

• ✅ 1.1-1.3: Config schema updates (AgentSchema, DEFAULT_CONFIG, config.yaml)
• ✅ 2.1-2.7: Loop nudge injection logic (config reading, nudge tracking, HumanMessage injection)
• ✅ 3.1-3.2: Session state management (nudgeCount is local variable, resets on new call)
• ✅ 4.1-4.8: Unit tests (8 test suites covering all requirements)
• ✅ 5.1-5.5: Verification (tests pass, lint passes, coverage maintained, UI nudge unchanged, app starts)

Quality Check

• Tests: 1209 pass, 0 fail, 1 skipped
• Lint: 0 warnings, 0 errors
• Coverage: react.js 94.70%, schemas.js 100.00%
• No forbidden patterns used
• Conventional Commit style applied

Deviations from Original Plan

• The nudge count is tracked as a local variable in callReactAgentStreaming rather than in the LangGraph state. This is simpler and achieves the same result since the count resets on each new call (equivalent to session clear).
• The nudge is injected during the stream event loop (when loop_detected is emitted) rather than after the stream completes. This ensures the nudge is added to currentMessages before the next iteration of the while loop.

Verdict

All goals fulfilled, all specs implemented, all tests passing. Ready for merge.