Fix: Raise error when agentic workflow hits max-turns limit

[Copilot]

Problem

When an agentic workflow hits its configured max-turns limit, the execution stops but no error is raised. This leads to silent failures where:

• The agent task is incomplete
• Safe-outputs may not be executed properly
• Users have no clear indication that the workflow was forcefully stopped mid-execution

This is particularly problematic for workflows using safe-outputs, as the incomplete execution can result in missing or partial results.

Solution

Modified the Claude log parser to detect when the max-turns limit is hit and fail the workflow with a clear error message.

The parser now:

1. Checks if num_turns from the final log entry equals or exceeds the configured GH_AW_MAX_TURNS environment variable
2. Returns a maxTurnsHit flag in the parse result
3. Calls core.setFailed() with a descriptive error message when the limit is detected

Changes

pkg/workflow/js/parse_claude_log.cjs:

• Added maxTurnsHit boolean flag to the parseClaudeLog() return value
• Added logic to compare num_turns >= GH_AW_MAX_TURNS when both values are available
• Updated main() function to call core.setFailed() when max-turns limit is detected

pkg/workflow/js/parse_claude_log.test.cjs:

• Added 3 unit tests for the parseClaudeLog() function
• Added 1 integration test for the main() function
• Tests cover: limit hit, below limit, and no limit configured scenarios

Example

When a workflow now hits the max-turns limit, users will see:

Error: Agent execution stopped: max-turns limit reached. The agent did not complete its task successfully.

This makes it immediately clear that:

• The workflow stopped due to a configured limit (not an unexpected error)
• The task did not complete successfully
• Safe-outputs may not have been executed

Implementation Notes

• Scope: Only implemented for Claude engine, as it's currently the only engine that supports max-turns (Copilot and Codex do not support it yet)
• Comparison: Uses >= instead of == to handle edge cases where turns might exceed the limit
• Environment variable: Leverages existing GH_AW_MAX_TURNS variable set by the workflow compiler

Testing

✅ All 24 tests in parse_claude_log.test.cjs passing
✅ All Go unit tests passing
✅ JavaScript linter clean
✅ Code review completed with no issues

Fixes #[issue-number]

Original prompt

---

This section details on the original issue you should resolve

<issue_title>An agentic run that hits the max-runs limit should raise an error</issue_title>
<issue_description>Typically means the safe-output won't be executed. Hitting the max-runs limit should be treated as an error.</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #2225

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[github-actions]

Agentic Changeset Generator triggered by this pull request.