Skip to content
Merged
Show file tree
Hide file tree
Changes from 15 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions docs/manage-sandboxes/update-sandboxes.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -78,9 +78,10 @@ During the automatic upgrade path, the installer prepares the current NemoClaw C
If any sandbox is skipped or fails, the installer exits before it changes the gateway.
After backup, the installer requires any existing OpenShell executable it will use to report a version, then compares that version with the supported range declared by the prepared current source.
It retires the running gateway before replacing an out-of-range OpenShell installation, keeps the gateway when the installed version is supported, and stops without retiring it when the installed version or supported range cannot be validated.
On Linux, failed OpenShell lifecycle commands cause the installer to check a verified NemoClaw-managed gateway PID file for any configured gateway port.
For the default gateway on port `8080`, the installer first checks a verified active `nemoclaw-openshell-gateway.service`, then checks the PID file.
The service path requires an active `nemoclaw-openshell-gateway.service` with a trusted unit path, NemoClaw-managed marker, file owner, and `ExecStart` binary.
If OpenShell lifecycle commands cannot retire the gateway, the installer can use verified service or PID-file evidence on Linux and macOS.
For the default gateway on port `8080`, Linux first checks verified systemd service evidence for `nemoclaw-openshell-gateway.service`, while macOS first checks verified Homebrew gateway service evidence.
On either platform, the installer can then use a verified NemoClaw-managed gateway PID file for the configured gateway port.
If macOS cannot obtain a conclusive `lsof` listener observation for a stale PID, the installer stops retirement and preserves the PID file, OpenShell registration, and every sandbox backup.
After the service or PID-file check confirms the gateway process is stopped, the installer tries to remove the selected OpenShell registration.
If registration removal fails, the installer warns that onboarding will replace the stale registration.
If neither fallback can verify and stop the process, the installer stops after backup, preserves every sandbox backup, and reports the failed operation.
Expand Down
9 changes: 7 additions & 2 deletions docs/reference/commands.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -673,14 +673,19 @@ When existing sandboxes were created with OpenShell earlier than `0.0.37`, the i
For scripted installs, set `NEMOCLAW_ACCEPT_EXPERIMENTAL_OPENSHELL_UPGRADE=1` to allow the automatic path to prepare the current CLI without replacing OpenShell, back up every registered sandbox with the current state manifest, retire an installed gateway whose OpenShell version is outside the current release's supported range, install the supported OpenShell release, and recover the existing sandboxes.
The installer reads that supported range from the prepared current source and stops without retiring the gateway if the installed version is unknown or the range is missing or invalid.
When the installed OpenShell version is already supported, the installer keeps the running gateway through the host update.
On Linux, if installed OpenShell lifecycle commands cannot retire the gateway, the installer checks a verified NemoClaw-managed gateway PID file for any configured gateway port.
For the default gateway on port `8080`, the installer first checks a verified active `nemoclaw-openshell-gateway.service`, then checks the PID file.
On Linux and macOS, if installed OpenShell lifecycle commands cannot retire the gateway, the installer uses verified NemoClaw-managed service or PID-file evidence for the supported recovery path.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Keep the operational upgrade guide in sync

This page now describes the macOS Homebrew-service and PID-file recovery path, but docs/manage-sandboxes/update-sandboxes.mdx:81-86 still says the fallback is Linux-only and describes only systemd. That is the operator-facing upgrade/recovery procedure, so macOS users are given conflicting support and recovery guidance. Please update that page with the same macOS service/PID fallback and fail-closed lsof preservation behavior, then run the docs validation.

