Document harness watchdog, retry, and timeout environment settings

[dsyme]

Problem

Several environment variables alter agent harness behavior but are not documented in the user-facing gh-aw reference. In particular, GH_AW_HARNESS_WATCHDOG_TIMEOUT_MS is currently discoverable only by reading the harness source.

This makes post-result termination difficult to diagnose and leaves workflow authors unaware that they can tune the inactivity window for monorepos, builds, tests, and other quiet shell commands. See #51289 for the proposal to raise the default from 20 seconds to 2 minutes.

The retry controls are mentioned in docs/adr/43051-configurable-harness-retry-policy.md, but an ADR is not an adequate user-facing configuration reference.

Settings to document or classify

Please audit at least these settings and document those intended to be supported public controls:

Setting	Purpose to document
GH_AW_HARNESS_WATCHDOG_TIMEOUT_MS	Post-terminal-safe-output stdio inactivity timeout, in milliseconds; default, minimum, maximum, and clamping behavior
GH_AW_HARNESS_MAX_RETRIES	Maximum harness retry count
GH_AW_HARNESS_INITIAL_DELAY_MS	Initial retry delay
GH_AW_HARNESS_BACKOFF_MULTIPLIER	Retry backoff multiplier
GH_AW_HARNESS_MAX_DELAY_MS	Maximum retry delay
GH_AW_HARNESS_LONG_RUN_TOKEN_THRESHOLD	Token threshold used to classify long-running partial executions
GH_AW_CLAUDE_STARTUP_RETRIES	Claude-specific startup retry behavior, if this remains a supported workflow setting
GH_AW_TIMEOUT_MINUTES	Relationship to workflow/agent timeout handling, or mark it internal if users should not set it

Also identify any equivalent Codex, Copilot, Claude, or shared harness settings missed by this list. Internal-only variables should be explicitly distinguished from supported workflow configuration rather than silently presented as public API.

Watchdog semantics that need explanation

The documentation should explain that:

• the watchdog is dormant until a terminal safe output is observed
• noop and ordinary task outputs such as comments, labels, pushes, and PR creation are terminal; diagnostic outputs such as missing_tool, missing_data, and report_incomplete are not
• after arming, 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
• a watchdog-fired process may be treated as successful when a terminal safe output already exists
• values are milliseconds and are clamped to the supported range

Suggested documentation

Add a user-facing Harness Settings or Runtime Tuning section and link it from:

• the environment variables reference
• engine/harness troubleshooting documentation
• timeout and workflow debugging documentation

Include a workflow-level example:

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

Explain that workflow-level env values are visible to the agent and must not contain secrets.

Acceptance criteria

• GH_AW_HARNESS_WATCHDOG_TIMEOUT_MS has a user-facing reference entry with units, default, range, and exact behavior.
• Supported retry and long-run settings are documented with defaults and units.
• Engine-specific versus shared settings are clearly identified.
• Internal-only variables are marked as such or omitted with an explanation in contributor documentation.
• At least one frontmatter example shows how to configure the watchdog.
• Troubleshooting guidance mentions silent long-running shell commands and builds.