fix: harden fallback handling and trusted release flow

Author: blazejpawlak

.github/workflows/ci.yml

@@ -7,10 +7,14 @@ on:
 jobs:
   validate:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
 
     steps:
       - name: Checkout
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          persist-credentials: false
 
       - name: Setup Bun
         uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
@@ -21,12 +25,12 @@ jobs:
         uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5
         with:
           path: ~/.bun/install/cache
-          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock') }}
+          key: ${{ runner.os }}-bun-ci-${{ hashFiles('bun.lock') }}
           restore-keys: |
-            ${{ runner.os }}-bun-
+            ${{ runner.os }}-bun-ci-
 
       - name: Install dependencies
-        run: bun install
+        run: bun install --frozen-lockfile
 
       - name: Lint
         run: bun run lint

.github/workflows/release-gate.yml

@@ -0,0 +1,46 @@
+name: Release Gate
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
+        with:
+          bun-version: latest
+
+      - name: Cache Bun packages
+        uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5
+        with:
+          path: ~/.bun/install/cache
+          key: ${{ runner.os }}-bun-release-gate-${{ hashFiles('bun.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-bun-release-gate-
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Lint
+        run: bun run lint
+
+      - name: Test
+        run: bun test
+
+      - name: Type check
+        run: bunx tsc --noEmit
+
+      - name: Build
+        run: bun run build

.github/workflows/release.yml

@@ -2,12 +2,16 @@ name: Release
 
 on:
   workflow_run:
-    workflows: ["CI"]
+    workflows: ["Release Gate"]
     types: [completed]
 
+concurrency:
+  group: release-main
+  cancel-in-progress: false
+
 jobs:
   release:
-    if: ${{ github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.head_branch == 'main' }}
+    if: ${{ github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.event == 'push' && github.event.workflow_run.head_branch == 'main' && github.event.workflow_run.head_sha == github.sha }}
     runs-on: ubuntu-latest
     permissions:
       contents: write
@@ -19,43 +23,66 @@ jobs:
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           fetch-depth: 0
-          ref: ${{ github.event.workflow_run.head_sha }}
-
-      - name: Setup Node.js
-        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5
-        with:
-          node-version: 24
+          persist-credentials: false
 
       - name: Setup Bun
         uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
         with:
           bun-version: latest
 
+      - name: Setup Node.js
+        uses: actions/setup-node@a0853c24544627f65ddf259abe73b1d18a591444 # v5
+        with:
+          node-version: 24
+
       - name: Cache Bun packages
         uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5
         with:
           path: ~/.bun/install/cache
-          key: ${{ runner.os }}-bun-${{ hashFiles('bun.lock') }}
+          key: ${{ runner.os }}-bun-release-${{ hashFiles('bun.lock') }}
           restore-keys: |
-            ${{ runner.os }}-bun-
+            ${{ runner.os }}-bun-release-
 
       - name: Install dependencies
-        run: bun install
+        run: bun install --frozen-lockfile
+
+      - name: Lint
+        run: bun run lint
 
       - name: Build
         run: bun run build
 
       - name: Import GPG key
-        uses: crazy-max/ghaction-import-gpg@cb9bde2e2525e640591a934b1fd28eef1dcaf5e5 # v6
-        with:
-          gpg_private_key: ${{ secrets.GPG_PRIVATE_KEY }}
-          passphrase: ${{ secrets.GPG_PASSPHRASE }}
-          git_user_signingkey: true
-          git_commit_gpgsign: true
-          git_tag_gpgsign: true
+        env:
+          GPG_PRIVATE_KEY: ${{ secrets.GPG_PRIVATE_KEY }}
+          GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }}
+        run: |
+          set -euo pipefail
+          echo "$GPG_PRIVATE_KEY" | gpg --batch --import
+          KEYGRIP=$(gpg --with-keygrip --list-secret-keys --with-colons \
+            | awk -F: '/^grp/{print $10; exit}')
+          if [ -z "$KEYGRIP" ]; then
+            echo "Unable to determine GPG keygrip" >&2
+            exit 1
+          fi
+          echo "allow-preset-passphrase" >> ~/.gnupg/gpg-agent.conf
+          gpgconf --kill gpg-agent
+          gpg-connect-agent reloadagent /bye
+          "$(gpgconf --list-dirs libexecdir)/gpg-preset-passphrase" \
+            --preset -P "$GPG_PASSPHRASE" "$KEYGRIP"
+          KEY_ID=$(gpg --list-secret-keys --with-colons | awk -F: '/^sec/{print $5; exit}')
+          if [ -z "$KEY_ID" ]; then
+            echo "Unable to determine imported GPG key id" >&2
+            exit 1
+          fi
+          git config --global user.signingkey "$KEY_ID"
+          git config --global commit.gpgsign true
+          git config --global tag.gpgsign true
 
-      - name: Set GPG_TTY
-        run: echo "GPG_TTY=$(tty)" >> $GITHUB_ENV
+      - name: Configure git auth for release
+        run: git remote set-url origin "https://x-access-token:${GITHUB_TOKEN}@github.com/${{ github.repository }}.git"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Release
         run: bun run release

AGENTS.md

@@ -9,7 +9,7 @@ OpenCode plugin that adds ordered model fallback chains with a health state mach
 ## Commands
 
 ```bash
-bun test              # Run all unit tests (145 tests across 11 files)
+bun test              # Run all unit tests (163 tests across 16 files)
 bunx tsc --noEmit     # Type check
 bun run build         # Build to dist/
 ```
@@ -34,7 +34,7 @@ After each successful implementation cycle (feature, fix, refactor), execute all
 
 ```
 src/
-  plugin.ts           # Entry point — event router + chat.message hook (preemptive redirect)
+  plugin.ts           # Entry point — event router + chat.message hook + /fallback-status command bootstrap
   preemptive.ts       # Sync preemptive redirect logic for chat.message hook
   types.ts            # Shared type definitions
   config/             # Zod schema, file discovery, defaults, auto-migration
@@ -114,16 +114,18 @@ Commits and tags are signed with GPG key `60BFBD78D728EEE4`.
 
 Fetches the passphrase via `op environment read opencode-env` (1Password Environments) and presets it into `gpg-agent` so subsequent `git commit`/`git tag` calls don't prompt. Env var overrides:
 
-| Variable | Default | Purpose |
-|---|---|---|
-| `GPG_SIGN_KEY` | `60BFBD78D728EEE4` | Key ID to unlock |
-| `OPENCODE_MANIFEST_SIGN_1PASSWORD_ENV_ID` | `opencode-env` | 1Password environment name |
-| `OPENCODE_MANIFEST_SIGN_1PASSWORD_ACCOUNT` | _(CLI default)_ | 1Password account |
-| `OPENCODE_MANIFEST_SIGN_1PASSWORD_VAR` | `OPENCODE_MANIFEST_SIGN_PASSPHRASE` | Variable name in the env |
+| Variable                                   | Default                             | Purpose                    |
+| ------------------------------------------ | ----------------------------------- | -------------------------- |
+| `GPG_SIGN_KEY`                             | `60BFBD78D728EEE4`                  | Key ID to unlock           |
+| `OPENCODE_MANIFEST_SIGN_1PASSWORD_ENV_ID`  | `opencode-env`                      | 1Password environment name |
+| `OPENCODE_MANIFEST_SIGN_1PASSWORD_ACCOUNT` | _(CLI default)_                     | 1Password account          |
+| `OPENCODE_MANIFEST_SIGN_1PASSWORD_VAR`     | `OPENCODE_MANIFEST_SIGN_PASSPHRASE` | Variable name in the env   |
 
 **CI — GitHub Actions:**
 
-`release.yml` uses `crazy-max/ghaction-import-gpg` with `secrets.GPG_PRIVATE_KEY` and `secrets.GPG_PASSPHRASE` stored as org-level GitHub secrets. The CI key is a dedicated key separate from the personal signing key — rotate it independently without touching local config. No 1Password service account is needed in CI.
+`release-gate.yml` runs trusted validation on `push` to `main`. `release.yml` is a privileged `workflow_run` that fires only after `Release Gate` succeeds for a `push` on `main`.
+
+`release.yml` imports the CI GPG key from `secrets.GPG_PRIVATE_KEY`, presets the passphrase from `secrets.GPG_PASSPHRASE`, and enables commit/tag signing before `semantic-release`. The CI key is a dedicated key separate from the personal signing key — rotate it independently without touching local config. No 1Password service account is needed in CI.
 
 ## Testing
 
@@ -133,6 +135,8 @@ Integration tests for the replay orchestrator and full fallback flow exist in `t
 
 Plugin event-handler hardening tests are in `test/plugin.test.ts`. `/fallback-status` tool output tests are in `test/fallback-status.test.ts`.
 
+Additional coverage includes startup command bootstrap (`test/plugin-create.test.ts`), logger redaction/fault-tolerance (`test/logger.test.ts`), fallback usage aggregation (`test/usage.test.ts`), and health-store timer lifecycle (`test/model-health-lifecycle.test.ts`).
+
 ## Config
 
 Plugin reads `model-fallback.json` from:

Implementation.plan.md

@@ -34,10 +34,11 @@ opencode-model-fallback/
 ├── .github/
 │   ├── workflows/
 │   │   ├── ci.yml                # CI quality gates (lint, test, typecheck, build)
-│   │   └── release.yml           # semantic-release pipeline on main
+│   │   ├── release-gate.yml      # Trusted push-to-main validation gate for releases
+│   │   └── release.yml           # Privileged semantic-release workflow_run (gated by Release Gate)
 │   └── dependabot.yml            # Weekly dependency updates
 ├── src/
-│   ├── plugin.ts                 # Plugin entry point — event router + chat.message hook
+│   ├── plugin.ts                 # Plugin entry point — event router + chat.message hook + command bootstrap
 │   ├── preemptive.ts             # Sync preemptive redirect logic for chat.message hook
 │   ├── types.ts                  # Shared type definitions
 │   ├── config/
@@ -77,6 +78,12 @@ opencode-model-fallback/
 │   ├── plugin.test.ts            # ✓ Event handler hardening (malformed payloads, recovery toast dedupe)
 │   ├── fallback-status.test.ts   # ✓ Tool output with partially seeded session state
 │   ├── agent-loader.test.ts      # ✓ Agent file parsing, frontmatter, overrides
+│   ├── notifier.test.ts          # ✓ Notification message rendering and labels
+│   ├── plugin-create.test.ts     # ✓ Startup command-file bootstrap and write-failure handling
+│   ├── logger.test.ts            # ✓ Redaction and logging fault tolerance
+│   ├── usage.test.ts             # ✓ Usage aggregation and fallback-period boundaries
+│   ├── health-tick.test.ts       # ✓ Tick-driven transition and callback behavior
+│   ├── model-health-lifecycle.test.ts # ✓ Timer unref + destroy lifecycle
 │   └── helpers/
 │       └── mock-client.ts        # Mock OpenCode client for integration tests
 └── examples/
@@ -315,7 +322,7 @@ Addresses two problems: wasted 429 round-trips per message after a successful fa
 
 ## Verification Plan
 
-1. **Unit tests** (per module): config validation, pattern matching, classification, health transitions, chain resolution, message conversion, agent loader, preemptive redirect, plugin events, fallback-status tool, tick recovery transitions, path traversal security, YAML schema enforcement — **145/145 passing**
+1. **Unit tests** (per module): config validation, pattern matching, classification, health transitions, chain resolution, message conversion, agent loader, preemptive redirect, plugin events, plugin startup bootstrap, logger redaction/fault tolerance, usage aggregation, fallback-status tool, tick recovery transitions, health timer lifecycle, path traversal security, YAML schema enforcement — **163/163 passing**
 2. **Integration tests** (mock client): full fallback flow, cascading, max depth, concurrent events, session deletion — **complete**
 3. **Manual E2E test**: Install as local plugin, configure fallback chains, trigger rate limit, verify:
    - Detection logged correctly

README.md

@@ -5,7 +5,7 @@ OpenCode plugin that adds automatic model fallback when your primary model hits
 ## How it works
 
 1. **Preemptive redirect** — intercepts outgoing messages via `chat.message` hook; if the target model is known to be rate-limited, redirects the message to a healthy fallback _before_ it hits the provider (no 429 round-trip)
-2. **Reactive fallback** — if a 429 still occurs (first hit, or preemptive not available), listens for `session.status: retry` events, aborts the retry loop, reverts the failed message, and replays it with the next healthy fallback model
+2. **Reactive fallback** — if a fallback-triggering error still occurs (first hit, or preemptive not available), listens for both `session.status: retry` and `session.error` (`APIError`) events, aborts the retry loop, reverts the failed message, and replays it with the next healthy fallback model
 3. Shows an inline toast notification and logs the event
 4. Tracks model health globally (rate limits are account-wide) — automatically recovers after configurable cooldown periods
 5. **Depth reset** — when the TUI reverts to the original model between messages, `fallbackDepth` resets so `maxFallbackDepth` only guards true cascading failures within a single message
@@ -176,6 +176,8 @@ With the `verbose` flag:
 
 Includes token/cost breakdown per model period.
 
+When enabled, the plugin auto-creates `~/.config/opencode/commands/fallback-status.md` at startup so the slash command is available without manual setup.
+
 ## Health state machine
 
 ```
@@ -187,14 +189,17 @@ cooldown ──[retryOriginalAfterMs elapsed]──→ healthy
 - **healthy** — model is usable; preferred for fallback selection
 - **rate_limited** — recently hit a limit; skipped when walking fallback chain
 - **cooldown** — cooling off; used as last resort if no healthy model is available
-- State transitions are checked every 30 seconds via a background timer
+- State transitions are checked every 30 seconds via a background timer (the timer is unref'ed so it does not keep the process alive)
 - When the original model recovers to healthy, a toast appears on the next `session.idle`
 
 ## Troubleshooting
 
 **Toast doesn't appear**
 The TUI notification requires an active OpenCode TUI session. Headless/API usage won't show toasts but logs are always written.
 
+**`/fallback-status` command is missing**
+The plugin writes `~/.config/opencode/commands/fallback-status.md` on startup. If the command does not appear, verify the directory is writable and check for `fallback-status.command.write.failed` in OpenCode logs.
+
 **"no fallback chain configured"**
 Your `model-fallback.json` has no `agents["*"].fallbackModels` (or no entry for the active agent). Add at least a wildcard entry with one model.
 
@@ -214,11 +219,14 @@ Key log events: `plugin.init`, `retry.detected`, `fallback.success`, `fallback.e
 
 To see the full event stream (including `event.received` and `retry.nomatch`), set `"logLevel": "debug"` in your config and restart OpenCode.
 
+For safety, free-form provider error text is redacted in plugin logs; use category/model/session fields for diagnosis.
+
 ## Release automation
 
 - Uses **Conventional Commits** + `semantic-release` for automated versioning/changelog/release notes
 - CI runs lint, tests, type check, and build on every push/PR via `.github/workflows/ci.yml`
-- Release workflow runs on `main` after successful CI via `.github/workflows/release.yml`
+- Trusted release gate runs on pushes to `main` via `.github/workflows/release-gate.yml`
+- Release workflow (`.github/workflows/release.yml`) runs on successful `Release Gate` completion (`workflow_run`), only for `push` events on `main`, and only when `head_sha` matches `github.sha`
 - Published as `@smart-coders-hq/opencode-model-fallback`
 - To publish to npm, set repository secret `NPM_TOKEN`
 
@@ -227,7 +235,7 @@ To see the full event stream (including `event.received` and `retry.nomatch`), s
 ```bash
 bun install
 bun run lint          # lint checks
-bun test              # 145 tests across 11 files
+bun test              # 163 tests across 16 files
 bunx tsc --noEmit     # type check
 bun run build         # build to dist/
 ```