github · pelikhan · Aug 13, 2026 · Aug 13, 2026 · Aug 13, 2026
diff --git a/docs/src/content/docs/reference/engines.md b/docs/src/content/docs/reference/engines.md
@@ -372,7 +372,9 @@ When an expression is used, it must already be in milliseconds (GitHub Actions e
 | `max-delay-ms` | `60000` | Maximum delay cap in ms |
 | `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.
+
+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`.
 
 ### Copilot SDK Support
 

diff --git a/docs/src/content/docs/reference/environment-variables.md b/docs/src/content/docs/reference/environment-variables.md
@@ -121,6 +121,63 @@ env:
 > [!NOTE]
 > These variables are injected by the compiler and cannot be overridden by user-defined `env:` blocks in the workflow frontmatter.
 
+## Harness Settings and Runtime Tuning Variables
+
+The built-in Copilot, Claude, and Codex harnesses expose a small set of supported runtime controls. Prefer the structured `engine.harness` frontmatter fields when possible; set the underlying environment variables only when you need a value that is supplied by a GitHub Actions expression or shared across a workflow.
+
+### Shared harness retry settings
+
+These settings apply to the built-in Copilot, Claude, and Codex harnesses.
+
+| Variable | Frontmatter field | Default | Units / range | Description |
+| --- | --- | --- | --- | --- |
+| `GH_AW_HARNESS_MAX_RETRIES` | `engine.harness.max-retries` | `3` | retry attempts after the initial run; minimum `0`, maximum `100` | Maximum number of harness retries. `0` disables retries. Invalid values use the default; values above `100` are clamped to `100`. |
+| `GH_AW_HARNESS_INITIAL_DELAY_MS` | `engine.harness.initial-delay-ms` | `5000` | milliseconds; minimum `1` | Delay before the first retry. Invalid values use the default. |
+| `GH_AW_HARNESS_BACKOFF_MULTIPLIER` | `engine.harness.backoff-multiplier` | `2` | decimal multiplier; minimum `1` | Multiplier applied after each retry. Invalid values use the default. |
+| `GH_AW_HARNESS_MAX_DELAY_MS` | `engine.harness.max-delay-ms` | `60000` | milliseconds; minimum `1` | Maximum retry delay. Invalid values use the default. If set below `GH_AW_HARNESS_INITIAL_DELAY_MS`, it is clamped up to the initial delay. |
+
+### Shared post-result watchdog
+
+`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.
+
+After the watchdog arms, any stdout or stderr activity resets the inactivity clock. A quiet child process can therefore be terminated even while it is doing useful CPU or I/O work, such as a monorepo scan, build, or test command that produces no logs. If the watchdog fires after a terminal safe output already exists, the harness may still treat the run as successful because the requested safe output was already produced.
+
+For literal frontmatter values, use `engine.harness.watchdog-timeout` in seconds. For raw environment variables, use milliseconds:
+
+```yaml wrap
+---
+env:
+  # Allow quiet monorepo scans and builds after an intermediate safe output.
+  # Workflow-level env is visible to the agent; do not put secrets here.
+  GH_AW_HARNESS_WATCHDOG_TIMEOUT_MS: "600000"
+---
+```
+
+```yaml wrap
+---
+engine:
+  id: copilot
+  harness:
+    # Same timeout expressed as a literal frontmatter value in seconds.
+    watchdog-timeout: 600
+---
+```
+
+### Engine-specific harness settings
+
+| 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. |
+
+There is no separate public Codex, Gemini, or Copilot startup-retry environment variable beyond the shared retry policy above. Copilot SDK driver settings such as `COPILOT_SDK_SEND_TIMEOUT_MS` are documented in [Copilot SDK Support](/gh-aw/reference/engines/#copilot-sdk-support) and the [Copilot SDK Driver Specification](/gh-aw/specs/copilot-sdk-driver-specification/).
+
+### Internal runtime variables
+
+`GH_AW_TIMEOUT_MINUTES` is compiler-managed. gh-aw derives it from the workflow `timeout-minutes` frontmatter value and passes it to harness and driver code so soft timeouts and SDK send timeouts stay below the GitHub Actions job timeout. Do not set `GH_AW_TIMEOUT_MINUTES` directly; set `timeout-minutes` in frontmatter instead.
+
 ## CLI Configuration Variables
 
 These variables configure the `gh aw` CLI tool. Set them in your local shell environment or as repository/organization variables in GitHub Actions.

diff --git a/docs/src/content/docs/reference/frontmatter.md b/docs/src/content/docs/reference/frontmatter.md
@@ -179,6 +179,18 @@ Specifies which AI engine interprets the markdown section. See [AI Engines](/gh-
 engine: copilot
 ```
 
+Harness retry and post-result watchdog settings live under `engine.harness` for built-in Copilot, Claude, and Codex harnesses:
+
+```yaml wrap
+engine:
+  id: copilot
+  harness:
+    # Allow quiet monorepo scans and builds after an intermediate safe output.
+    watchdog-timeout: 600  # seconds
+```
+
+See [Harness Retry and Post-result Watchdog Policy](/gh-aw/reference/engines/#harness-retry-and-post-result-watchdog-policy) for defaults, units, and the equivalent `GH_AW_HARNESS_*` environment variables.
+
 ### Engine Driver (`engine.driver:`)
 
 Overrides the built-in engine runtime driver for engines that support driver mode. For Copilot, setting `engine.driver` also enables SDK mode. `engine.driver` accepts either a string path/command or an inline source object with exactly one of `node:`, `python:`, `go:`, or `java:`. See [AI Engines](/gh-aw/reference/engines/#copilot-sdk-support) for driver requirements and supported formats.

diff --git a/docs/src/content/docs/troubleshooting/common-issues.md b/docs/src/content/docs/troubleshooting/common-issues.md
@@ -347,6 +347,7 @@ GitHub Actions marks the run as `timed_out` when the job exceeds `timeout-minute
 | Codex | `Tool call timed out after 120 seconds` | `tools: timeout: N` (default: 120s) |
 | Copilot | *(task incomplete, workflow succeeds)* | `max-continuations: N` |
 | Any | `Failed to register tools error="initialize: timeout"` | `tools: startup-timeout: N` |
+| Copilot/Codex | Harness log says `post-result watchdog terminating idle process` after a comment, label, PR, push, or `noop` output | Increase `engine.harness.watchdog-timeout` (seconds) or `GH_AW_HARNESS_WATCHDOG_TIMEOUT_MS` (milliseconds) |
 
 ```yaml wrap
 timeout-minutes: 60      # job-level limit
@@ -357,6 +358,17 @@ max-turns: 30            # Claude: max turns
 max-continuations: 5     # Copilot: autopilot continuations
 ```
 
+The post-result watchdog only starts after a terminal safe output is written. It is useful for cleaning up child processes after a result, but it can terminate silent long-running shell commands and builds that continue doing CPU or I/O work without writing stdout or stderr. For quiet monorepo scans or builds, increase the watchdog window:
+
+```yaml wrap
+engine:
+  id: copilot
+  harness:
+    watchdog-timeout: 600  # seconds
+```
+
+See [Harness Settings and Runtime Tuning Variables](/gh-aw/reference/environment-variables/#harness-settings-and-runtime-tuning-variables) for the raw `GH_AW_HARNESS_WATCHDOG_TIMEOUT_MS` environment variable, default, range, and clamping behavior.
+
 ### Why Did My Workflow Fail?
 
 Common causes include missing tokens, permission mismatches, network restrictions, disabled tools, and rate limits. The quickest path is usually to give an agent the run URL so it can inspect logs and suggest a fix.

diff --git a/docs/src/content/docs/troubleshooting/debugging.md b/docs/src/content/docs/troubleshooting/debugging.md
@@ -115,6 +115,12 @@ See [Network Configuration](/gh-aw/guides/network-configuration/) for common dom
 
 The safe-outputs job failed, the agent didn't produce the expected output, or permissions are missing. Inspect the safe-outputs section in `gh aw audit <run-id>` and review the [Safe Outputs Reference](/gh-aw/reference/safe-outputs/).
 
+### 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.
+
+Increase `engine.harness.watchdog-timeout` for literal frontmatter values, or set `GH_AW_HARNESS_WATCHDOG_TIMEOUT_MS` when you need a millisecond environment-variable override. See [Harness Settings and Runtime Tuning Variables](/gh-aw/reference/environment-variables/#harness-settings-and-runtime-tuning-variables).
+
 ### Compilation Errors
 
 The frontmatter has schema validation errors or unsupported fields. Use `--verbose` to diagnose, `gh aw fix --write` to auto-correct, and `--validate` to check without writing the lock file. See [Error Reference](/gh-aw/troubleshooting/errors/) for specific messages.