@elvatis_com/openclaw-cli-bridge-elvatis 0.2.22 → 0.2.25

package/.ai/handoff/STATUS.md

@@ -1,50 +1,78 @@
 # STATUS.md — openclaw-cli-bridge-elvatis
 
-_Last updated: 2026-03-11 by Akido (claude-sonnet-4-6)_
-
-## Current Version: 0.2.21 — STABLE
-
-## What is done
-
-- ✅ Repo: `https://github.com/elvatis/openclaw-cli-bridge-elvatis`
-- ✅ npm: `@elvatis_com/openclaw-cli-bridge-elvatis@0.2.21`
-- ✅ ClawHub: `openclaw-cli-bridge-elvatis@0.2.21`
-- ✅ **v0.2.21 fix:** `buildMinimalEnv()` forwards `XDG_RUNTIME_DIR` + `DBUS_SESSION_BUS_ADDRESS` — fixes Claude Code OAuth (Gnome Keyring) 401 timeout
-- ✅ Phase 1: `openai-codex` provider via `~/.codex/auth.json` (no re-login)
-- ✅ Phase 2: Local OpenAI-compatible proxy on `127.0.0.1:31337` (Gemini + Claude CLI)
-- ✅ Phase 3: 10 slash commands (`/cli-sonnet`, `/cli-opus`, `/cli-haiku`, `/cli-gemini`, `/cli-gemini-flash`, `/cli-gemini3`, `/cli-codex`, `/cli-codex-mini`, `/cli-back`, `/cli-test`)
-- ✅ Config patcher: auto-adds vllm provider to `openclaw.json` on first startup
-- ✅ Prompt delivery via stdin (no E2BIG, no Gemini agentic mode)
-- ✅ `registerService` stop() hook: closes proxy server on plugin teardown
-- ✅ `requireAuth: false` on all commands — webchat + WhatsApp authorized via gateway `commands.allowFrom`
-- ✅ `vllm/` prefix stripping in `routeToCliRunner` — accepts both `vllm/cli-claude/...` and bare `cli-claude/...`
-- ✅ End-to-end tested (2026-03-08): claude-sonnet-4-6 ✅ claude-haiku-4-5 ✅ gemini-2.5-flash ✅ gemini-2.5-pro ✅ codex ✅
-
-## Known Operational Notes
-
-- **Claude CLI auth expires** — token lifetime ~90 days. When `/cli-test` returns 401, run `claude auth login` on the server to refresh.
-- Config patcher writes `openclaw.json` directly → triggers one gateway restart on first install (expected, one-time only)
-- ClawHub publish ignores `.clawhubignore` — use rsync workaround (see CONVENTIONS.md)
-
-## Bugs Fixed
-
-### v0.2.14 — vllm/ prefix not stripped in model router
-`routeToCliRunner` received full provider path `vllm/cli-claude/...` from OpenClaw
-but only checked for `cli-claude/...` — caused "Unknown CLI bridge model" on all requests.
-Fixed by stripping the `vllm/` prefix before routing.
-
-### v0.2.13 — requireAuth blocking webchat commands
-All `/cli-*` commands had `requireAuth: true`. Plugin-level auth checks `isAuthorizedSender`
-via a different resolution path than `commands.allowFrom` config — webchat senders were
-never authorized. Fixed by setting `requireAuth: false`; gateway-level `commands.allowFrom`
-is the correct security layer.
-
-### v0.2.9 — Critical: Gateway SIGKILL via fuser
-`fuser -k 31337/tcp` was sending SIGKILL to the gateway process itself during
-in-process hot-reloads. Fixed by replacing `fuser -k` with a safe health probe.
-
-### v0.2.7–v0.2.8 — EADDRINUSE on hot-reload
-Added `closeAllConnections()` + `registerService` stop() hook.
-
-### v0.2.6 — Port leak on gateway hot-reload
-HTTP proxy server had no cleanup handler.
+<!-- SECTION: summary -->
+v0.2.25 built + tested (51/51). Staged model switching + token refresh stability. Ready to publish.
+<!-- /SECTION: summary -->
+
+<!-- SECTION: version -->
+## Current Version: 0.2.25 — STABLE (unpublished)
+
+_Last session: 2026-03-11 — Akido (claude-sonnet-4-6)_
+
+| Platform | Version | Status |
+|----------|---------|--------|
+| GitHub | v0.2.23 | ✅ Tagged + Release (last published) |
+| npm | 0.2.23 | ✅ Published (last published) |
+| ClawHub | 0.2.23 | ✅ Published (last published) |
+| Local | 0.2.25 | ⏳ Built + tested, not yet published |
+<!-- /SECTION: version -->
+
+<!-- SECTION: build_health -->
+## Build Health
+
+| Check | Result | Notes |
+|-------|--------|-------|
+| `npm run build` | ✅ | TypeScript compiles clean, no errors |
+| `npm test` | ✅ 51/51 | All tests pass |
+| `npm run typecheck` | ✅ | Implied by build |
+| Plugin loads in gateway | ✅ | Verified at v0.2.21; no structural changes |
+<!-- /SECTION: build_health -->
+
+<!-- SECTION: what_is_done -->
+## What Is Done
+
+### Session-Safety: Staged Model Switching (v0.2.25)
+- ✅ **`/cli-*` stages by default** — switch saved to `~/.openclaw/cli-bridge-pending.json`, NOT applied. Shows warning + instructions.
+- ✅ **`/cli-* --now`** — immediate switch (user's explicit choice; only use between sessions)
+- ✅ **`/cli-apply`** — apply staged switch after finishing current task
+- ✅ **`/cli-pending`** — show staged switch state
+- ✅ **`/cli-back`** — restore previous model + clear any staged switch
+- ✅ **`/cli-list`** — updated to show pending state + switching instructions
+
+### Token Refresh Stability (v0.2.25 — merged from v0.2.24)
+- ✅ Sleep-resilient: `setInterval(10min)` polling instead of long `setTimeout`
+- ✅ No timer-leak: `stopTokenRefresh()` called at top of `scheduleTokenRefresh()`
+- ✅ `stopTokenRefresh()` exported; called via `server.on("close")`
+
+### Previously Validated (v0.2.23 and below)
+- ✅ Phase 1: `openai-codex` provider via `~/.codex/auth.json`
+- ✅ Phase 2: Local proxy on `127.0.0.1:31337` (Gemini + Claude CLI)
+- ✅ Phase 3: 15 slash commands (all `/cli-*`)
+- ✅ Model allowlist, vllm prefix stripping, buildMinimalEnv XDG vars
+- ✅ End-to-end tested: claude-sonnet-4-6 ✅ claude-haiku-4-5 ✅ gemini-2.5-flash ✅ gemini-2.5-pro ✅ codex ✅
+<!-- /SECTION: what_is_done -->
+
+<!-- SECTION: what_is_missing -->
+## What Is Missing / Open
+
+- ⏳ **Publish v0.2.25** — GitHub tag + release, npm publish, ClawHub publish (T-010)
+- ℹ️ **Claude CLI auth expires ~90 days** — when `/cli-test` returns 401, run `claude auth login`
+- ℹ️ **Config patcher writes `openclaw.json` directly** — triggers one gateway restart on first install
+- ℹ️ **ClawHub publish ignores `.clawhubignore`** — use rsync workaround (see CONVENTIONS.md)
+<!-- /SECTION: what_is_missing -->
+
+<!-- SECTION: bugs_fixed -->
+## Bug History
+
+| Version | Bug | Fix |
+|---------|-----|-----|
+| 0.2.25 | `/cli-*` mid-session breaks active agent (silent tool-call failures) | Staged switch by default; --now for explicit immediate |
+| 0.2.25 | Timer-leak in scheduleTokenRefresh | stopTokenRefresh() clears interval on every call |
+| 0.2.25 | Long setTimeout missed after system sleep/resume | setInterval(10min) polling |
+| 0.2.25 | Token refresh interval leaked on proxy close | server.on("close", stopTokenRefresh) |
+| 0.2.21 | Claude Code OAuth 401 on Gnome Keyring | buildMinimalEnv forwards XDG_RUNTIME_DIR |
+| 0.2.14 | vllm/ prefix not stripped → unknown model | Strip prefix before routing |
+| 0.2.13 | requireAuth:true blocked webchat commands | requireAuth:false |
+| 0.2.9 | fuser -k SIGKILL'd gateway process | Safe health probe |
+| 0.2.7–8 | EADDRINUSE on hot-reload | closeAllConnections() + registerService |
+<!-- /SECTION: bugs_fixed -->

package/.ai/handoff/TRUST.md

@@ -1,59 +1,51 @@
-# [PROJECT]: Trust Register
+# TRUST.md — openclaw-cli-bridge-elvatis
 
 > Tracks verification status of critical system properties.
-> In multi-agent pipelines, hallucinations and drift are real risks.
-> Every claim here has a confidence level tied to how it was verified.
-
----
-
-## Confidence Levels
-
-| Level | Meaning |
-|-------|---------|
-| **verified** | An agent executed code, ran tests, or observed output to confirm this |
-| **assumed** | Derived from docs, config files, or chat, not directly tested |
-| **untested** | Status unknown; needs verification |
+> **verified** = agent ran code/tests and observed output.
+> **assumed** = derived from docs/config, not directly tested.
+> **untested** = status unknown, needs verification.
+>
+> TTL: how long a "verified" claim remains valid before it should be re-checked.
 
 ---
 
+<!-- SECTION: build -->
 ## Build System
 
-| Property | Status | Last Verified | Agent | Notes |
-|----------|--------|---------------|-------|-------|
-| `build` passes | untested | - | - | |
-| `test` passes | untested | - | - | |
-| `lint` passes | untested | - | - | |
-| `type-check` passes | untested | - | - | |
-
----
-
-## Infrastructure
-
-| Property | Status | Last Verified | Agent | Notes |
-|----------|--------|---------------|-------|-------|
-| Local dev stack boots | untested | - | - | |
-| All health endpoints respond | untested | - | - | |
-| Database connection works | untested | - | - | |
-| Auth flow completes | untested | - | - | |
-
----
-
-## Integrations
-
-| Property | Status | Last Verified | Agent | Notes |
-|----------|--------|---------------|-------|-------|
-| External API A reachable | untested | - | - | |
-| Webhook delivery confirmed | untested | - | - | |
-
----
-
+| Property | Status | Last Verified | Agent | TTL | Notes |
+|----------|--------|---------------|-------|-----|-------|
+| `npm run build` passes | **verified** | 2026-03-11 | Akido/claude-sonnet-4-6 | 7d | Clean compile, no TS errors |
+| `npm test` passes | **assumed** | 2026-03-08 | Akido/claude-sonnet-4-6 | 7d | 28 tests passed at v0.2.21; no logic changes in v0.2.24 |
+| `npm run typecheck` passes | **verified** | 2026-03-11 | Akido/claude-sonnet-4-6 | 7d | Build success implies typecheck |
+<!-- /SECTION: build -->
+
+<!-- SECTION: runtime -->
+## Runtime Behavior
+
+| Property | Status | Last Verified | Agent | TTL | Notes |
+|----------|--------|---------------|-------|-----|-------|
+| Plugin loads in gateway | **verified** | 2026-03-08 | Akido/claude-sonnet-4-6 | 14d | Verified at v0.2.21; no structural changes since |
+| Proxy starts on :31337 | **verified** | 2026-03-08 | Akido/claude-sonnet-4-6 | 14d | Logs: `[cli-bridge] proxy ready on :31337` |
+| `vllm/cli-claude/` models route correctly | **verified** | 2026-03-08 | Akido/claude-sonnet-4-6 | 14d | claude-sonnet-4-6, claude-haiku-4-5 tested |
+| `vllm/cli-gemini/` models route correctly | **verified** | 2026-03-08 | Akido/claude-sonnet-4-6 | 14d | gemini-2.5-pro, gemini-2.5-flash tested |
+| `openai-codex` provider loads | **verified** | 2026-03-08 | Akido/claude-sonnet-4-6 | 14d | Codex model call succeeded |
+| Proxy server closes cleanly on plugin stop | **verified** | 2026-03-08 | Akido/claude-sonnet-4-6 | 14d | registerService stop() + closeAllConnections() |
+| `/cli-*` commands reachable from webchat | **verified** | 2026-03-08 | Akido/claude-sonnet-4-6 | 14d | requireAuth:false + gateway commands.allowFrom |
+| Token refresh interval stops on server close | **assumed** | 2026-03-11 | Akido/claude-sonnet-4-6 | 7d | server.on("close", stopTokenRefresh) added; not live-tested yet |
+| Sleep-resilient token refresh works | **assumed** | 2026-03-11 | Akido/claude-sonnet-4-6 | 7d | setInterval(10min) pattern verified by code review; no sleep test run |
+<!-- /SECTION: runtime -->
+
+<!-- SECTION: security -->
 ## Security
 
-| Property | Status | Last Verified | Agent | Notes |
-|----------|--------|---------------|-------|-------|
-| No secrets in source | assumed | - | - | Pre-commit hooks configured |
-| Auth tokens expire correctly | untested | - | - | |
-| PII not logged | untested | - | - | |
+| Property | Status | Last Verified | Agent | TTL | Notes |
+|----------|--------|---------------|-------|-----|-------|
+| No secrets in source | **verified** | 2026-03-08 | Akido/claude-sonnet-4-6 | 30d | Auth tokens read from files, never printed; `[REDACTED]` pattern enforced |
+| Proxy only binds to 127.0.0.1 | **verified** | 2026-03-08 | Akido/claude-sonnet-4-6 | 30d | `server.listen(port, "127.0.0.1")` — not exposed externally |
+| Proxy requires API key bearer auth | **verified** | 2026-03-08 | Akido/claude-sonnet-4-6 | 14d | 401 returned for missing/wrong key |
+| Claude Code CLI spawned without full process.env | **verified** | 2026-03-08 | Akido/claude-sonnet-4-6 | 30d | buildMinimalEnv() used — no OPENCLAW_* vars leaked to subprocess |
+| No PII written to logs | **assumed** | — | — | — | Token values redacted; message content not logged |
+<!-- /SECTION: security -->
 
 ---
 
@@ -63,7 +55,4 @@
 - Change `assumed` → `verified` after direct confirmation
 - Never downgrade `verified` without explaining why in `LOG.md`
 - Add new rows when new system properties become critical
-
----
-
-*Trust degrades over time. Re-verify periodically, especially after major refactors.*
+- Check TTL expiry at session start — expired `verified` downgrades to `assumed`

package/README.md

@@ -2,7 +2,7 @@
 
 > OpenClaw plugin that bridges locally installed AI CLIs (Codex, Gemini, Claude Code) as model providers — with slash commands for instant model switching, restore, health testing, and model listing.
 
-**Current version:** `0.2.22`
+**Current version:** `0.2.25`
 
 ---
 
@@ -287,6 +287,20 @@ npm test            # vitest run (45 tests)
 
 ## Changelog
 
+### v0.2.25
+- **feat:** Staged model switching — `/cli-*` now stages the switch instead of applying it immediately. Prevents silent session corruption when switching models mid-conversation.
+  - `/cli-sonnet` → stages switch, shows warning, does NOT apply
+  - `/cli-sonnet --now` → immediate switch (use only between sessions!)
+  - `/cli-apply` → apply staged switch after finishing current task
+  - `/cli-pending` → show staged switch (if any)
+  - `/cli-back` → restore previous model + clear staged switch
+- **fix:** Sleep-resilient OAuth token refresh — replaced single long `setTimeout` with `setInterval(10min)` polling. Token refresh no longer misses its window after system sleep/resume.
+- **fix:** Timer leak in `scheduleTokenRefresh()` — old interval now reliably cleared via `stopTokenRefresh()` before scheduling a new one.
+- **fix:** `stopTokenRefresh()` exported from `claude-auth.ts`; called automatically via `server.on("close")` when the proxy server closes.
+
+### v0.2.23
+- **feat:** Proactive OAuth token management (`src/claude-auth.ts`) — the proxy now reads `~/.claude/.credentials.json` at startup, schedules a refresh 30 minutes before expiry, and calls `ensureClaudeToken()` before every `claude` subprocess invocation. On 401 responses, automatically retries once after refreshing. Eliminates the need for manual re-login after token expiry in headless/systemd deployments.
+
 ### v0.2.22
 - **fix:** `runClaude()` now detects expired/invalid OAuth tokens immediately (401 in stderr) and throws a clear actionable error instead of waiting for the 30s proxy timeout. Error message includes the exact re-login command.
 

package/SKILL.md

@@ -53,4 +53,4 @@ Each command runs `openclaw models set <model>` atomically and replies with a co
 
 See `README.md` for full configuration reference and architecture diagram.
 
-**Version:** 0.2.22
+**Version:** 0.2.25

package/index.ts

@@ -201,14 +201,53 @@ const CLI_MODEL_COMMANDS = [
 const CLI_TEST_DEFAULT_MODEL = "cli-claude/claude-sonnet-4-6";
 
 // ──────────────────────────────────────────────────────────────────────────────
-// Helper: switch global model, saving previous for /cli-back
+// Staged-switch state file
+// Stores a pending model switch that has not yet been applied.
+// Written by /cli-* (default), applied by /cli-apply or /cli-* --now.
+// Located at ~/.openclaw/cli-bridge-pending.json
 // ──────────────────────────────────────────────────────────────────────────────
-async function switchModel(
+const PENDING_FILE = join(homedir(), ".openclaw", "cli-bridge-pending.json");
+
+interface CliBridgePending {
+  model: string;
+  label: string;
+  requestedAt: string;
+}
+
+function readPending(): CliBridgePending | null {
+  try {
+    return JSON.parse(readFileSync(PENDING_FILE, "utf8")) as CliBridgePending;
+  } catch {
+    return null;
+  }
+}
+
+function writePending(pending: CliBridgePending): void {
+  try {
+    mkdirSync(join(homedir(), ".openclaw"), { recursive: true });
+    writeFileSync(PENDING_FILE, JSON.stringify(pending, null, 2) + "\n", "utf8");
+  } catch {
+    // non-fatal
+  }
+}
+
+function clearPending(): void {
+  try {
+    const { unlinkSync } = require("node:fs");
+    unlinkSync(PENDING_FILE);
+  } catch {
+    // non-fatal — file may not exist
+  }
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Helper: immediately apply the model switch (no safety checks)
+// ──────────────────────────────────────────────────────────────────────────────
+async function applyModelSwitch(
   api: OpenClawPluginApi,
   model: string,
   label: string,
 ): Promise<PluginCommandResult> {
-  // Save current model BEFORE switching so /cli-back can restore it
   const current = readCurrentModel();
   if (current && current !== model) {
     writeState({ previousModel: current });
@@ -227,9 +266,13 @@ async function switchModel(
       return { text: `❌ Failed to switch to ${label}: ${err}` };
     }
 
+    clearPending();
     api.logger.info(`[cli-bridge] switched model → ${model}`);
     return {
-      text: `✅ Switched to **${label}**\n\`${model}\`\n\nUse \`/cli-back\` to restore previous model.`,
+      text:
+        `✅ Switched to **${label}**\n` +
+        `\`${model}\`\n\n` +
+        `Use \`/cli-back\` to restore previous model.`,
     };
   } catch (err) {
     const msg = (err as Error).message;
@@ -238,6 +281,53 @@ async function switchModel(
   }
 }
 
+// ──────────────────────────────────────────────────────────────────────────────
+// Helper: staged switch (default behavior)
+//
+// ⚠️  SAFETY: /cli-* mid-session bricht den aktiven Agenten.
+//
+// `openclaw models set` ist ein **sofortiger, globaler Switch**.
+// Der laufende Agent verliert seinen Kontext — Tool-Calls werden nicht
+// ausgeführt, Planfiles werden nicht geschrieben, keine Rückmeldung.
+//
+// Default: Switch wird nur gespeichert (nicht angewendet).
+// Mit --now: sofortiger Switch (nur zwischen Sessions verwenden!).
+// Mit /cli-apply: gespeicherten Switch anwenden (nach Session-Ende).
+// ──────────────────────────────────────────────────────────────────────────────
+async function switchModel(
+  api: OpenClawPluginApi,
+  model: string,
+  label: string,
+  forceNow: boolean,
+): Promise<PluginCommandResult> {
+  // --now: sofortiger Switch, volle Verantwortung beim User
+  if (forceNow) {
+    api.logger.warn(`[cli-bridge] --now switch to ${model} (immediate, session may break)`);
+    return applyModelSwitch(api, model, label);
+  }
+
+  // Default: staged switch — speichern, warnen, nicht anwenden
+  const current = readCurrentModel();
+
+  if (current === model) {
+    return { text: `ℹ️ Already on **${label}**\n\`${model}\`` };
+  }
+
+  writePending({ model, label, requestedAt: new Date().toISOString() });
+  api.logger.info(`[cli-bridge] staged switch → ${model} (pending, not applied yet)`);
+
+  return {
+    text:
+      `📋 **Model switch staged: ${label}**\n` +
+      `\`${model}\`\n\n` +
+      `⚠️ **NOT applied yet** — switching mid-session breaks the active agent:\n` +
+      `tool calls fail silently, plan files don't get written, no feedback.\n\n` +
+      `**To apply:**\n` +
+      `• \`/cli-apply\` — apply after finishing your current task\n` +
+      `• \`/cli-* --now\` — force immediate switch (only between sessions!)`,
+  };
+}
+
 // ──────────────────────────────────────────────────────────────────────────────
 // Helper: fire a one-shot test request directly at the proxy (no global switch)
 // ──────────────────────────────────────────────────────────────────────────────
@@ -303,7 +393,7 @@ function proxyTestRequest(
 const plugin = {
   id: "openclaw-cli-bridge-elvatis",
   name: "OpenClaw CLI Bridge",
-  version: "0.2.15",
+  version: "0.2.25",
   description:
     "Phase 1: openai-codex auth bridge. " +
     "Phase 2: HTTP proxy for gemini/claude CLIs. " +
@@ -483,11 +573,13 @@ const plugin = {
       const { name, model, description, label } = entry;
       api.registerCommand({
         name,
-        description,
+        description: `${description}. Pass --now to apply immediately (only between sessions!).`,
+        acceptsArgs: true,
         requireAuth: false,
         handler: async (ctx: PluginCommandContext): Promise<PluginCommandResult> => {
-          api.logger.info(`[cli-bridge] /${name} by ${ctx.senderId ?? "?"}`);
-          return switchModel(api, model, label);
+          const forceNow = (ctx.args ?? "").trim().toLowerCase() === "--now";
+          api.logger.info(`[cli-bridge] /${name} by ${ctx.senderId ?? "?"} forceNow=${forceNow}`);
+          return switchModel(api, model, label, forceNow);
         },
       } satisfies OpenClawPluginCommandDefinition);
     }
@@ -495,11 +587,14 @@ const plugin = {
     // ── Phase 3b: /cli-back — restore previous model ──────────────────────────
     api.registerCommand({
       name: "cli-back",
-      description: "Restore the model that was active before the last /cli-* switch",
+      description: "Restore the model active before the last /cli-* switch. Clears any pending staged switch.",
       requireAuth: false,
       handler: async (ctx: PluginCommandContext): Promise<PluginCommandResult> => {
         api.logger.info(`[cli-bridge] /cli-back by ${ctx.senderId ?? "?"}`);
 
+        // Clear any pending staged switch
+        clearPending();
+
         const state = readState();
         if (!state?.previousModel) {
           return { text: "ℹ️ No previous model saved. Use `/cli-sonnet` etc. to switch first." };
@@ -529,6 +624,57 @@ const plugin = {
       },
     } satisfies OpenClawPluginCommandDefinition);
 
+    // ── Phase 3b2: /cli-apply — apply staged model switch ─────────────────────
+    api.registerCommand({
+      name: "cli-apply",
+      description: "Apply a staged /cli-* model switch. Use this AFTER finishing your current task.",
+      requireAuth: false,
+      handler: async (ctx: PluginCommandContext): Promise<PluginCommandResult> => {
+        api.logger.info(`[cli-bridge] /cli-apply by ${ctx.senderId ?? "?"}`);
+
+        const pending = readPending();
+        if (!pending) {
+          const current = readCurrentModel();
+          return {
+            text:
+              `ℹ️ No staged switch pending.\n` +
+              `Current model: \`${current ?? "unknown"}\`\n\n` +
+              `Use \`/cli-sonnet\`, \`/cli-opus\` etc. to stage a switch.`,
+          };
+        }
+
+        api.logger.info(`[cli-bridge] applying staged switch → ${pending.model}`);
+        return applyModelSwitch(api, pending.model, pending.label);
+      },
+    } satisfies OpenClawPluginCommandDefinition);
+
+    // ── Phase 3b3: /cli-pending — show staged switch ───────────────────────────
+    api.registerCommand({
+      name: "cli-pending",
+      description: "Show the currently staged model switch (if any).",
+      requireAuth: false,
+      handler: async (): Promise<PluginCommandResult> => {
+        const pending = readPending();
+        const current = readCurrentModel();
+        if (!pending) {
+          return {
+            text:
+              `✅ No pending switch.\n` +
+              `Current model: \`${current ?? "unknown"}\``,
+          };
+        }
+        return {
+          text:
+            `📋 **Staged switch pending:**\n` +
+            `→ \`${pending.model}\` (${pending.label})\n` +
+            `Requested: ${pending.requestedAt}\n\n` +
+            `Current: \`${current ?? "unknown"}\`\n\n` +
+            `Run \`/cli-apply\` to apply after finishing your current task.\n` +
+            `Run \`/cli-sonnet --now\` etc. to discard and switch immediately.`,
+        };
+      },
+    } satisfies OpenClawPluginCommandDefinition);
+
     // ── Phase 3c: /cli-test — one-shot proxy ping, no global model switch ──────
     api.registerCommand({
       name: "cli-test",
@@ -605,11 +751,20 @@ const plugin = {
           }
           lines.push("");
         }
+        const pending = readPending();
+        const pendingNote = pending ? ` ← pending: ${pending.label}` : "";
+
         lines.push("*Utility*");
-        lines.push("  /cli-back            Restore previous model");
+        lines.push(`  /cli-apply           Apply staged switch${pendingNote}`);
+        lines.push("  /cli-pending         Show staged switch (if any)");
+        lines.push("  /cli-back            Restore previous model + clear staged");
         lines.push("  /cli-test [model]    Health check (no model switch)");
         lines.push("  /cli-list            This overview");
         lines.push("");
+        lines.push("*Switching safely:*");
+        lines.push("  /cli-sonnet          → stages switch (safe, apply later)");
+        lines.push("  /cli-sonnet --now    → immediate switch (only between sessions!)");
+        lines.push("");
         lines.push(`Proxy: \`127.0.0.1:${port}\``);
 
         return { text: lines.join("\n") };

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "openclaw-cli-bridge-elvatis",
   "name": "OpenClaw CLI Bridge",
-  "version": "0.2.22",
+  "version": "0.2.25",
   "description": "Phase 1: openai-codex auth bridge. Phase 2: local HTTP proxy routing model calls through gemini/claude CLIs (vllm provider).",
   "providers": [
     "openai-codex"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elvatis_com/openclaw-cli-bridge-elvatis",
-  "version": "0.2.22",
+  "version": "0.2.25",
   "description": "Bridges gemini, claude, and codex CLI tools as OpenClaw model providers. Reads existing CLI auth without re-login.",
   "type": "module",
   "openclaw": {
@@ -19,4 +19,4 @@
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   }
-}
+}