…x md lint

Address PR review findings:

1. Merge origin/main to pick up PR #3312 (isGatewayHttpReady from
   src/lib/onboard/gateway-http-readiness.ts). Replace our ad-hoc
   verifyDockerDriverGatewayListening (TCP probe) with a call to the
   shared isGatewayHttpReady helper — HTTP is strictly stronger than
   a raw TCP connect and is already the de-facto standard used by
   every other gateway-reuse decision site in onboard.ts after #3312.
   Docker-driver and K3s paths now converge on the same probe.

2. Drop the parallel test/gateway-tcp-probe.test.ts (9 tests for a
   helper that no longer exists). The shared helper's behavior is
   already covered by test/gateway-http-reuse-wait.test.ts (21 tests).
   Replace with test/gateway-health-honest-integration.test.ts (6
   source-shape tests) guarding the #3111 integration pattern.

3. Fix 7 markdownlint errors in ACCEPTANCE.md (MD040, MD022, MD031) —
   the 'checks' job flagged these; now passes locally.

4. Update ACCEPTANCE.md to reflect the simpler design: Phase 1 is
   'reuse existing helper' rather than 'add new TCP probe helper',
   and the refactoring alignment table records #3312 as 'adopted'
   rather than 'to be coordinated'.

Behavior of the fix is unchanged:
  - child.once('exit') listener tracks zombies (detached children
    that process.kill(pid, 0) would falsely report as alive)
  - poll loop guard is childExited || !isPidAlive(childPid)
  - healthy log gated on isGatewayHttpReady() after isGatewayHealthy()
  - user-visible exit code/signal surfaced on failure

Related: #3111
Coverage guard: #3362 — gateway-health-honest-e2e

…iness

Addresses the failing openshell-gateway-upgrade-e2e surfaced by the
e2e-advisor on PR #3378.

## Problem

