Fix doc inconsistency.

Author: beacoder

README.md

@@ -333,6 +333,15 @@ with a `result` line carrying `errors[].code` of `budget` or `timeout`
 plus the token usage consumed — a host bills and reports it like any
 other outcome.
 
+`timeout` is **cooperative** — checked between rounds, not by a
+watchdog — so it bounds work at those checkpoints but does not
+forcibly interrupt a blocking operation mid-round (a hung tool, a slow
+network read, or a run parked on a mid-run question awaiting a human
+answer). Use `--answer-timeout` to cap how long an ask waits, and rely
+on the hosting process's own exec watchdog (which sends `cancel` then
+kills) as the hard wall-clock stop for anything the cooperative budget
+cannot reach.
+
 ### Slash commands
 
 | Command | Description |

diff.txt

@@ -0,0 +1,58 @@
+diff --git a/README.md b/README.md
+index 93296de..f1c8fea 100644
+--- a/README.md
++++ b/README.md
+@@ -333,6 +333,15 @@ with a `result` line carrying `errors[].code` of `budget` or `timeout`
+ plus the token usage consumed — a host bills and reports it like any
+ other outcome.
+ 
++`timeout` is **cooperative** — checked between rounds, not by a
++watchdog — so it bounds work at those checkpoints but does not
++forcibly interrupt a blocking operation mid-round (a hung tool, a slow
++network read, or a run parked on a mid-run question awaiting a human
++answer). Use `--answer-timeout` to cap how long an ask waits, and rely
++on the hosting process's own exec watchdog (which sends `cancel` then
++kills) as the hard wall-clock stop for anything the cooperative budget
++cannot reach.
++
+ ### Slash commands
+ 
+ | Command | Description |
+diff --git a/python_agent_harness/entry/cli.py b/python_agent_harness/entry/cli.py
+index 110ac2c..d627070 100644
+--- a/python_agent_harness/entry/cli.py
++++ b/python_agent_harness/entry/cli.py
+@@ -510,8 +510,10 @@ def build_parser() -> argparse.ArgumentParser:
+         metavar="SECONDS",
+         type=float,
+         default=None,
+-        help="wall-clock limit for EACH run in seconds (per-submit budget; "
+-        "default: config serve.timeout, else unlimited)",
++        help="wall-clock limit for EACH run in seconds (per-submit budget, "
++        "cooperative — checked between rounds, does not interrupt a run "
++        "blocked on a mid-run question; default: config serve.timeout, else "
++        "unlimited)",
+     )
+     return parser
+ 
+diff --git a/python_agent_harness/entry/server.py b/python_agent_harness/entry/server.py
+index 3154e9e..e4931c3 100644
+--- a/python_agent_harness/entry/server.py
++++ b/python_agent_harness/entry/server.py
+@@ -79,6 +79,15 @@ unwinds the agent loop through its normal path, so the run still ends
+ with a ``result`` line carrying ``errors[].code`` of ``budget`` or
+ ``timeout`` plus the usage consumed.
+ 
++The ``timeout`` is COOPERATIVE: it is checked between rounds, not by a
++watchdog, so it bounds work at those checkpoints but does not forcibly
++interrupt a blocking operation mid-round — a hung tool, a slow HTTP
++read, or a run parked on a mid-run ``ask`` awaiting a human answer.
++Bound those separately: ``--answer-timeout`` caps how long an ask
++waits, and the hosting process's own exec watchdog (it already sends
++``cancel`` then kills) is the hard wall-clock stop for anything the
++cooperative budget cannot reach.
++
+ Concurrency: one run at a time (the web controller already enforces
+ "one running run per conversation"); a submit while a run is active is
+ rejected with an ``error`` line.  The reader loop stays live while a
+

python_agent_harness/entry/cli.py

@@ -510,8 +510,10 @@ def build_parser() -> argparse.ArgumentParser:
         metavar="SECONDS",
         type=float,
         default=None,
-        help="wall-clock limit for EACH run in seconds (per-submit budget; "
-        "default: config serve.timeout, else unlimited)",
+        help="wall-clock limit for EACH run in seconds (per-submit budget, "
+        "cooperative — checked between rounds, does not interrupt a run "
+        "blocked on a mid-run question; default: config serve.timeout, else "
+        "unlimited)",
     )
     return parser
 

python_agent_harness/entry/server.py

@@ -79,6 +79,15 @@
 with a ``result`` line carrying ``errors[].code`` of ``budget`` or
 ``timeout`` plus the usage consumed.
 
+The ``timeout`` is COOPERATIVE: it is checked between rounds, not by a
+watchdog, so it bounds work at those checkpoints but does not forcibly
+interrupt a blocking operation mid-round — a hung tool, a slow HTTP
+read, or a run parked on a mid-run ``ask`` awaiting a human answer.
+Bound those separately: ``--answer-timeout`` caps how long an ask
+waits, and the hosting process's own exec watchdog (it already sends
+``cancel`` then kills) is the hard wall-clock stop for anything the
+cooperative budget cannot reach.
+
 Concurrency: one run at a time (the web controller already enforces
 "one running run per conversation"); a submit while a run is active is
 rejected with an ``error`` line.  The reader loop stays live while a