feat: upgrade-opencode stays on its major; --major/--version switches (fixes #99)

.github/workflows/test-e2e-ddev.yml

@@ -117,10 +117,14 @@ jobs:
         env:
           E2E_DDEV_SITE: ${{ (github.event_name != 'workflow_dispatch' || inputs.site_tier == true) && 'camino' || 'none' }}
           DDEV_VERSION: ${{ inputs.ddev_version }}
+          # Authorize api.github.com calls (rate-limit resilience, lib.sh
+          # gh_latest_tag) — the ephemeral workflow token, no secret needed.
+          OPK_GH_TOKEN: ${{ github.token }}
         run: |
           chmod +x ./tests/e2e/run.sh ./tests/e2e/run-docker-rootless.sh ./tests/e2e/run-ddev.sh ./tests/e2e/lib.sh ./tests/check-host.sh ./tests/unit/test-opencode-as-opencode.sh ./tests/unit/test-jsonc-parser.sh ./tests/unit/test-git-config.sh ./tests/unit/test-container-backend.sh ./tests/unit/test-bypass-guard.sh ./tests/unit/test-ddev-as-opencode.sh ./tests/unit/test-ddev-migrate.sh ./tests/unit/test-ddev-hosts.sh ./tests/unit/test-mkcert-reuse.sh ./tests/unit/test-wsl-exposure.sh ./tests/unit/test-ui.sh ./tests/unit/test-docs.sh ./tests/unit/test-kit-cli.sh ./tests/unit/test-project-paths.sh ./tests/unit/test-workflows.sh ./tests/unit/test-install-args.sh ./tests/unit/test-kit-files.sh ./tests/unit/test-tui-mode.sh ./tests/unit/test-uninstall.sh ./tests/unit/test-status.sh ./tests/unit/test-update-flags.sh ./tests/unit/test-release.sh ./tests/unit/test-fs-baseline.sh ./tests/unit/test-browser-bridge.sh ./tests/unit/test-e2e-sources.sh \
             ./files/install.sh ./files/etc/umask.sh ./files/opencode-permissions-kit-lib/management/config.sh ./files/opencode-permissions-kit-lib/management/update.sh ./files/opencode-permissions-kit-lib/management/uninstall.sh ./files/opencode-permissions-kit-lib/management/status.sh ./files/opencode-permissions-kit-lib/bin/opencode-as-opencode ./files/opencode-permissions-kit-lib/bin/opk ./files/opencode-permissions-kit-lib/sh/log.sh ./files/opencode-permissions-kit-lib/sh/ui.sh ./files/opencode-permissions-kit-lib/sh/shell-warn.sh ./files/opencode-permissions-kit-lib/bin/setup-container-backend ./files/opencode-permissions-kit-lib/bin/socket-check ./files/opencode-permissions-kit-lib/bin/cwd-check ./files/opencode-permissions-kit-lib/sh/ddev-terminal.sh ./files/opencode-permissions-kit-lib/sh/ddev-handover.sh ./files/opencode-permissions-kit-lib/sh/ddev-migrate.sh ./files/opencode-permissions-kit-lib/bin/ddev-migrate ./files/opencode-permissions-kit-lib/sh/ddev-hosts.sh ./files/opencode-permissions-kit-lib/sh/fs-baseline.sh ./files/opencode-permissions-kit-lib/sh/wsl-browser-bridge.sh ./files/opencode-permissions-kit-lib/bin/browser-bridge ./files/opencode-permissions-kit-lib/tui/kit-mode.tsx ./files/opencode-permissions-kit-lib/tui/kit-mode-2x.tsx ./files/opencode-permissions-kit-lib/tui/opencode-danger.theme.json ./files/opencode-permissions-kit-lib/tui/tui.json ./files/opencode-permissions-kit-lib/tui/tui-danger.json ./files/opencode-permissions-kit-lib/bin/ddev-as-opencode
           ./tests/e2e/run-ddev.sh
+
       - name: Summary
         if: always()
         env:
@@ -175,6 +179,7 @@ jobs:
         env:
           E2E_DDEV_SITE: ${{ (github.event_name != 'workflow_dispatch' || inputs.site_tier == true) && 'camino' || 'none' }}
           DDEV_VERSION: ${{ inputs.ddev_version }}
+          OPK_GH_TOKEN: ${{ github.token }}
         run: |
           chmod +x ./tests/e2e/run.sh ./tests/e2e/run-docker-rootless.sh ./tests/e2e/run-ddev.sh ./tests/e2e/lib.sh ./tests/check-host.sh ./tests/unit/test-opencode-as-opencode.sh ./tests/unit/test-jsonc-parser.sh ./tests/unit/test-git-config.sh ./tests/unit/test-container-backend.sh ./tests/unit/test-bypass-guard.sh ./tests/unit/test-ddev-as-opencode.sh ./tests/unit/test-ddev-migrate.sh ./tests/unit/test-ddev-hosts.sh ./tests/unit/test-mkcert-reuse.sh ./tests/unit/test-wsl-exposure.sh ./tests/unit/test-ui.sh ./tests/unit/test-docs.sh ./tests/unit/test-kit-cli.sh ./tests/unit/test-project-paths.sh ./tests/unit/test-workflows.sh ./tests/unit/test-install-args.sh ./tests/unit/test-kit-files.sh ./tests/unit/test-tui-mode.sh ./tests/unit/test-uninstall.sh ./tests/unit/test-status.sh ./tests/unit/test-update-flags.sh ./tests/unit/test-release.sh ./tests/unit/test-fs-baseline.sh ./tests/unit/test-browser-bridge.sh ./tests/unit/test-e2e-sources.sh \
             ./files/install.sh ./files/etc/umask.sh ./files/opencode-permissions-kit-lib/management/config.sh ./files/opencode-permissions-kit-lib/management/update.sh ./files/opencode-permissions-kit-lib/management/uninstall.sh ./files/opencode-permissions-kit-lib/management/status.sh ./files/opencode-permissions-kit-lib/bin/opencode-as-opencode ./files/opencode-permissions-kit-lib/bin/opk ./files/opencode-permissions-kit-lib/sh/log.sh ./files/opencode-permissions-kit-lib/sh/ui.sh ./files/opencode-permissions-kit-lib/sh/shell-warn.sh ./files/opencode-permissions-kit-lib/bin/setup-container-backend ./files/opencode-permissions-kit-lib/bin/socket-check ./files/opencode-permissions-kit-lib/bin/cwd-check ./files/opencode-permissions-kit-lib/sh/ddev-terminal.sh ./files/opencode-permissions-kit-lib/sh/ddev-handover.sh ./files/opencode-permissions-kit-lib/sh/ddev-migrate.sh ./files/opencode-permissions-kit-lib/bin/ddev-migrate ./files/opencode-permissions-kit-lib/sh/ddev-hosts.sh ./files/opencode-permissions-kit-lib/sh/fs-baseline.sh ./files/opencode-permissions-kit-lib/sh/wsl-browser-bridge.sh ./files/opencode-permissions-kit-lib/bin/browser-bridge ./files/opencode-permissions-kit-lib/tui/kit-mode.tsx ./files/opencode-permissions-kit-lib/tui/kit-mode-2x.tsx ./files/opencode-permissions-kit-lib/tui/opencode-danger.theme.json ./files/opencode-permissions-kit-lib/tui/tui.json ./files/opencode-permissions-kit-lib/tui/tui-danger.json ./files/opencode-permissions-kit-lib/bin/ddev-as-opencode

.github/workflows/test-e2e.yml

@@ -120,6 +120,10 @@ jobs:
           chmod +x ./tests/e2e/run.sh ./tests/e2e/run-docker-rootless.sh ./tests/e2e/run-ddev.sh ./tests/e2e/lib.sh ./scripts/release.sh ./tests/check-host.sh ./tests/unit/test-opencode-as-opencode.sh ./tests/unit/test-jsonc-parser.sh ./tests/unit/test-git-config.sh ./tests/unit/test-container-backend.sh ./tests/unit/test-bypass-guard.sh ./tests/unit/test-ddev-as-opencode.sh ./tests/unit/test-ddev-migrate.sh ./tests/unit/test-ddev-hosts.sh ./tests/unit/test-mkcert-reuse.sh ./tests/unit/test-wsl-exposure.sh ./tests/unit/test-ui.sh ./tests/unit/test-docs.sh ./tests/unit/test-kit-cli.sh ./tests/unit/test-project-paths.sh ./tests/unit/test-workflows.sh ./tests/unit/test-install-args.sh ./tests/unit/test-kit-files.sh ./tests/unit/test-tui-mode.sh ./tests/unit/test-uninstall.sh ./tests/unit/test-status.sh ./tests/unit/test-update-flags.sh ./tests/unit/test-release.sh ./tests/unit/test-fs-baseline.sh ./tests/unit/test-browser-bridge.sh ./tests/unit/test-e2e-sources.sh \
             ./files/install.sh ./files/etc/umask.sh ./files/opencode-permissions-kit-lib/management/config.sh ./files/opencode-permissions-kit-lib/management/update.sh ./files/opencode-permissions-kit-lib/management/uninstall.sh ./files/opencode-permissions-kit-lib/management/status.sh ./files/opencode-permissions-kit-lib/bin/opencode-as-opencode ./files/opencode-permissions-kit-lib/bin/opk ./files/opencode-permissions-kit-lib/sh/log.sh ./files/opencode-permissions-kit-lib/sh/ui.sh ./files/opencode-permissions-kit-lib/sh/shell-warn.sh ./files/opencode-permissions-kit-lib/bin/setup-container-backend ./files/opencode-permissions-kit-lib/bin/socket-check ./files/opencode-permissions-kit-lib/bin/cwd-check ./files/opencode-permissions-kit-lib/sh/ddev-terminal.sh ./files/opencode-permissions-kit-lib/sh/ddev-handover.sh ./files/opencode-permissions-kit-lib/sh/ddev-migrate.sh ./files/opencode-permissions-kit-lib/bin/ddev-migrate ./files/opencode-permissions-kit-lib/sh/ddev-hosts.sh ./files/opencode-permissions-kit-lib/sh/fs-baseline.sh ./files/opencode-permissions-kit-lib/sh/wsl-browser-bridge.sh ./files/opencode-permissions-kit-lib/bin/browser-bridge ./files/opencode-permissions-kit-lib/tui/kit-mode.tsx ./files/opencode-permissions-kit-lib/tui/kit-mode-2x.tsx ./files/opencode-permissions-kit-lib/tui/opencode-danger.theme.json ./files/opencode-permissions-kit-lib/tui/tui.json ./files/opencode-permissions-kit-lib/tui/tui-danger.json ./files/opencode-permissions-kit-lib/bin/ddev-as-opencode
           ./tests/e2e/run.sh
+        env:
+          # Authorize api.github.com calls (rate-limit resilience, lib.sh
+          # gh_latest_tag) — the ephemeral workflow token, no secret needed.
+          OPK_GH_TOKEN: ${{ github.token }}
 
   # docker-rootless daemon e2e (Phase 3). Same triggers + shared binary cache;
   # needs systemd-in-container + nested user namespaces, and SKIPs wholesale
@@ -152,6 +156,8 @@ jobs:
             ./tests/unit/test-opencode-as-opencode.sh ./tests/unit/test-jsonc-parser.sh ./tests/unit/test-git-config.sh ./tests/unit/test-container-backend.sh ./tests/unit/test-bypass-guard.sh ./tests/unit/test-ddev-as-opencode.sh ./tests/unit/test-ddev-migrate.sh ./tests/unit/test-ddev-hosts.sh ./tests/unit/test-mkcert-reuse.sh ./tests/unit/test-wsl-exposure.sh ./tests/unit/test-ui.sh ./tests/unit/test-docs.sh ./tests/unit/test-kit-cli.sh ./tests/unit/test-project-paths.sh ./tests/unit/test-workflows.sh ./tests/unit/test-install-args.sh ./tests/unit/test-kit-files.sh ./tests/unit/test-tui-mode.sh ./tests/unit/test-uninstall.sh ./tests/unit/test-status.sh ./tests/unit/test-fs-baseline.sh ./tests/unit/test-browser-bridge.sh ./tests/unit/test-e2e-sources.sh \
             ./files/install.sh ./files/etc/umask.sh ./files/opencode-permissions-kit-lib/management/config.sh ./files/opencode-permissions-kit-lib/management/update.sh ./files/opencode-permissions-kit-lib/management/uninstall.sh ./files/opencode-permissions-kit-lib/management/status.sh ./files/opencode-permissions-kit-lib/bin/opencode-as-opencode ./files/opencode-permissions-kit-lib/bin/opk ./files/opencode-permissions-kit-lib/sh/log.sh ./files/opencode-permissions-kit-lib/sh/ui.sh ./files/opencode-permissions-kit-lib/sh/shell-warn.sh ./files/opencode-permissions-kit-lib/bin/setup-container-backend ./files/opencode-permissions-kit-lib/bin/socket-check ./files/opencode-permissions-kit-lib/bin/cwd-check ./files/opencode-permissions-kit-lib/sh/ddev-terminal.sh ./files/opencode-permissions-kit-lib/sh/ddev-handover.sh ./files/opencode-permissions-kit-lib/sh/ddev-migrate.sh ./files/opencode-permissions-kit-lib/bin/ddev-migrate ./files/opencode-permissions-kit-lib/sh/ddev-hosts.sh ./files/opencode-permissions-kit-lib/sh/fs-baseline.sh ./files/opencode-permissions-kit-lib/sh/wsl-browser-bridge.sh ./files/opencode-permissions-kit-lib/bin/browser-bridge ./files/opencode-permissions-kit-lib/tui/kit-mode.tsx ./files/opencode-permissions-kit-lib/tui/kit-mode-2x.tsx ./files/opencode-permissions-kit-lib/tui/opencode-danger.theme.json ./files/opencode-permissions-kit-lib/tui/tui.json ./files/opencode-permissions-kit-lib/tui/tui-danger.json ./files/opencode-permissions-kit-lib/bin/ddev-as-opencode
           E2E_STRICT="${{ inputs.strict == true && '1' || '0' }}" ./tests/e2e/run-docker-rootless.sh
+        env:
+          OPK_GH_TOKEN: ${{ github.token }}
 
   # opencode 2.x pin (issue #80): the same suite against the CURRENT 2.x
   # release, resolved from the npm registry at run time — 2.x ships no
@@ -200,6 +206,8 @@ jobs:
           chmod +x ./tests/e2e/run.sh ./tests/e2e/run-docker-rootless.sh ./tests/e2e/run-ddev.sh ./tests/e2e/lib.sh ./scripts/release.sh ./tests/check-host.sh ./tests/unit/test-opencode-as-opencode.sh ./tests/unit/test-jsonc-parser.sh ./tests/unit/test-git-config.sh ./tests/unit/test-container-backend.sh ./tests/unit/test-bypass-guard.sh ./tests/unit/test-ddev-as-opencode.sh ./tests/unit/test-ddev-migrate.sh ./tests/unit/test-ddev-hosts.sh ./tests/unit/test-mkcert-reuse.sh ./tests/unit/test-wsl-exposure.sh ./tests/unit/test-ui.sh ./tests/unit/test-docs.sh ./tests/unit/test-kit-cli.sh ./tests/unit/test-project-paths.sh ./tests/unit/test-workflows.sh ./tests/unit/test-install-args.sh ./tests/unit/test-kit-files.sh ./tests/unit/test-tui-mode.sh ./tests/unit/test-uninstall.sh ./tests/unit/test-status.sh ./tests/unit/test-update-flags.sh ./tests/unit/test-release.sh ./tests/unit/test-fs-baseline.sh ./tests/unit/test-browser-bridge.sh ./tests/unit/test-e2e-sources.sh \
             ./files/install.sh ./files/etc/umask.sh ./files/opencode-permissions-kit-lib/management/config.sh ./files/opencode-permissions-kit-lib/management/update.sh ./files/opencode-permissions-kit-lib/management/uninstall.sh ./files/opencode-permissions-kit-lib/management/status.sh ./files/opencode-permissions-kit-lib/bin/opencode-as-opencode ./files/opencode-permissions-kit-lib/bin/opk ./files/opencode-permissions-kit-lib/sh/log.sh ./files/opencode-permissions-kit-lib/sh/ui.sh ./files/opencode-permissions-kit-lib/sh/shell-warn.sh ./files/opencode-permissions-kit-lib/bin/setup-container-backend ./files/opencode-permissions-kit-lib/bin/socket-check ./files/opencode-permissions-kit-lib/bin/cwd-check ./files/opencode-permissions-kit-lib/sh/ddev-terminal.sh ./files/opencode-permissions-kit-lib/sh/ddev-handover.sh ./files/opencode-permissions-kit-lib/sh/ddev-migrate.sh ./files/opencode-permissions-kit-lib/bin/ddev-migrate ./files/opencode-permissions-kit-lib/sh/ddev-hosts.sh ./files/opencode-permissions-kit-lib/sh/fs-baseline.sh ./files/opencode-permissions-kit-lib/sh/wsl-browser-bridge.sh ./files/opencode-permissions-kit-lib/bin/browser-bridge ./files/opencode-permissions-kit-lib/tui/kit-mode.tsx ./files/opencode-permissions-kit-lib/tui/kit-mode-2x.tsx ./files/opencode-permissions-kit-lib/tui/opencode-danger.theme.json ./files/opencode-permissions-kit-lib/tui/tui.json ./files/opencode-permissions-kit-lib/tui/tui-danger.json ./files/opencode-permissions-kit-lib/bin/ddev-as-opencode
           E2E_OC_VERSION=${{ steps.version2x.outputs.OC2_VERSION }} ./tests/e2e/run.sh
+        env:
+          OPK_GH_TOKEN: ${{ github.token }}
 
   # docker-rootless daemon e2e, opencode 2.x pin (issue #80) — the same
   # mirrored trigger/cache layout as its v1 job above; see e2e-2x for the
@@ -240,3 +248,5 @@ jobs:
             ./tests/unit/test-opencode-as-opencode.sh ./tests/unit/test-jsonc-parser.sh ./tests/unit/test-git-config.sh ./tests/unit/test-container-backend.sh ./tests/unit/test-bypass-guard.sh ./tests/unit/test-ddev-as-opencode.sh ./tests/unit/test-ddev-migrate.sh ./tests/unit/test-ddev-hosts.sh ./tests/unit/test-mkcert-reuse.sh ./tests/unit/test-wsl-exposure.sh ./tests/unit/test-ui.sh ./tests/unit/test-docs.sh ./tests/unit/test-kit-cli.sh ./tests/unit/test-project-paths.sh ./tests/unit/test-workflows.sh ./tests/unit/test-install-args.sh ./tests/unit/test-kit-files.sh ./tests/unit/test-tui-mode.sh ./tests/unit/test-uninstall.sh ./tests/unit/test-status.sh ./tests/unit/test-fs-baseline.sh ./tests/unit/test-browser-bridge.sh ./tests/unit/test-e2e-sources.sh \
             ./files/install.sh ./files/etc/umask.sh ./files/opencode-permissions-kit-lib/management/config.sh ./files/opencode-permissions-kit-lib/management/update.sh ./files/opencode-permissions-kit-lib/management/uninstall.sh ./files/opencode-permissions-kit-lib/management/status.sh ./files/opencode-permissions-kit-lib/bin/opencode-as-opencode ./files/opencode-permissions-kit-lib/bin/opk ./files/opencode-permissions-kit-lib/sh/log.sh ./files/opencode-permissions-kit-lib/sh/ui.sh ./files/opencode-permissions-kit-lib/sh/shell-warn.sh ./files/opencode-permissions-kit-lib/bin/setup-container-backend ./files/opencode-permissions-kit-lib/bin/socket-check ./files/opencode-permissions-kit-lib/bin/cwd-check ./files/opencode-permissions-kit-lib/sh/ddev-terminal.sh ./files/opencode-permissions-kit-lib/sh/ddev-handover.sh ./files/opencode-permissions-kit-lib/sh/ddev-migrate.sh ./files/opencode-permissions-kit-lib/bin/ddev-migrate ./files/opencode-permissions-kit-lib/sh/ddev-hosts.sh ./files/opencode-permissions-kit-lib/sh/fs-baseline.sh ./files/opencode-permissions-kit-lib/sh/wsl-browser-bridge.sh ./files/opencode-permissions-kit-lib/bin/browser-bridge ./files/opencode-permissions-kit-lib/tui/kit-mode.tsx ./files/opencode-permissions-kit-lib/tui/kit-mode-2x.tsx ./files/opencode-permissions-kit-lib/tui/opencode-danger.theme.json ./files/opencode-permissions-kit-lib/tui/tui.json ./files/opencode-permissions-kit-lib/tui/tui-danger.json ./files/opencode-permissions-kit-lib/bin/ddev-as-opencode
           E2E_STRICT="${{ inputs.strict == true && '1' || '0' }}" E2E_OC_VERSION=${{ steps.version2x.outputs.OC2_VERSION }} ./tests/e2e/run-docker-rootless.sh
+        env:
+          OPK_GH_TOKEN: ${{ github.token }}

docs/design/opencode-2x.md

@@ -88,6 +88,17 @@ edits reload only after seconds). Both were observed in the e2e as
 then a pkill fallback that catches a wedged daemon; both best-effort,
 1.x ignores the unknown subcommand) and re-stamps `OPENCODE_MAJOR`.
 
