@clawops/cli 1.7.1 → 1.7.3

package/README.md

@@ -12,113 +12,58 @@ and Cursor drive them through typed MCP tools with explicit safety controls.
 
 ---
 
-## What's new in v1.7.0
+## What's new in v1.7.3
 
-**`clawops harden`** — run an idempotent set of server-hardening modules against a deployed
-stack over SSH. Each module has a read-only `check()` and an `apply()` step; `check()` runs first
-and `apply()` is skipped when the box is already compliant. Sentinel files under
-`/etc/clawops/hardening/` record what has been applied.
-
-```bash
-clawops harden --list                          # show available modules
-clawops harden --stack prod --dry-run          # preview changes, apply nothing
-clawops harden --stack prod                     # apply the default module set
-clawops harden --stack prod --options ssh,ufw   # apply a specific subset
-```
-
-**Common modules (all providers), ON by default:** `ssh` (hardens `sshd_config`, guards against
-lockout by verifying `authorized_keys` is non-empty before restarting sshd), `ufw` (deny-all
-incoming, allow SSH + gateway 18789), `fail2ban` (SSH jail: 5 failures → 10-minute ban),
-`unattended-upgrades` (security-only auto updates), and `docker-socket` (verify
-`/var/run/docker.sock` is `root:docker 660`). **Opt-in:** `auditd`, `lynis` (CIS Level 1 scan →
-`~/.clawops/reports/`), `sysctl`.
-
-**AWS modules (check-only, ON by default):** `aws-sg-audit` (warns on `0.0.0.0/0` ingress on
-unexpected ports) and `aws-ssm-check` (verifies `AmazonSSMManagedInstanceCore` for emergency SSM
-shell access). **Opt-in:** `aws-flow-logs`, `aws-guardduty`.
-
-`clawops setup` now presents a multi-select hardening step after deploy (skippable with
-`--no-harden`), and `clawops doctor --stack <name>` gains a Hardening section showing which
-modules are applied, missing, or drifted.
+**README maintenance.** The release-notes section had grown to four versions and was missing
+v1.7.2 entirely. It now carries the current line only; [`CHANGELOG.md`](CHANGELOG.md) remains the
+full history.
 
 ---
 
-## What's new in v1.6.0
+## What's new in v1.7.2
 
-**`clawops bug`** — open a pre-filled GitHub issue with system context (version, Node, OS,
-provider, stack count, SSH key presence) populated automatically. `--json` emits the URL without
-prompting or opening a browser, suitable for scripting. `clawops doctor` now prints a `clawops bug`
-hint in its footer when it exits with an error.
+**Refuses OpenClaw 2.0.** OpenClaw `2026.8.1` changed the container runtime contract — state moved
+into SQLite, config moved to a writable path, and model providers became install-gated plugins.
+Deploying it from this release line produces a crash-looping gateway. `doctor`, `plan`, `up` and
+`apply` now refuse anything above `2026.7.1-2`.
 
-```bash
-clawops bug              # open a pre-filled issue in the browser
-clawops bug --json       # print the issue URL for scripting
-```
+The support range in `spec/openclaw-versions.yaml` was previously unbounded *and read by no code*,
+so any OpenClaw release was accepted. Moving tags are now resolved to a concrete version **before**
+the range check, and an unresolved tag is refused rather than assumed safe — `latest` and `stable`
+both point at 2.0 today. The default is now a concrete pin.
 
-**Cloud deploy bug fixes (AWS, GCP, Azure).** This release fixes 10 bugs found in a deploy audit,
-several deploy-blocking:
-
-- **Azure:** updated deprecated image reference `UbuntuServer/22.04-LTS` →
-  `0001-com-ubuntu-server-jammy/22_04-lts-gen2` — every Azure deployment was broken; and fixed a
-  malformed Key Vault `roleDefinitionId` that broke Key Vault RBAC entirely.
-- **AWS:** Bedrock startup script now uses the IMDSv2 PUT→GET token flow (a plain `curl` to IMDS
-  returned 401, so the region always fell back to `us-east-1`); replaced
-  `AmazonBedrockFullAccess` with a least-privilege inline policy.
-- **AWS (⚠️ migration impact):** migrated from inline Security Group ingress/egress arrays to
-  individual `SecurityGroupIngressRule`/`SecurityGroupEgressRule` resources so CIDR changes no
-  longer replace the whole Security Group. **Existing AWS stacks have their Security Group
-  replaced on the first `clawops up` after this upgrade** — see
-  `docs/decisions/0009-aws-sg-rule-resources.md` for the import-based mitigation.
-- **All providers:** `accessMode=auto` egress-IP detection now returns a `Result` and throws a
-  clear error on failure instead of silently producing a VM with zero ingress rules.
+`clawops doctor --stack <name>` reports the version a deployed gateway is actually running, so an
+existing deployment that already picked up 2.0 through a moving tag can be identified.
 
