docs: state that workflow_deadline_seconds is only enforced on sync

[mrthankyou]

Summary

[run].workflow_deadline_seconds reads like a guaranteed wall-clock limit, but it is only checked inside run synchronization, which runs only when an operator command touches the run (run once at launch, then status, inspect, why, stats). An unattended run keeps executing, and keeps incurring provider cost, past its deadline (#1110).

This PR is documentation only. In docs/reference/configuration.md it:

• rewords the workflow_deadline_seconds row in the [run] table
• adds a paragraph explaining when the deadline is actually checked, what happens when it fires (cancel, timed-out, workflow-deadline-exceeded event), and how to bound an unattended run today (periodic ultrafuzz status, or ultrafuzz cancel)

No behavior change.

Context

The proper fix is enforcing the deadline inside the workflow engine. Smithers has no run-level deadline today; it is proposed in smithersai/smithers#1683. #1110 stays open to track that.

Test plan

• pnpm docs:check
• prettier --check docs/reference/configuration.md

Refs #1110

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge, though the periodic-status guidance should be corrected so operators can detect skipped deadline checks.

Findings

1.  Status warnings can be hidden ▶

Fix with agent prompt

### Issue 1
docs/reference/configuration.md:155-156
The suggested periodic `ultrafuzz status` check may not show the warnings operators are told to act on. If synchronization is skipped because control evidence has diverged, `status` returns a successful result with a warning, but plain-text output omits diagnostics for successful results. A cron check can therefore appear to succeed even though the deadline was not checked. Recommend using JSON output and inspecting its diagnostics, or making the warning visible in plain-text output.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

The PR clarifies that the workflow deadline is checked during run synchronization rather than enforced by a timer.

• Documents synchronization entry points, conditional timeout outcomes, and options for monitoring or cancelling unattended runs.
• The suggested plain-text status monitoring does not display a warning when synchronization is skipped.

_{Reviews (3) · Last reviewed commit: "docs: correct when workflow_deadline_sec..."}

[greptile-apps]

Status warnings can be hidden

The suggested periodic ultrafuzz status check may not show the warnings operators are told to act on. If synchronization is skipped because control evidence has diverged, status returns a successful result with a warning, but plain-text output omits diagnostics for successful results. A cron check can therefore appear to succeed even though the deadline was not checked. Recommend using JSON output and inspecting its diagnostics, or making the warning visible in plain-text output.

Prompt To Fix With AI

This is a comment left during a code review.
Path: docs/reference/configuration.md
Line: 155-156

Comment:
**Status warnings can be hidden**

The suggested periodic `ultrafuzz status` check may not show the warnings operators are told to act on. If synchronization is skipped because control evidence has diverged, `status` returns a successful result with a warning, but plain-text output omits diagnostics for successful results. A cron check can therefore appear to succeed even though the deadline was not checked. Recommend using JSON output and inspecting its diagnostics, or making the warning visible in plain-text output.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[aviggiano]

Corrected the paragraph in 5382af9 against current code: ultrafuzz run never synchronizes; the deadline is anchored at run creation and re-armed by resume/replay/fork; paused and pending runs are also timed out; a failed or skipped synchronization does not check the deadline; the dashboard inspect action and the eval poll loop also synchronize.