[feature] TC-driven OpenClaw update button (blocked: SSH user lacks container-runtime access)

[Jason-Vaughan]

What

A per-connection "Update" affordance in the connection panel that updates the OpenClaw instance to a newer image tag — since OpenClaw's own in-app update is broken.

Blocker (discovered 2026-06-01)

Neither docker nor podman is on the SSH user's (habitat-admin) PATH on the Docker-Desktop-for-Mac host, and sudo needs a password. So TC cannot run compose pull && up -d to actually perform the update from current access.

What's doable without runtime access (interim)

• Detect "update available" — compare the pinned OPENCLAW_IMAGE tag (see version feature) against the latest tag on ghcr.io/openclaw/openclaw (registry API) and show a badge.
• Optionally rewrite the .env tag over SSH.

What the real one-click update needs (host-side decision, pick one)

• Give the SSH user container-runtime access (docker/podman group membership, or a scoped passwordless sudo rule for the compose recreate), or
• An OpenClaw-side / Atlas-run recreate hook TC can trigger.

Acceptance (phased)

• Phase 1 (no new access): "update available" indicator from the registry tag comparison.
• Phase 2 (after host-access decision): one-click pull + recreate + verify.

Depends on the version feature (shares the tag source). Sibling of the version-display issue.

[Jason-Vaughan]

⛏ Blocker is actually solvable — openclaw-update host-helper spec (captured 2026-06-01)

Revised finding: docker is present at /usr/local/bin on habitat; it's only absent from the non-interactive SSH PATH. Fix: the helper exports
PATH=/usr/local/bin:/Applications/Docker.app/Contents/Resources/bin:$PATH
(covers docker + the docker-credential-desktop cred helper). So a TC-driven update IS doable: TC SSHes and runs a durable host-helper.

Why the prior attempt vanished

The previous script lived only in habitat:~/bin + Cursatory:/tmp and was lost on reboot / a failed commit. #1 requirement: git-tracked + durably installed, never ephemeral.

What it does

Bump the OpenClaw image tag + recreate the gateway, for either stack on habitat:

• RentalClaw: ~/openclaw (gateway container openclaw-openclaw-gateway-1)
• TiLT: ~/openclaw-tilt (gateway tiltclaw-gateway; also tiltclaw-cli)

Non-obvious gotchas it MUST handle

1. The tag lives in .env (OPENCLAW_IMAGE=...:<tag>), NOT docker-compose.yml (compose references ${OPENCLAW_IMAGE}). Editing compose is a no-op — back up + sed the .env.
2. Non-interactive SSH lacks docker + cred-helper on PATH → docker-credential-desktop: executable file not found. Fix = the PATH export above.
3. Resolve latest STABLE tag (GitHub releases "latest" endpoint returns latest non-prerelease → lands on 2026.5.28, not a 2026.6.x beta). Never auto-pick a beta.
4. No port-drain step — habitat widened the ephemeral range (net.inet.ip.portrange.first=32768); fresh gateway has free ports. Do NOT add a "wait for TIME_WAIT→0" loop (those sockets don't drain).

Interface

openclaw-update                 # bump current stack to latest STABLE
openclaw-update --check         # dry-run: print current vs latest, no changes
openclaw-update --tag 2026.5.28 # pin explicit tag
openclaw-update --tilt          # target TiLT stack (~/openclaw-tilt)
openclaw-update --rollback      # restore most recent .env.bak and recreate

Behavior

1. Resolve stack dir + gateway service from flags (default RentalClaw).
2. Read current tag; resolve target (latest-stable or --tag).
3. --check: print "current X -> target Y", exit 0, no changes.
4. Back up .env → .env.bak-<UTC>.
5. sed the OPENCLAW_IMAGE tag.
6. docker compose pull <gateway-service> then up -d <gateway-service> (gateway only by default, so the cli isn't disturbed; confirm exact service names per stack — TiLT = tiltclaw-gateway).
7. Verify + print: docker inspect -f '{{.Config.Image}}' <gw>, docker exec <gw> openclaw --version, healthz/docker ps.
8. Do NOT auto-rollback on failure — print the .env.bak path + --rollback hint.

Durability

• Git-track the script (natural home: RentalClaw-Project/tools/network/, alongside rc-research + tiltclaw-watch; keep a git-tracked copy in TangleClaw deploy assets if TC wires it into the update feature).
• Idempotent, re-runnable installer that copies it to habitat:~/bin.

TangleClaw integration (this issue)

• Web UI "Update" button shells out to this host-helper over SSH (TC already has habitat SSH + proxy), OR hide the button when the Docker socket isn't mounted. File the upstream ask against openclaw/openclaw either way.

Verified 2026-06-01: RentalClaw .env = 2026.5.6, TiLT .env = 2026.5.28 (running container still 2026.5.6, pending recreate); docker + docker-credential-desktop both at /usr/local/bin. Prior design also in RentalClaw-Project memory reference_openclaw_update.