release: prepare v0.2.5

Author: mideco-tech

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## v0.2.5 - 2026-05-06
+
+- Added the Telegram notification contract: `New run` is configurable, `[Plan]` and `[Final]` notify, while live progress, direct responses, menus, callbacks, exports, and errors are sent silently.
+- Changed Final rendering to send a new `[Final]` message and best-effort delete transient live cards, preserving Details routing on the new Final Card.
+- Fixed tool-only runs so live current tools are not erased by stale polling snapshots and completed tool-only commands remain visible in Details and Tools file.
+- Added explicit Default Mode escape hatches through `/default` and `/reply --default` for threads that remain in App Server Plan Mode.
+- Added ADR-015, contract/regression documentation, release validation notes, Telegram transport tests for `disable_notification`, and live E2E coverage for notification and tool-only Details behavior.
+
 ## v0.2.4 - 2026-05-05
 
 - Changed `/newchat <prompt>` to create a real Codex UI Chat folder under `CTR_GO_CODEX_CHATS_ROOT` before starting the new thread.

README.md

@@ -4,7 +4,7 @@ Codex Telegram bot and remote UI for local OpenAI Codex App Server, built in Go.
 
 `codex-tg` turns a Telegram bot into a mobile control surface for local Codex threads: it watches Codex GUI/CLI activity, keeps thread identity visible, routes replies back to the right thread, and exposes high-signal controls such as Plan Mode prompts, Stop, Steer, Details, Tools file, and Get full log.
 
-Current release: `v0.2.4`.
+Current release: `v0.2.5`.
 
 ![codex-tg Telegram Plan Mode demo](docs/assets/telegram-plan-mode-demo.png)
 
