fix(onboard): reuse registered dashboard forward

[sandl99]

Outcome

Repeated onboarding of a Ready sandbox now reuses its registered, bound primary dashboard forward after proving both the sandbox identity and the live listener's ownership. Before this change, step 7 tried to allocate the persisted port again and failed with Registered dashboard port 18789 is already occupied; it cannot be reallocated or adopted.

Reason

Direct ForwardTcp services are not returned by the legacy forward-list compatibility path. During Ready-sandbox reuse, the dashboard reconciler therefore saw the existing listener but not its legacy owner and treated the registered port as a conflicting new allocation. Reachability alone is not ownership evidence, so reuse must retain the exact Ready-sandbox identity and identify the exact direct-forward process at the final ownership boundary.

Related issues

Fixes #11074

Changes

• Carry process-local identity authority for the exact Ready sandbox selected by both onboarding reuse routes through sandbox, core, and final flow handling.
• Revalidate that identity immediately before inspecting the registered dashboard listener, including the earlier dashboard-state restore path.
• Preserve a registered, bound listener only for an actual reuse and only after stable listener scans prove the current user, trusted OpenShell executable, configuration home, and exact gateway/workspace/sandbox/port command.
• Reinspect the forward process after the final listener scan so PID reuse or a process identity change fails closed.
• Use lsof when available and a bounded Linux procfs fallback otherwise; ambiguous, changing, foreign, or unobservable ownership remains an error.
• Delay the strict sandbox-identity observation until an actual dashboard-managed reuse path is selected, leaving create, recreate, and terminal-only paths unchanged.
• Require the process-local Ready-sandbox identity lease for preservation; a persisted skipped-step receipt alone cannot authorize a bound listener.
• Enforce the identity lease again at the dashboard boundary so a preservation Boolean without its revalidator cannot trigger even the ownership probe.
• Carry the reuse intent through agent-aware finalization and preserve only the agent's primary registered dashboard forward; secondary forwards keep strict occupied-port handling.
• Report the ownership failure code and a specific, effective recovery action when a registered listener cannot be safely reused; a foreign-listener mismatch instructs the operator to free the registered port before resuming.
• Extend the existing live double-onboard target to retain the exact forward-process identity, prove the dashboard remains reachable after the second onboarding, and reject a real foreign process on the registered port without replacing the sandbox.
• Extend the interrupted-onboarding resume target to retain the exact forward-process identity and prove the dashboard remains reachable after route repair.
• Inspect live-test listeners through the production bounded Linux procfs scanner so the target has no undeclared lsof host dependency or duplicate listener parser.
• Keep the shared listener helper in the live-runtime utility boundary and route changes to both live targets that consume it, avoiding unrelated full-suite fan-out.

Verification

• npm run validate:pr — passed on commit 7fbe756a2 against canonical main 685eab2f5ac0fbd18c07c44a39143abceac4ca03, including formatting, lint, repository checks, secret scan, source-shape budget, growth guardrails, commit lint, and CLI TypeScript.
• npm run build:cli — passed.
• npm run test:changed — passed for the final follow-up; 45 growth-guardrail tests and 23 affected CLI/integration tests passed. The preceding broader evidence revision passed 45 growth-guardrail tests and 525 affected CLI/plugin/E2E-support tests.
• Focused agent-dashboard tests — 8 passed; focused dashboard-finalization integration tests — 11 passed; focused machine-handler tests — 11 passed; focused sandbox-reuse and listener-ownership tests — 31 passed.
• The four exact create/recreate, terminal reuse, OpenClaw dashboard reuse, and messaging reuse cases implicated by the first exact-head CI run all pass locally.
• npx tsx scripts/checks/e2e-mock-parity.mts --base origin/main --head HEAD — passed with both live reuse targets mapped to their fast orchestration and ownership tests.
• npm run test:e2e-phases:check — passed; 132 semantic tests across 88 live E2E files.
• NEMOCLAW_RUN_LIVE_E2E=1 npx vitest list --project e2e-live test/e2e/live/double-onboard.test.ts test/e2e/live/onboard-resume.test.ts — both extended targets register successfully.
• Exact-head CI passed on 7fbe756a2, including CLI shards, static checks, package contracts, security scans, managed-image checks, and rootless-Podman qualification.
• All nine artifacts from the twelfth Advisor cycle were inspected; no specialist reported a change-required defect on 7fbe756a2.
• The live double-onboard and onboard-resume targets have not been executed on an external host for this revision; the PR remains draft pending live evidence and the current automated review cycle.

Review notes

Twelve completed Advisor cycles identified progressively deeper gaps: reachability without ownership, a missing identity fence and Linux fallback, incomplete production handoff, bounded enumeration and PID-reuse concerns, direct constructor evidence, actionable recovery diagnostics, lost reuse intent in the agent-aware helper and machine-handler paths, an undeclared live-test dependency, missing real-process negative evidence, unsafe reliance on a stale skipped-step receipt without a live identity lease, ineffective alternate-port guidance for a resumed sandbox, missing helper-to-live-target ownership routing, incomplete route-repair resume evidence, unintended full-suite E2E fan-out from placing a focused helper under the shared-fixture boundary, a dashboard-boundary authority split that allowed the preservation Boolean without its identity lease, and a duplicate Linux listener scanner in live evidence. The first exact-head CI cycle also exposed eager identity observation outside the selected dashboard-reuse path. This revision addresses those findings and retains strict failure behavior outside proven reuse. The twelfth cycle found no further change-required issue.

---

Signed-off-by: San Dang sdang@nvidia.com

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall line coverage in commit 7fbe756 in the fix/onboard-dashboar... branch remains at 96%, unchanged from commit 8ee4e37 in the main branch.

TypeScript / code-coverage/cli

The overall line coverage in commit 7fbe756 in the fix/onboard-dashboar... branch remains at 83%, unchanged from commit ba5aa64 in the main branch.

Show a line coverage summary of the most impacted files.

File	main ba5aa64	fix/onboard-dashboar... 7fbe756	+/-
src/lib/inferen...ocal-runtime.ts	97%	87%	-10%
src/lib/actions...oy-execution.ts	94%	91%	-3%
src/lib/actions...dbox/destroy.ts	90%	88%	-2%
src/lib/onboard...ce-lifecycle.ts	85%	83%	-2%
src/lib/onboard...-transaction.ts	69%	70%	+1%
src/lib/onboard...ed-lifecycle.ts	75%	77%	+2%
src/lib/onboard.../application.ts	69%	71%	+2%
src/lib/onboard...on-authority.ts	81%	88%	+7%
src/lib/onboard...oard-forward.ts	79%	94%	+15%
src/lib/adapter...ce-ownership.ts	0%	54%	+54%

---

_{Updated September 05, 2026 13:56 UTC}

[github-actions]

PR Review Advisor finished for commit 7fbe756. Include the Advisor findings in the complete PR feedback collection. Verify and group valid findings before repair.

All previous runs

[sandl99]

The latest #11074 failure classification confirms one shared onboarding boundary, but the current lsof/procfs ownership scanner conflicts with the accepted #10691 ForwardTcp model, which deliberately removed NemoClaw-owned PID/process inspection. I am superseding that mechanism in this draft with the existing Ready-sandbox identity/registry authority and deferred deployment verification, while preserving the strict occupied-port path for every unqualified listener. No competing PR will be opened.

[sandl99]

Follow-up after checking OpenShell 0.0.106 and the accepted #10691 contract: registry identity plus post-verification is not sufficient to supersede the listener scanner. forward service is intentionally absent from forward list; its generated service-forward:<sandbox>:<target-host>:<target-port> identity is sent only inside ForwardTcp, and OpenShell exposes no active-service inspection/reconciliation API. Sandbox logs can prove relay delivery, but omit that service identity, so they cannot distinguish NemoClaw's service from an undeclared user forward.

This leaves no implementation that satisfies all current constraints simultaneously: #10691 forbids persisted process state and ForwardTcp process inspection/adoption; #11074 requires preserving the healthy service while rejecting every foreign listener; and this issue forbids a new registry, process heuristic, or lifecycle workaround. I have not changed or pushed this draft. @ericksoa, please choose one scoped authority: an attested OpenShell service lookup, an explicit amendment permitting bounded listener ownership inspection, or an accepted stop/start reconciliation contract. My earlier comment's registry-plus-post-verify direction is withdrawn because it would weaken fail-closed behavior.

[sandl99]

Superseded by the smaller replacement in #11128, which keeps the investigation and follow-up review on the reduced implementation.