The previous commit converged the Docker-driver gateway's readiness
probe onto isGatewayHttpReady from ./onboard/gateway-http-readiness
(introduced by #3312). That broke openshell-gateway-upgrade-e2e:

    Starting OpenShell gateway...
    [PASS] Stale gateway is healthy with supervisor:0.0.36
    [INFO] Invoking NemoClaw gateway start path; it must restart the stale process
    Docker-driver gateway failed to start.    <-- 60s timeout

The gateway log showed the process was actually serving correctly:
    POST /openshell.v1.OpenShell/Health response status=200 latency_ms=0
    POST /openshell.v1.OpenShell/Health response status=200 latency_ms=0
    GET  /                                  response status=404 latency_ms=0

## Root cause

isGatewayHttpReady does GET /, and only accepts {200, 401}. The K3s-path
gateway answers GET / via a dispatcher catch-all. The Docker-driver
gateway, by contrast, only serves routes under /openshell.v1.OpenShell/*
and returns 404 for GET /. So the probe always fails on the Docker-
driver path regardless of whether the gateway is up.

## Fix

Revert to a plain TCP probe on the gateway port for the Docker-driver
path. Add a small isDockerDriverGatewayTcpReady(port, timeoutMs, host)
helper next to isPidAlive. This is semantic-free — it just asks "is
anyone listening" — which is exactly what's needed to detect the #3111
failure mode (crashed binary → nothing listening) without making
assumptions about HTTP route shape.

isGatewayHttpReady is left in place for all K3s-path call sites; the
two paths use different probes because the two gateway types expose
different HTTP surfaces. TODO(#3213) filed for future convergence.

## Tests

test/gateway-health-honest-integration.test.ts now has 10 tests:
  5 behavioural: listening / closed / timeout / min-timeout / no-throw
  5 source-shape: child-exit tracking, poll-loop guard, TCP probe call
    site, regression guard against reintroducing the HTTP probe in the
    Docker-driver loop, exit-details surfaced

## Expected CI result

  - gateway-health-honest-e2e: GREEN (already was — this was never affected)
  - openshell-gateway-upgrade-e2e: FLIPS BACK to GREEN (the breakage this
    commit addresses)

Related: #3111
Broke in: 29bba3e (refactor(onboard): converge on shared isGatewayHttpReady)

Addresses PR review feedback — onboard.ts is the God Object being
decomposed, and growing its exports is an anti-pattern. Follow the
pattern established by PR #3312 (which added
src/lib/onboard/gateway-http-readiness.ts) and create a peer module
for the Docker-driver path.

New file: src/lib/onboard/gateway-tcp-readiness.ts
  Exports: isGatewayTcpReady(port, timeoutMs, host)
  Model: mirrors gateway-http-readiness.ts structure exactly —
         default port from GATEWAY_PORT, minimum-timeout clamp,
         pure async, never throws.

New file: src/lib/onboard/gateway-tcp-readiness.test.ts
  Co-located behavioural tests per the established pattern
  (see temp-files.test.ts, legacy-command.test.ts, etc.)
  6 tests: listening / closed / timeout / min-timeout / no-throw /
  default-port. Imports via ES module, not via dist/ indirection.

onboard.ts net change:
  Before: +88 lines (+48 helper + integration)
  After:  +22 lines (2 require lines + integration only)

Related to: #3111

…odules

Addresses PR review: 'This PR is adding lines to onboard.ts — which is
now an antipattern' and the onboard-entrypoint-budget CI check.

src/lib/onboard.ts is the God Object being decomposed; growing it is
explicitly flagged as "away from target architecture" in the repo's
review guidelines, and the onboard-entrypoint-budget workflow fails the
PR if the entrypoint grows net-positive.

## Changes

Extract three focused modules under src/lib/onboard/ that collectively
replace the inline logic added in earlier commits on this branch:

- src/lib/onboard/gateway-tcp-readiness.ts
    isGatewayTcpReady(port, timeoutMs, host): plain TCP liveness probe
    for the Docker-driver gateway. Peer of gateway-http-readiness.ts
    (introduced by #3312). Uses a minimum-timeout clamp so a regression
    that drops Math.max(50, timeoutMs) is caught by tests.

- src/lib/onboard/child-exit-tracker.ts
    trackChildExit(child): attaches a one-shot 'exit' listener to a
    ChildProcess and returns a ChildExitState view. Zombie-safe: fires
    reliably for detached children that isPidAlive(pid, 0) would
    falsely report as alive (#3111). Also exposes describeExit() —
    'exited with code 127' / 'killed by signal SIGKILL' — so callers
    don't have to reformat the signal/code themselves.

- src/lib/onboard/docker-driver-gateway-failure.ts
    reportDockerDriverGatewayStartFailure(logPath, childExit, opts):
    the full diagnostic bundle emitted on startup failure — 'failed to
    start' header, exit descriptor, redacted log tail, troubleshooting
    footer. Honors exitOnFailure (production) vs. throw-only (recovery).

Each module has co-located behavioural tests (6 + 5 + 6 tests = 17),
using direct ES imports instead of the dist/ indirection that
test/onboard.test.ts uses. Source-shape guards in
test/gateway-health-honest-integration.test.ts enforce that the
three modules stay extracted (the entrypoint cannot reintroduce the
inline implementations).

## Result

  src/lib/onboard.ts: 15 additions, 21 deletions — net -6 lines.
  src/lib/onboard/**: 3 new modules, 17 new unit tests, full behavioural
      + signal-vs-code coverage on all three helpers.

Both E2E tests remain green on this branch:
  - gateway-health-honest-e2e (#3111 coverage guard)
  - openshell-gateway-upgrade-e2e (regression target the earlier
    HTTP-probe attempt broke; TCP probe is the correct fit)

Related: #3111
Aligns with architecture goal tracked by onboard-entrypoint-budget CI.

…eporting healthy (#3111) (#3378)

## Summary

`nemoclaw onboard` was printing `✓ Docker-driver gateway is healthy`
even when the openshell-gateway binary crashed immediately on startup,
then failing the next step with `Connection refused`. The reported
trigger on Ubuntu 22.04 was a GLIBC 2.38/2.39 mismatch in the shipped
binary, but the underlying NemoClaw bug is **platform-independent** —
any reason the binary fails to start (missing shared lib, CDI spec
error, port conflict, permissions, corrupted download) surfaces the same
false-positive.

This PR fixes the false-positive at the caller site in
`startDockerDriverGateway()`, without modifying the shared
`isGatewayHealthy()` (which is pinned to pure-function status by the
#2020 follow-up test).

Fixes #3111.
Closes the gap covered by the failing E2E test added in #3362 —
`gateway-health-honest-e2e` flips from 🔴 red on `main` to 🟢 green on
this branch.

## Root cause

`startDockerDriverGateway()` in `src/lib/onboard.ts` spawned the gateway
binary with `spawn(..., { detached: true })` + `child.unref()`, then
polled using two checks that could both lie:

1. **`isPidAlive(childPid)`** uses `process.kill(pid, 0)` which returns
`true` for **zombies**. Since the parent Node process never `wait()`s on
the detached child, crashed children linger as zombies and `isPidAlive`
reports them as alive.

2. **`isGatewayHealthy(status, gwInfo, activeGwInfo)`** is a pure string
match over openshell CLI output. `isGatewayConnected` in
`src/lib/state/gateway.ts` matches on `"Server Status"` — the **table
header** that `openshell status` always prints. On a crashed gateway,
the header is still emitted and the body contains `× client error
(Connect) tcp connect error Connection refused` — but
`isGatewayConnected` returns true anyway.

Smoking gun from the red-on-main run
[25698031380](https://github.com/NVIDIA/NemoClaw/actions/runs/25698031380):

```
[DIAG] openshell status: Server Status
  Gateway: nemoclaw
  Server: http://127.0.0.1:8080
Error:   × client error (Connect)
  ├─▶ tcp connect error
  ╰─▶ Connection refused (os error 111)
```

## Changes

**`src/lib/onboard.ts`** — three coordinated changes in
`startDockerDriverGateway`:

1. **Track child-exit via the ChildProcess `'exit'` event**, not just
`isPidAlive`. A `child.once('exit', ...)` listener flips a `childExited`
flag that the poll loop consults alongside `isPidAlive`. This catches
zombies that `isPidAlive` misses and also captures the exit code/signal
for the failure message.

2. **Add `verifyDockerDriverGatewayListening(port, timeoutMs)`** — a TCP
connect probe to `127.0.0.1:${GATEWAY_PORT}` using `node:net` with a
socket timeout. Resolves boolean, never throws. This is the
Docker-driver path equivalent of `verifyGatewayContainerRunning` (added
for #2020 on the K3s path).

3. **Gate the "healthy" log on the TCP probe**: the poll loop now only
logs `✓ Docker-driver gateway is healthy` after `isGatewayHealthy`
**AND** a successful TCP connect. On probe failure the loop keeps
polling — the binary may still be binding its listener. The
`childExited` check at the top of the loop terminates us if the process
actually died.

Also improves the final failure message to include **how** the gateway
exited (signal vs. exit code) so users don't have to `tail` the gateway
log.

## What this PR does NOT change

`isGatewayHealthy` in `src/lib/state/gateway.ts` is left untouched. The
#2020 follow-up test at `test/gateway-liveness-probe.test.ts:74` pins it
to pure-function status ("no I/O, no docker, no spawn, no exec"). Fix at
the caller, not the shared helper — same pattern as #2020.

## Tests

- **New unit test:** `test/gateway-tcp-probe.test.ts` (9 tests)
- `verifyDockerDriverGatewayListening` resolves true for listening ports
  - resolves false for closed ports (Connection refused)
  - resolves false on timeout (non-routable RFC 1918 host)
  - enforces minimum 50 ms timeout
  - never throws
- **source-shape guards** (regexes over `src/lib/onboard.ts`):
child-exit tracking present, `childExited || !isPidAlive` check at
poll-loop top, TCP probe called before the "healthy" log, exit details
surfaced in the failure message
- **E2E acceptance gate:** `gateway-health-honest-e2e` (from #3362) —
red on main, expected green on this branch. Will dispatch via
nightly-e2e selective run once PR opens.
- **Existing tests:** full `vitest` suite passes (CLI);
`test/gateway-state.test.ts` (47 tests) and
`test/gateway-liveness-probe.test.ts` (7 tests) still green — no
behavior change in the shared helpers.

## Refactoring alignment

Noted in `ACCEPTANCE.md` (also in this branch):

- **#2562** (unified timeout abstraction) — `TODO(#2562)` on the TCP
probe helper's timeout logic, for mechanical adoption later.
- **#3213** (unified advisory registry) — `TODO(#3213)` on the
failure-message format so it can migrate to structured advisories later.
- **PR #3312** (laitingsheng — `isGatewayHttpReady` for K3s path) — same
pattern, different surface. Easy to converge once both land; can extract
a shared "gateway liveness probe" module if desired.
- **PR #3306** (cv — `gateway-bootstrap.ts` extraction) — doesn't touch
`startDockerDriverGateway`; no conflict expected.

## Related

- Fixes #3111
- Coverage guard: #3362 (`gateway-health-honest-e2e`)
- Cross-reference patterns: #2020 (K3s path equivalent), #3312 (HTTP
readiness for K3s reuse)


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added a TCP readiness check during gateway startup to ensure the
service is actually listening before reporting healthy.
* **Bug Fixes**
* Reduced false “alive” reports for the gateway by detecting early
child-process termination.
* Improved startup failure messages to include how the gateway process
terminated (signal vs exit code).
* **Tests**
* Added integration and unit tests to validate startup health and TCP
probe behavior.

[![Review Change
Stack](https://storage.googleapis.com/coderabbit_public_assets/review-stack-in-coderabbit-ui.svg)](https://app.coderabbit.ai/change-stack/NVIDIA/NemoClaw/pull/3378)
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Carlos Villela <cvillela@nvidia.com>