Add a whole-run deadline to CLI execution

docs/cli.md

@@ -64,6 +64,7 @@ Optional flags:
 | `--top-p <float>` | Runtime top-p override. |
 | `--reasoning-effort <value>` | Runtime reasoning-effort override. |
 | `--timeout <duration>` | Runtime timeout override using Go duration syntax. |
+| `--run-timeout <duration>` | Optional whole-run engine deadline using Go duration syntax; zero or omission adds no deadline, negative values are invalid. |
 | `--transient-retries <integer>` | Nonnegative additional transient attempt count for this request; `0` disables additional attempts. |
 
 Deprecated aliases: `--prompt-id` for `--prompt`, and `--profile-id` for
@@ -78,6 +79,13 @@ zero-second override. The timeout layers are defined in the
 [Promptkit outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/integrations/openai-compatible-chat.md#timeout-and-cancellation).
 With the built-in client, each transient retry gets a fresh generation timeout;
 this flag does not limit the complete run.
+`--run-timeout` keeps subsecond precision and starts immediately before engine
+execution. It bounds preparation, capacity waits, retry waits, generation, and
+repairs where they honor context. Parsing, engine construction, and output
+writes are outside that interval. A failed run whose execution context reaches
+this deadline exits 1 with a safe deadline diagnostic; a completed invalid
+output still exits 2. It does not promise immediate interruption of synchronous
+work.
 Omitting `--transient-retries` inherits the application setting or Promptkit's
 current default of two additional attempts. The flag overrides only this
 request; it does not alter the configured engine. Structural repair generations

docs/integrations/subprocess.md

@@ -37,5 +37,11 @@ process according to its own process-management policy. A later invocation is a
 new request and can make another model call; there is no resume or checkpoint
 protocol.
 
+For `run`, callers may set the [whole-run deadline](../cli.md) to bound the
+engine invocation. It is separate from the per-attempt generation timeout and
+does not include child startup or output writing. A deadline failure exits 1;
+supervisors still own process termination when they need to stop the child
+outside that engine interval.
+
 For deployment, filesystem permissions, and sensitive-artifact handling, see
 the [operations guide](../operations.md).

docs/operations.md

@@ -123,6 +123,12 @@ per attempt, while the caller context covers the complete operation. Provider
 [outbound integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/integrations/openai-compatible-chat.md)
 for details.
 
+CLI `run` can set a [whole-run deadline](cli.md) when total execution time must
+be bounded. The existing generation timeout applies afresh to each attempt and
+does not cap retry waits or the complete invocation. The whole-run interval
+covers the engine call, including capacity waiting and repairs as supported by
+context cancellation; it excludes parsing, engine setup, and output writes.
+
 Before increasing a limit:
 
 1. measure representative input, generated-output, and optional raw-output

docs/roadmap/implementation.md

@@ -176,7 +176,7 @@ body text exposes provider diagnostics or secrets.
 
 ## Stage 4: Add The CLI Whole-Run Deadline
 
-**Status: Pending.**
+**Status: Complete.**
 
 Selected interface: `run --run-timeout <Go duration>`. Omission or zero adds
 no deadline, a positive duration retains full duration precision, and a negative