PR #76192: fix(onboarding): prevent TUI hatch hang by adding timeouts, abort logic, and improved watchdog (#76132)

• Repository: openclaw/openclaw
• Author: michaelatamuk
• State: closed | merged: False
• Link: https://github.com/openclaw/openclaw/pull/76192

Description (problem / solution / changelog)

Summary

Problem:
On Ubuntu 26 with OpenAI Cloud, the onboarding flow (“Hatch in Terminal”) freezes during the initial agent hatch. The TUI becomes unresponsive, the watchdog fires after 30 seconds, and no assistant output is ever produced. Users cannot complete onboarding.

Why it matters:
This regression blocks first‑run onboarding for affected environments. The embedded TUI run can hang indefinitely due to silent provider stalls, OAuth delays, or missing final events — and the default 48‑hour timeout prevents recovery.

What changed:
This PR introduces a comprehensive fix across the TUI, embedded backend, and provider OAuth layer:

1. Added a 5‑minute default timeout for embedded TUI runs
2. Upgraded the streaming watchdog to actively abort stuck runs
3. Added a 5‑minute timeout wrapper around OpenAI OAuth flows
4. Added detailed diagnostic logging across all layers

What did NOT change:

• No changes to provider routing
• No changes to model selection
• No changes to session identity formats
• No changes to the hatch script or onboarding UI flow

Change Type

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope

• TUI / onboarding
• Embedded agent runtime
• Provider OAuth
• Gateway
• Skills / tools
• UI / DX
• CI/CD

Linked Issue/PR

• Closes #76132
• This PR fixes a regression

Root Cause

1. Embedded TUI runs inherited the global 48‑hour agent timeout

The onboarding hatch uses a local embedded run.
This run inherited the default 48‑hour timeout, meaning:

• If the provider stalled
• If OAuth hung
• If the model never emitted a final event

…the TUI would wait 48 hours before aborting.

2. The streaming watchdog only reset UI state

The watchdog fired after 30 seconds of no stream updates, but:

• It did not abort the run
• It did not surface an actionable error
• It did not break the hang

This left the TUI frozen.

3. OAuth authentication could hang indefinitely

The OpenAI OAuth flow had no timeout wrapper.
If the callback server stalled or the provider delayed, onboarding froze.

Regression Test Plan

• Coverage level that should have caught this:

  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient

• Target test or file:
  tui/tests/onboarding-hatch-timeout.spec.ts (recommended)

• Scenario the test should lock in:

  • Embedded TUI runs time out after 5 minutes
  • Watchdog aborts runs with no stream updates
  • OAuth authentication cannot hang indefinitely
  • TUI remains responsive to keystrokes

• Why this is the smallest reliable guardrail:
  Only an integration test can detect TUI freezes and silent provider stalls.

User-visible / Behavior Changes

• Onboarding no longer freezes during hatch
• TUI remains responsive
• If the provider stalls, users see a clear error message
• Users are guided to run:
  • openclaw models status
  • openclaw logs --follow
  • openclaw doctor
• OAuth failures now surface within 5 minutes instead of hanging indefinitely

Diagram

Before:
TUI hatch → provider stall → watchdog fires → UI resets but run still active
→ TUI frozen → no output → user stuck

After:
TUI hatch → provider stall → watchdog aborts run → 5-minute timeout fallback
→ clear error message → TUI remains responsive

Security Impact

• No new permissions
• No changes to secrets
• OAuth timeout improves safety by preventing indefinite hangs

Repro + Verification

Environment

• OS: Ubuntu 26
• OpenClaw: 2026.4.29
• Provider: OpenAI Cloud (gpt‑5.5)
• Install method: install script

Steps

1. Install OpenClaw
2. Choose “Hatch in Terminal (recommended)”
3. Observe TUI behavior

Expected

• Agent hatches normally
• If provider stalls, TUI aborts with clear diagnostics

Actual (before fix)