For the default gateway on port `8080`, Linux recovery first checks a verified active `nemoclaw-openshell-gateway.service`, while macOS recovery first checks a verified active Homebrew gateway service.
Both paths then check a verified NemoClaw-managed gateway PID file for any configured gateway port.
When a macOS PID file names a process that is no longer running, the installer removes the stale PID file only after `lsof` reports no listener and no diagnostic output.
If `lsof` is unavailable, reports permission or other diagnostics, or produces inconsistent listener results, the installer stops before retiring the gateway and preserves the PID file, OpenShell registration, and sandbox backups.
After either fallback confirms the gateway process is stopped, the installer tries to remove the selected OpenShell registration and warns if onboarding must replace a stale registration.
If neither fallback can verify and stop the process, the installer stops after backup with every sandbox backup preserved.
If any registered sandbox cannot be backed up, the installer aborts before it changes the gateway.
After the automatic path retires an out-of-range gateway, it forces installation of the OpenShell version pinned by the prepared source before recovery.
This mandatory installation applies to source and managed install modes and cannot remain deferred after gateway retirement.
If the forced installation fails, the installer does not stage a gateway service or start recovery, preserves the backups, and tells you to rerun with `NEMOCLAW_OPENSHELL_UPGRADE_PREPARED=1`.
On macOS, if the verified Homebrew installation does not resolve executable OpenShell CLI and gateway binaries, the installer also stops before recovery and preserves the backups and prepared recovery state.
It does not fall back to a stale user-local OpenShell binary.
When the registry contains a pre-fingerprint OpenClaw or Hermes entry with no recorded custom-image evidence, an interactive install asks you to confirm that the listed sandbox used a NemoClaw-managed image.
For a non-interactive install, set `NEMOCLAW_CONFIRM_LEGACY_MANAGED_RECREATE` to the JSON array of names printed by the installer, such as `["my-assistant","preserve-hermes"]`, only after verifying every named sandbox used a managed image.
The confirmation permits those legacy entries to recover onto the current managed image, but it does not override recorded custom-image evidence.
Expand Down
Empty file removed handoff-issue-contract.md
Empty file.
16 changes: 10 additions & 6 deletions scripts/checks/extract-installer-pins.mts
Original file line number Diff line number Diff line change
Expand Up @@ -347,12 +347,11 @@ const TRUSTED_OPENSHELL_RELEASES: readonly OpenShellReleaseTrust[] = [
// The first template came from the downstream 0.0.106 pin. The second authorizes its
// fail-before-download strings preflight. The third authorizes repair when an existing formula
// has an invalid checksum or its release formula is unavailable. The fourth preserves that
// template after installer tests moved under test/install. Following the intentional two-step
// trust rollout in check-installer-hash.sh, the fifth authorizes the dev-channel installer
// template, which selects a MUSL sandbox while retaining the GNU gateway. The sixth preserves
// that dev-channel template with the historical flat installer-test paths. The seventh
// authorizes the exact successor template after macOS install selection becomes method-bound
// and fail-closed.
// template after installer tests moved under test/install. The next four authorize those
// same transitions after macOS install selection became method-bound and fail-closed. Per the
// intentional two-step trust rollout in check-installer-hash.sh, the final four authorize the
// exact tested follow-up templates before the installer can select the MUSL development
// sandbox while preserving stable GNU, both before and after that macOS selection change.
// Homebrew owns the formula source state, so NemoClaw cannot correct it there; the installer
// verifies the trusted release formula before reuse. installer-homebrew-formula-reuse-trust.test.ts
// and installer-hash-check.test.ts lock the template and trust transitions. Remove the repair
Expand All @@ -362,9 +361,14 @@ const TRUSTED_OPENSHELL_RELEASES: readonly OpenShellReleaseTrust[] = [
"e850e927aab619d52c5de72967137569d65dd7fa669920c7c5b558f0770140d1",
"e7d51536442b217e3d5e77c4ba3b7c25e6a74898bf22523f7fb58627d34329cb",
"18175cf47a0fece8ce75e5d523185062c7a7c913a3f4ceafbba4a7ca4df7c69b",
"139ad73792b019048b1d3bd9a8a7fbac56a354643aa1a4606115bdf1cc271fea",
"1846d9051f4c588d0961d83107066521e436643ec95c13c0be43f298971139f1",
"77d3abb360880c96a63424c4850ddb2e8db81b126bb7474a3b24fcde7844a3dd",
"03215130365310e907390ceeb685088db6e75b963adf80c9c939de670381797c",
"293f45ea1d54e1531c3a070123c04b47f972f29504bd8902a44ab71acdfe6cca",
"ee3db19d06d34a625bff9e0ab021f095ce97eadf5f7a98fc60def62af87577ad",
"4b45161017a5936331300e982168160575701632711328cbbb97480eb087fb51",
"65d9d9f8867103975d22f60596b1cf7a803a583f53a59df65c84855695a30b6a",
],
manifests: [
{
Expand Down
15 changes: 15 additions & 0 deletions scripts/install-openshell.sh
Original file line number Diff line number Diff line change
Expand Up @@ -168,6 +168,21 @@ fi

HOMEBREW_TAP="nvidia/openshell"
HOMEBREW_FORMULA_NAME="openshell"
MACOS_INSTALL_METHOD="${_NEMOCLAW_OPENSHELL_INSTALL_METHOD:-auto}"
case "$MACOS_INSTALL_METHOD" in
auto) ;;
homebrew)
[ "$OS" = "Darwin" ] || fail "The Homebrew OpenShell installation method is valid only on macOS."
command -v brew >/dev/null 2>&1 \
|| fail "The selected Homebrew OpenShell installation method became unavailable before installation."
;;
standalone)
[ "$OS" = "Darwin" ] || fail "The standalone macOS OpenShell installation method is valid only on macOS."
! command -v brew >/dev/null 2>&1 \
|| fail "Homebrew appeared after standalone OpenShell installation was selected; refusing an ambiguous installation method."
;;
*) fail "The internal macOS OpenShell installation method is invalid." ;;
esac

# Honour the TS installer's blueprint-derived env overrides only on the stable
# channel — the dev channel installs from the `dev` tag and uses DEV_MIN_VERSION
Expand Down
Loading
Loading