[gwdp]

Why

Recover a failed public tunnel without changing the session URL.

How

• Check both local and public endpoints. Reopen the tunnel after repeated public failures while the local service is healthy.
• Bound retries and wait times, and track listeners for shutdown cleanup.

Test Plan

• Rebased onto main (6fe396e4) after the startup and egress changes landed; the net diff is unchanged. Claude Code ran the build-tools build, typecheck, oxfmt and oxlint on the changed files, and the session step/util tests (1894 passed, 8 skipped). CI passes on the new head.
• Real ngrok SDK/service tested in an isolated Tart clone with HTTP/WebSocket fixtures and guest-only network faults. Normal traffic, backend failure, short interruption and long-outage recovery on the same URL passed.
• One shutdown case failed: stop timed out after four seconds during a pending native reopen. The late replacement closed, but the old listener's failed close was never retried after network recovery. This remains unfixed; a live public endpoint leak was not established.

Earlier local launch E2E passed: Universe-generated steps through build-tools download/install/start to pinned serve-sim on a real iOS Simulator, checking one app start, arguments and deep link. Cloud calls used loopback adapters. This predates the current head; hosted recovery and real preview/controller reconnection remain unverified.

Authorship and LLM use

Gabe set the direction and reviewed every line of the final diff. Codex implemented tunnel supervision, iterated with AI reviews, and ran the local tests and Tart fault checks.

[codecov]

Codecov Report

❌ Patch coverage is 95.95376% with 7 lines in your changes missing coverage. Please review.
✅ Project coverage is 75.36%. Comparing base (53ac936) to head (6fe396e).

Files with missing lines	Patch %	Lines
...ackages/build-tools/src/steps/utils/ngrokTunnel.ts	95.91%	6 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4526      +/-   ##
==========================================
+ Coverage   75.30%   75.36%   +0.07%     
==========================================
  Files        1053     1054       +1     
  Lines       52170    52323     +153     
  Branches    11356    11427      +71     
==========================================
+ Hits        39281    39430     +149     
- Misses      11901    11904       +3     
- Partials      988      989       +1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[linear-code]

ENG-26486

[gwdp]

Codex contribution: implemented tunnel supervision and its cleanup handling, then restacked this layer under Gabe's direction. Updated the description with the exact-head CI/local results and real-ngrok Tart fault evidence, including the unfixed shutdown race. Gabe reviewed every line of the final diff.

— Codex

[github-actions]

✅ Thank you for adding a changeset!