• TUI frozen
• Watchdog fired repeatedly
• No assistant output
• No keystroke response

Evidence

• Manual verification
• TUI test suite passing
• Logging verified
• Automated onboarding test (future work)

Human Verification

• Verified on Ubuntu 26
• Verified with OpenAI Cloud
• Verified both OAuth and non‑OAuth flows
• Verified TUI responsiveness after abort
• Verified watchdog behavior

Compatibility / Migration

• Backward compatible: Yes
• Config changes: No
• Migration needed: No

Risks and Mitigations

• Risk: Timeout too short for slow providers
  Mitigation: Timeout is configurable; 5 minutes is safe default

• Risk: Aborting runs may hide deeper provider issues
  Mitigation: Diagnostic logging now surfaces root causes

Code Changes Included in This PR

1. src/tui/embedded-backend.ts

• Added DEFAULT_TUI_TIMEOUT_MS = 300000
• Added timeout to embedded run lifecycle
• Added detailed logging for start, completion, abort

2. src/tui/tui-event-handlers.ts

• Watchdog now calls abortActive()
• Added structured error messages
• Improved recovery behavior

3. src/tui/tui.ts

• Added abort callback wiring
• Improved TUI responsiveness after abort

4. src/plugins/provider-openai-codex-oauth.ts

• Added withTimeout() helper
• Wrapped OAuth login with 5‑minute timeout
• Added detailed OAuth lifecycle logging

5. CHANGELOG.md

• Documented onboarding hatch regression and fix

Changed files

• CHANGELOG.md (modified, +1/-0)
• src/plugins/provider-openai-codex-oauth.ts (modified, +46/-12)
• src/tui/embedded-backend.ts (modified, +26/-1)
• src/tui/tui-event-handlers.ts (modified, +28/-8)
• src/tui/tui.ts (modified, +1/-0)

PR #76241: Wizard: bound hatch TUI timeout

• Repository: openclaw/openclaw
• Author: joshavant
• State: closed | merged: True
• Link: https://github.com/openclaw/openclaw/pull/76241

Description (problem / solution / changelog)

Summary

• Problem: onboarding Terminal hatch launches the local TUI with the bootstrap wake message but without a bounded run timeout, so a provider stream that stops producing updates can leave the hatch run stuck behind the watchdog recovery state.
• Why it matters: first-run users can reach local ready | idle after the 30s watchdog while the original embedded run is still hanging, making hatch look broken.
• What changed: setup now passes a 5 minute timeout into the stock Terminal hatch launch, and tests cover setup -> TUI launch -> embedded agent timeout propagation.
• What did NOT change (scope boundary): this does not change the default timeout for normal user-started TUI sessions, and it does not add a new user-facing switch requirement.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Related #76132
• Related #76192
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: the setup hatch path auto-sent Wake up, my friend! through launchTuiCli without a timeout, so the embedded TUI run fell back to the agent default timeout instead of a bounded first-run hatch timeout.
• Missing detection / guardrail: tests covered relaunch argument filtering and embedded abort behavior, but not the setup hatch timeout contract across setup, launch, and embedded agent command conversion.
• Contributing context: the TUI watchdog resets visible streaming state after 30s without necessarily aborting the underlying provider request.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/wizard/setup.finalize.test.ts, src/tui/tui-launch.test.ts, src/tui/embedded-backend.test.ts
• Scenario the test should lock in: setup Terminal hatch passes timeoutMs: 300_000; TUI relaunch converts that to --timeout-ms 300000; embedded local chat converts it to agent timeout seconds.
• Why this is the smallest reliable guardrail: it validates the exact timeout propagation chain without depending on a real provider outage.
• Existing test that already covers this (if any): none before this PR.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

Terminal hatch from setup now has a stock/default 5 minute timeout for the bootstrap wake run. Users do not need to pass a new switch.

Diagram (if applicable)

Before:
setup hatch -> TUI --message "Wake up, my friend!" -> embedded run uses long default timeout

