release: v0.1.5 current stability + plan interaction

Author: tonyHu08

README.md

@@ -13,6 +13,8 @@ Control your local Codex threads from Telegram. Keep working while away from you
 
 Quick links: [Download](https://github.com/tonyHu08/CodeX_Telegram/releases) · [Commands](./docs/COMMANDS.md) · [FAQ](./docs/FAQ.md) · [Troubleshooting](./docs/TROUBLESHOOTING.md) · [Press kit](./assets/press-kit/README.md) · [Report issue](https://github.com/tonyHu08/CodeX_Telegram/issues)
 
+Latest: **v0.1.5** — `/current` stability patch (degrade-first snapshot), native Plan interaction path hardening, and full regression gate before release.
+
 ---
 
 ## English
@@ -33,14 +35,15 @@ Codex is great on desktop, but it is not remote-first: your work stalls the mome
 
 | Desktop app home | Telegram remote control |
 | --- | --- |
-| ![Desktop app home](./docs/assets/readme/desktop-home.png) | ![Telegram remote control](./docs/assets/readme/telegram-threads.png) |
+| ![Desktop app home](./docs/assets/readme/desktop-home-real.png) | ![Telegram remote control](./docs/assets/readme/telegram-threads-real.png) |
 
 ### Features ✨
 
 - **Remote chat with context**: keep using the same local Codex thread from Telegram.
 - **Approvals**: when Codex wants to run commands or change files, you can approve/deny from Telegram.
 - **Queue + cancel**: long runs can be cancelled with `/cancel`.
 - **Usage**: check your remaining limits with `/usage` (alias: `/limits`).
+- **Native Plan mode with interaction**: toggle with `/plan on|off|status`, answer plan questions in Telegram buttons/text, then confirm `Execute / Refine / Cancel`.
 
 Notes:
 
@@ -70,12 +73,16 @@ Notes:
 | `/current` | Show snapshot of the current bound thread |
 | `/status` | Show bridge status |
 | `/usage` / `/limits` | Show Codex rate limits remaining |
+| `/plan on` | Enable native Plan mode |
+| `/plan off` | Switch back to Code mode |
+| `/plan status` | Show mode + pending plan questions + pending execution confirmation |
 | `/cancel` | Cancel the current task |
 | `/unbind` | Clear current binding |
 
 ### Recent stability fixes 🛠️
 
 - `/threads` is now resilient: if `thread/list` is slow/unavailable, it degrades to the Codex sidebar cache so Telegram still gets a fast reply.
+- `/current` is now degrade-first: if full `includeTurns` read is slow, it returns a fallback snapshot instead of failing hard.
 - Reduced “stuck waiting” cases caused by Keychain prompts/hangs (best-effort Keychain access with short timeouts).
 
 ### Visual flow
@@ -149,14 +156,15 @@ Codex 在桌面端很强，但它不是“随时随地继续工作”的工具
 
 | 电脑端主页 | Telegram 远程控制 |
 | --- | --- |
-| ![Desktop app home](./docs/assets/readme/desktop-home.png) | ![Telegram remote control](./docs/assets/readme/telegram-threads.png) |
+| ![Desktop app home](./docs/assets/readme/desktop-home-real.png) | ![Telegram remote control](./docs/assets/readme/telegram-threads-real.png) |
 
 ### 功能亮点 ✨
 
 - **带上下文的远程续聊**：不是消息转发，是继续你本机的真实 thread。
 - **审批**：需要执行命令/修改文件时，可在 Telegram 一键同意/拒绝。
 - **队列与终止**：长任务可以用 `/cancel` 主动停止。
 - **用量**：`/usage`（别名 `/limits`）查看剩余额度。
+- **原生 Plan 模式（可交互）**：通过 `/plan on|off|status` 切换，并可在 Telegram 内回答计划问题，最终确认“执行 / 继续改 / 取消”。
 
 说明：
 
@@ -186,12 +194,16 @@ Codex 在桌面端很强，但它不是“随时随地继续工作”的工具
 | `/current` | 查看当前会话快照 |
 | `/status` | 查看桥接状态 |
 | `/usage` / `/limits` | 查看剩余用量与重置时间 |
+| `/plan on` | 开启原生 Plan 模式 |
+| `/plan off` | 切回 Code 模式 |
+| `/plan status` | 查看当前模式、待回答计划问题、待确认执行状态 |
 | `/cancel` | 终止当前任务 |
 | `/unbind` | 解除绑定 |
 
 ### 最近稳定性修复 🛠️
 
 - `/threads` 更稳：`thread/list` 超时会降级到 Codex 侧边栏缓存，确保 Telegram 仍能快速拿到列表。
+- `/current` 改为“降级优先”：`includeTurns` 读取慢时仍返回基础快照，不再直接红叉失败。
 - 降低 Keychain 造成的“卡住/无回包”风险（Keychain 访问改为短超时 best-effort）。
 
 ### 相关文档

apps/desktop/electron/local-relay.ts

@@ -43,7 +43,7 @@ interface IncomingUserMessageEvent {
   createdAt: number;
 }
 
-type ControlCommandName = 'threads' | 'bind' | 'status' | 'current' | 'active' | 'detail' | 'usage' | 'unbind' | 'cancel' | 'help';
+type ControlCommandName = 'threads' | 'bind' | 'status' | 'current' | 'active' | 'detail' | 'usage' | 'plan' | 'unbind' | 'cancel' | 'help';
 
 interface IncomingControlCommandEvent {
   type: 'incomingControlCommand';
@@ -550,6 +550,9 @@ function parseSupportedCommand(rawText: string): { command: ControlCommandName;
   if (name === 'usage' || name === 'limits') {
     return { command: 'usage', args };
   }
+  if (name === 'plan') {
+    return { command: 'plan', args };
+  }
   if (name === 'unbind') {
     return { command: 'unbind', args };
   }
@@ -588,6 +591,18 @@ function parseCallbackCommand(data: string): { command: ControlCommandName; args
   if (value === 'usage') {
     return { command: 'usage', args: '' };
   }
+  if (value === 'plan_on') {
+    return { command: 'plan', args: 'on' };
+  }
+  if (value === 'plan_off') {
+    return { command: 'plan', args: 'off' };
+  }
+  if (value === 'plan_status') {
+    return { command: 'plan', args: 'status' };
+  }
+  if (/^plan_[artsxcef]:/i.test(value)) {
+    return { command: 'plan', args: `callback ${value}` };
+  }
   if (value === 'unbind') {
     return { command: 'unbind', args: '' };
   }
@@ -609,7 +624,9 @@ function buildMainReplyKeyboard(): Record<string, unknown> {
       [{ text: '/threads' }, { text: '/bind latest' }],
       [{ text: '/usage' }, { text: '/status' }],
       [{ text: '/active' }, { text: '/current' }],
-      [{ text: '/detail' }, { text: '/cancel' }],
+      [{ text: '/plan on' }, { text: '/plan off' }],
+      [{ text: '/plan status' }, { text: '/cancel' }],
+      [{ text: '/detail' }],
       [{ text: '/unbind' }],
     ],
     resize_keyboard: true,
@@ -848,6 +865,7 @@ export async function startLocalRelay(options: LocalRelayStartOptions): Promise<
         return;
       }
 
+      const baseOptions = event.options || {};
       const failureText = event.text.trim();
       const isFailure = /^(执行失败|execution failed)[:：]?/i.test(failureText) || /app-server stopped/i.test(failureText);
       if (isFailure) {
@@ -856,11 +874,13 @@ export async function startLocalRelay(options: LocalRelayStartOptions): Promise<
           ? `${failureText}\n\n${t('建议：请确认 Codex App 已打开且在线，然后重试。', 'Tip: make sure Codex App is open and online, then retry.')}`
           : failureText;
         void sendTelegramMessage(event.chatId, `❌ ${decoratedFailure}`, {
-          replyMarkup: buildMainReplyKeyboard(),
+          ...baseOptions,
+          replyMarkup: baseOptions.replyMarkup || buildMainReplyKeyboard(),
         });
       } else {
         void sendTelegramMessage(event.chatId, `${t('✅ 已完成', '✅ Completed')}\n\n${event.text}`, {
-          replyMarkup: buildMainReplyKeyboard(),
+          ...baseOptions,
+          replyMarkup: baseOptions.replyMarkup || buildMainReplyKeyboard(),
         });
       }
     }
@@ -1365,6 +1385,7 @@ export async function startLocalRelay(options: LocalRelayStartOptions): Promise<
         { command: 'bind', description: t('绑定会话（/bind latest 或 /bind <id>）', 'Bind a thread (/bind latest or /bind <id>)') },
         { command: 'usage', description: t('查询 Codex 剩余用量', 'Show Codex usage limits') },
         { command: 'limits', description: t('查询 Codex 剩余用量（别名）', 'Show Codex usage limits (alias)') },
+        { command: 'plan', description: t('切换 Plan 模式（on/off/status）', 'Switch Plan mode (on/off/status)') },
         { command: 'current', description: t('查看当前会话快照', 'Show current thread snapshot') },
         { command: 'active', description: t('查看当前会话标题', 'Show active thread title') },
         { command: 'detail', description: t('查看会话详情（来源/ID/CWD）', 'Show thread details (source/ID/CWD)') },

apps/desktop/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codex-bridge/desktop",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "private": true,
   "main": "dist/electron/main.js",
   "scripts": {

docs/COMMANDS.md

@@ -17,6 +17,13 @@
 - `/bind <threadId|index>`
 - `/usage` (alias: `/limits`)
   - Show Codex rate limits remaining and reset time.
+- `/plan on|off|status`
+  - Toggle/query native Codex collaboration mode (Plan/Code).
+  - In Plan mode, if Codex asks follow-up questions, answer directly with Telegram buttons or text.
+  - After plan draft is produced, Telegram shows confirmation buttons:
+    - Execute plan
+    - Refine plan
+    - Cancel
 - `/active`
 - `/current`
 - `/detail <index|threadId|current|latest>`
@@ -46,6 +53,13 @@
 - `/bind <threadId|编号>`
 - `/usage`（别名：`/limits`）
   - 查询 Codex 剩余用量与重置时间。
+- `/plan on|off|status`
+  - 切换/查询 Codex 原生协作模式（Plan/Code）。
+  - Plan 模式下如果 Codex 追问决策点，可直接在 Telegram 中点按钮或发文本回答。
+  - 计划草稿完成后会出现确认按钮：
+    - 确认并执行
+    - 继续改计划
+    - 取消本轮
 - `/active`
 - `/current`
 - `/detail <编号|threadId|current|latest>`

docs/E2E_NEW_USER_REPORT.md

@@ -1,65 +1,61 @@
-# E2E New User Report (Real Desktop App + Real Telegram)
+# E2E New User Report (v0.1.5 Gate)
 
-Date: 2026-02-15  
-Target: validate "fresh install -> pair -> /threads -> bind -> remote ask -> final reply" loop.
+Date: 2026-02-25  
+Target: verify the full Telegram remote control loop and ensure `/current` no longer hard-fails with `12000ms` timeout.
 
 ## Summary
 
 ### Pass
-- Local relay starts and stays healthy.
-- Device WebSocket stream connects (`/v1/devices/stream`, `websocketClients: 1`).
-- Telegram outbound replies (from device -> relay -> Telegram) work.
-- `/threads` is now resilient:
-  - If `thread/list` is slow/unavailable, it degrades to Codex sidebar cache so Telegram always gets a reply quickly.
+- `/threads` works and returns list.
+- `/bind latest` works.
+- `/current` called 10 times continuously: no red-cross hard timeout failure text.
+- `/status` and `/usage` return expected data.
+- `/plan on`, `/plan status`, `/plan off` are accepted.
+- Baseline Plan interaction path is available.
+- `/cancel` works.
 
-### Notes (Test Harness)
-- Telegram UI automation via shell AppleScript is unreliable in this environment, so it is not used as a requirement.
-- Manual Telegram interaction is the primary verification method (real user -> bot updates).
-- The relay injection endpoint (`POST /v1/bot/incoming`) is still useful as a fast regression test for the device outbound path.
+### Key result for this release
+- `/current` is now degrade-first. Under busy thread/read conditions, it returns a fallback snapshot instead of hard-failing the command.
 
 ## Environment
-- Desktop: CodeX Telegram (packaged app in `/Applications`)
+
+- Repo: `CodeX_Telegram`
+- Desktop app: CodeX Telegram
 - Relay mode: local (`http://127.0.0.1:8787`)
-- Telegram bot: `@tony_test_2_bot`
-- Device binding:
-  - `~/.codex-bridge/data/local-relay-store.json`
+- Test harness: synthetic Telegram command loop through local relay (`/v1/bot/incoming`) with live agent websocket
+
+## Evidence
 
-## Evidence (Screens)
-- `docs/assets/e2e/01-onboarding-initial.png`
-- `docs/assets/e2e/02-telegram-pairing-attempt.png`
-- `docs/assets/e2e/03-pairing-confirmed.png`
-- `docs/assets/e2e/04-telegram-start-pressed.png`
-- `docs/assets/e2e/05-threads-response.png`
-- `docs/assets/readme/desktop-home.png`
-- `docs/assets/readme/telegram-threads.png`
+- Result JSON: `/tmp/cb_v015_release_e2e_result.json`
+- Screens:
+  - `docs/assets/readme/desktop-home-real.png`
+  - `docs/assets/readme/telegram-threads-real.png`
 
-## Key Fixes Landed During This Run
+## Automated checks
 
-### 1) `/threads` reply stability
-- Behavior:
-  - Try `thread/list` once with a short timeout.
-  - On failure, degrade to Codex Desktop sidebar cache (`~/.codex/.codex-global-state.json`) and still return a usable list.
-- User-facing note:
-  - When degraded, the reply includes a short warning that timestamps may be missing.
+1. `/threads returns list` ✅
+2. `/bind latest works` ✅
+3. `/current x10 no hard timeout text` ✅
+4. `/status works` ✅
+5. `/usage works` ✅
+6. `/plan on accepted` ✅
+7. `/plan status works` ✅
+8. `plan interaction baseline` ✅
+9. `/cancel works` ✅
+10. `/plan off works` ✅
 
-### 2) Device stream reliability (Keychain pitfalls)
-- Avoid blocking flows caused by Keychain writeback prompts/hangs.
-- Keychain reads are now best-effort with a short timeout, and token restoration can fall back to local relay store.
+## Notes
 
-## Verification Steps Executed
+- This gate focuses on command reliability and regression safety for release.
+- Telegram UI automation is intentionally not treated as required; command-path verification is done through the bridge agent test harness plus manual message checks.
 
-### Phase A: Health + binding
-1. Confirm relay health:
-   - `GET /healthz` returns `telegramEnabled: true` and the expected `botUsername`.
-2. Confirm device stream:
-   - `GET /v1/devices/me` (Bearer token from local relay store) returns `connected: true`.
 
-### Phase B: Command loop (real Telegram)
-1. In Telegram, run `/threads`, bind a thread, and send a short prompt.
-2. Verify relay forwards device outbound event and Telegram receives message:
-   - Relay logs show `eventType: finalResponse` with the command/turn content preview.
+### Release gate evidence
 
-## Follow-ups
-- Add an in-app "Send test command" (local-only) button in onboarding to validate inbound/outbound without requiring UI automation.
-- Improve end-user diagnostics when Telegram polling is unhealthy:
-  - Show last polling error + a "Restart bot polling" action.
+- `/threads` x5 pass
+- `/bind latest` pass
+- `/current` x10 pass (no `thread/read timed out after 12000ms` red-cross failure)
+- `/status` pass
+- `/usage` pass
+- `/plan on` + `/plan status` + plan message + `/plan off` pass
+- `/cancel` pass

docs/assets/readme/desktop-home-real.png

@@ -0,0 +1,29 @@
+# v0.1.5
+
+Release date: 2026-02-25
+
+## Highlights
+
+- `/current` stability fix:
+  - Reworked thread snapshot read into a degrade-first pipeline.
+  - Increased stage timeouts and removed old hard-fail behavior in busy/large threads.
+  - If full turns cannot be loaded in time, Telegram now gets a fallback snapshot instead of a red-cross fatal timeout.
+- Native Plan mode interaction loop:
+  - `/plan on|off|status` available in command parser + keyboard.
+  - Preserved callback keyboards in final responses so plan confirmations are actionable.
+- Reliability hardening:
+  - Better retry/degrade logs for `thread/read` and `thread/resume`.
+
+## Regression checklist
+
+- `/threads` works repeatedly
+- `/bind latest` works
+- `/current` no hard timeout red-cross across repeated calls
+- `/status` and `/usage` work
+- `/plan on`/`/plan off`/`/plan status` work
+- `/cancel` works
+
+## Assets
+
+- `CodeX Telegram-0.1.5-arm64.dmg`
+- `CodeX Telegram-0.1.5-arm64-mac.zip`

docs/assets/readme/telegram-threads-real.png

@@ -1,6 +1,6 @@
 {
   "name": "codex-telegram",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "private": true,
   "license": "MIT",
   "description": "CodeX Telegram monorepo (bridge-core + desktop app + cloud relay)",