----
+**`clawops config set` now applies.** It never has. The config clawops mounted was read by nothing
+on either OpenClaw line — models, channels and auth mode were silently discarded. Setting
+`OPENCLAW_CONFIG_PATH` fixes it, with four guards: `gateway.port` normalisation (with a warning),
+an argv `--port` pin, a parse check, and a post-restart health gate. The MCP `gateway restart`
+tool, which dropped the config mount entirely, now matches the CLI path.
 
-## What's new in v1.5.0
+**A fresh local deployment starts.** OpenClaw refuses a non-loopback bind without auth and always
+binds `0.0.0.0` in a container, and the bootstrap never supplied a token — so the gateway exited 78
+and systemd restart-looped. A token is now generated once, kept in a `0600` env file, and passed
+via `--env-file`, never on the command line.
 
-**`clawops mcp wire`** — wire the OpenClaw gateway's own AI as an MCP client of clawops.
-Once wired, in-conversation commands like "check if my stack is healthy" or "show me the last 20
-log lines" invoke the real `clawops` CLI rather than having the gateway AI guess.
+**Ollama is reachable.** `localhost` inside the container is the container. clawops now passes
+`--add-host=host.docker.internal:host-gateway` and defaults the Ollama address to match.
 
-```bash
-clawops mcp wire                   # wire the default stack
-clawops mcp wire --stack prod      # target a named stack
-clawops mcp wire --force           # bypass gateway version check
-```
+**Packaging.** `spec/` was missing from the published files, and neither it nor
+`bootstrap.sh.tmpl` resolved from the bundle — so `clawops plan` and `clawops up --provider local`
+failed from an npm install. Both are now shipped and resolved correctly.
 
-Version-gated: requires OpenClaw ≥ 2026.4 on the gateway side. If the version is older, the
-command surfaces a clear upgrade prompt and exits cleanly.
+**SSH host keys.** The verifier read each `known_hosts` line's *key type* as the key, so any
+standard entry failed permanently with `Host denied`. Standard entries now parse, including
+comma-separated host lists, `[host]:port`, hashed hostnames, `@revoked` / `@cert-authority`
+markers, and wildcard and negated patterns.
 
-The `clawops setup` wizard now also asks at the end of a successful deploy:
-*"Should the OpenClaw gateway's AI also be able to manage this stack?"* — accepting wires the
-client automatically over the same SSH session.
+> **Behaviour change:** a host covered by a wildcard whose key does not match is now refused where
+> it previously connected. Ignoring wildcards meant trust-on-first-use accepted a key your own
+> `known_hosts` contradicted. This matches OpenSSH.
 
 ---
 
-## What's new in v1.4.0
-
-**`clawops monitor`** — live dashboard for any deployed stack. Shows gateway health, container
-status, CPU/memory, disk usage, and a rolling log tail. Refreshes on an interval with `[r]`,
-toggles logs with `[l]`, and quits with `[q]`.
-
-Run without `--stack` to get an **interactive stack picker** first — probes all registered stacks
-in parallel, shows only running ones by default, and lets you toggle to a full list (`[a]`) where
-not-deployed stacks can be deleted from the registry with `[d]`. Press `[s]` inside the dashboard
-to go back to the picker.
-
-```bash
-clawops monitor              # interactive stack selection → dashboard
-clawops monitor --stack prod # jump straight to a named stack
-clawops monitor --stack prod | cat  # one-shot snapshot for CI
-```
-
-**`clawops_monitor` MCP tool** — same snapshot as a single structured JSON call, so Claude Code
-and Cursor can check stack health without opening a terminal.
-
-**`clawops stacks delete` guard** — now blocks deletion of a still-deployed stack and requires
-`--force` to remove from the registry without tearing down cloud resources first.
-
----
 
 ## Who this is for
 
