install.sh/brew upgrade to 0.1.3: local gateway silently fails on an existing config, shown only as a generic listener timeout #4412

First off, thanks for OpenShell. I know it is still in beta, so an upgrade not being perfectly seamless is completely understandable. I am filing this mainly in the spirit of establishing good upgrade hygiene early, since the gateway config schema will likely keep evolving. Here is a concrete case and a few suggestions.

Environment

• macOS (Apple Silicon), Homebrew install
• podman machine as the container engine
• Upgrading 0.1.2 -> 0.1.3 via OPENSHELL_VERSION=v0.1.3 ./install.sh

What happened

The formula upgraded fine, but the installer's "wait for local gateway listener" step failed, and brew services list showed openshell error. The only visible hint from the installer was a generic timeout:

local gateway listener did not become reachable at https://localhost:17670/ within 30s

The actual cause was only in /opt/homebrew/var/log/openshell/openshell-gateway.err.log, as two sequential config-schema errors (the second appeared only after fixing the first):

failed to parse gateway config file '~/.config/openshell/gateway.toml':
  TOML parse error at line 10: ttl_secs = 0
  invalid value: integer `0`, expected a nonzero u64

gateway config schema version is required; add `[openshell]` and `version = 2`

Root cause

0.1.3 changed the gateway config schema: [openshell] with version = 2 is now required, and ttl_secs must be nonzero. An existing ~/.config/openshell/gateway.toml from an earlier version is neither migrated nor rejected with a clear, surfaced message, so the brew-managed gateway service just goes to error state and the install output only shows the generic listener timeout.

Suggestions (upgrade hygiene)

1. On upgrade, migrate or validate an existing gateway config: bump it to version = 2 and coerce a now-invalid value such as ttl_secs = 0 to a sane default, or refuse with a clear message that names the file and the exact fix.
2. At minimum, surface the openshell-gateway stderr (the real parse error) when install.sh's listener wait times out, instead of only the generic timeout.
3. Document the 0.1.3 gateway config-schema changes and a short migration note in the release notes.

Workaround that fixed it

Add [openshell] / version = 2 and set a nonzero ttl_secs (for example 3600) in ~/.config/openshell/gateway.toml, then brew services restart openshell. The gateway then came up on podman in about 10s and reports Version: 0.1.3.