+*Issue #99:* version upgrades never cross majors silently. Without flags
+the latest release **of the installed major** resolves — 1.x through
+GitHub `releases/latest`, 2.x through the npm dist-tag `latest` of
+`@opencode/cli-<target>` (§8's channel split, now in `update.sh` itself;
+a resolution off the requested major fails loudly instead). `--major 1|2`
+switches majors explicitly, `--version <ver>` pins an exact release. A
+major flip re-anchors the TUI registration immediately
+(`sync_tui_registration`: plugin dir on 2.x, removed on 1.x — the 1.x
+tui.json/danger theme are major-agnostic and stay), even in
+`--only-binary` runs.
+
 ## 6. Headless classification: subcommand union
 
 The wrapper's HEADLESS list keeps every 1.x name (unknown to 2.x, which

docs/how-to/update.md

@@ -114,7 +114,9 @@ the bundled config sets `autoupdate: false`, and `update.sh` is the upgrade
 entry point:
 
 ```bash
-opk upgrade-opencode                 # latest release
+opk upgrade-opencode                 # latest release of the current major
+opk upgrade-opencode --major 2       # switch to the latest opencode 2.x
+opk upgrade-opencode --version 2.0.11  # pin an exact version
 opk upgrade-opencode --binary-path ./opencode  # specific file
 # equivalent long form:
 opk update --only-binary

docs/reference/cli.md

@@ -184,14 +184,26 @@ sudo opk update --channel stable   # or master, a feature branch, or a tag
 |---|---|
 | `--yes` | Skip the confirmation prompt |
 | `--refresh` | Also re-apply the group baseline |
-| `--binary` | Also upgrade the opencode binary to the latest release |
+| `--binary` | Also upgrade the opencode binary to the latest release **of the current major** |
 | `--only-binary` | Skip every kit step, only upgrade the opencode binary |
 | `--binary-path <file>` | Install a specific binary file instead |
 | `--channel <ref>` | Switch the tracking ref for this and every future update (re-stamps `KIT_CHANNEL`) |
+| `--major 1\|2` | Switch the opencode major (TUI registration flips with it) |
+| `--version <ver>` | Upgrade to exactly this opencode version (channel by prefix: `2.*` from npm, `1.x` from GitHub) |
 
-`opk upgrade-opencode` is the shorthand for
-`update --yes --only-binary` — extra flags (e.g. `--binary-path`) pass
-through.
+Upgrades never cross majors silently (issue #99): without `--major` /
+`--version` the latest release **of the installed major** is used — 1.x
+resolves through GitHub releases, 2.x through the npm dist-tag `latest`
+(the channel the official v2 installer uses). `opk upgrade-opencode` is
+the shorthand for `update --yes --only-binary` — extra flags (e.g.
+`--binary-path`, `--major 2`, `--version 2.0.11`) pass through:
+
+```bash
+sudo opk upgrade-opencode                 # latest of the current major
+sudo opk upgrade-opencode --major 2       # switch 1.x -> 2.x (latest 2.x)
+sudo opk upgrade-opencode --major 1       # switch back to latest 1.x
+sudo opk upgrade-opencode --version 2.0.11
+```
 
 Never touches `projects.conf` or the agent's `opencode.jsonc`. See
 [update](../how-to/update.md).