fix(portable): unify Hermes lifecycle lock roots

[prekshivyas]

Outcome

Hermes portable lifecycle operations now use the receipt-owned host lock root across CLI dispatch, start, stop, provider recovery, and connect. A failed OpenShell start is reconciled and rolled back even when it changed container state before reporting failure.

Reason

Follow-up review after #11336 merged found that non-default gateway ports could give start and stop opposite lock ordering, while interactive connect still selected the gateway-scoped lock. The same review found that a partially successful OpenShell start could return a failure without entering rollback.

Related issues

• Follow-up to fix(portable): hold host fence during sandbox start #11336
• Refs Add Hermes-specific experimental portable lifecycle on rootless Podman #9203
• Refs Requalify experimental Portable authority after replaceable HOME and user-session transitions #10423

Changes

• Centralize Hermes portable lifecycle-lock root selection on the receipt-owned state directory.
• Apply that selection to CLI commands, public start and stop actions, the Docker provider, and both connect lock boundaries.
• Treat a nonzero or errored OpenShell start result as a failed mutation, reconcile exact container state, and roll back when running.
• Add regressions for port 18080 stop and interactive connect plus partial-start rollback.

Verification

• npm ci — passed, including the CLI build.
• Focused Vitest run for CLI locks, connect locks, portable lifecycle, Docker provider, start, and stop — 176 tests passed.
• npm run typecheck — passed.
• npm run test:titles:check — passed.
• npm run test-size:check — 45 tests passed.
• NODE_OPTIONS=--max-old-space-size=8192 npm run validate:pr — passed with no skipped applicable validator.
• git diff --check — passed.
• Reviewed diff contains no secrets, API keys, or credentials.

Review notes

The first canonical validation attempt reached tsc-cli and exhausted Node’s default approximately 4 GB heap. The identical gate passed after raising only the Node heap ceiling to 8 GB; no check was bypassed.

---

Signed-off-by: Prekshi Vyas 34834085+prekshivyas@users.noreply.github.com

Summary by CodeRabbit

• Bug Fixes

  • Improved sandbox lifecycle coordination for Hermes Portable environments, reducing conflicts during connect, start, and stop operations.
  • Failed OpenShell startup attempts now immediately trigger recovery and rollback handling instead of proceeding as successful starts.
  • Improved handling of interactive Hermes connections and nonzero startup responses.

• Tests

  • Added coverage for lifecycle locking, connection behavior, startup failures, reconciliation, and rollback scenarios.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: b2fd0ca3-12dc-4bb4-94e2-a37b87c5086d

📥 Commits

Reviewing files that changed from the base of the PR and between aeab35b and 03803aa.

📒 Files selected for processing (12)

• src/lib/actions/sandbox/connect-lifecycle-lock.test.ts
• src/lib/actions/sandbox/connect.ts
• src/lib/actions/sandbox/gateway-state.ts
• src/lib/actions/sandbox/start.ts
• src/lib/actions/sandbox/stop.ts
• src/lib/cli/nemoclaw-oclif-command.test.ts
• src/lib/cli/nemoclaw-oclif-command.ts
• src/lib/onboard/experimental/hermes-portable-lifecycle.test.ts
• src/lib/onboard/experimental/hermes-portable-lifecycle.ts
• src/lib/onboard/experimental/portable-agent-lifecycle.ts
• src/lib/onboard/runtime-provider/docker.ts
• test/support/connect-flow-test-harness.ts

Included review availability: Your plan provides up to 12 included reviews per hour; 11 remain after this review.

---

📝 Walkthrough

Walkthrough

Hermes Portable lifecycle lock options are centralized and applied to connect, start, stop, CLI, and Docker lifecycle flows. OpenShell startup failures now trigger reconciliation and rollback handling. Tests cover Portable lock usage and startup failure recovery.

Changes

Hermes Portable lifecycle