@@ -38,7 +38,8 @@ The demo flow is documented in [docs/demo/telegram-plan-mode-demo.md](docs/demo/
 - Telegram-origin live current tool rendering from App Server `item/*` events, while foreign GUI/CLI panels stay completed-tool only.
 - Stable visual identity per thread: emoji marker plus project/thread/run chips.
 - Explicit `New run -> [User] -> [commentary] -> [Tool] -> [Output] -> [Final]` chronology with status on the live commentary/final card.
-- Plan Mode starts from Telegram via `/plan` or `/reply --plan`, then renders `[Plan]` prompt-cards with reply-first routing and structured buttons when Codex provides choices.
+- Low-noise Telegram notifications: only `New run` (configurable), `[Plan]`, and `[Final]` are audible; live progress and exports are sent silently.
+- Plan Mode starts from Telegram via `/plan` or `/reply --plan`, and Default Mode can be forced with `/default` or `/reply --default` if a thread needs to leave Plan Mode; `[Plan]` prompt-cards keep reply-first routing and structured buttons when Codex provides choices.
 - Final Card with Details pagination and on-demand Tools file export.
 - On-demand full log archive from Codex session JSONL.
 - SQLite-backed durable state for bindings, routes, callbacks, observer target, panels, and delivery metadata.
@@ -47,7 +48,7 @@ The demo flow is documented in [docs/demo/telegram-plan-mode-demo.md](docs/demo/
 ## Platform Status
 
 - Windows: actively tested with the local Codex App Server, Telegram Bot API, observer flows, and live E2E demo.
-- macOS: `v0.2.4` is verified stable on macOS 26.3.1 arm64 with Go 1.26.2, LaunchAgent daemon startup, local build, Details binding validation, Telegram command-menu readback, real Chat folder creation, and live Telegram readback E2E.
+- macOS: `v0.2.5` is verified stable on macOS 26.3.1 arm64 with Go 1.26.2, LaunchAgent daemon startup, local build, Details binding validation, Telegram command-menu readback, real Chat folder creation, low-noise notification validation, and live Telegram readback E2E.
 - Linux: CI runs tests/builds on Ubuntu; full local daemon/runtime validation is still pending.
 
 ## Quickstart
@@ -79,7 +80,9 @@ In Telegram:
 /context
 ```
 
-Start or continue a Codex thread from Codex GUI/CLI. `codex-tg` should create a `New run` card, a `[User]` card, live progress cards, and then collapse the completed run into a final answer card with Details.
+Start or continue a Codex thread from Codex GUI/CLI. `codex-tg` should create a `New run` card, a `[User]` card, live progress cards, and then send a final answer card with Details while cleaning up transient live cards.
+
+Set `CTR_GO_NOTIFY_NEW_RUN=off` to keep `New run` visible but silent. `[Plan]` prompts and `[Final]` cards still use normal Telegram notifications.
 
 ## Runtime Commands
 
@@ -93,7 +96,7 @@ go run ./cmd/ctr-go daemon run
 Telegram commands:
 
 - `/start`, `/help`
-- `/threads`, `/projects`, `/new`, `/newchat`, `/newthread`, `/show`, `/bind`, `/reply`, `/plan`
+- `/threads`, `/projects`, `/new`, `/newchat`, `/newthread`, `/show`, `/bind`, `/reply`, `/default`, `/plan`
 - `/settings`, `/model`, `/effort`
 - `/context`, `/whereami`
 - `/observe all`, `/observe off`
@@ -121,6 +124,7 @@ Primary environment variables:
 - `CTR_GO_ALLOWED_CHAT_IDS`
 - `CTR_GO_DEFAULT_CWD`
 - `CTR_GO_CODEX_CHATS_ROOT` (`~/Documents/Codex` by default)
+- `CTR_GO_NOTIFY_NEW_RUN` (`true` by default; set `false`/`off`/`0` to send `New run` silently)
 - `CTR_GO_LOG_ENABLED` (`true` by default; set `false`/`off`/`0` to discard daemon stdout logs)
 - `CTR_GO_DIAGNOSTIC_LOGS` (`true` by default; set `false`/`off`/`0` to keep normal bot logs but suppress structured `daemon_event` diagnostics)
 - `CTR_GO_OBSERVER_POLL_SECONDS`

docs/adr/ADR-004-final-card-details-ux.md

@@ -2,23 +2,24 @@
 
 - Status: accepted
 - Decision: active runs keep trio live visibility, while completed runs collapse into one Final Card with a Details view.
+- Amended by: ADR-015 for Final Card notification delivery.
 
 ## Decisions
 
 - An active run remains live-visible through the trio of Telegram surfaces used for current execution state, tool activity, and output activity.
-- After the final answer is available, the completed run collapses into one Final Card.
+- After the final answer is available, the completed run collapses into one newly sent Final Card.
 - `Details` is view-state of that one Telegram message, not a stream of new detail messages.
 - Details mode may page through final text, tool calls, and output without creating a replacement message stream.
 - Tool and output content remains available on demand in Details tool mode.
 - Full tool and output content is also available as a `.txt` file when message-sized rendering is not practical.
-- Deletion of old live tool/output messages after finalization is best-effort.
+- Deletion of old live commentary/tool/output messages after finalization is best-effort.
 - Details callbacks are bound to the completed run panel/card that created them. Missing, stale, or mismatched panel metadata must fail closed instead of falling back to the current panel for the thread.
 
 ## Consequences
 
-- The completed-run operator surface is one stable message with Final and Details states.
+- The completed-run operator surface is one stable message with Final and Details states. That stable message is the new Final card, not the earlier live commentary message.
 - Callback handlers must edit the existing card whenever Telegram permits it instead of emitting a new stream of messages.
 - Pagination state belongs to the card view and must be recoverable from callback payloads or persisted card metadata.
 - Callback handlers must verify the panel, thread, turn, chat/topic, and message id before editing a Details/Final card or exporting Details tools.
 - Tool/output live messages must not be treated as durable final history; the final card and on-demand `.txt` export are the durable review surface.
-- Cleanup failures for old live tool/output messages must not fail final delivery.
+- Cleanup failures for old live commentary/tool/output messages must not fail final delivery.

docs/adr/ADR-006-plan-prompt-mode.md

@@ -8,6 +8,7 @@
 - A waiting Plan Mode prompt is rendered as a separate `[Plan]` prompt-card, not as a Final Card state and not as a passive tool/output message.
 - Telegram-originated Plan Mode runs must be started with App Server `turn/start` `collaborationMode.mode = plan`; prompt wording alone is not treated as Plan Mode.
 - Telegram exposes Plan start commands through `/plan <text>`, `/plan_mode <text>`, `/plan <thread> <text>`, `/plan_mode <thread> <text>`, and `/reply --plan <thread> <text>`.
+- Telegram exposes Default Mode reset commands through `/default <text>`, `/default <thread> <text>`, and `/reply --default <thread> <text>`, which pass App Server `turn/start` `collaborationMode.mode = default`.
 - `/plan <text>` and `/plan_mode <text>` use normal routing precedence after the command: reply-to route, armed state, then bound thread.
 - `/plan <thread> <text>` and `/plan_mode <thread> <text>` are treated as explicit-thread commands only when the first token is a known thread id or UUID-like Codex thread id. Unknown plain words remain part of the prompt text for the implicit route.
 - `/reply --plan <thread> <text>` stays strict and requires an explicit thread id.

docs/adr/ADR-010-run-chronology-and-user-notice.md

@@ -2,6 +2,7 @@
 
 - Status: accepted
 - Supersedes: ADR-009
+- Amended by: ADR-015 for notification policy and Final Card delivery mechanics.
 
 ## Context
 
@@ -16,7 +17,7 @@ The Telegram observer is also a security surface: if a local GUI/CLI or another
 - `New run` is an orientation card with source metadata only. It does not own run status.
 - `[User]` is delivered once as request context. It does not show run status and is not updated for status-only changes.
 - The live `[commentary]` card owns run status while the run is active.
-- At terminal finalization, `New run`, `[Tool]`, and `[Output]` are deleted best-effort. `[User]` remains as historical request context, and `[commentary]` is edited into `[Final]`.
+- At terminal finalization, the bridge sends a new `[Final]` card, then deletes `New run`, `[commentary]`, `[Tool]`, and `[Output]` best-effort. `[User]` remains as historical request context.
 - `[Final]` shows final-answer text and status only; completed commentary/tool/output history is available through Details.
 - DB message routes and callback tokens remain the routing source of truth.
 

docs/adr/ADR-015-telegram-notification-contract.md

@@ -0,0 +1,35 @@
+# ADR-015: Telegram Notification Contract
+
+- Status: accepted
+- Supersedes: the terminal finalization message-edit detail in ADR-004 and ADR-010.
+
+## Context
+
+Telegram notification volume can become noisy when every observer card is sent as a normal message. The operator still needs audible attention for genuinely important events: a new run, a final answer, and a Plan Mode question that needs a choice or reply.
+
+Telegram edits do not provide a reliable per-edit notification contract. Therefore a `[Final]` that is produced by editing the live `[commentary]` card cannot be made audible without also making the earlier commentary message audible.
+
+## Decision
+
+- New messages are silent by default through Telegram Bot API `disable_notification=true`.
+- Audible messages are limited to:
+  - `New run`, controlled by `CTR_GO_NOTIFY_NEW_RUN` and enabled by default;
+  - a newly sent `[Final]` card;
+  - a routeable `[Plan]` prompt-card for user input or structured choices.
+- `[commentary]`, `[Tool]`, `[Output]`, `[User]`, command/menu responses, explicit exports, and fallback/error messages are silent.
+- Finalization sends a new `[Final]` card, records its message route, moves the panel summary message id to that new card, and then best-effort deletes the old `[commentary]`, `New run`, `[Tool]`, and `[Output]` messages.
+- `[User]` remains as historical request context.
+- Details and Back callbacks remain bound to the completed run panel/card. After finalization, the panel's summary message id is the new `[Final]` message id.
+
+## Consequences
+
+- The operator receives fewer notifications while preserving alerts for run start, required Plan input, and run completion.
+- The completed-run surface is still one stable Final/Details message, but it is no longer the same Telegram message that previously held live commentary.
+- Old routes for deleted live commentary messages may remain in SQLite, but active callback routing uses the new Final card message id.
+- Cleanup failures for old live messages must not fail Final delivery.
+
+## Non-goals
+
+- This does not add per-chat notification profiles.
+- This does not make Telegram edits audible.
+- This does not change App Server protocol or Plan Mode routing.

docs/release/v0.2.5.md

@@ -0,0 +1,28 @@
+# v0.2.5 Release Notes
+
+## Highlights
+
+- Telegram notification noise is reduced: only `New run` (configurable), `[Plan]`, and `[Final]` use normal Telegram notifications.
+- `[Final]` is delivered as a new message and transient live cards are cleaned up best-effort after finalization.
+- Tool-only runs, such as a single long shell command with empty output, keep their current tool visible while running and expose the completed command in Details and Tools file.
+- `/default` and `/reply --default` can force the next Telegram-origin turn into App Server Default Mode when a thread remains in Plan Mode.
+- ADR-015 records the notification contract.
+
+## Validation
+
+- `go test ./internal/appserver ./internal/daemon ./internal/telegram`
+- `go test ./internal/telegram ./internal/config ./internal/daemon ./internal/storage ./tests`
+- `go test ./...`
+- `go build -buildvcs=false ./...`
+- `git diff --check`
+- Python compile for the live E2E harness
+- targeted secret/local scan
+- macOS LaunchAgent rebuild/restart
+- checked-in live Telegram E2E cases: `tool_only_sleep_details` and `notification_contract`
+
+## Notes
+
+- No App Server protocol changes were required.
+- No database migration is required.
+- `CTR_GO_NOTIFY_NEW_RUN=false` keeps the `New run` card visible but silent.
+- `v0.2.5` is a patch release on top of `v0.2.4`.

docs/research/contract-matrix.md

@@ -15,7 +15,9 @@ This file now serves two purposes:
 - `/projects`
 - `/show <thread>`
 - `/bind <thread>`
-- `/reply [--plan] <thread> <text>`
+- `/reply [--plan|--default] <thread> <text>`
+- `/default <thread> <text>`
+- `/default <text>`
 - `/plan <thread> <text>`
 - `/plan <text>`
 - `/plan_mode <thread> <text>`
@@ -53,9 +55,11 @@ This file now serves two purposes:
 - The summary panel owns `Stop` and `Steer`.
 - Tool/output stream messages do not carry buttons.
 - Final answers are delivered separately and expose `Получить полный лог`.
+- Telegram sends normal notifications only for `New run` (configurable through `CTR_GO_NOTIFY_NEW_RUN`), `[Plan]` prompt-cards, and `[Final]`; other bot messages are silent.
 - Plan Mode / waiting-input states create a separate routeable `[Plan]` prompt-card.
 - `[Plan]` buttons are structured-only: they come from Codex `choices/options/suggestions/responses`, never from bridge heuristics.
 - Telegram-originated Plan Mode starts use App Server `turn/start` with `collaborationMode.mode = plan`; prompt wording alone is not Plan Mode.
+- Telegram-originated Default Mode starts through `/default` and `/reply --default` use App Server `turn/start` with `collaborationMode.mode = default`, which is the operator escape hatch when a thread remains in Plan Mode.
 - `/model` and `/effort` are button menus backed by SQLite daemon state for Telegram-started collaboration-mode model settings.
 - After a model or reasoning-effort selection, the edited settings message removes inline choice buttons.
 - `/projects` groups cached non-Chat projects by normalized `cwd`, sorts projects by latest cached thread activity, shows latest Codex UI Chat previews, opens full Chats pagination through `Open Chats`, and never accepts arbitrary filesystem paths from Telegram.
@@ -135,6 +139,7 @@ Additional route rules:
 - reply-to `[Plan]` routes before binding and carries `thread_id`, `turn_id`, and `request_id` when available
 - real `request_id` Plan answers use App Server server-request response; synthetic Plan answers use `turn/steer`
 - `/reply --plan`, `/plan`, and `/plan_mode` carry an explicit Plan Mode start intent when they create a new turn
+- `/reply --default` and `/default` carry an explicit Default Mode start intent when they create a new turn
 
 ## Observer targets
 
@@ -163,6 +168,7 @@ Observer/UI v2 presentation contract:
   - appears before `[User]` and summary/tool/output for new runs
   - carries source markers, source mode, and route metadata, but not run status
   - is deleted best-effort after finalization
+  - uses normal Telegram notification only when `CTR_GO_NOTIFY_NEW_RUN` is enabled
 - user notice:
   - appears after `New run` for GUI/CLI runs and before summary/tool/output
   - remains after finalization as the historical request marker
@@ -171,14 +177,18 @@ Observer/UI v2 presentation contract:
   - carries project/thread source markers
   - owns live run status while active
   - carries action buttons such as `Stop` and `Steer`
+  - is sent silently and deleted best-effort after finalization
 - tool/output message:
   - carries source markers
   - carries no buttons
   - is deleted best-effort after finalization
 - final-answer message:
   - carries source markers
   - carries on-demand `Получить полный лог`
+  - is sent as a new message with a normal Telegram notification
+  - becomes the panel summary message id for Details/Back callbacks
   - contains final answer/status without replaying completed commentary/tool/output transcript
+  - exposes completed tool-only turns through Details as `Tool activity`
 
 Minimal event payload expected by the Telegram layer: