Document harness watchdog and retry runtime settings by Copilot · Pull Request #52511 · github/gh-aw

Copilot · 2026-08-13T14:57:54Z

Several harness environment variables affected runtime behavior without a user-facing reference, making post-result watchdog termination and retry tuning hard to diagnose. This adds supported configuration docs and separates public knobs from compiler-managed/internal runtime variables.

Harness settings reference
- Added shared retry settings with defaults, units, ranges, and clamping behavior.
- Documented GH_AW_HARNESS_WATCHDOG_TIMEOUT_MS semantics, including arming conditions, stdio inactivity reset behavior, and success handling after terminal safe outputs.
- Classified GH_AW_TIMEOUT_MINUTES as compiler-managed and directed users to timeout-minutes.
Engine-specific controls
- Documented Copilot’s GH_AW_HARNESS_LONG_RUN_TOKEN_THRESHOLD.
- Documented Claude’s GH_AW_CLAUDE_STARTUP_RETRIES.
- Clarified that Codex/Gemini/Copilot do not have additional public startup-retry env vars beyond shared harness retry policy.
Discoverability and troubleshooting
- Linked harness tuning from the environment variables, engines, frontmatter, debugging, and timeout troubleshooting docs.
- Added guidance for silent long-running shell commands and builds after terminal safe outputs.

Example workflow-level watchdog tuning:

env:
  # Allow quiet monorepo scans and builds after an intermediate safe output.
  GH_AW_HARNESS_WATCHDOG_TIMEOUT_MS: "600000"

Equivalent structured frontmatter form:

engine:
  id: copilot
  harness:
    watchdog-timeout: 600  # seconds

Fixes Document harness watchdog, retry, and timeout environment settings #51290

Co-authored-by: dsyme <7204669+dsyme@users.noreply.github.com>

github-actions · 2026-08-13T17:14:48Z

👋 @Copilot — thanks for documenting the harness watchdog and retry settings! This addresses #51290 comprehensively.

The PR looks well-structured and ready:

✅ Focused scope — adds documentation across reference and troubleshooting sections for harness tuning, environment variables, and frontmatter examples.

✅ Complete coverage — documents watchdog semantics, retry policy, engine-specific controls (Copilot, Claude), and includes concrete workflow examples.

✅ Cross-linked — connects harness settings from environment variables, engines, frontmatter, debugging, and timeout docs for discoverability.

✅ Clear descriptions — the PR body and issue #51290 provide full context and acceptance criteria.

This is ready for maintainer review!

Generated by ✅ Contribution Check · auto · 48.3 AIC · ⌖ 4.04 AIC · ⊞ 8.8K · ◷

github-actions · 2026-08-13T17:45:43Z

✅ Test Quality Sentinel completed test quality analysis.

No test files were added or modified in this PR. Test Quality Sentinel skipped.

🧪 Test quality analysis by Test Quality Sentinel

Copilot

Pull request overview

Documents public harness watchdog and retry controls and improves runtime troubleshooting.

Changes:

Adds shared and engine-specific harness settings.
Documents watchdog behavior, limits, and examples.
Links runtime tuning guidance across references and troubleshooting.

Show a summary per file

File	Description
`docs/src/content/docs/troubleshooting/debugging.md`	Adds watchdog troubleshooting.
`docs/src/content/docs/troubleshooting/common-issues.md`	Adds timeout diagnosis and tuning example.
`docs/src/content/docs/reference/frontmatter.md`	Documents structured watchdog configuration.
`docs/src/content/docs/reference/environment-variables.md`	Adds the harness settings reference.
`docs/src/content/docs/reference/engines.md`	Expands harness policy documentation.

Review details

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

Suppressed comments (1)

docs/src/content/docs/reference/engines.md:377

This new shared GH_AW_HARNESS_* guidance conflicts with the note at line 337, which still says the entire engine.harness object only applies to Copilot. Retry fields are compiled for Copilot, Claude, and Codex, so scope that earlier note specifically to engine.harness.use; otherwise readers may reasonably conclude the settings documented here do nothing on Claude/Codex.

You can also set the underlying `GH_AW_HARNESS_*` env vars directly via `engine.env` when you need expression-level control, including `GH_AW_HARNESS_WATCHDOG_TIMEOUT_MS` for the post-result watchdog. Explicit `engine.env` values take precedence over `engine.harness` sub-key values. See [Harness Settings and Runtime Tuning Variables](/gh-aw/reference/environment-variables/#harness-settings-and-runtime-tuning-variables) for supported env vars, units, clamping behavior, and engine-specific controls such as `GH_AW_CLAUDE_STARTUP_RETRIES`.

Files reviewed: 5/5 changed files
Comments generated: 5
Review effort level: Balanced

 engine: copilot
 ```

+Harness retry and post-result watchdog settings live under `engine.harness` for built-in Copilot, Claude, and Codex harnesses:



+### Silent Long-running Commands After a Result
+
+If the harness log says `post-result watchdog terminating idle process`, the agent already emitted a terminal safe output and then the child process went quiet. The watchdog is dormant until a terminal safe output such as `noop`, a comment, label, push, or pull request creation is observed; diagnostic outputs such as `missing_tool`, `missing_data`, and `report_incomplete` do not arm it. After arming, stdout or stderr activity resets the clock, so quiet builds, tests, or monorepo scans can be terminated even while they are still doing useful CPU or I/O work.


+
+`GH_AW_HARNESS_WATCHDOG_TIMEOUT_MS` configures the post-result stdio inactivity watchdog used by the built-in Copilot and Codex harnesses. It is measured in **milliseconds**. The default is `120000` ms (2 minutes), the minimum is `50` ms, and the maximum is `600000` ms (10 minutes). Unset, non-numeric, zero, and negative values use the default; positive values outside the supported range are clamped.
+
+The watchdog is dormant until the agent emits a terminal safe output. `noop` and ordinary task outputs such as comments, labels, pushes, and pull request creation are terminal. Diagnostic safe outputs such as `missing_tool`, `missing_data`, and `report_incomplete` are not terminal and do not arm the watchdog by themselves.


 | `watchdog-timeout` | `120` | Post-result idle watchdog timeout in seconds before terminating a quiet process |

-You can also set the underlying `GH_AW_HARNESS_*` env vars directly via `engine.env` when you need expression-level control, including `GH_AW_HARNESS_WATCHDOG_TIMEOUT_MS` for the post-result watchdog. Explicit `engine.env` values take precedence over `engine.harness` sub-key values.
+The post-result watchdog is dormant until the harness observes a terminal safe output. `noop` and ordinary task outputs such as comments, labels, pushes, and pull request creation are terminal; diagnostics such as `missing_tool`, `missing_data`, and `report_incomplete` are not. Once armed, any stdout or stderr activity resets the inactivity clock. A quiet child process can still be terminated while it is doing useful work, and the harness may treat that termination as successful when a terminal safe output already exists.


+| Variable | Engine | Default | Units / range | Description |
+| --- | --- | --- | --- | --- |
+| `GH_AW_HARNESS_LONG_RUN_TOKEN_THRESHOLD` | Copilot | `10000` | tokens; minimum `0` | Token threshold used to classify long-running partial executions as `long_run_exit` instead of a generic partial execution. Invalid or negative values use the default. |
+| `GH_AW_CLAUDE_STARTUP_RETRIES` | Claude | `1` | retry attempts; range `0`-`2` | Additional fresh-run retry budget for zero-output Claude startup failures. Invalid values use the default; out-of-range integers are clamped. |


github-actions · 2026-08-13T18:39:47Z

🔍 PR Triage

Category: docs · Risk: low · Priority score: 28/100 (impact 8, urgency 5, quality 15)
Recommended action: auto_merge

Score breakdown:

Impact: Documentation-only change clarifying harness watchdog/retry env vars.
Urgency: Low — improves diagnosability, not blocking.
Quality: CI green (14 success/1 skipped), no code risk.

Good candidate for auto-merge once any final doc review is done.

Generated by 🔧 PR Triage Agent · auto · 71.4 AIC · ⌖ 2.63 AIC · ⊞ 7.8K · ◷

Initial plan

6a3c816

Copilot AI assigned Copilot and dsyme Aug 13, 2026

Copilot started work on behalf of dsyme August 13, 2026 14:58 View session

Copilot AI linked an issue Aug 13, 2026 that may be closed by this pull request

Document harness watchdog, retry, and timeout environment settings #51290

Closed

6 tasks

Document harness runtime tuning settings

dc91991

Co-authored-by: dsyme <7204669+dsyme@users.noreply.github.com>

Copilot AI changed the title ~~[WIP] Document harness watchdog, retry, and timeout environment settings~~ Document harness watchdog and retry runtime settings Aug 13, 2026

Copilot finished work on behalf of dsyme August 13, 2026 15:10

Copilot AI requested a review from dsyme August 13, 2026 15:10

github-actions Bot mentioned this pull request Aug 13, 2026

[Contribution Check Report] Contribution Check — 2026-08-13 #52398

Closed

pelikhan marked this pull request as ready for review August 13, 2026 17:44

Copilot AI balanced review requested due to automatic review settings August 13, 2026 17:44

Copilot started reviewing on behalf of pelikhan August 13, 2026 17:44 View session

Copilot AI reviewed Aug 13, 2026

View reviewed changes

github-actions Bot added pr-action:auto_merge pr-agent:copilot pr-priority:low pr-risk:low pr-type:docs labels Aug 13, 2026

github-actions Bot mentioned this pull request Aug 13, 2026

[PR Triage Report] PR Triage Report — 2026-08-13 (Run 31730872872) #52545

Closed

pelikhan merged commit eeba2d9 into main Aug 13, 2026
15 checks passed

pelikhan deleted the copilot/document-harness-settings branch August 13, 2026 18:43

This was referenced Aug 13, 2026

Smoke Test: MAI-Code-1-Flash - 31732554364 #52551

Closed

[docs] Update glossary - daily scan #52692

Open

Navigation Menu

Uh oh!

Document harness watchdog and retry runtime settings - #52511

Document harness watchdog and retry runtime settings#52511
pelikhan merged 2 commits into
mainfrom
copilot/document-harness-settings

Copilot AI commented Aug 13, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Aug 13, 2026

Uh oh!

github-actions Bot commented Aug 13, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

github-actions Bot commented Aug 13, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants


		### Silent Long-running Commands After a Result

		If the harness log says `post-result watchdog terminating idle process`, the agent already emitted a terminal safe output and then the child process went quiet. The watchdog is dormant until a terminal safe output such as `noop`, a comment, label, push, or pull request creation is observed; diagnostic outputs such as `missing_tool`, `missing_data`, and `report_incomplete` do not arm it. After arming, stdout or stderr activity resets the clock, so quiet builds, tests, or monorepo scans can be terminated even while they are still doing useful CPU or I/O work.


		`GH_AW_HARNESS_WATCHDOG_TIMEOUT_MS` configures the post-result stdio inactivity watchdog used by the built-in Copilot and Codex harnesses. It is measured in milliseconds. The default is `120000` ms (2 minutes), the minimum is `50` ms, and the maximum is `600000` ms (10 minutes). Unset, non-numeric, zero, and negative values use the default; positive values outside the supported range are clamped.

		The watchdog is dormant until the agent emits a terminal safe output. `noop` and ordinary task outputs such as comments, labels, pushes, and pull request creation are terminal. Diagnostic safe outputs such as `missing_tool`, `missing_data`, and `report_incomplete` are not terminal and do not arm the watchdog by themselves.

Uh oh!

Conversation

Copilot AI commented Aug 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Aug 13, 2026

Uh oh!

github-actions Bot commented Aug 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Review details

Uh oh!

github-actions Bot commented Aug 13, 2026

🔍 PR Triage

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Copilot AI commented Aug 13, 2026 •

edited

Loading

github-actions Bot commented Aug 13, 2026 •

edited

Loading