After:
setup hatch -> TUI --message "Wake up, my friend!" --timeout-ms 300000 -> embedded run timeout=300s

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: macOS local dev host; controlled loopback provider stall harness; earlier smoke also used real OpenAI from an isolated local state dir.
• Runtime/container: Node/pnpm local repo checkout.
• Model/provider: openai/gpt-5.5; controlled repro points models.providers.openai.baseUrl at a loopback OpenAI-compatible stall server.
• Integration/channel (if any): local embedded TUI hatch path.
• Relevant config (redacted): isolated OPENCLAW_HOME, OPENCLAW_STATE_DIR, and OPENCLAW_CONFIG_PATH; fake local OPENAI_API_KEY for controlled stall.

Steps

1. Reproduced the timeout contract failure on the unfixed path: setup hatch did not pass timeoutMs, and PR #76192's timeout approach still allowed the 48h default to win in the deterministic check.
2. Used a temporary local repro harness to run the TUI under a pty against a loopback /v1/responses endpoint that intentionally stalls; the harness was not kept in the final branch.
3. Ran the controlled stall against an unfixed checkout and observed the wake message, the 30s streaming watchdog, return to idle, and the provider request remaining open.
4. Ran the controlled stall with an explicit short timeout and observed the stalled provider socket close at approximately the configured timeout.
5. Ran real OpenAI smoke on both fixed and unfixed checkouts; OpenAI completed normally during those runs, so the natural live OpenAI hang did not reproduce.

Expected

• Setup Terminal hatch should bound the bootstrap run without requiring a user-provided CLI switch.
• A stalled provider request should be abortable by the timeout passed through the TUI path.

Actual

• Fixed branch passes timeoutMs: 300_000 from setup hatch and propagates it through the TUI relaunch and embedded agent command.
• Controlled stall with --timeout-ms 5000 closed the stalled provider socket at about 5s.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Key local validation:

temporary local hatch-stall harness against an unfixed checkout
=> sawWakeMessage=true, sawWatchdog=true, sawIdle=true, responsesRequestClosedBeforeWall=false, responsesRequestCount=1

temporary local hatch-stall harness with --timeout-ms 5000
=> responsesRequestClosedBeforeWall=true, responsesRequestCloseDelayMs≈4980

Commands run after the final rebase:

pnpm exec oxfmt --check --threads=1 src/wizard/setup.finalize.ts src/wizard/setup.finalize.test.ts src/tui/tui-launch.test.ts src/tui/embedded-backend.test.ts
pnpm test src/wizard/setup.finalize.test.ts src/tui/tui-launch.test.ts src/tui/embedded-backend.test.ts

Human Verification (required)

• Verified scenarios: setup hatch timeout propagation; TUI relaunch timeout argument; embedded local chat timeout conversion; controlled provider stall aborts when timeout is present; controlled unfixed stall reaches watchdog and idle while request remains open.
• Edge cases checked: no natural OpenAI stall occurred during real OpenAI smoke, so the real provider path completed normally on both fixed and unfixed checkouts.
• What you did not verify: I did not validate that the real OpenAI Cloud service naturally reproduces every reported symptom from #76132 today, and a Ctrl-C liveness probe showed the unfixed TUI was not frozen to all keystrokes after the watchdog.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: a slow but still healthy first-run hatch could be interrupted after 5 minutes.
  • Mitigation: the timeout only applies to setup's bootstrap hatch run, not normal TUI sessions; 5 minutes is intentionally longer than the 30s UI watchdog and long enough for ordinary first responses.

Changed files

• CHANGELOG.md (modified, +1/-0)
• src/tui/embedded-backend.test.ts (modified, +29/-0)
• src/tui/tui-launch.test.ts (modified, +29/-0)
• src/wizard/setup.finalize.test.ts (modified, +47/-0)
• src/wizard/setup.finalize.ts (modified, +2/-0)