docs(agent): document the host deadline bound and how to raise a timeout

`nemoclaw <name> agent` gained a host-side deadline and a nonzero exit for a
timed-out turn, and neither was described anywhere. The recovery question
#8723 raised was also unanswered: a reader who hit a timeout had no documented
way to give the next attempt more time.

Describe the host bound in the command reference, including the three argv
forms that leave the OpenShell wait unbounded, and record that a turn whose
deadline fired now exits 1 rather than the upstream 0. Add `timeoutPhase` to
the JSON completion markers that already produce that exit.

Explain in the inference timeout page that the two configuration keys bound
different deadlines. `agents.defaults.timeoutSeconds` bounds the run and
`agent --timeout` overrides it for a single run; the provider request keeps
`models.providers.<provider-id>.timeoutSeconds`, which no flag overrides.
Every timeout measured for #8723 fired in the provider phase, so a reader who
raises only the run deadline is not helped. Add the in-place procedure beside
the existing rebuild instruction.

Name those same commands in the failure text, so an operator reads the
documented `shields down` and `config set --restart` pair instead of an
instruction to edit a file.

Signed-off-by: Hung Le <hple@nvidia.com>

Author: hunglp6d

docs/inference/configure-inference-timeouts.mdx

@@ -46,6 +46,18 @@ $$nemoclaw onboard
 This setting is baked into the sandbox image.
 Recreate an existing sandbox to apply a new value.
 
+Each key bounds a different deadline.
+`agents.defaults.timeoutSeconds` bounds one agent run, and `$$nemoclaw <name> agent --timeout <seconds>` overrides it for a single run.
+`models.providers.<provider-id>.timeoutSeconds` bounds one provider request, and no flag overrides it.
+Raise the provider key when a turn times out while waiting for the model server, because a longer `--timeout` does not extend the provider request.
+
+To change a deadline on an existing sandbox instead of recreating it, lower shields first and write the key directly.
+
+```bash
+$$nemoclaw <sandbox-name> shields down
+$$nemoclaw <sandbox-name> config set --key agents.defaults.timeoutSeconds --value 1800 --restart
+```
+
 </AgentOnly>
 
 <AgentOnly variant="hermes">

docs/reference/commands.mdx

@@ -1288,6 +1288,17 @@ Because a delivered turn always writes to one of the two streams, the wrapper re
 The wrapper prints recovery guidance to `stderr` and exits with status `1`.
 Pressing `Ctrl+C` interrupts the OpenShell child, and sending `SIGTERM` to the host wrapper forwards `SIGTERM` to that child.
 NemoClaw waits for OpenShell to stop the in-sandbox turn, replays captured output, and returns status `130` for `SIGINT` or `143` for `SIGTERM`.
+When the forwarded argv sets `openclaw agent --timeout <seconds>`, both captured paths bound the OpenShell command at that value plus 30 seconds.
+The extra seconds let the in-sandbox turn report its own timeout first, so the host bound catches only a turn that stops answering.
+
+These leave the OpenShell wait unbounded:
+
+- `--timeout 0`.
+- A value NemoClaw cannot read as a positive whole number of seconds.
+- An argv without `--timeout`.
+
+When the captured output reports that the turn's deadline fired, the wrapper replays the partial output and writes deadline guidance to `stderr`.
+It exits with status `1` instead of the upstream status `0`.
 The diagnostic shell-quotes the sandbox name and forwarded arguments, then redacts detected credential values before writing the recovery command to `stderr`.
 If redaction changes the recovery command, the diagnostic tells you not to replay it; otherwise, it labels the command as runnable inside the sandbox.
 For a registered sandbox, both captured paths pin the sandbox's recorded gateway with an explicit `-g`.
@@ -1297,11 +1308,12 @@ Raw `stderr`, including structured JSON diagnostics, is forwarded unchanged.
 NemoClaw appends failed-tool or untrusted-child provenance only from the `stdout` JSON.
 The wrapper reads completion markers only from the final matching OpenClaw response envelope: a local `{ payloads, meta }` response or a gateway `{ status, result: { payloads, meta } }` response.
 It ignores earlier JSON progress or log records.