@@ -612,7 +557,7 @@ pnpm dev doctor        # verify toolchain
 ```bash
 pnpm dev                   # run CLI from src/ via tsx
 pnpm build                 # tsup → dist/
-pnpm test                  # vitest (493 tests, ~3s)
+pnpm test                  # vitest (786 tests, ~4s)
 pnpm test:changed          # vitest --changed (fast edit loop)
 pnpm test:integration      # Docker-based SSH integration tests
 pnpm typecheck             # tsc --noEmit

package/dist/{apply-BTZFFGAD.js → apply-PZ5IIU7Z.js}

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
 import {
   applyPlan
-} from "./chunk-ISFHLA4G.js";
-import "./chunk-YTH4L2GN.js";
+} from "./chunk-5SPESD5N.js";
 import "./chunk-6ZFIFDBJ.js";
 import "./chunk-BOPSG2LI.js";
-import "./chunk-ZFNPM2WG.js";
-import "./chunk-3MFZ7E74.js";
+import "./chunk-6X45DDGH.js";
+import "./chunk-O3F7OGH7.js";
+import "./chunk-P5LKWRPL.js";
+import "./chunk-PVUVI35Y.js";
 import "./chunk-A2I76FTA.js";
 import "./chunk-CX5SL5HP.js";
 import "./chunk-KGXPLI7W.js";

package/dist/{aws-D7Y6LCGK.js → aws-L4RR2LSE.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   makeStartupScript
-} from "./chunk-XKT42M34.js";
+} from "./chunk-C5X375RO.js";
 
 // src/providers/aws/index.ts
 import process2 from "process";

package/dist/{azure-JQAMNVHN.js → azure-7OXQENQL.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   makeStartupScript
-} from "./chunk-XKT42M34.js";
+} from "./chunk-C5X375RO.js";
 
 // src/providers/azure/index.ts
 import process2 from "process";

package/dist/{bootstrap-RY4VOSDJ.js → bootstrap-HL4DNUNG.js}

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import {
   acquireSession
-} from "./chunk-LCKD7L7X.js";
-import "./chunk-GJEF6UQA.js";
+} from "./chunk-DQDAWNGB.js";
+import "./chunk-3XK66DKK.js";
 import {
   writeLocalState
 } from "./chunk-A2I76FTA.js";
@@ -12,7 +12,7 @@ import {
 } from "./chunk-KGXPLI7W.js";
 
 // src/providers/local/bootstrap.ts
-import { readFileSync } from "fs";
+import { readFileSync, existsSync } from "fs";
 import path from "path";
 import { fileURLToPath } from "url";
 var GATEWAY_PORT = 18789;
@@ -20,7 +20,16 @@ var HEALTH_POLL_INTERVAL_MS = 3e3;
 var HEALTH_TIMEOUT_MS = 12e4;
 function loadTemplate() {
   const dir = path.dirname(fileURLToPath(import.meta.url));
-  return readFileSync(path.join(dir, "bootstrap.sh.tmpl"), "utf-8");
+  const candidates = [
+    path.join(dir, "bootstrap.sh.tmpl"),
+    path.join(dir, "../src/providers/local/bootstrap.sh.tmpl")
+  ];
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return readFileSync(candidate, "utf-8");
+  }
+  throw new Error(
+    `Cannot find bootstrap.sh.tmpl (looked in: ${candidates.join(", ")}). If this is an installed package, the template may be missing from the build output.`
+  );
 }
 function renderScript(openclawVersion) {
   return loadTemplate().replace(/\{\{OPENCLAW_VERSION\}\}/g, openclawVersion);

package/dist/bootstrap.sh.tmpl

@@ -0,0 +1,204 @@
+#!/bin/bash
+# clawops bootstrap script — idempotent; safe to re-run.
+# Rendered by clawops and executed via SSH on the target host.
+# Supports: Ubuntu/Debian, RHEL/Fedora/CentOS (dnf/yum), Alpine (apk), macOS.
+set -euo pipefail
+
+OPENCLAW_VERSION="{{OPENCLAW_VERSION}}"
+OPENCLAW_PORT=18789
+
+# ── OS detection ──────────────────────────────────────────────────────────────
+OS="$(uname -s)"
+
+case "$OS" in
+  Linux)
+    if command -v apt-get &>/dev/null; then
+      PKG_MANAGER=apt
+    elif command -v dnf &>/dev/null; then
+      PKG_MANAGER=dnf
+    elif command -v yum &>/dev/null; then
+      PKG_MANAGER=yum
+    elif command -v apk &>/dev/null; then
+      PKG_MANAGER=apk
+    else
+      echo "clawops: unsupported Linux distribution (no apt/dnf/yum/apk found)" >&2
+      exit 1
+    fi
+    OPENCLAW_USER=clawops
+    OPENCLAW_CONFIG=/home/${OPENCLAW_USER}/openclaw.json
+    ;;
+  Darwin)
+    PKG_MANAGER=darwin
+    # When invoked via sudo the script runs as root but SUDO_USER is the real caller.
+    # Fall back to id -un for passwordless (non-sudo) invocations.
+    OPENCLAW_USER="${SUDO_USER:-$(id -un)}"
+    OPENCLAW_CONFIG="${HOME}/.config/openclaw/config.json"
+    mkdir -p "${HOME}/.config/openclaw"
+    # Fix ownership so subsequent non-sudo SSH writes (atomicWriteConfig) can overwrite.
+    chown "${OPENCLAW_USER}" "${HOME}/.config/openclaw" 2>/dev/null || true
+    # sudo resets PATH; add common Docker install locations so `command -v docker` works.
+    # Covers: Docker Desktop (Intel + AS), Homebrew (AS), Colima.
+    export PATH="/usr/local/bin:/opt/homebrew/bin:/Applications/Docker.app/Contents/Resources/bin:$PATH"
+    ;;
+  *)
+    echo "clawops: unsupported OS: $OS" >&2
+    exit 1
+    ;;
+esac
+
+# ── Create clawops user (Linux only) ─────────────────────────────────────────
+if [ "$OS" = "Linux" ]; then
+  id -u "${OPENCLAW_USER}" &>/dev/null || useradd -m -s /bin/bash "${OPENCLAW_USER}"
+fi
+
+# ── Install Docker ─────────────────────────────────────────────────────────────
+if ! command -v docker &>/dev/null; then
+  case "$PKG_MANAGER" in
+    darwin)
+      echo "clawops: Docker not found on macOS." >&2
+      echo "Install one of:" >&2
+      echo "  Docker Desktop: https://www.docker.com/products/docker-desktop/" >&2
+      echo "  Homebrew:       brew install --cask docker" >&2
+      echo "  Colima (FOSS):  brew install colima docker && colima start" >&2
+      exit 1
+      ;;
+    apt)
+      export DEBIAN_FRONTEND=noninteractive
+      apt-get update -q
+      apt-get install -y -q ca-certificates curl gnupg lsb-release
+      install -m 0755 -d /etc/apt/keyrings
+      # Detect Ubuntu vs Debian; use the correct Docker APT repo for each.
+      # /etc/os-release ID is 'ubuntu' on Ubuntu and 'debian' on Debian.
+      # Other debian-based distros (Raspbian, Mint, etc.) fall back to the debian repo.
+      . /etc/os-release
+      case "${ID:-ubuntu}" in
+        ubuntu) DOCKER_DISTRO=ubuntu ;;
+        *)      DOCKER_DISTRO=debian ;;
+      esac
+      curl -fsSL "https://download.docker.com/linux/${DOCKER_DISTRO}/gpg" \
+        | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
+      chmod a+r /etc/apt/keyrings/docker.gpg
+      echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
+        https://download.docker.com/linux/${DOCKER_DISTRO} $(lsb_release -cs) stable" \
+        > /etc/apt/sources.list.d/docker.list
+      apt-get update -q
+      apt-get install -y -q docker-ce docker-ce-cli containerd.io
+      systemctl enable --now docker
+      ;;
+    dnf|yum)
+      $PKG_MANAGER install -y dnf-plugins-core 2>/dev/null || $PKG_MANAGER install -y yum-utils
+      $PKG_MANAGER config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
+      $PKG_MANAGER install -y docker-ce docker-ce-cli containerd.io
+      systemctl enable --now docker
+      ;;
+    apk)
+      apk add --no-cache docker
+      rc-update add docker boot
+      service docker start
+      ;;
+  esac
+fi
+
+# ── Verify Docker daemon is reachable ─────────────────────────────────────────
+# Try docker version (faster than docker info) across all known socket paths.
+docker_reachable() {
+  docker version >/dev/null 2>&1 && return 0
+  if [ "$OS" = "Darwin" ]; then
+    DOCKER_HOST="unix://${HOME}/.docker/run/docker.sock" docker version >/dev/null 2>&1 && return 0
+    DOCKER_HOST="unix://${HOME}/.colima/default/docker.sock" docker version >/dev/null 2>&1 && return 0
+  fi
+  return 1
+}
+
+if ! docker_reachable; then
+  echo "clawops: Docker is installed but the daemon is not running." >&2
+  if [ "$PKG_MANAGER" = "darwin" ]; then
+    echo "Start Docker Desktop or run: colima start" >&2
+  else
+    echo "Try: systemctl start docker" >&2
+  fi
+  exit 1
+fi
+
+# ── Add clawops user to docker group (Linux only) ────────────────────────────
+if [ "$OS" = "Linux" ]; then
+  usermod -aG docker "${OPENCLAW_USER}" || true
+fi
+
+# ── Pull OpenClaw image ────────────────────────────────────────────────────────
+docker pull "ghcr.io/openclaw/openclaw:${OPENCLAW_VERSION}"
+
+# ── Gateway auth token ────────────────────────────────────────────────────────
+# OpenClaw refuses to bind a non-loopback listener without auth, and in a container
+# it always binds 0.0.0.0 — so without a token the gateway exits 78 and systemd
+# restart-loops. Generated once and reused on re-runs so restarts don't rotate it.
+OPENCLAW_ENV_FILE=/home/clawops/openclaw.env
+if [ ! -s "${OPENCLAW_ENV_FILE}" ]; then
+  OPENCLAW_TOKEN=$(openssl rand -hex 32 2>/dev/null || head -c 32 /dev/urandom | od -An -tx1 | tr -d ' \n')
+  printf 'OPENCLAW_GATEWAY_TOKEN=%s\n' "${OPENCLAW_TOKEN}" > "${OPENCLAW_ENV_FILE}"
+  chmod 600 "${OPENCLAW_ENV_FILE}"
+  chown "${OPENCLAW_USER}" "${OPENCLAW_ENV_FILE}" 2>/dev/null || true
+fi
+
+# ── Write default openclaw.json if absent ─────────────────────────────────────
+# clawops up --config will overwrite this with the plan config overlay.
+if [ ! -f "${OPENCLAW_CONFIG}" ]; then
+  cat > "${OPENCLAW_CONFIG}" <<'OPENCLAWJSON'
+{"meta":{"lastTouchedVersion":"2026.4"},"gateway":{"port":18789,"auth":{"mode":"token"}},"models":{},"channels":{}}
+OPENCLAWJSON
+  if [ "$OS" = "Linux" ]; then
+    chown "${OPENCLAW_USER}:${OPENCLAW_USER}" "${OPENCLAW_CONFIG}"
+  else
+    chown "${OPENCLAW_USER}" "${OPENCLAW_CONFIG}" 2>/dev/null || true
+  fi
+fi
+
+# ── Start service ─────────────────────────────────────────────────────────────
+if [ "$OS" = "Linux" ]; then
+  SERVICE_FILE=/etc/systemd/system/openclaw.service
+  cat > "${SERVICE_FILE}" <<UNIT
+[Unit]
+Description=OpenClaw gateway
+After=docker.service
+Requires=docker.service
+
+[Service]
+User=${OPENCLAW_USER}
+Restart=always
+RestartSec=5
+ExecStartPre=-/usr/bin/docker stop openclaw
+ExecStartPre=-/usr/bin/docker rm openclaw
+ExecStart=/usr/bin/docker run --name openclaw --rm \
+  -p ${OPENCLAW_PORT}:${OPENCLAW_PORT} \
+  -e OPENCLAW_CONFIG_PATH=/app/config.json --add-host=host.docker.internal:host-gateway \
+  --env-file ${OPENCLAW_ENV_FILE} \
+  -v ${OPENCLAW_CONFIG}:/app/config.json:ro \
+  ghcr.io/openclaw/openclaw:${OPENCLAW_VERSION} \
+  node openclaw.mjs gateway run --allow-unconfigured --port ${OPENCLAW_PORT}
+ExecStop=/usr/bin/docker stop openclaw
+
+[Install]
+WantedBy=multi-user.target
+UNIT
+  systemctl daemon-reload
+  systemctl enable openclaw
+  systemctl restart openclaw
+
+elif [ "$OS" = "Darwin" ]; then
+  # macOS: no systemd; run as foreground-detached container.
+  # LaunchAgent support is a future enhancement.
+  docker stop openclaw 2>/dev/null || true
+  docker rm openclaw 2>/dev/null || true
+  docker run -d \
+    --name openclaw \
+    --restart unless-stopped \
+    -p "${OPENCLAW_PORT}:${OPENCLAW_PORT}" \
+    -e OPENCLAW_CONFIG_PATH=/app/config.json --add-host=host.docker.internal:host-gateway \
+    --env-file "${OPENCLAW_ENV_FILE}" \
+  --env-file ${OPENCLAW_ENV_FILE} \
+    -v "${OPENCLAW_CONFIG}":/app/config.json:ro \
+    "ghcr.io/openclaw/openclaw:${OPENCLAW_VERSION}" \
+    node openclaw.mjs gateway run --allow-unconfigured --port ${OPENCLAW_PORT}
+fi
+
+echo "clawops: bootstrap complete"

package/dist/chunk-2YOP6N7X.js

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+import {
+  resolveSpecDir
+} from "./chunk-PVUVI35Y.js";
+
+// src/openclaw/versions.ts
+import { readFileSync } from "fs";
+import { join } from "path";
+
+// src/types/result.ts
+function ok(value) {
+  return { ok: true, value };
+}
+function err(error) {
+  return { ok: false, error };
+}
+
+// src/openclaw/versions.ts
+var MOVING_TAGS = ["latest", "stable", "dev", "main"];
+function isMovingTag(v) {
+  return MOVING_TAGS.includes(v);
+}
+var _spec;
+function loadVersionSpec(yaml) {
+  if (_spec) return _spec;
+  const specPath = join(resolveSpecDir(), "openclaw-versions.yaml");
+  try {
+    const raw = yaml.load(readFileSync(specPath, "utf-8"));
+    if (!raw?.support?.min) {
+      throw new Error("missing support.min");
+    }
+    _spec = {
+      support: {
+        min: raw.support.min,
+        max: raw.support.max ?? "",
+        recommended: raw.support.recommended ?? raw.support.min
+      }
+    };
+    return _spec;
+  } catch (e) {
+    throw new Error(
+      `Cannot load OpenClaw version support matrix from ${specPath}: ${e.message}`
+    );
+  }
+}
+function _resetVersionSpecCache() {
+  _spec = void 0;
+}
+function compareVersions(a, b) {
+  const parse = (v) => v.split(/[.-]/).map((seg) => Number.parseInt(seg, 10)).map((n) => Number.isNaN(n) ? 0 : n);
+  const pa = parse(a);
+  const pb = parse(b);
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const diff = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+function checkVersion(version, support) {
+  if (isMovingTag(version)) {
+    return err({
+      requested: version,
+      resolved: version,
+      reason: "too-new",
+      supportedRange: describeRange(support),
+      message: `Cannot verify OpenClaw compatibility: "${version}" is a moving tag that was not resolved to a concrete release. Pin an explicit version (${support.recommended}) or re-run once tag resolution is available.`
+    });
+  }
+  if (compareVersions(version, support.min) < 0) {
+    return err({
+      requested: version,
+      resolved: version,
+      reason: "too-old",
+      supportedRange: describeRange(support),
+      message: `OpenClaw ${version} is older than this clawops release supports (${describeRange(support)}). Upgrade OpenClaw, or pin ${support.recommended}.`
+    });
+  }
+  if (support.max && compareVersions(version, support.max) > 0) {
+    return err({
+      requested: version,
+      resolved: version,
+      reason: "too-new",
+      supportedRange: describeRange(support),
+      message: `OpenClaw ${version} is newer than this clawops release supports (${describeRange(support)}).
+OpenClaw 2026.8.1+ changed the container runtime contract: state moved to SQLite, config moved to a writable path, and provider plugins became install-gated.
+Use clawops 2.x for OpenClaw 2026.9.1 and later:  npm install -g @clawops/cli@latest
+To stay on this line, pin an OpenClaw version at or below ${support.max}.`
+    });
+  }
+  return ok(version);
+}
+function describeRange(support) {
+  if (!support.max) return `>= ${support.min}`;
+  return `${support.min} \u2013 ${support.max}`;
+}
+async function resolveVersion(version, resolver) {
+  if (!isMovingTag(version)) return version;
+  if (!resolver) return version;
+  try {
+    return await resolver(version) ?? version;
+  } catch {
+    return version;
+  }
+}
+async function assertSupportedVersion(version, yaml, resolver) {
+  const spec = loadVersionSpec(yaml);
+  const resolved = await resolveVersion(version, resolver);
+  const result = checkVersion(resolved, spec.support);
+  if (!result.ok && resolved !== version) {
+    return err({ ...result.error, requested: version });
+  }
+  return result;
+}
+
+export {
+  MOVING_TAGS,
+  isMovingTag,
+  loadVersionSpec,
+  _resetVersionSpecCache,
+  compareVersions,
+  checkVersion,
+  describeRange,
+  resolveVersion,
+  assertSupportedVersion
+};