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 [Bug]: Onboarding Bug - Stuck at Hatching #76132
• Related fix(onboarding): prevent TUI hatch hang by adding timeouts, abort logic, and improved watchdog (#76132) #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 fix(onboarding): prevent TUI hatch hang by adding timeouts, abort logic, and improved watchdog (#76132) #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 [Bug]: Onboarding Bug - Stuck at Hatching #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.