-It exits with status `1` when that metadata contains `error.kind: "incomplete_turn"`, `livenessState: "abandoned"`, or `replayInvalid: true`, even when the envelope reports success.
+It exits with status `1` when that metadata contains `error.kind: "incomplete_turn"`, `livenessState: "abandoned"`, `replayInvalid: true`, or a `timeoutPhase` value, even when the envelope reports success.
 Marker-shaped values inside tool results, tool-call arguments, or other descendants do not change the exit status.
 A turn can run every tool successfully and still become abandoned before it produces a reply.
 The wrapper writes the unchanged JSON trace to `stdout` before it reports the incomplete turn, so the partial tool trace remains available.
 The wrapper writes the verdict, the detected markers, and verify-before-retry guidance to `stderr`.
+A `timeoutPhase` value names the phase the deadline fired in, so the wrapper writes deadline guidance in place of the generic incomplete-turn text.
 Tool calls in a partial trace may have already applied side effects, so verify what the turn changed before you retry it.
 The wrapper passes through an upstream non-zero exit status unchanged.
 Literal `--json` values consumed by flags such as `-m` or `--reply-channel`, or arguments after `--`, stay on the normal passthrough path.

src/lib/actions/sandbox/agent/passthrough-help.test.ts

@@ -189,14 +189,20 @@ describe("writeTimedOutAgentTurnFailure", () => {
     expect(written).toContain("before retrying");
   });
 
-  it("offers the transcript export as the runnable recovery path (#8723)", () => {
+  it("offers the documented commands that read the trace and raise a deadline (#8723)", () => {
     const { lines, proc } = collectStderr();
 
     writeTimedOutAgentTurnFailure(proc, "my-assistant");
 
     const written = lines.join("");
     expect(written).toContain("'my-assistant' sessions list");
     expect(written).toContain("'my-assistant' sessions export <key>");
+    expect(written).toContain(
+      "'my-assistant' config set --key <deadline-key> --value <seconds> --restart",
+    );
+    // Writing the config fails while shields are up, so the order is part of
+    // the guidance rather than a detail the reader has to discover.
+    expect(written.indexOf("shields down")).toBeLessThan(written.indexOf("config set"));
   });
 
   it("names both deadlines instead of offering --timeout as the fix (#8723)", () => {
@@ -205,11 +211,9 @@ describe("writeTimedOutAgentTurnFailure", () => {
     writeTimedOutAgentTurnFailure(proc, "my-assistant", "provider");
 
     const written = lines.join("");
-    expect(written).toContain("agents.defaults.timeoutSeconds sets the run deadline");
-    expect(written).toContain(
-      "models.providers.<id>.timeoutSeconds sets the provider request deadline",
-    );
-    expect(written).toContain("never changes");
+    expect(written).toContain("agents.defaults.timeoutSeconds bounds the run");
+    expect(written).toContain("models.providers.<id>.timeoutSeconds");
+    expect(written).toContain("no flag overrides it");
     // A provider-phase timeout does not respond to the flag, so it is never
     // presented as a runnable recovery command.
     expect(written).not.toMatch(/^ {4}\S*nemoclaw.* agent --timeout/m);

src/lib/actions/sandbox/agent/passthrough-help.ts

@@ -120,13 +120,19 @@ export function writeTimedOutAgentTurnFailure(
   proc.stderr.write(
     `    ${CLI_NAME} ${target} sessions export <key>  — export the partial transcript\n`,
   );
-  proc.stderr.write("  A longer deadline is an openclaw.json change, not a flag.\n");
   proc.stderr.write(
-    "  agents.defaults.timeoutSeconds sets the run deadline, which `agent --timeout` overrides for one run.\n",
+    `    ${CLI_NAME} ${target} shields down           — unlock configuration writes\n`,
   );
   proc.stderr.write(
-    "  models.providers.<id>.timeoutSeconds sets the provider request deadline, which `agent --timeout` never changes.\n",
+    `    ${CLI_NAME} ${target} config set --key <deadline-key> --value <seconds> --restart  — raise the deadline\n`,
   );
+  proc.stderr.write(
+    "  Two keys carry a deadline. agents.defaults.timeoutSeconds bounds the run, and\n",
+  );
+  proc.stderr.write(
+    "  `agent --timeout <seconds>` overrides it for a single run. models.providers.<id>.timeoutSeconds\n",
+  );
+  proc.stderr.write("  bounds the provider request, and no flag overrides it.\n");
   proc.stderr.write("  Inspect the partial output and affected resources before retrying.\n");
 }