[Epic] Harden Portable Hermes lifecycle and optimize click-to-prompt
- Dominant language
- TypeScript
- Stars
- 22.5k
- Forks
- 3.1k
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 715
Description
## Outcome
Make Portable Hermes Portable lifecycle operations reliable across onboarding, resume, stop, start, probe, launch, and prompt, while reducing Play click-to-first-prompt latency without weakening authority or health checks.
This is a standalone delivery epic. It is related to #9211, but it does not replace or belong under that broader Hermes Portable qualification epic.
## Scope
- Select one receipt-owned lifecycle lock domain after acquiring the Portable HOME fence.
- Keep OpenShell authoritative for sandbox lifecycle transitions and rollback partial starts.
- Preserve inference provider, route, network, receipt, and published-state consistency across restart and resume.
- Recover or adopt only exact receipt-owned forwards; reject foreign or ambiguous listeners.
- Initialize state for the selected agent and bound managed generation requests.
- Reuse previously proved Portable authority only behind explicit Portable gates and with fail-closed fallback verification.
- Measure fresh Play click-to-first-prompt and useful first response on an exact commit.
## Delivered foundation
- #11336 — hold the Portable HOME fence during sandbox start and repair lifecycle recovery correctness.
- #11482 — unify lifecycle lock roots and roll back partial starts.
- #11490 — select one lifecycle lock authority after the HOME fence and protect synchronous callers.
- #11427 — reuse verified Hermes dashboard/API forwards and skip OpenClaw state initialization for Hermes.
## Current candidate
- Branch: [`perf/gfn-hermes-click-to-prompt-main`](https://github.com/NVIDIA/NemoClaw/tree/perf/gfn-hermes-click-to-prompt-main)
- Commit: [`30ef9ec7a`](https://github.com/NVIDIA/NemoClaw/commit/30ef9ec7a198270b9524ddaa8c4d0aef9b0da918)
- Two consecutive stop/start/probe cycles passed:
- start: 6.98s and 6.93s;
- separate authenticated probe: 1.72s and 1.73s;
- cold Hermes TUI displayed its input prompt at approximately 1s;
- a real prompt returned the requested `READY` response; generation displayed 11s.
- A true Portable Play click-to-first-prompt measurement has not yet been recorded for this commit.
- The current 16–20s expectation is a projection based on the overlapping Portable prewarm trace, not acceptance evidence.
- Delivered bug-fix PR: #11578 — restore forwards before interactive launch and preserve managed auxiliary output limits; merged at `f77236827783f399d22333932e3da2db032a4848`.
- Remaining performance delivery is consolidated in #11574; #11559 remains the separate end-to-end acceptance task.
## Pull-request map
| Sub-issue | Pull request | Delivery status |
| --- | --- | --- |
| #11555 | #11336 | Merged |
| #11560 | #11482 | Merged |
| #11561 | #11490 | Merged |
| #11557 | #11427 | Merged; local candidate superseded |
| #11569 | #11427 | Merged; local candidate superseded |
| #11567 | #11578 | Merged |
| #11568 | #11578 | Merged |
| #11558 | No direct PR | Source implementation completed; current-main port tracked by #11574 |
| #11570 | Consolidated into #11574 | Requirements and candidate references retained in #11574 |
| #11571 | Consolidated into #11574 | Requirements and candidate references retained in #11574 |
| #11572 | Consolidated into #11574 | Requirements and candidate references retained in #11574 |
| #11574 | Not opened | Consolidated performance delivery: durable authority, inference reuse, lifecycle gate retention, and startup-to-probe evidence reuse |
| #11559 | Validation task | Exact-commit lifecycle and timing acceptance for the delivered fixes and consolidated performance issue #11574 |
## Acceptance criteria
- No HOME-fence or lifecycle-lock-path failure on default or non-default gateway ports.
- All lifecycle entry points select one receipt-owned lock authority after acquiring the host fence.
- OpenShell remains authoritative for start and stop, including partial-start rollback.
- Inference receipt, provider version, route reservation, registry state, and live route remain consistent after restart.
- Exact-owned forwards are reused; foreign or ambiguous listeners are rejected.
- Fresh onboarding, resume, three stop/start cycles, authenticated probe, cold TUI prompt, and a useful response all pass on one exact commit.
- A real Play click-to-first-prompt measurement is 20s or less, or an explicit disposition is recorded.
- Branch-only fixes and optimizations pass review and full CI before delivery to `main`.
## Test-environment findings outside this epic
- Missing debug-volume mount.
- Port `11434` already owned by the seat's Ollama instance.
- Use of port `18080` itself; the defect was inconsistent state-path selection, not the port number.
- A concurrent raw OpenShell stop initiated by another task.
- TypeScript compilation exhausting CI memory.
- Generic `destroy` being intentionally unsupported for experimental Hermes Portable.
- The Portable kiosk ready-file polling interval, which is outside NemoClaw.
## Work tracking
The native sub-issues below are the source of truth for scope, status, and assignee. Each sub-issue covers one technical concern.
Contributor guide
Research direction
Start with the native sub-issues listed in the epic and inspect candidate commit 30ef9ec7a on branch perf/gfn-hermes-click-to-prompt-main; the payload names no source files or tests. Done means the lifecycle acceptance criteria pass on one exact commit and a real Play click-to-first-prompt measurement is 20 seconds or less, or an explicit disposition is recorded.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- infrastructure
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 20/100