Layer / File(s)	Summary
Portable lock option resolution src/lib/onboard/experimental/portable-agent-lifecycle.ts, src/lib/actions/sandbox/gateway-state.ts, src/lib/onboard/runtime-provider/docker.ts	The shared helper resolves Portable state-directory lock options from sandbox environment and receipt status. Gateway state re-exports the helper, and Docker lifecycle locking uses it.
Sandbox operation lock integration src/lib/actions/sandbox/connect.ts, src/lib/actions/sandbox/start.ts, src/lib/actions/sandbox/stop.ts	Connect, start, and stop pass Hermes Portable lock options to lifecycle lock wrappers.
CLI Portable stop handling src/lib/cli/nemoclaw-oclif-command.ts, src/lib/cli/nemoclaw-oclif-command.test.ts, test/support/connect-flow-test-harness.ts	CLI lifecycle locking uses the shared helper. Tests verify Portable stop uses the Portable lock without the broader host fence.
OpenShell startup failure recovery src/lib/onboard/experimental/hermes-portable-lifecycle.ts, src/lib/onboard/experimental/hermes-portable-lifecycle.test.ts	OpenShell startup now raises errors for failed responses. Tests cover startup failure and post-start inspection failure recovery.
Interactive connect lock validation src/lib/actions/sandbox/connect-lifecycle-lock.test.ts	Tests verify that interactive Hermes connect invokes the Portable lifecycle lock twice with the expected sandbox and state directory.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Connect
  participant hermesPortableLifecycleLockOptions
  participant LifecycleLock
  participant HermesPortableLifecycle
  participant OpenShell
  Connect->>hermesPortableLifecycleLockOptions: resolve sandbox lock options
  hermesPortableLifecycleLockOptions-->>Connect: state directory or undefined
  Connect->>LifecycleLock: run preflight and child preparation
  HermesPortableLifecycle->>OpenShell: start sandbox
  OpenShell-->>HermesPortableLifecycle: status and error output
  HermesPortableLifecycle->>HermesPortableLifecycle: reconcile and rollback on failure

Loading

Suggested reviewers: ericksoa, cv

Merge Risk: ⚪ Minimal · up to 03803

This change centralizes how Hermes Portable sandboxes acquire their lifecycle lock and improves failure handling when a Portable container fails to start, ensuring partial starts are rolled back correctly. The changes are well covered by targeted tests for lock behavior, non-default port stop, interactive connect locking, and partial-start rollback, and no material risk was found in the affected CLI, sandbox action, or Docker runtime paths.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 41.67% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 12 functions across 12 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the primary change: unifying Hermes portable lifecycle lock roots.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/hermes-portable-lifecycle-lock-consistency

---

_{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 03803aa in the fix/hermes-portable-... branch remains at 96%, unchanged from commit fd98dc2 in the main branch.

TypeScript / code-coverage/cli

The overall line coverage in commit 03803aa in the fix/hermes-portable-... branch remains at 83%, unchanged from commit 194324d in the main branch.

Show a line coverage summary of the most impacted files.

File	main 194324d	fix/hermes-portable-... 03803aa	+/-
src/lib/inferen...ycle-adapter.ts	86%	77%	-9%
src/lib/actions...ateway-state.ts	79%	78%	-1%
src/lib/actions...dbox/connect.ts	86%	86%	0%
src/lib/inferen...file/cleanup.ts	81%	82%	+1%
src/lib/onboard...ce-lifecycle.ts	83%	84%	+1%
src/lib/onboard...le-lifecycle.ts	76%	77%	+1%
src/lib/onboard...nt-lifecycle.ts	76%	78%	+2%
src/lib/onboard...vider/docker.ts	77%	79%	+2%
src/lib/onboard...box-prebuild.ts	91%	94%	+3%
src/lib/domain/dns/coredns.ts	88%	100%	+12%

---

_{Updated September 10, 2026 22:07 UTC}

[rsliter]

Reviewed commit 03803aa8da7d341e40a013f69c6aefcf0d1403be. The shared lock-option helper now keeps Hermes Portable lifecycle roots consistent across connect, start, stop, CLI, and Docker flows. Startup failures also enter the existing reconciliation and rollback path. The complete diff and adjacent lock and recovery code show no blocking correctness or security issue across the nine security categories. Required checks pass, CodeRabbit found no actionable issue, and exact-commit CI source tests pass. Focused local validation passed 174 cases; two additional local cases were limited by the macOS sandbox environment rather than candidate behavior.