Codex review: needs maintainer review before merge. Reviewed July 6, 2026, 12:15 AM ET / 04:15 UTC.

Summary
Adds starting up to the TUI busy activity set, claims it during post-connect initialization only when no busy run owns the status line, and adds unit plus PTY coverage.

PR surface: Source +12, Tests +24. Total +36 across 3 files.

Reproducibility: yes. by source inspection: current main and v2026.6.11 set local ready or connected before awaited post-connect initialization while the busy-status set excludes startup initialization. I did not run a live interactive Hatch session in this read-only review.

Review metrics: none identified.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #74385
Summary: This PR is the active candidate fix for the canonical Terminal Hatch missing-startup-loader issue; earlier loader work was closed unmerged, and nearby Hatch timeout work covered a different stuck-Hatch mode.

Members:

• canonical: [Bug]: Stuck and ultra slow during Hatch (terminal mode) - took a minute to come back up #74385 - The PR body uses closing syntax for this issue, and the issue discussion identifies this PR as the active candidate fix.
• superseded: fix(tui): show loading status during hatch initialization (#74385) #75120 - The earlier PR attempted the same startup-loader fix but is closed unmerged after correctness and proof problems.
• partial_overlap: [Bug]: Onboarding Bug - Stuck at Hatching #76132 - That issue also reports Hatch appearing stuck, but its evidence centers on watchdog/provider timeout behavior rather than only the missing post-connect loader.
• partial_overlap: Wizard: bound hatch TUI timeout #76241 - That merged PR bounded the Hatch bootstrap timeout for a related flow but did not add this post-connect startup activity loader.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🦞 diamond lobster
Proof: 🦞 diamond lobster
Patch quality: 🦞 diamond lobster
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Next step before merge

• [P2] No repair lane is needed; the maintainer action is to wait for exact-head CI and normal merge checks on 5ec2bb19ff5df5f83183ef18fcbb49cac01f6d4c, then land or close the PR.

Security
Cleared: Cleared: the diff only changes TUI status logic and tests, with no dependency, workflow, secret, package, download, or code-execution surface change.

Addressed the correctness concern from the last review: the post-connect onConnected path unconditionally cleared the activity status to idle right after loadHistory(), which clobbered the streaming status loadHistory() sets when it adopts a gateway-reported in-flight run — hiding the resumed run's work (the same freeze symptom this loader fix targets).

Changes:

• loadHistory() now returns Promise<boolean> — true when it adopted an in-flight run and set streaming.
• onConnected only clears the startup starting up status to idle when loadHistory() did not adopt an in-flight run; otherwise the resumed run keeps its streaming status.
• Widened the loadHistory type in the tui-command-handlers / tui-event-handlers consumer interfaces to match.
• Added a regression test asserting loadHistory() returns true on adoption and false when no in-flight run exists.

Verified: tsgo clean, scoped oxlint clean, tui-session-actions (34) + tui-command-handlers/tui-event-handlers/tui (201) tests pass.

@clawsweeper re-review

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Addressed the remaining review finding (Preserve reconnect-owned streaming before startup — src/tui/tui.ts:1548):

reconnectStreamingWatchdog() can restore streaming for a still-active run, but onConnected then unconditionally overwrote it with starting up. The startup status is now gated:

• New resolveStartupActivityStatus(currentStatus) claims starting up only when no active-run status (streaming/running/finishing context) owns the line; otherwise it preserves the existing status. onConnected uses it for the initial set.
• The post-init idle clear is now gated the same way, so a reconnect-owned active-run status (or an in-flight run adopted by loadHistory(), which sets streaming) is not clobbered.
• Added isTuiActiveRunActivityStatus + resolveStartupActivityStatus helpers and reconnect regression tests (resolveStartupActivityStatus preserves streaming/running/finishing context).

Verified: tsgo + tsgo:core:test clean, scoped oxlint clean, tui/tui-session-actions/tui-command-handlers tests pass (159). Updated the PR body's Real behavior proof to exercise the real exported helpers and document the reconnect-preservation behavior.

On the real-interactive-proof ask: the TUI requires an interactive TTY and won't boot headless on Windows (Crestodian needs an interactive TTY); the PTY harness only runs reliably in the Linux CI shard with a fake backend. A real interactive TUI/Hatch recording needs a real backend on hardware — per the review, a maintainer can capture it with @openclaw-mantis visual task: capture OpenClaw TUI during slow post-connect initialization and verify the starting up loader appears without hiding active streaming after reconnect.

@clawsweeper re-review

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Added real-render PTY evidence to the PR body (addressing the "helper terminal output" gap):

Captured the ACTUAL rendered terminal bytes from the production runTui()/onConnected/renderStatus()/Loader path under a real Linux PTY (Node v22.22.0, ssh lxy-tx), via src/tui/tui-pty-harness.e2e.test.ts "shows a busy startup loader during post-connect initialization" with OPENCLAW_TUI_PTY_MIRROR_PATH set to mirror the raw PTY output. A slow post-connect init fixture makes the loader window visible (the scenario issue #74385 reports).

AFTER (PR head 0a5b6eb) — real rendered status line:

starting up • 0s | starting local runtime   <- busy loader renders during post-connect init
local ready | idle                          <- static ready line once init completes

BEFORE (upstream main) — real rendered status line, same harness:

"starting up" busy-loader frames during init: 0
local ready | idle                          <- no loader; init shows no spinner (looks frozen)

So on main the loader never renders during init (0 "starting up" frames); on the PR head the busy "starting up" loader renders during post-connect init then clears to the unchanged "local ready | idle" ready line. The reconnect-owned-streaming preservation half is covered by the real exported resolveStartupActivityStatus (preserves streaming/running/finishing context) plus the resolveStartupActivityStatus unit tests.

Honest scope: the render path driven is production code under a real PTY, but the harness backend is a test fixture (not a live gateway/embedded runtime), and a slow-init fixture makes the loader window visible. A real-backend interactive Terminal Hatch recording on physical hardware is still outstanding — a maintainer can capture it via @openclaw-mantis visual task: capture OpenClaw TUI during slow post-connect initialization and verify the starting up loader appears without hiding active streaming after reconnect.

@clawsweeper re-review

Strengthened the proof with a REAL embedded-backend local runtime capture (not the fake-backend harness):

Ran src/tui/tui-pty-local.e2e.test.ts on Linux (Node v22.22.0) — this drives the REAL local embedded runtime under a real PTY, with only the upstream model HTTP endpoint mocked (the embedded runtime / onConnected / session / loadHistory path is real). It boots, post-connect init completes, the status line reaches local ready | idle, and a full chat round-trip returns LOCAL_PTY_RESPONSE:

local ready | idle
(user) send the local PTY smoke response
(assistant) LOCAL_PTY_RESPONSE

So the real local runtime/session path is exercised end-to-end (this is not the fake-backend harness barred by src/tui/AGENTS.md). The "starting up" busy loader itself only paints when post-connect init is slow; on a fresh workspace the real init is fast, so the loader's paint is shown via the slow-init fixture (real runTui/renderStatus/Loader render path) in the PR body:

starting up • 0s | starting local runtime   <- busy loader during slow post-connect init
local ready | idle

and on upstream main the same harness renders 0 "starting up" frames (no loader — the reported freeze).

The remaining gap is a real interactive Terminal Hatch run with naturally slow first-run init on physical hardware, which the contributor cannot capture (Windows host cannot boot the TUI headless). That can be captured via @openclaw-mantis visual task: capture OpenClaw TUI during slow post-connect initialization and verify the starting up loader appears without hiding active streaming after reconnect.

@clawsweeper re-review

@steipete @vincentkoc — requesting a maintainer Mantis capture for the one piece of proof I could not produce as an external contributor.

What the fix does (bot-endorsed): adds a starting up busy activity status so the TUI shows the loader during post-connect init instead of looking frozen; gates it so it never overwrites a reconnect-owned streaming/running/finishing context status, and so the post-init idle clear doesn't clobber an in-flight run adopted by loadHistory(). ClawSweeper rates patch 🐚 platinum (the source blocker is resolved) — the only holdup is proof.

The proof I could and couldn't capture (all on Linux, real runTui/renderStatus/Loader):

Captured (in the PR body):

1. Real-PTY render capture via tui-pty-harness.e2e.test.ts slow-init fixture, with OPENCLAW_TUI_PTY_MIRROR_PATH mirroring the actual rendered terminal bytes. AFTER (PR head): starting up • 0s | starting local runtime → local ready | idle. BEFORE (main): 0 starting up frames, jumps straight to local ready | idle (no loader — the reported freeze).
2. Real embedded-backend local-runtime run via tui-pty-local.e2e.test.ts (only the upstream model HTTP endpoint mocked; the embedded runtime / onConnected / session / loadHistory path is real): boots, reaches local ready | idle, full chat round-trip returns LOCAL_PTY_RESPONSE.

Could NOT capture (the gap):

• The starting up loader painting during a naturally slow real-backend init. Per src/tui/AGENTS.md, the fake-backend slow-init fixture (item 1) must not be claimed as proof of the embedded runtime itself, so it shows the loader render but not against a real backend.
• I tried to make the real embedded-backend init slow enough for the loader to paint, on a Linux box: flipped skipBootstrap: true→false, raised LOCAL_STARTUP_TIMEOUT_MS (20s→120s) + LOCAL_TEST_TIMEOUT_MS (150s→300s), and added a 2.5s delay to the mock /v1/models endpoint (all temporary, reverted). None painted the loader — the real local onConnected init completes faster than the first render tick, so setActivityStatus("starting up") is set and cleared before any frame renders; the capture contains 0 starting up frames and goes straight to local ready | idle.
• The loader is only visible when post-connect init is genuinely multi-second slow, which happens in the real heavy first-run Terminal Hatch environment (model discovery, agent bootstrap, large history restore) — not reproducible on a fresh-temp-workspace Linux box, and the TUI requires an interactive TTY so it won't boot headless on my Windows host (Crestodian needs an interactive TTY).

So the one missing artifact is a real interactive Terminal Hatch run with naturally slow first-run init showing the starting up loader — which needs real Hatch hardware a contributor can't easily provide.

ClawSweeper itself flags this as the sole remaining rank-up move and suggests exactly this capture. Could a maintainer run it?

@openclaw-mantis visual task: capture OpenClaw TUI during slow post-connect initialization and verify the starting up loader appears without hiding active streaming after reconnect.

CI is fully green (65/65) on 0a5b6eb8f2. Thanks for looking.

Maintainer refresh complete at bd748975324.

What changed:

• replaced the stale multi-helper patch with one ownership rule on current main: startup claims the activity line only when no busy run owns it, and clears only the exact starting up state it created;
• preserved reconnect-restored streaming/running states without widening the loadHistory API;
• added focused status coverage and a real PTY test with deliberately delayed post-connect initialization;
• preserved contributor credit in the replacement commit.

Verification:

• node scripts/run-vitest.mjs src/tui/tui.test.ts — 66 tests passed
• node scripts/run-vitest.mjs run --config test/vitest/vitest.tui-pty.config.ts — 18 PTY scenarios passed
• pnpm check:changed -- src/tui/tui.ts src/tui/tui.test.ts src/tui/tui-pty-harness.e2e.test.ts
• fresh branch autoreview: no accepted/actionable findings

Remote proof: Blacksmith Testbox through Crabbox, tbx_01kwtkghw4hd4pxzwt7esdrc4c (tidal-shrimp), Actions run https://github.com/openclaw/openclaw/actions/runs/28763626933. The PTY visibly showed starting up before local ready | idle.

Thanks @ml12580 for the original diagnosis and fix direction.

Exact-head land-ready update: 5ec2bb1 is the clean current-main-plus-reviewed-patch head. Hosted CI run https://github.com/openclaw/openclaw/actions/runs/28767169467 passed at that exact SHA. The rebase changed ancestry only; the tested diff and Testbox/browser/PTY proof above are unchanged. Known proof gaps: none.

Merged via squash.

• Prepared head SHA: 5ec2bb19ff5df5f83183ef18fcbb49cac01f6d4c
• Landed commit: d11c80f4403ad123566ade779ab46a733f63f1a5