From 72a6cb8a7286564f2b88eefaf1aefcd909b4e207 Mon Sep 17 00:00:00 2001 From: manhnguyen24-dev Date: Mon, 14 Sep 2026 13:26:38 +0700 Subject: [PATCH 01/71] feat(remote): Task 1 - remote-pairing schema and OS-vault credential store Foundation for the Telegram remote-control feature (spec: documents/plans/remote-channel-telegram.md, plan: documents/plans/remote-access-telegram-implementation.md). - app/core/credential_store.py: standalone, keyed OS-vault credential store (service/account at construction). Independent of app/conductor/, which keeps its own separate implementation unchanged - evo-conductor depends on Conductor's current behavior and constructor signature. - app/models/remote.py: RemoteConnection (per-installation bot connection, non-secret metadata only) and RemotePairing (connection-scoped principal/ destination binding), both registered in app/models/__init__.py and app/migrations/env.py. - Migration 00000064 creates remote_connections and remote_pairings; SCHEMA_HEAD bumped to match. - Tests: tests/core/test_credential_store.py, tests/remote/test_models.py, and extended tests/core/test_alembic_migrations.py to assert the new tables/columns/FKs/unique constraints at head. tests/conductor/test_client_service.py still passes unmodified, confirming Conductor has zero behavior change. AC-3, AC-4, AC-5, AC-6, AC-17 (partial - schema only; service/route behavior follows in Task 2+). --- app/core/credential_store.py | 68 ++ app/core/schema_version.py | 2 +- app/migrations/env.py | 1 + .../00000064_create_remote_pairings.py | 80 ++ app/models/__init__.py | 3 + app/models/remote.py | 86 ++ .../remote-access-telegram-implementation.md | 772 ++++++++++++++++++ documents/plans/remote-channel-telegram.md | 771 +++++++++++++++++ tests/core/test_alembic_migrations.py | 45 + tests/core/test_credential_store.py | 69 ++ tests/remote/test_models.py | 43 + 11 files changed, 1939 insertions(+), 1 deletion(-) create mode 100644 app/core/credential_store.py create mode 100644 app/migrations/versions/00000064_create_remote_pairings.py create mode 100644 app/models/remote.py create mode 100644 documents/plans/remote-access-telegram-implementation.md create mode 100644 documents/plans/remote-channel-telegram.md create mode 100644 tests/core/test_credential_store.py create mode 100644 tests/remote/test_models.py diff --git a/app/core/credential_store.py b/app/core/credential_store.py new file mode 100644 index 00000000..5468bd93 --- /dev/null +++ b/app/core/credential_store.py @@ -0,0 +1,68 @@ +"""Keyed storage for integration credentials in the operating-system vault.""" + +from __future__ import annotations + +from typing import Protocol + + +class CredentialStoreProtocol(Protocol): + def load(self) -> str | None: ... + + def save(self, credential: str) -> None: ... + + def delete(self) -> None: ... + + +class CredentialStoreError(RuntimeError): + """The operating-system credential vault could not complete an operation.""" + + +class CredentialStore: + """Store one credential under an explicit service and account key.""" + + def __init__(self, *, service: str, account: str) -> None: + if not service.strip() or not account.strip(): + raise ValueError("Credential service and account must not be empty.") + self._service = service + self._account = account + + def load(self) -> str | None: + try: + import keyring + + return keyring.get_password(self._service, self._account) + except Exception as exc: + raise CredentialStoreError( + "The operating system credential vault is unavailable." + ) from exc + + def save(self, credential: str) -> None: + try: + import keyring + + keyring.set_password(self._service, self._account, credential) + except Exception as exc: + raise CredentialStoreError( + "The credential could not be saved to the operating system credential vault." + ) from exc + + def delete(self) -> None: + try: + import keyring + from keyring.errors import PasswordDeleteError + except Exception as exc: + raise CredentialStoreError( + "The operating system credential vault is unavailable." + ) from exc + + try: + keyring.delete_password(self._service, self._account) + except PasswordDeleteError: + return + except Exception as exc: + raise CredentialStoreError( + "The credential could not be deleted from the operating system credential vault." + ) from exc + + +__all__ = ["CredentialStore", "CredentialStoreError", "CredentialStoreProtocol"] diff --git a/app/core/schema_version.py b/app/core/schema_version.py index 49b6340d..b8a44dfc 100644 --- a/app/core/schema_version.py +++ b/app/core/schema_version.py @@ -13,7 +13,7 @@ # Keep this in sync with the single Alembic head. The migration tests and the # sidecar build validate the value, so a release cannot silently ship a stale # marker. -SCHEMA_HEAD = "00000063" +SCHEMA_HEAD = "00000064" @dataclass(frozen=True) diff --git a/app/migrations/env.py b/app/migrations/env.py index 25bdc91e..b6d3302e 100644 --- a/app/migrations/env.py +++ b/app/migrations/env.py @@ -13,6 +13,7 @@ from app.models import ChatSession, SessionMessage # noqa: F401 from app.models import DelegationTask, GitServerConnection # noqa: F401 from app.models import MemoryExtractionState, MemoryFact, MemoryFactEvidence # noqa: F401 +from app.models import RemoteConnection, RemotePairing # noqa: F401 from app.models import ( # noqa: F401 TraceDeviation, TraceEvidence, diff --git a/app/migrations/versions/00000064_create_remote_pairings.py b/app/migrations/versions/00000064_create_remote_pairings.py new file mode 100644 index 00000000..62e29538 --- /dev/null +++ b/app/migrations/versions/00000064_create_remote_pairings.py @@ -0,0 +1,80 @@ +"""create remote connection and pairing tables + +Revision ID: 00000064 +Revises: 00000063 +Create Date: 2026-09-14 +""" + +from typing import Sequence, Union + +import sqlalchemy as sa +from alembic import op + +from app.models.chat import TZDateTime + +revision: str = "00000064" +down_revision: Union[str, Sequence[str], None] = "00000063" +branch_labels: Union[str, Sequence[str], None] = None +depends_on: Union[str, Sequence[str], None] = None + + +def upgrade() -> None: + op.create_table( + "remote_connections", + sa.Column("id", sa.Uuid(), primary_key=True), + sa.Column("adapter", sa.String(length=32), nullable=False), + sa.Column("label", sa.String(length=120), nullable=False), + sa.Column("enabled", sa.Boolean(), nullable=False, server_default=sa.false()), + sa.Column("adapter_principal_id", sa.String(length=128), nullable=False), + sa.Column( + "adapter_username", sa.String(length=128), nullable=False, server_default="" + ), + sa.Column("created_at", TZDateTime(), nullable=False), + sa.Column("updated_at", TZDateTime(), nullable=False), + ) + op.create_index( + "ix_remote_connections_enabled", "remote_connections", ["enabled"] + ) + + op.create_table( + "remote_pairings", + sa.Column("id", sa.Uuid(), primary_key=True), + sa.Column( + "connection_id", + sa.Uuid(), + sa.ForeignKey("remote_connections.id", ondelete="CASCADE"), + nullable=False, + ), + sa.Column("principal_id", sa.String(length=128), nullable=False), + sa.Column("destination_id", sa.String(length=128), nullable=False), + sa.Column("label", sa.String(length=120), nullable=False), + sa.Column("display", sa.String(length=120), nullable=False, server_default=""), + sa.Column( + "active_session_id", + sa.Uuid(), + sa.ForeignKey("chat_sessions.id", ondelete="SET NULL"), + nullable=True, + ), + sa.Column("created_at", TZDateTime(), nullable=False), + sa.Column("last_seen_at", TZDateTime(), nullable=False), + sa.UniqueConstraint( + "connection_id", + "principal_id", + name="uq_remote_pairings_connection_principal", + ), + sa.UniqueConstraint( + "connection_id", + "destination_id", + name="uq_remote_pairings_connection_destination", + ), + ) + op.create_index( + "ix_remote_pairings_connection", "remote_pairings", ["connection_id"] + ) + + +def downgrade() -> None: + op.drop_index("ix_remote_pairings_connection", table_name="remote_pairings") + op.drop_table("remote_pairings") + op.drop_index("ix_remote_connections_enabled", table_name="remote_connections") + op.drop_table("remote_connections") diff --git a/app/models/__init__.py b/app/models/__init__.py index 2f971bed..9439684f 100644 --- a/app/models/__init__.py +++ b/app/models/__init__.py @@ -7,6 +7,7 @@ ) from .goal import SessionGoal from .memory import MemoryExtractionState, MemoryFact, MemoryFactEvidence +from .remote import RemoteConnection, RemotePairing from .team import DelegationTask from .trace import ( TraceDeviation, @@ -39,6 +40,8 @@ "MemoryExtractionState", "MemoryFact", "MemoryFactEvidence", + "RemoteConnection", + "RemotePairing", "SessionMessage", "ScheduledTask", "SessionGoal", diff --git a/app/models/remote.py b/app/models/remote.py new file mode 100644 index 00000000..ee299b2c --- /dev/null +++ b/app/models/remote.py @@ -0,0 +1,86 @@ +"""Durable, non-secret metadata for remote connections and pairings.""" + +from __future__ import annotations + +from datetime import datetime +from uuid import UUID, uuid4 + +import sqlalchemy as sa +from sqlalchemy import Column, ForeignKey +from sqlmodel import Field, SQLModel + +from app.models.chat import TZDateTime, _utcnow + + +class RemoteConnection(SQLModel, table=True): + __tablename__: str = "remote_connections" # type: ignore[reportIncompatibleVariableOverride] + __table_args__ = (sa.Index("ix_remote_connections_enabled", "enabled"),) + + id: UUID = Field(default_factory=uuid4, primary_key=True) + adapter: str = Field(sa_column=Column(sa.String(32), nullable=False)) + label: str = Field(sa_column=Column(sa.String(120), nullable=False)) + enabled: bool = Field( + default=False, + sa_column=Column(sa.Boolean(), nullable=False, server_default=sa.false()), + ) + adapter_principal_id: str = Field( + sa_column=Column(sa.String(128), nullable=False) + ) + adapter_username: str = Field( + default="", + sa_column=Column(sa.String(128), nullable=False, server_default=""), + ) + created_at: datetime = Field( + default_factory=_utcnow, sa_column=Column(TZDateTime(), nullable=False) + ) + updated_at: datetime = Field( + default_factory=_utcnow, + sa_column=Column(TZDateTime(), nullable=False, onupdate=_utcnow), + ) + + +class RemotePairing(SQLModel, table=True): + __tablename__: str = "remote_pairings" # type: ignore[reportIncompatibleVariableOverride] + __table_args__ = ( + sa.UniqueConstraint( + "connection_id", + "principal_id", + name="uq_remote_pairings_connection_principal", + ), + sa.UniqueConstraint( + "connection_id", + "destination_id", + name="uq_remote_pairings_connection_destination", + ), + sa.Index("ix_remote_pairings_connection", "connection_id"), + ) + + id: UUID = Field(default_factory=uuid4, primary_key=True) + connection_id: UUID = Field( + sa_column=Column( + sa.Uuid(), + ForeignKey("remote_connections.id", ondelete="CASCADE"), + nullable=False, + ) + ) + principal_id: str = Field(sa_column=Column(sa.String(128), nullable=False)) + destination_id: str = Field(sa_column=Column(sa.String(128), nullable=False)) + label: str = Field(sa_column=Column(sa.String(120), nullable=False)) + display: str = Field( + default="", + sa_column=Column(sa.String(120), nullable=False, server_default=""), + ) + active_session_id: UUID | None = Field( + default=None, + sa_column=Column( + sa.Uuid(), + ForeignKey("chat_sessions.id", ondelete="SET NULL"), + nullable=True, + ), + ) + created_at: datetime = Field( + default_factory=_utcnow, sa_column=Column(TZDateTime(), nullable=False) + ) + last_seen_at: datetime = Field( + default_factory=_utcnow, sa_column=Column(TZDateTime(), nullable=False) + ) diff --git a/documents/plans/remote-access-telegram-implementation.md b/documents/plans/remote-access-telegram-implementation.md new file mode 100644 index 00000000..f90e5ad8 --- /dev/null +++ b/documents/plans/remote-access-telegram-implementation.md @@ -0,0 +1,772 @@ +# Remote Access over Telegram Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Add one-tap, outbound-only phone access to a running EvoFlux installation through one user-owned Telegram bot. + +**Architecture:** A connection-aware `app/remote/` core owns authorization, lifecycle, routing, projection, and ephemeral capabilities; a Telegram adapter owns only Bot API translation and polling. Two database tables hold non-secret connection/pairing metadata, while a new, independent OS-vault abstraction stores tokens by connection ID. Phone text enters the existing persisted interactive path and normalized stream events leave through an explicit redaction boundary. + +**Tech Stack:** Python 3.12, FastAPI, SQLModel/Alembic, asyncio, httpx, keyring, Pydantic v2, pytest; React 19, TypeScript, TanStack Query, existing Settings primitives, Bun/Vitest. + +**Spec:** [`remote-channel-telegram.md`](remote-channel-telegram.md) + +## Global Constraints + +- Telegram is the only v1 adapter; public storage and service contracts remain connection-aware. +- One configured connection and one paired Telegram account are allowed per installation in v1. +- Each installation uses a user-supplied personal bot token; there is no shared bot or relay. +- No inbound listener, tunnel, public URL, LAN mode, or loopback self-call is introduced. +- Tokens live only in the OS credential vault; vault failure leaves no partial configuration and has no `.env` fallback. +- Private chats only; principal ID authorizes and destination ID addresses replies. +- Messages received while EvoFlux is stopped are discarded at the next startup. +- Remote permission replies are limited to `once` and `reject`; remote access cannot widen durable policy or configuration. +- All outbound user/agent text uses explicit remote-channel redaction, defaults to `redact`, and is sent without Telegram parse mode. +- Stream observers are synchronous, bounded, and non-blocking; no network or database work runs under stream locks. +- **`app/conductor/client.py` and `app/conductor/service.py` are never modified.** Conductor is relied on externally by `evo-conductor`, including the exact public constructor signature of its existing credential wrapper; the new OS-vault abstraction (`app/core/credential_store.py`) is standalone code used only by `app/remote/`, not a refactor Conductor is migrated onto. +- Every task cites its ACs, adds focused evidence first, and leaves the application usable at its checkpoint. +- Commit all resulting changes in the repository, including unrelated pre-existing modifications already in the working tree, as a single commit once implementation is verified. + +--- + +## File and interface map + +New backend units: + +- `app/core/credential_store.py` — keyed OS-vault protocol and implementation, standalone and used only by `app/remote/` (Conductor keeps its own separate implementation, untouched). +- `app/remote/contracts.py` — provider-neutral dataclasses/enums/protocols. +- `app/remote/connection_service.py` — durable connection CRUD, v1 cardinality, vault coordination. +- `app/remote/pairing.py` — deep-link capability issuance and principal binding. +- `app/remote/inbound.py` — authorization, commands, current-task selection, persisted chat admission. +- `app/remote/outbound.py` — allowlisted event projection, redaction, splitting, delivery queues. +- `app/remote/gates.py` — opaque callbacks and existing gate-service resolution. +- `app/remote/actions.py` — optional Workflow/Coding/EASD/Scheduler menus. +- `app/remote/runtime.py` — process lifecycle and per-connection adapter ownership. +- `app/remote/telegram/models.py` — bounded Pydantic payloads with `extra="ignore"`. +- `app/remote/telegram/client.py` — raw Bot API HTTP calls and error classification. +- `app/remote/telegram/adapter.py` — polling loop and normalized action translation. +- `app/api/schemas/remote.py`, `app/api/routes/remote.py` — authenticated desktop API. +- `tests/core/test_credential_store.py`, `tests/remote/`, `tests/api/routes/test_remote.py` — focused backend evidence. + +New frontend units: + +- `web/src/api/client/remote.ts` — typed remote Settings/connection API. +- `web/src/components/settings/RemoteAccessSettings.tsx` — setup, QR/link, pairing, status, removal. +- `web/src/__tests__/components/settings/RemoteAccessSettings.test.tsx` — primary UI states and secret handling. + +Changed shared units: + +- `app/models/__init__.py`, `app/migrations/env.py`, `app/core/schema_version.py` — model/migration registration. +- `app/core/runtime_settings.py`, `app/api/schemas/settings.py`, `app/api/routes/settings.py` — remote outbound policy. +- `app/services/memory_stream_store.py` — synchronous global observer registry. +- `app/services/interactive_message_service.py` — channel-neutral source metadata lookup. +- `app/agent/outbound_redaction.py` — add `remote` to `OutboundChannel`. +- `app/api/app.py` — lazy optional remote startup and structured shutdown. +- Settings navigation/client exports, three Help locales, and current docs named by the spec. + +--- + +### Task 1: Keyed OS-vault abstraction and connection-aware schema + +**ACs:** AC-3, AC-4, AC-5, AC-6, AC-17 + +**Files:** + +- Create: `app/core/credential_store.py` (standalone; Conductor is not touched or migrated onto it) +- Replace unfinished content: `app/models/remote.py` +- Replace unfinished content: `app/migrations/versions/00000064_create_remote_pairings.py` +- Modify: `app/models/__init__.py` +- Modify: `app/migrations/env.py` +- Keep/verify: `app/core/schema_version.py` +- Create: `tests/core/test_credential_store.py` +- Create: `tests/remote/test_models.py` +- Modify: `tests/core/test_alembic_migrations.py` + +**Interfaces:** + +- Produces `CredentialStoreProtocol.load/save/delete`, keyed by service/account at construction. +- Produces `RemoteConnection` and `RemotePairing`; later tasks import them from `app.models`. +- No network or runtime service is introduced in this task. + +- [ ] **Step 1: Write vault tests that prove key isolation and secret-safe errors** + +```python +def test_keyed_store_uses_supplied_service_and_account(fake_keyring): + store = CredentialStore(service="EvoFlux Remote", account="connection:abc") + store.save("secret") + assert fake_keyring.saved == ("EvoFlux Remote", "connection:abc", "secret") + +def test_vault_error_does_not_echo_secret(fake_keyring): + fake_keyring.set_password.side_effect = RuntimeError("boom") + with pytest.raises(CredentialStoreError) as exc: + CredentialStore(service="EvoFlux Remote", account="connection:abc").save("secret") + assert "secret" not in str(exc.value) +``` + +- [ ] **Step 2: Run the vault tests and confirm they fail before the abstraction exists** + +```powershell +uv run pytest --no-cov -q tests/core/test_credential_store.py +``` + +Expected: collection/import failure for `app.core.credential_store`. + +- [ ] **Step 3: Implement the generic vault as new, standalone infrastructure** + +```python +class CredentialStoreProtocol(Protocol): + def load(self) -> str | None: ... + def save(self, credential: str) -> None: ... + def delete(self) -> None: ... + +class CredentialStore: + def __init__(self, *, service: str, account: str) -> None: ... + def load(self) -> str | None: ... + def save(self, credential: str) -> None: ... + def delete(self) -> None: ... +``` + +Use `keyring.get_password/set_password/delete_password`, preserve missing-entry delete behavior, and wrap all other failures in `CredentialStoreError` with fixed messages. **Do not touch Conductor.** `app/conductor/client.py` and `app/conductor/service.py` keep their own separate `CredentialStore`/`CredentialStoreError`/`CredentialStoreProtocol` definitions and parameterless constructor exactly as they are today — Conductor is relied on externally by `evo-conductor`, and this module exists purely for `app/remote/` to construct as `CredentialStore(service="EvoFlux Remote", account=f"connection:{connection_id}")`. + +- [ ] **Step 4: Write model and migration tests before replacing the partial schema** + +```python +def test_pairing_keeps_authorization_and_destination_separate(): + pairing = RemotePairing( + connection_id=uuid4(), principal_id="user-1", destination_id="chat-9", label="Phone" + ) + assert pairing.principal_id != pairing.destination_id +``` + +Extend migration evidence to assert head `00000064`, tables `remote_connections` and `remote_pairings`, both uniqueness constraints, connection cascade, and session `SET NULL`. + +- [ ] **Step 5: Implement and register the exact models** + +```python +class RemoteConnection(SQLModel, table=True): + id: UUID + adapter: str + label: str + enabled: bool + adapter_principal_id: str + adapter_username: str + created_at: datetime + updated_at: datetime + +class RemotePairing(SQLModel, table=True): + id: UUID + connection_id: UUID + principal_id: str + destination_id: str + label: str + display: str + active_session_id: UUID | None + created_at: datetime + last_seen_at: datetime +``` + +The migration creates both tables in dependency order. Do not retain the unfinished `channel`, `account_id`, or `revoked_at` columns from the earlier draft. + +- [ ] **Step 6: Run focused schema tests and confirm Conductor is untouched** + +```powershell +uv run pytest --no-cov -q tests/core/test_credential_store.py tests/remote/test_models.py tests/core/test_alembic_migrations.py tests/conductor/test_client_service.py +uv run ruff check app/core/credential_store.py app/models/remote.py tests/core/test_credential_store.py tests/remote/test_models.py +uv run ty check app/ +git diff --stat -- app/conductor +``` + +Expected: all tests pass; the last command prints no output, proving `app/conductor/` has no diff. + +--- + +### Task 2: Remote settings, core contracts, and durable connection service + +**ACs:** AC-3, AC-4, AC-5, AC-6, AC-23, AC-32, AC-34 + +**Files:** + +- Create: `app/remote/__init__.py` +- Create: `app/remote/contracts.py` +- Create: `app/remote/connection_service.py` +- Modify: `app/core/runtime_settings.py` +- Modify: `app/api/schemas/settings.py` +- Modify: `app/api/routes/settings.py` +- Modify: `app/agent/outbound_redaction.py` +- Create: `tests/remote/test_connection_service.py` +- Modify: `tests/api/test_settings_routes.py` +- Modify: `tests/agent/test_outbound_redaction.py` + +**Interfaces:** + +- Produces `RemoteSettings(outbound_data_policy="redact", outbound_pii_policy="standard")`. +- Produces `RemoteConnectionService.create/update_token/set_enabled/remove/list/get`. +- Consumes a `RemoteAdapterFactory.validate_token(adapter, token)` protocol so tests never call Telegram. +- Produces `OutboundChannel` value `remote` for Tasks 6–11. + +- [ ] **Step 1: Write failing settings and connection-transaction tests** + +Cover default redaction, settings round trip, one-connection `409` domain error, token validation before vault save, vault failure rollback, different-bot replacement invalidating pairing, same-bot replacement retaining it, and removal deleting the vault value. + +```python +async def test_create_rolls_back_when_vault_save_fails(session, service): + service.credentials.save.side_effect = CredentialStoreError("vault unavailable") + with pytest.raises(RemoteCredentialError): + await service.create_connection(session, token="bot-token", label="My phone") + assert (await session.exec(select(RemoteConnection))).all() == [] +``` + +- [ ] **Step 2: Run the focused failures** + +```powershell +uv run pytest --no-cov -q tests/remote/test_connection_service.py tests/api/test_settings_routes.py -k "remote or outbound" +``` + +- [ ] **Step 3: Define provider-neutral contracts** + +```python +class RemoteAdapterKind(StrEnum): + TELEGRAM = "telegram" + +@dataclass(frozen=True) +class ValidatedRemoteIdentity: + adapter: RemoteAdapterKind + principal_id: str + username: str + +class RemoteAdapterFactory(Protocol): + async def validate_token(self, adapter: RemoteAdapterKind, token: str) -> ValidatedRemoteIdentity: ... +``` + +Also define bounded enums for lifecycle state, safe error class, inbound action kind, outbound priority, and immutable principal/message/button values. External payload types do not escape adapter modules. + +- [ ] **Step 4: Implement settings and connection coordination** + +Add `RemoteSettings` to `RuntimeSettings`; add exact GET/PUT schemas/routes at `/api/settings/remote`. Construct vault accounts as `connection:`. Do not persist the token or a fingerprint. Keep DB transactions free of vault and network calls by validating first, storing the vault value, then committing metadata with compensating vault deletion on commit failure. + +- [ ] **Step 5: Run focused checks** + +```powershell +uv run pytest --no-cov -q tests/remote/test_connection_service.py tests/api/test_settings_routes.py tests/agent/test_outbound_redaction.py +uv run ruff check app/remote app/core/runtime_settings.py app/api/routes/settings.py app/api/schemas/settings.py app/agent/outbound_redaction.py tests/remote +``` + +--- + +### Task 3: Telegram Bot API client and adapter lifecycle + +**ACs:** AC-1, AC-6, AC-11, AC-12, AC-13, AC-24, AC-34 + +**Files:** + +- Create: `app/remote/telegram/__init__.py` +- Create: `app/remote/telegram/models.py` +- Create: `app/remote/telegram/client.py` +- Create: `app/remote/telegram/adapter.py` +- Create: `tests/remote/telegram/test_client.py` +- Create: `tests/remote/telegram/test_adapter.py` + +**Interfaces:** + +- Produces `TelegramClient.get_me/delete_webhook/get_updates/send_text/edit_text/answer_callback/set_commands`. +- Produces `TelegramAdapter.start/stop` and normalized inbound callback delivery. +- Consumes a token and callbacks; owns `httpx.AsyncClient`, offsets, polling, and Bot API error classification. + +- [ ] **Step 1: Write client translation and safe-error tests** + +Mock `httpx.MockTransport` for successful `getMe`, `getUpdates`, send/edit/ack, invalid-token `401`, conflict `409`, `429` with `parameters.retry_after`, chat `403`, malformed response, and transport failure. Assert exception strings never contain the request URL because it embeds the token. + +- [ ] **Step 2: Run the client tests and verify failure** + +```powershell +uv run pytest --no-cov -q tests/remote/telegram/test_client.py +``` + +- [ ] **Step 3: Implement bounded external payloads and the client** + +```python +class TelegramResponse(BaseModel, Generic[T]): + model_config = ConfigDict(extra="ignore") + ok: bool + result: T | None = None + error_code: int | None = None + description: str | None = None + parameters: TelegramResponseParameters | None = None +``` + +Build requests without logging full URLs, omit `parse_mode`, enforce the 1–64 byte callback payload contract before send, and translate failures to safe internal error classes. + +- [ ] **Step 4: Write poll lifecycle tests with injected clock/jitter** + +Prove webhook deletion uses `drop_pending_updates=True`; only `message` and `callback_query` are requested; updates are ordered; accepted update offsets advance; conflict/rate-limit/transport backoff follows policy; stop interrupts long poll/backoff promptly; duplicate start/stop is safe. + +- [ ] **Step 5: Implement the adapter state machine** + +```python +class TelegramAdapter: + async def start(self, on_action: Callable[[RemoteInboundAction], Awaitable[Admission]]) -> None: ... + async def stop(self) -> None: ... + def status(self) -> RemoteAdapterStatus: ... +``` + +Use an `asyncio.Event` for interruptible waits and a single owner task for polling. Never retry `invalid_token` until token replacement or explicit restart. + +- [ ] **Step 6: Run adapter checks** + +```powershell +uv run pytest --no-cov -q tests/remote/telegram +uv run ruff check app/remote/telegram tests/remote/telegram +uv run ty check app/ +``` + +--- + +### Task 4: One-tap pairing and principal authorization + +**ACs:** AC-7, AC-8, AC-9, AC-10 + +**Files:** + +- Create: `app/remote/pairing.py` +- Create: `tests/remote/test_pairing.py` + +**Interfaces:** + +- Produces `PairingService.issue_link/consume/unpair/authorize`. +- Consumes connection metadata and normalized `RemotePrincipal`. +- Issues opaque base64url tokens and returns `PairingLink(url, qr_payload, expires_at)`. + +- [ ] **Step 1: Write pairing capability tests** + +```python +def test_issued_token_is_url_safe_bounded_and_single_use(pairing_service): + link = pairing_service.issue_link(connection) + token = parse_qs(urlparse(link.url).query)["start"][0] + assert re.fullmatch(r"[A-Za-z0-9_-]{22,64}", token) + assert pairing_service.consume(token, principal) + assert not pairing_service.consume(token, principal) +``` + +Add expiry, private-chat, bot sender, wrong connection, one-pairing limit, separate destination, per-principal/global rate limit, silence decision, and immediate token invalidation cases. + +- [ ] **Step 2: Run and confirm focused failures** + +```powershell +uv run pytest --no-cov -q tests/remote/test_pairing.py +``` + +- [ ] **Step 3: Implement in-memory pairing tokens and durable binding** + +Use `secrets.token_urlsafe(16)` or stronger, a ten-minute monotonic expiry, constant-time token comparison where lookup does not already provide equivalent protection, and fixed refusal results that expose no connection state. Persist principal/destination only after every check passes. + +- [ ] **Step 4: Run pairing checks** + +```powershell +uv run pytest --no-cov -q tests/remote/test_pairing.py tests/remote/test_connection_service.py +uv run ruff check app/remote/pairing.py tests/remote/test_pairing.py +``` + +--- + +### Task 5: Desktop API and lazy runtime lifecycle + +**ACs:** AC-1, AC-2, AC-3, AC-5, AC-7, AC-10, AC-12, AC-13, AC-33, AC-34 + +**Files:** + +- Create: `app/api/schemas/remote.py` +- Create: `app/api/routes/remote.py` +- Create: `app/remote/runtime.py` +- Modify: `app/api/app.py` +- Create: `tests/api/routes/test_remote.py` +- Create: `tests/remote/test_runtime.py` + +**Interfaces:** + +- Produces the authenticated routes listed in the specification. +- Produces singleton `remote_runtime.start/stop/reconcile_connection/status`. +- Consumes connection, pairing, vault, and adapter services from Tasks 1–4. + +- [ ] **Step 1: Write route/auth/secret-shape tests** + +Cover zero-or-one list, create, patch enable/label, token replacement, remove, pairing-link issue, pairing read/revoke, status, second-connection `409`, invalid UUID, missing resource, desktop auth, and OpenAPI absence of returned token fields. + +- [ ] **Step 2: Write disabled-lifespan and shutdown tests** + +```python +async def test_disabled_start_does_not_import_telegram(monkeypatch): + sys.modules.pop("app.remote.telegram.adapter", None) + await remote_runtime.start() + assert "app.remote.telegram.adapter" not in sys.modules +``` + +Prove optional startup failure does not fail health readiness and shutdown stops the remote runtime after pending optional startup completes. + +- [ ] **Step 3: Implement thin routes and lazy runtime construction** + +Routes validate HTTP shape and call services; they do not call Telegram directly. Import `app.remote.telegram.adapter` inside the enabled connection factory only. Add remote startup beside other optional services and explicit shutdown beside Conductor/Scheduler cleanup. + +- [ ] **Step 4: Run route and lifecycle evidence** + +```powershell +$env:EVOFLUX_DESKTOP_TOKEN=$null +uv run pytest --no-cov -q tests/api/routes/test_remote.py tests/remote/test_runtime.py tests/api/test_app_lifespan.py +uv run ruff check app/api/routes/remote.py app/api/schemas/remote.py app/remote/runtime.py app/api/app.py tests/api/routes/test_remote.py tests/remote/test_runtime.py +``` + +--- + +### Task 6: Natural-language ingress and current-task behavior + +**ACs:** AC-14, AC-15, AC-16, AC-17, AC-18, AC-29 + +**Files:** + +- Create: `app/remote/inbound.py` +- Modify: `app/services/interactive_message_service.py` +- Create: `tests/remote/test_inbound.py` +- Modify: `tests/services/test_interactive_message_service.py` + +**Interfaces:** + +- Produces `RemoteInboundService.handle_text/new_task/continue_task/stop_current`. +- Consumes `PairingService.authorize`, `create_chat_session`, `resolve_team_for_session`, `submit_persisted_interactive_message`, and existing interrupt behavior. +- Generalizes persisted source metadata from `webbridge_source` to channel-neutral `interactive_source` while reading legacy metadata for compatibility. + +- [ ] **Step 1: Write channel-neutral idempotency compatibility tests** + +Persist one `interactive_source` message and prove lookup/dedup; retain a regression that legacy `webbridge_source` rows still deduplicate WebBridge retries. + +- [ ] **Step 2: Write inbound behavior tests** + +Cover first plain text creating a top-level Work session with provenance tags; subsequent text using the current session; queued/pending/accepted status; duplicate update effect-once; deleted current session recovery; **New task** clearing without deletion; **Continue this task** selecting only top-level Work/Coding; refusal of team-member, Side Chat, and internal sessions; `/stop` interrupting only the current live turn. + +- [ ] **Step 3: Run failures** + +```powershell +uv run pytest --no-cov -q tests/services/test_interactive_message_service.py tests/remote/test_inbound.py +``` + +- [ ] **Step 4: Implement the channel-neutral source record** + +```python +message_extra = { + "interactive_source": { + "channel": "remote", + "adapter": "telegram", + "connection_id": str(connection.id), + "key": f"remote:telegram:{connection.id}:{update_id}", + "request_hash": request_hash, + "state": "pending", + } +} +``` + +Do not make HTTP self-calls. Reuse existing team/session defaults and message locking. + +- [ ] **Step 5: Run ingress evidence** + +```powershell +uv run pytest --no-cov -q tests/services/test_interactive_message_service.py tests/remote/test_inbound.py +uv run ruff check app/remote/inbound.py app/services/interactive_message_service.py tests/remote/test_inbound.py +``` + +--- + +### Task 7: Global stream observation and safe completion delivery + +**ACs:** AC-18, AC-19, AC-20, AC-21, AC-22, AC-23, AC-24, AC-34 + +**Files:** + +- Modify: `app/services/memory_stream_store.py` +- Create: `app/remote/outbound.py` +- Create: `tests/services/test_memory_stream_observers.py` +- Create: `tests/remote/test_outbound.py` + +**Interfaces:** + +- Produces `register_observer(callback) -> Callable[[], None]`. +- Produces `RemoteProjection.observe`, delivery workers, redaction, completion lookup, Unicode-safe plain-text splitting, and one lifecycle-message correlation per phone-admitted turn. +- Consumes normalized `StreamEnvelope`, database session factory, and adapter send/edit methods. + +- [ ] **Step 1: Write observer isolation tests** + +Prove registration/unregistration, ordering, observer exception isolation, no coroutine acceptance, no await under the stream lock, and unchanged subscriber behavior with no observer. + +- [ ] **Step 2: Implement the minimal synchronous observer registry** + +```python +Observer = Callable[[str, StreamEnvelope], None] + +def register_observer(observer: Observer) -> Callable[[], None]: ... +``` + +Invoke observers after state mutation and before leaving the existing lock only if the callback performs a pure `put_nowait`; alternatively snapshot observers under lock and invoke immediately after releasing it. Tests must establish the chosen ordering and non-blocking behavior. + +- [ ] **Step 3: Write exhaustive projection tests** + +Drive every known event family plus an unknown type. Assert only gates/replies, terminal errors, `done`, and relevant desktop notifications enqueue. Assert child/Side Chat/internal sessions are excluded, duplicate completion sources collapse, finalized assistant text is queried after `done`, missing text uses a stub, and desktop tasks emit no activity chatter. + +- [ ] **Step 4: Write redaction and rendering tests** + +Test task titles, gate fields, question options, plans, errors, and final text with planted secret/PII markers under `redact`, `block`, and `off`. Verify fixed block stubs, no parse mode, 4096-character provider bound, Unicode safety, and callback-free agent text. + +- [ ] **Step 5: Implement bounded priority queues and delivery** + +Use separate high-priority and informational queues. `observe` may only normalize bounded scalar fields and call `put_nowait`. Delivery workers perform DB lookup, explicit `protect_outbound_text(..., context=OutboundContext(channel="remote", ...))`, splitting, and Telegram sends. High-priority overflow increments a critical counter and leaves gates unresolved. + +- [ ] **Step 6: Run observer/outbound evidence** + +```powershell +uv run pytest --no-cov -q tests/services/test_memory_stream_observers.py tests/remote/test_outbound.py +uv run ruff check app/services/memory_stream_store.py app/remote/outbound.py tests/services/test_memory_stream_observers.py tests/remote/test_outbound.py +uv run ty check app/ +``` + +--- + +### Task 8: Gate cards, callback capabilities, and race handling + +**ACs:** AC-10, AC-23, AC-25, AC-26, AC-27, AC-28 + +**Files:** + +- Create: `app/remote/gates.py` +- Create: `tests/remote/test_gates.py` + +**Interfaces:** + +- Produces `RemoteGateBridge.on_gate/on_reply/handle_callback`. +- Consumes existing permission/question/plan lookup and reply services directly. +- Consumes adapter `answer_callback` before any resolution and `edit_text` after it. + +- [ ] **Step 1: Write all gate rendering tests** + +Cover permission `once/reject` only, multi-question validated answers, plan approve/reject, every callback under 64 bytes, redacted fields, and fixed provenance headings. + +- [ ] **Step 2: Write callback ordering and ownership tests** + +```python +async def test_callback_is_acknowledged_before_resolution(bridge, adapter): + await bridge.handle_callback(action) + assert adapter.calls.index("answer_callback") < adapter.calls.index("resolve_gate") +``` + +Add wrong principal, destination, connection, action, expired token, restart-empty map, already-resolved gate, duplicate tap, desktop-wins race, phone-wins race, and reply-event button removal. + +- [ ] **Step 3: Implement opaque capability records and service adapters** + +Use random compact tokens mapped to records containing connection/principal/destination/session/request IDs, allowed action set, Telegram message reference, and expiry. Do not serialize internal IDs into callback data. Resolve via the active `PermissionService`, `AskUserService`, or `PlanApprovalService` registry. + +- [ ] **Step 4: Run gate evidence** + +```powershell +uv run pytest --no-cov -q tests/remote/test_gates.py tests/agent/test_permission.py tests/agent/test_ask_user_validation.py tests/agent/test_ask_user_sse.py tests/agent/test_plan_mode.py +uv run ruff check app/remote/gates.py tests/remote/test_gates.py +``` + +--- + +### Task 9: Secondary actions without widening owner contracts + +**ACs:** AC-18, AC-25, AC-30, AC-31, AC-32 + +**Files:** + +- Create: `app/remote/actions.py` +- Create: `tests/remote/test_actions.py` + +**Interfaces:** + +- Produces `/start`, `/help`, `/status`, `/new`, `/stop`, `/unpair`, and **More actions** dispatch. +- Consumes existing read/start/fire services for sessions, Coding projects, Workflows, Evo Agent Specs, and Scheduler. +- Reuses the opaque capability store from Task 8 for list choices. + +- [ ] **Step 1: Write command allowlist and refusal tests** + +Assert no command accepts credentials, repository paths, settings changes, permission mode, workflow approval, or arbitrary identifiers. Unknown slash commands return bounded help only to the paired principal. + +- [ ] **Step 2: Write one happy and one denied path per owner** + +Prove approved Workflow starts and changed hash refuses; authorized Coding project creates a task and unknown/unowned project refuses; eligible EASD action starts and blocked action preserves structured refusal; manually-triggerable schedule fires and unavailable task refuses. + +- [ ] **Step 3: Implement small owner-specific adapters** + +Each menu loader returns bounded `RemoteMenuItem(token, label, description)` and each action calls one existing service entry point. Do not copy owner validation into `actions.py`; translate owning exceptions into safe remote messages. + +- [ ] **Step 4: Run action evidence** + +```powershell +uv run pytest --no-cov -q tests/remote/test_actions.py tests/workflow tests/scheduler -k "remote or approval or trigger" +uv run ruff check app/remote/actions.py tests/remote/test_actions.py +``` + +--- + +### Task 10: Settings UI, one-tap connection, and status + +**ACs:** AC-3, AC-5, AC-7, AC-10, AC-12, AC-34, AC-35, AC-36 + +**Files:** + +- Create: `web/src/api/client/remote.ts` +- Modify: `web/src/api/types.ts` +- Modify: `web/src/api/client/settings.ts` +- Create: `web/src/components/settings/RemoteAccessSettings.tsx` +- Modify: Settings navigation/layout owning files identified during implementation +- Create: `web/src/__tests__/components/settings/RemoteAccessSettings.test.tsx` +- Modify: `web/package.json` and `web/bun.lock` only if no existing QR renderer can safely render the payload + +**Interfaces:** + +- Produces typed hooks/client calls for connection CRUD, pairing link, pairing state, and status. +- Consumes existing Settings overlay cards, form controls, secret inputs, confirmation dialog, and query cache conventions. + +- [ ] **Step 1: Write UI tests for the primary states** + +Render unconfigured, validating, vault failure, configured-disabled, connecting QR/link, paired, invalid token, used elsewhere, phone unreachable, and removal confirmation. Assert the token input clears after submit and never appears in rendered status or cached GET data. + +- [ ] **Step 2: Run the tests and confirm failure** + +```powershell +Set-Location web +bun test src/__tests__/components/settings/RemoteAccessSettings.test.tsx +``` + +- [ ] **Step 3: Implement the typed client and Settings page** + +The primary copy is: EvoFlux must stay running; create a personal bot; paste its token once; select **Connect phone**; scan or open Telegram. Render the QR from the returned HTTPS payload locally, never through a remote image service. Use connection-neutral labels except where identifying Telegram as the selected adapter. + +- [ ] **Step 4: Verify keyboard, focus, and narrow layout behavior** + +Test labels, error announcements, tab order, QR alternative link, secret-input autocomplete, destructive removal confirmation, and mobile-width wrapping. Avoid adding a new app route; Settings remains an overlay. + +- [ ] **Step 5: Run frontend evidence** + +```powershell +Set-Location web +bun test src/__tests__/components/settings/RemoteAccessSettings.test.tsx +bun run lint +bun run typecheck +bun run build +``` + +--- + +### Task 11: Current documentation, Help, and operator guidance + +**ACs:** AC-3, AC-11, AC-12, AC-30, AC-32, AC-35, AC-36 + +**Files:** + +- Create: `documents/features/remote-access.md` +- Modify: `documents/features/README.md` +- Modify: `documents/features/security-and-permissions.md` +- Modify: `documents/architecture/system-overview.md` +- Modify: `documents/reference/configuration.md` +- Modify: `documents/reference/http-api.md` +- Modify: `web/src/help/locales/en.ts` +- Modify: `web/src/help/locales/vi.ts` +- Modify: `web/src/help/locales/ja.ts` + +**Interfaces:** + +- Produces current-state documentation only after runtime behavior exists. +- Keeps this plan in `documents/plans/` as historical design rationale. + +- [ ] **Step 1: Write the current feature contract from verified behavior** + +Document setup, one-bot-per-computer scope, one-tap pairing, current task, automatic gates/completion, offline discard, permission limits, Telegram retention, revocation, states, source map, and focused tests. Mark the feature Optional because it needs a user-owned Telegram bot and network access. + +- [ ] **Step 2: Reconcile architecture and public references** + +Add the outbound remote adapter to the system topology/trust boundaries, exact `remote` settings fields, exact HTTP route family, lifecycle states, and secret masking. Link rather than duplicate long explanations. + +- [ ] **Step 3: Add equivalent Help in all three locales** + +Each locale must explain the same steps and warnings: EvoFlux must remain running; messages sent while stopped do not run later; bot chats leave the machine; **Allow once** is the maximum remote permission; each computer needs its own bot; revoke from Settings or `/unpair`. + +- [ ] **Step 4: Validate documentation and Help consumers** + +```powershell +Set-Location web +bun run lint +bun run typecheck +bun run build +Set-Location .. +rg -n "Remote access|Telegram|remote_connections|/api/remote" documents web/src/help/locales +``` + +Expected: current docs agree with implemented names and every local link resolves. + +--- + +### Task 12: Cross-boundary acceptance and clean handoff + +**ACs:** AC-1–AC-37 + +**Files:** + +- Modify only files needed to fix failures caused by Tasks 1–11. +- Do not alter unrelated desktop-generated permissions or user documentation files. + +**Interfaces:** + +- Validates the complete path: vault → connection → one-tap pair → phone text → persisted task → gate/completion projection → callback resolution → revoke/shutdown. + +- [ ] **Step 1: Add one end-to-end mocked Telegram integration test** + +Use a real temporary database and fake vault/Telegram transport. Create a connection, issue/consume a pairing link, submit text, observe one persisted message, push a permission gate, resolve it by callback, persist assistant completion, observe one completion, then unpair and prove later input is refused. + +- [ ] **Step 2: Run all focused remote and seam tests** + +```powershell +$env:EVOFLUX_DESKTOP_TOKEN=$null +uv run pytest --no-cov -q tests/remote tests/core/test_credential_store.py tests/core/test_alembic_migrations.py tests/services/test_interactive_message_service.py tests/services/test_memory_stream_observers.py tests/api/routes/test_remote.py +``` + +- [ ] **Step 3: Run backend quality gates** + +```powershell +uv run ruff check app/ tests/ +uv run ruff format --check app/ tests/ +uv run ty check app/ +uv run pytest --no-cov -q +``` + +- [ ] **Step 4: Run frontend quality gates** + +```powershell +Set-Location web +bun run lint +bun run typecheck +bun run build +Set-Location .. +``` + +- [ ] **Step 5: Inspect schema, privacy, and diff boundaries** + +```powershell +uv run alembic heads +uv run pytest --no-cov -q tests/core/test_alembic_migrations.py +rg -n "BOT_TOKEN|api\.telegram\.org/bot|pairing_token|callback_token" app tests documents web/src +git diff --check +git status --short +``` + +Inspect every match so tests/examples remain synthetic and no real secret, raw update, or token-bearing URL reaches logs, diagnostics, committed fixtures, or GET responses. Confirm only the intended migration head exists and unrelated worktree changes remain untouched. + +- [ ] **Step 6: Produce the AC evidence handoff, then commit everything together** + +Report changed files, exact commands/results, evidence grouped by AC, any pre-existing failures, checks not run, and remaining risk. Per the user's instruction, once implementation is verified, stage and commit the full working tree — this feature's changes together with any pre-existing unrelated modifications already present — as a single commit, rather than isolating this feature into its own commit. + +## Rollback + +Disable the connection first to stop the poller. If code rollback is required, +remove the remote router/lifecycle hook, `app/core/credential_store.py`, and +Settings surface, unregister the stream observer, and downgrade migration +`00000064` to drop only `remote_pairings` and `remote_connections`. Conductor +is never part of this rollback since it was never modified. Existing chat +sessions and their normal messages remain intact; provenance tags on +remote-created sessions are harmless if retained or may be removed by a +bounded migration-independent cleanup. diff --git a/documents/plans/remote-channel-telegram.md b/documents/plans/remote-channel-telegram.md new file mode 100644 index 00000000..e9114198 --- /dev/null +++ b/documents/plans/remote-channel-telegram.md @@ -0,0 +1,771 @@ +# Remote access over Telegram + +Status: proposed + +## Problem and outcome + +EvoFlux is a local-first desktop application. The Tauri shell starts the +FastAPI sidecar on loopback with a per-launch bearer token, so a phone cannot +reach the application directly. When the user leaves a long-running task and +takes only their phone, a permission request, question, or plan review can +block the run until they return. Completion notices also remain on the desktop. + +The outcome is a personal remote connection that dials out from a running +EvoFlux installation to Telegram. Each user creates and configures their own +bot on their own computer. After that one-time setup, they select **Connect +phone**, scan a QR code or open a link, and press Telegram's Start button. The +phone is paired without entering server addresses, session identifiers, or a +manual code. + +Once paired, the user opens the bot and writes naturally. EvoFlux keeps one +current remote task for that connection, creates a Work task for the first +message when needed, and lets the user start a fresh task with one button. +Blocking gates and completion notices from user-visible desktop tasks arrive +automatically with the task name. Selecting **Continue this task** makes that +desktop task the phone's current conversation. + +Telegram is the only adapter in the first release and each installation permits +one configured connection and one paired Telegram account. The core is +connection-aware: stored records, credential keys, service interfaces, source +keys, and callback ownership include a connection identifier. A later release +can permit several connections or add another adapter without changing those +ownership contracts. This is a narrow adapter seam, not a general plugin +framework. + +Telegram's `getUpdates` long poll is outbound. The feature adds no listener, +tunnel, public URL, or LAN requirement. Telegram deep links carry a private +`start` parameter of at most 64 base64url characters, which is sufficient for a +single-use pairing token. Protocol constraints are defined by the official +[Bot API](https://core.telegram.org/bots/api) and +[deep-linking contract](https://core.telegram.org/bots/features#deep-linking). + +## Goals + +- Let a user operate their running EvoFlux installation from a phone without an + inbound network path. +- Make first connection a scan-or-tap flow after the bot token is configured on + the desktop. +- Accept natural-language work without requiring the user to understand + sessions, IDs, modes, or command syntax. +- Deliver and resolve `permission_asked`, `question_asked`, and + `plan_approval_requested` gates from the phone. +- Deliver one completion report for each user-visible top-level task, including + tasks started on the desktop. +- Allow the user to continue a desktop task or start a new remote Work task with + one explicit action. +- Keep approved workflows, Coding projects, Evo Agent Specs runs, and scheduled + tasks available through a secondary menu without making that menu part of the + primary flow. +- Preserve all existing permission, sandbox, workspace, workflow-approval, and + outbound-data policies. +- Keep the feature free at rest: when unconfigured or disabled, it performs no + imports of adapter code, creates no tasks, and makes no network calls. +- Make every installation responsible for its own bot and credential; EvoFlux + provides no shared relay or hosted bot. +- Keep the first implementation ready for multiple connection records while + enforcing a one-connection product limit in v1. + +## Non-goals + +- No inbound HTTP endpoint, public listener, tunnel, reverse proxy, or + `evoflux start --lan` requirement. +- No EvoFlux-hosted Telegram bot, shared bot token, account service, cloud + relay, or cross-installation routing. +- No more than one configured remote connection or one paired Telegram account + per installation in v1. +- No group chats, channel chats, topics, inline mode, Mini Apps, guest mode, or + business-bot behavior. +- No attachments, voice, photos, files, location, contacts, reactions, or media + in either direction. +- No remote entry or modification of provider credentials, bot credentials, + sandbox policy, outbound-data policy, connection settings, model-provider + configuration, or `permission_mode: bypass`. +- No durable **Always allow** permission decision from the phone. +- No remote approval of a new or changed Workflow definition. A remotely + started Workflow must already satisfy the existing definition-hash approval + contract. +- No execution of Telegram messages accumulated while EvoFlux is stopped. +- No complete session browser or transcript export. The channel sends bounded + event projections and finalized replies, not historical session content. +- No durable outbound outbox, Telegram update archive, callback table, or + remote-interaction table in v1. +- No general remote-channel plugin SDK, adapter discovery protocol, or + third-party adapter loading. + +## User flows and states + +### Configure the personal connection + +The user creates a bot with `@BotFather`, opens **Settings → Remote access**, +and pastes the token. EvoFlux calls `getMe` before storing anything. A valid +response supplies the immutable bot identifier and display username shown for +review. EvoFlux then stores the token in the OS credential vault under the new +connection ID and creates the connection record. + +If validation or vault storage fails, no connection record remains and the UI +shows an actionable error. The token is never written to `settings.yaml`, the +application database, logs, diagnostics, or the config-directory `.env` file. + +The installation permits one configured connection in v1. The service returns +a stable conflict response if a second connection is requested. This is a +service-level product limit rather than a database uniqueness constraint. + +### Connect the phone + +The user selects **Connect phone**. EvoFlux creates an in-memory, single-use +pairing token with at least 128 bits of entropy and a ten-minute expiry. The UI +shows both a QR code and an **Open Telegram** action for: + +```text +https://t.me/?start= +``` + +Opening the link presents Telegram's normal Start action. The resulting +`/start ` update must come from a private chat. EvoFlux binds the +transport-reported principal ID and destination/chat ID to the connection, +deletes the pairing token, sends **Connected to EvoFlux on **, +and displays the paired Telegram account on the desktop. + +The principal ID authorizes actions. The destination ID addresses replies. +They are stored separately and are never assumed to be equal, even when the +first adapter commonly reports matching values for a private chat. + +A plain `/start` without a valid token does not pair. An invalid or expired +token receives no installation details. The UI can mint a replacement without +changing the connection or bot token. + +### Send the first task + +After pairing, the user sends ordinary text. If the pairing has no current +task, EvoFlux creates a top-level Work session using the existing default team, +model, permission mode, and Work workspace behavior. The message is persisted +and dispatched through the same interactive ingress used by the desktop. The +bot replies with a short accepted or queued acknowledgement. + +The created session receives channel-neutral provenance tags +`remote_origin` and `remote_connection:`. These tags support +diagnostics and future ownership checks; they do not weaken tool policy and are +not required for desktop sessions to emit remote notices. + +Later plain text continues the pairing's current task. If the task is already +running, existing follow-up delivery policy decides whether the message is +spliced into the turn or queued. The phone reports the actual accepted, +pending, or queued result. + +### Observe and continue a desktop task + +While the connection is enabled and paired, the remote service observes +user-visible top-level Work and Coding sessions. Team-member child sessions, +Side Chat sessions, internal sessions, and raw specialist activity are not +remote-addressable. + +Blocking gates and terminal completion notices are projected automatically. +Each message names the task and includes an opaque **Continue this task** +button. Pressing it changes only that pairing's `active_session_id`; it does not +modify the session, cancel work, or resend history. The bot confirms the new +current task. Subsequent plain text follows up in that session through the +normal persisted ingress. + +The phone never needs a `/sessions` command for the primary flow. A secondary +**Recent tasks** menu may list a bounded set of top-level sessions if the user +explicitly opens the menu. + +### Start a new task + +The persistent **New task** action clears the current binding and creates a new +top-level Work session when the user submits their next message. It never +deletes, interrupts, archives, or hides the previous task. + +Starting a Coding task requires selecting an existing authorized Coding +project from the secondary menu. Remote input cannot add a repository or widen +the selected project's authorized workspace paths. + +### Answer a blocking gate + +Permission cards identify the task, tool, and complete policy-relevant patterns +after outbound redaction. Choices are **Allow once** and **Deny**. There is no +remote **Always allow** action. + +Question cards render every required question and its allowed choices. Freeform +answers are accepted only when the existing question schema permits them. Plan +cards show a bounded plan summary and offer the same transient approval/reject +decisions as the existing plan-review service. + +The callback query is acknowledged immediately, before database access or gate +resolution. The card is then edited to a terminal state. If the gate was +answered on the desktop first, the buttons disappear and the card says that it +was answered elsewhere. + +### Receive status and completion + +A message admitted from the phone creates one short lifecycle message for that +turn. EvoFlux edits it only when the admission state changes, the turn fails, or +the turn completes. It does not send periodic progress or mirror activity. +Token deltas, model thinking, tool output, specialist mail, usage events, and +raw stream envelopes are never copied to Telegram. + +All user-visible top-level tasks may send a terminal completion notice. On +`done`, the service reads the finalized persisted assistant message rather than +reconstructing a result from stream deltas. It sends the task name, bounded +final text, and **Continue this task**. If no finalized assistant message is +available, it sends a completion stub that directs the user to EvoFlux. + +Long text is split at safe text boundaries within Telegram's message limit. +Messages are sent without a parse mode so model text cannot manufacture links, +mentions, or formatting through Telegram markup. + +### Advanced actions + +The bot profile exposes only `/start`, `/help`, `/status`, `/new`, `/stop`, and +`/unpair`. An optional **More actions** menu provides: + +- recent top-level tasks; +- existing Coding projects; +- approved Workflows; +- eligible Evo Agent Specs runs and currently available actions; +- existing scheduled tasks that permit manual triggering. + +Every list uses opaque, expiring choice tokens. It never embeds repository +paths, database UUIDs, definition hashes, or credentials in `callback_data`. +The menu is secondary: a user can pair, work, answer gates, receive results, +continue a desktop task, and start a new task without opening it. + +### Disable, unpair, and remove + +- **Disable connection** stops polling and outbound delivery but retains the + connection record, vault credential, and pairing. +- `/unpair` from the paired private account deletes the pairing and invalidates + its active callback tokens. It works even when other remote commands are + restricted. +- **Unpair phone** on the desktop performs the same deletion. +- **Remove connection** stops the adapter, deletes the pairing and connection, + deletes the vault credential, and invalidates all connection-owned tokens. + It does not delete or modify chat sessions. + +### Stale and refused states + +- An unpaired sender receives no response except when presenting a valid live + pairing token. +- A group, channel, bot-authored, edited, media-only, or unsupported update is + ignored and counted by reason. +- A callback after restart reports that the action expired. +- A callback after another surface resolved the gate reports that it was + already answered. +- A callback owned by another connection or principal is refused without + revealing its target. +- A revoked bot token stops the poller and produces an **Invalid token** state. +- Another consumer polling the same bot produces a **Used elsewhere** state and + bounded retries; the UI explains that each EvoFlux installation needs its + own bot. +- If the paired account blocks the bot or the chat becomes unavailable, + Settings shows **Phone unreachable** while the poller remains diagnosable. +- Messages accumulated while EvoFlux was stopped are discarded before live + polling starts and never execute later. + +## Requirements and acceptance criteria + +- **AC-1 — Off and free by default:** With no enabled connection, importing + `app.api.app` leaves Telegram adapter modules absent from `sys.modules`, no + remote task is created, and no network request is made. +- **AC-2 — Outbound only:** Enabling remote access opens no listening socket and + introduces no route authenticated by a Telegram token. Every new HTTP route + uses normal desktop authentication. +- **AC-3 — Per-installation ownership:** Setup creates a connection owned by the + local installation. No shared service or default bot exists, and v1 returns a + defined `409` response when a second connection is requested. +- **AC-4 — Connection-aware contracts:** Every pairing, credential key, inbound + source key, callback token, queue item, and runtime status carries a + connection ID. Tests can instantiate two service-level connections and prove + that messages and callbacks never cross them even though the public v1 API + prevents configuring the second. +- **AC-5 — Token custody:** A bot token is validated before persistence and + stored only in the OS credential vault under its connection ID. Vault failure + leaves no partial connection. No settings, model, API response, log, trace, + diagnostic, or exception string contains the token. +- **AC-6 — Bot identity binding:** `getMe` must report a bot account. The + connection stores its immutable bot ID and current username. Token replacement + that resolves to another bot invalidates the existing pairing and outstanding + callbacks before the new credential becomes active. +- **AC-7 — One-tap pairing:** **Connect phone** returns a QR payload and HTTPS + deep link whose `start` parameter has at least 128 bits of entropy, contains + only Telegram-permitted characters, is at most 64 characters, expires after + ten minutes, is single-use, and exists only in process memory. +- **AC-8 — Pairing authorization:** Pairing succeeds only for a valid token in a + private chat. The stored principal ID authorizes every message and callback; + the separately stored destination ID addresses replies. V1 permits one active + pairing per connection. +- **AC-9 — Silence and rate limits:** An unpaired sender, invalid token, group + chat, and unsupported update reveal no installation state. Pairing attempts + and accepted inbound actions have per-principal and connection-wide rate + limits that cannot be used as a response amplifier. +- **AC-10 — Immediate revocation:** Desktop unpair, `/unpair`, token replacement, + and connection removal invalidate applicable callback and menu tokens before + returning. A later update from the former principal is unauthorized. +- **AC-11 — No stale replay:** Startup removes any webhook, drops pending + updates, and establishes a fresh offset before accepting live input. An update + sent while EvoFlux is stopped never creates a session, message, or run. +- **AC-12 — Telegram error taxonomy:** Webhook conflict is cleared once; + concurrent-consumer conflict enters bounded backoff and a visible + `used_elsewhere` state; authentication failure stops polling in + `invalid_token`; `429` honors `retry_after`; transport errors use exponential + backoff with jitter; an unreachable paired chat affects delivery state without + crashing inbound polling. +- **AC-13 — Prompt shutdown:** Disabling or stopping the service cancels long + polling and interruptibly exits backoff without waiting for the configured + poll timeout or remaining retry delay. +- **AC-14 — Natural first message:** A valid plain-text message with no active + task creates one top-level Work session and submits the text without requiring + a command, mode, session ID, or desktop action. +- **AC-15 — Correct interactive ingress:** Remote text resolves the persisted + session/team and uses `submit_persisted_interactive_message`. Accepted, + pending, and queued outcomes are reported accurately. It never calls EvoFlux's + own HTTP API over loopback. +- **AC-16 — Inbound idempotency:** The source key includes adapter, connection + ID, and Telegram update ID. Redelivery within a process and replay after a + crash between persistence and offset acknowledgement produce at most one + persisted user message. +- **AC-17 — Current-task behavior:** Each pairing has at most one current task. + **Continue this task** changes only that pointer; **New task** clears it; the + next plain message creates the replacement Work session; deleting a current + session sets the pointer to null. +- **AC-18 — Addressable session boundary:** Only user-visible, top-level Work and + Coding sessions may be selected or notified. Team-member, Side Chat, and + internal sessions are neither listed nor addressable. +- **AC-19 — Non-perturbing observation:** Stream observation performs no await, + network, database, model, filesystem, or blocking work. It uses `put_nowait` + into bounded connection-owned queues and records overflow without delaying + the producing turn. +- **AC-20 — Explicit event allowlist:** Only gate asks/replies, terminal errors, + `done`, and relevant `desktop_notification` events are candidates for stream + projection. Thinking, content/tool deltas, widget deltas, summarization, + usage, inbox, delegation, handoff, member status, goal status, and unknown + event types are dropped. +- **AC-21 — Completion deduplication:** A turn emitting both `done` and + `desktop_notification(kind="assistant_done")` produces one completion notice. + Its body comes from the finalized persisted assistant message, not accumulated + stream chunks. +- **AC-22 — Quiet lifecycle status:** A phone-admitted turn owns at most one + lifecycle message. Accepted, queued, running, failed, and completed + transitions edit that message instead of appending progress. Desktop-started + tasks produce no activity chatter before a gate, error, or completion. +- **AC-23 — Explicit outbound policy:** Every user-controlled string and every + agent/session-derived field passes through the policy configured for the + `remote` outbound channel. Redaction is the default. A block decision emits a + fixed withheld-content stub and leaves observation running. +- **AC-24 — Safe text rendering:** Model text is sent without Telegram parse + mode, is split within provider limits without breaking Unicode, and never + becomes a gate or command solely because its content resembles EvoFlux UI. +- **AC-25 — Gate coverage:** Permission, question, and plan-review gates render + defined cards. Each `callback_data` payload is opaque, connection-owned, + principal-bound, process-memory-only, expiring, and at most 64 bytes. +- **AC-26 — Acknowledge first:** A callback query is answered before gate lookup, + database work, or execution. The subsequent edit communicates success, stale, + already answered, expired, or refused state. +- **AC-27 — Least durable authority:** Remote permission replies offer only + `once` or `reject`. Plan approval uses the existing exact request and session; + questions use the existing validated answer schema. Remote actions cannot + create durable permission rules. +- **AC-28 — Answered elsewhere:** Existing permission, question, and plan reply + events remove buttons from the matching Telegram card and mark it answered, + regardless of whether the resolution came from desktop or phone. +- **AC-29 — Safe interruption:** `/stop` interrupts only the pairing's current + active turn through the existing team interrupt path. It does not stop the + sidecar, delete the task, cancel unrelated sessions, or imply success when no + turn is active. +- **AC-30 — Existing approval boundaries:** An unapproved or changed Workflow + definition retains its existing refusal. Remote access cannot approve the + definition, add a Coding repository, change workspace authorization, or set + bypass permission mode. +- **AC-31 — Secondary run coverage:** Through the optional menu, an approved + Workflow, an authorized Coding project task, an eligible Evo Agent Specs + action, and an existing manually-triggerable scheduled task can be started. + Every refusal from the owning service is preserved and rendered safely. +- **AC-32 — No remote secrets or settings writes:** No Telegram command, menu + action, or natural-language shortcut accepts a credential value or changes + connection/provider/sandbox/outbound settings. Status output contains no + environment values or secret presence details beyond the current connection's + configured state. +- **AC-33 — Local API posture:** Packaged desktop authentication remains + unchanged. An external/LAN sidecar configuration must satisfy its existing + access-key policy; remote access neither bypasses nor self-calls that API. +- **AC-34 — Diagnosable:** Connection status reports lifecycle state, last safe + error class, last successful poll time, pairing state, phone reachability, and + bounded queue-drop counters. Logs contain no bot token, pairing token, + callback token, forwarded content, or raw Telegram payload. +- **AC-35 — Retention is explicit:** Setup and Help state that Telegram stores + bot chats on its service and that pairing permits bounded task information to + leave the machine. EvoFlux persists only normal session messages and the + connection/pairing metadata defined below. +- **AC-36 — Documented and localized:** The shipped feature contract, + configuration and HTTP references, Settings copy, and in-app Help in English, + Vietnamese, and Japanese describe setup, offline behavior, privacy, revocation, + and desktop-only operations. +- **AC-37 — Clean integration:** Focused backend/frontend tests, schema-head and + upgrade-path tests, Ruff, format check, ty, frontend lint/typecheck/build, and + `git diff --check` pass without incorporating unrelated worktree changes. + +## API, event, tool, and UI contracts + +### Desktop HTTP API + +All routes use existing desktop authentication and expose no Telegram-authenticated +HTTP surface. + +| Route | Purpose | +|---|---| +| `GET/PUT /api/settings/remote` | Read or update `outbound_data_policy` and `outbound_pii_policy`; connection enablement remains on the connection record | +| `GET /api/remote/connections` | Return the zero-or-one v1 connection summary and safe runtime state | +| `POST /api/remote/connections` | Validate a write-only token, save it to the vault, and create the connection; `409` when one already exists | +| `PATCH /api/remote/connections/{id}` | Change label or enabled state; adapter kind and bot identity are immutable | +| `PUT /api/remote/connections/{id}/token` | Validate and atomically replace the write-only token; re-pair if bot identity changes | +| `DELETE /api/remote/connections/{id}` | Stop and remove the connection, pairing, tokens, and vault credential | +| `POST /api/remote/connections/{id}/pairing-links` | Mint a single-use deep link and return link, QR payload, and expiry | +| `GET /api/remote/connections/{id}/pairing` | Return safe paired-account decoration or `null` | +| `DELETE /api/remote/connections/{id}/pairing` | Revoke the paired account and outstanding interaction tokens | +| `GET /api/remote/connections/{id}/status` | Return adapter lifecycle, last safe error, poll time, reachability, and drop counts | + +Secret-bearing request models use write-only fields. OpenAPI examples and error +payloads contain placeholders, never realistic tokens. `GET` responses report +`token_configured: true|false`, not the credential or its fingerprint. + +### Internal channel seam + +`app/remote/contracts.py` defines provider-neutral values such as: + +- `RemoteAdapterKind`, initially `telegram`; +- `RemotePrincipal` with `principal_id`, `destination_id`, and untrusted display; +- `RemoteInboundAction` for text, callback, and pairing-start updates; +- `RemoteOutboundMessage` with plain text, buttons, correlation, and priority; +- `RemoteAdapterStatus` and safe error classes; +- `RemoteAdapter`, whose lifecycle and send/edit/ack methods never decide + EvoFlux authorization. + +`RemoteService` owns connection limits, credential access, adapter lifecycle, +pairing, principal authorization, current-task routing, source-key generation, +event projection, callback-token ownership, and status aggregation. +`TelegramAdapter` owns Bot API translation, long-poll offsets, provider limits, +and Telegram error classification. Generic services never import Telegram +payload models. + +The adapter is constructed lazily only for an enabled, credential-complete +connection. The first release uses EvoFlux's existing `httpx` dependency rather +than adding a Telegram framework with its own scheduler or global state. + +### Telegram update contract + +Long polling supplies `allowed_updates=["message", "callback_query"]`. The +adapter accepts only new private-chat text messages from non-bot users and +callback queries for bot-authored messages. It ignores edited messages and all +media/service-message variants except the `/start ` pairing input. + +The poller processes updates in update-ID order. It advances the next offset +only after an update is safely classified and any accepted text has reached +durable message admission. A crash between admission and offset confirmation is +safe because the source key deduplicates the repeated update. Restart backlog +discard intentionally provides no across-restart delivery promise for updates +that never reached admission. + +### Stream observer contract + +`app/services/memory_stream_store.py` gains process-wide observer registration. +Observers are synchronous callbacks invoked after the stream state has accepted +an envelope. Registration returns an idempotent unregister handle. Observer +failure is isolated, logged without payload content, and cannot fail the stream +producer. + +The remote observer copies only minimal allowed fields into immutable queue +items. A bounded high-priority queue carries gates and terminal notices. Phone +admission status is produced by the remote service and uses a separate bounded +informational queue. Informational overflow drops the oldest informational +item. High-priority overflow leaves the underlying gate unresolved, increments +a critical delivery-failure counter, and keeps desktop resolution available; +the design does not claim impossible losslessness from a bounded, non-blocking +queue. + +No new SSE event type is needed. The observer consumes existing normalized +events and reply events. + +### Remote interaction contract + +Buttons contain only a compact random token and action code. The in-memory token +record owns connection ID, principal ID, destination ID, session ID, source +event/request ID, allowed action set, Telegram message reference, creation time, +and expiry. Provider callback data never contains a raw session ID, database ID, +path, command, plan, or answer. + +Callback acknowledgement is transport-only and precedes resolution. Resolution +calls the existing permission, question, plan, interrupt, Workflow, Scheduler, +or Evo Agent Specs service directly. The remote service does not make loopback +HTTP requests and does not duplicate owning business rules. + +### Settings UI + +Settings adds one **Remote access** section using the existing Settings overlay +primitives. Its normal state contains: + +- a short explanation that EvoFlux must remain running; +- the one-time personal bot-token field; +- validated bot identity; +- enabled/disabled control; +- **Connect phone** with QR code and **Open Telegram** fallback; +- paired-account display and **Unpair phone**; +- connection health and last safe error; +- **Remove connection**; +- visible disclosure that task text sent through the bot is retained by + Telegram and is not end-to-end encrypted bot chat. + +The primary Telegram keyboard contains **New task**, **Status**, and **More +actions**. Gate and completion messages add contextual inline buttons. Internal +terms such as session UUID, SSE, update offset, adapter, and pairing row are not +shown in the normal user flow. + +## Data model, migration, and retention + +Migration `00000064` with `down_revision = "00000063"` creates two tables and +updates the schema-head marker. + +### `remote_connections` + +| Column | Contract | +|---|---| +| `id` | UUID primary key | +| `adapter` | bounded adapter kind, initially `telegram` | +| `label` | user-editable installation-local label | +| `enabled` | desired lifecycle state | +| `adapter_principal_id` | validated immutable bot identifier, not the token | +| `adapter_username` | current validated bot username, untrusted display/routing decoration | +| `created_at`, `updated_at` | timezone-aware timestamps | + +The vault account key derives from the connection ID and never appears in API +responses. Runtime status, last errors, offsets, queues, and retry state remain +in process memory. + +### `remote_pairings` + +| Column | Contract | +|---|---| +| `id` | UUID primary key | +| `connection_id` | required FK to `remote_connections`, cascade delete | +| `principal_id` | channel-attested account identity used for authorization | +| `destination_id` | channel address used for replies | +| `label` | user-editable local label | +| `display` | channel-reported untrusted decoration | +| `active_session_id` | nullable FK to `chat_sessions`, `ON DELETE SET NULL` | +| `created_at`, `last_seen_at` | timezone-aware timestamps | + +The table is unique on `(connection_id, principal_id)` and on +`(connection_id, destination_id)`. The service enforces one pairing per +connection in v1. Database cardinality remains connection-aware for later +product expansion. + +Revocation deletes the pairing instead of retaining identity history. Removing +a connection cascades its pairing. Session deletion only clears the active +pointer. No remote operation deletes session messages. + +Pairing tokens, callback/menu tokens, update offsets, progress-message IDs, +deduplication caches, outbound queues, rate-limit windows, and error/backoff +state are deliberately ephemeral. The normal persisted user and assistant +messages remain governed by existing session retention. EvoFlux stores no extra +copy of Telegram message content or raw update bodies. + +## Permissions, security, privacy, and trust + +Pairing is installation-level operating authority. A paired account may create +and continue tasks, interrupt its current task, answer transient gates, and +invoke already-approved actions. It may not configure or widen the installation. + +Telegram bot chats are an external retention boundary and are not end-to-end +encrypted. Telegram, anyone controlling the user's Telegram account, and anyone +holding the bot token may be able to read bot-chat content. This consequence is +shown before pairing and documented in Help. Redaction, event allowlisting, and +bounded replies reduce exposure but do not make the channel local or encrypted. + +The bot token is a root credential. Its holder can impersonate the bot and read +updates delivered to it. EvoFlux stores it only through an OS-vault +abstraction modeled on the existing Conductor credential pattern, but +implemented as an independent module used only by remote access. Conductor's +own credential handling is left unchanged: it is an external integration point +relied on by `evo-conductor`, and this feature must not alter its behavior or +its constructor contract. Vault unavailability is a setup failure, not a +reason to create a plaintext fallback. Recovery from suspected token theft is +regeneration through `@BotFather` and token replacement in EvoFlux. + +The Telegram principal ID, not username or display name, authorizes inbound +actions. Usernames and display names can change and remain decoration. Every +callback rechecks connection, pairing, principal, destination, allowed action, +expiry, and underlying EvoFlux request state. + +Remote natural language has the same potential to trigger tools as desktop +natural language. Existing permission mode, sandbox roots, workspace +authorization, outbound model policy, tool policy, and workflow approval remain +authoritative. The adapter cannot invoke tool functions directly. + +Agent-controlled text is untrusted channel content. It is plain text, carries a +fixed EvoFlux/task provenance header, and never creates Telegram buttons. Only +the remote service constructs buttons from normalized internal events. + +Gate context can contain commands, paths, or user data. Every field passes +through the explicit `remote` outbound channel policy. The existing +`OutboundChannel` contract gains `remote`; policy selection is explicit rather +than inherited from ambient sandbox state. + +Pairing and callback tokens are capability secrets with short lifetimes. They +are generated with a cryptographic RNG, compared without logging, invalidated +on successful use or ownership change, and never stored in session content. + +## Concurrency, failure, recovery, and idempotency + +One adapter task owns polling for one connection. Update classification is +sequential to preserve offset ordering. Outbound delivery uses separate worker +tasks so a slow Telegram send cannot hold a stream lock, database transaction, +or inbound poll loop. + +The service never performs network I/O, model calls, process startup, or file +operations within a database transaction. It reads or mutates the smallest +durable unit, commits it, then performs external delivery. Compensating cleanup +removes a connection record if vault persistence fails during creation. + +Telegram allows one `getUpdates` consumer per bot and disallows polling while a +webhook is installed. Startup calls the provider operation that removes an +existing webhook and drops queued updates, then begins long polling with an +explicit allowed-update set. A polling conflict is a visible connection state, +not a tight retry loop. The UI tells the user to configure a different personal +bot for each EvoFlux installation. + +Inbound accepted text is at-least-once within a process but effect-once through +the persisted source key. Restart deliberately discards never-admitted backlog. +Callback resolution is idempotent because the underlying gate service resolves +one request once and the remote token becomes terminal after the first attempt. + +Outbound messages have no durable delivery guarantee. Informational delivery +may be dropped under bounded pressure. A failed gate delivery never auto-allows +or auto-denies the request; the task remains blocked and resolvable on desktop. +The status surface exposes the failure. + +Disable and shutdown follow structured cancellation: stop accepting new +actions, cancel long polling, wake retry waits, stop delivery workers, unregister +the stream observer, clear ephemeral tokens/queues, then close the HTTP client. +Repeated stop is safe. + +## Observability and diagnostics + +Connection state is one of: + +```text +disabled | starting | pairing | polling | backoff | rate_limited | +used_elsewhere | invalid_token | phone_unreachable | credential_missing | error +``` + +The status response includes connection ID, adapter kind, enabled state, +validated bot decoration, paired/unpaired state, phone reachability, last +successful poll time, last safe error class, current backoff deadline, and +informational/high-priority drop counters. It never includes raw provider +responses or credential/token material. + +Metrics cover received updates by accepted/refused reason, admission outcomes, +delivery attempts/results, callback outcomes, rate-limit waits, polling state, +queue depth, queue drops, and redaction/block decisions. Labels use bounded +enums and never principal, destination, session, username, task title, or +message content. + +Logs cover lifecycle transitions, safe provider error classes, pairing creation +and revocation by internal record ID, and bounded counters. Principal and +destination identifiers are omitted or one-way pseudonymized for correlation. +The diagnostics snapshot checks that no token-like URL or authorization header +is present. + +## Compatibility, rollout, and rollback + +The feature is additive and disabled by default. Existing installations create +no adapter runtime until the user configures and enables a connection. No +existing route or SSE shape changes meaning. Process-wide observer registration +is inert when no observer exists. + +The first release permits one connection at the service/API/UI layer. Tables and +internal contracts have connection IDs and no singleton database constraint. +Supporting several bots later requires lifting the admission limit and adding +selection/notification policy; it does not require rekeying pairings, +credentials, callbacks, or inbound idempotency. + +Each computer requires its own bot token. Moving a user to another installation +means configuring another bot there; EvoFlux never transfers a bot token or +pairing automatically. + +Rollout is controlled by the connection record's `enabled` field. Disabling is +the immediate operational rollback. Removing the connection clears its durable +metadata and vault secret. Migration downgrade drops only the two remote tables +and leaves all chat sessions/messages intact. + +Implementation proceeds in independently verifiable vertical slices: + +1. connection/pairing schema, vault abstraction, routes, and Settings setup; +2. Telegram polling, one-tap pairing, authorization, lifecycle, and status; +3. natural-language Work task creation/continuation and inbound idempotency; +4. stream projection, persisted completion delivery, and task continuation; +5. gate cards, races, revocation, and interruption; +6. optional advanced actions, documentation, localization, and final regression. + +## Verification matrix + +| AC | Evidence | +|---|---| +| AC-1, AC-2 | Disabled-lifespan/import/network test; route/auth and socket inventory inspection | +| AC-3, AC-4 | Connection admission tests plus two-connection service isolation tests for credentials, sources, callbacks, and queues | +| AC-5, AC-6 | Credential-store failure/rollback, masked response/log/diagnostic tests, `getMe` bot validation, and bot-identity replacement tests | +| AC-7, AC-8, AC-9 | Pairing token entropy/charset/length/expiry/single-use tests; private-chat principal/destination and rate-limit cases | +| AC-10 | Desktop and remote revocation tests proving callback/menu invalidation before return | +| AC-11, AC-12, AC-13 | Mock-transport tests for webhook/backlog disposal, error classes, retry timing with fake clock/jitter, and interruptible shutdown | +| AC-14, AC-15, AC-16 | Service tests for first-message Work creation, existing interactive ingress, accurate status, and duplicate update/source-key handling | +| AC-17, AC-18 | Current/new/continued/deleted task tests and refusal of child, Side Chat, and internal sessions | +| AC-19, AC-20 | Stream-store observer tests proving no await/blocking work and exhaustive event allowlist/drop behavior | +| AC-21, AC-22, AC-24 | Persisted completion/dedup tests, single-message lifecycle transitions, Unicode-safe splitting, and plain-text rendering tests | +| AC-23 | Remote outbound redaction and blocking-policy tests for every user/agent-derived field | +| AC-25, AC-26, AC-27, AC-28 | All three gate families, callback byte limit/ownership/expiry, acknowledgement ordering, least authority, stale races, and edit-on-reply tests | +| AC-29, AC-30 | Current-turn-only interrupt test and Workflow/repository/policy mutation refusal tests | +| AC-31 | Focused service-contract tests for approved Workflow, Coding task, eligible Evo Agent Specs action, and scheduled-task manual trigger | +| AC-32, AC-33 | Command/route inventory and desktop-auth regression tests | +| AC-34 | Status, bounded-metric-label, log capture, and diagnostics secret-absence tests | +| AC-35, AC-36 | Settings disclosure plus feature/config/API and three-locale Help review | +| AC-37 | Migration head/upgrade tests, focused suites, backend/frontend quality gates, and `git diff --check` | + +## Ownership and source map + +- Connection-aware core, service, adapter contracts, Telegram transport, + pairing, projection, interaction tokens, and status: `app/remote/`. +- OS-vault abstraction modeled on the existing Conductor precedent but kept as + independent, standalone infrastructure used only by remote access: + `app/core/credential_store.py`. `app/conductor/client.py` and + `app/conductor/service.py` are not modified; Conductor is an external + integration point (`evo-conductor`) and keeps its own credential + implementation and constructor contract unchanged. +- Persistence: `app/models/remote.py`, model registration, and + `app/migrations/versions/00000064_create_remote_pairings.py`; schema marker: + `app/core/schema_version.py`. +- Thin schemas/routes and application lifecycle: `app/api/schemas/remote.py`, + `app/api/routes/remote.py`, `app/api/routes/settings.py`, and `app/api/app.py`. +- Stream observation: `app/services/memory_stream_store.py`. +- Existing task/session creation and interactive ingress: + `app/services/chat_service.py`, `app/services/interactive_message_service.py`, + and `app/services/team_manager.py`. +- Gate owners: `app/agent/permission.py`, `app/agent/ask_user.py`, and + `app/agent/plan.py`. +- Explicit remote outbound policy: `app/agent/outbound_redaction.py` and the + existing sandbox/runtime-settings boundary. +- Existing action owners: `app/workflow/`, `app/scheduler/`, and the Evo Agent + Specs services/routes. The remote layer calls services rather than copying + their approval rules. +- Settings client and UI: `web/src/api/types.ts`, `web/src/api/client/settings.ts`, + `web/src/components/settings/`, and the existing Settings navigation. +- In-app Help: `web/src/help/locales/en.ts`, `web/src/help/locales/vi.ts`, and + `web/src/help/locales/ja.ts`. +- Current feature contract to create when implementation ships: + `documents/features/remote-access.md`, plus a catalogue row in + `documents/features/README.md` and trust cross-reference from + `documents/features/security-and-permissions.md`. +- Current references to update when implementation ships: + `documents/reference/configuration.md` and + `documents/reference/http-api.md`. + +The plan remains historical/proposed until implementation is verified and the +current feature/reference/Help documents are reconciled. This file does not by +itself claim that remote access is available. diff --git a/tests/core/test_alembic_migrations.py b/tests/core/test_alembic_migrations.py index 4ab80642..7541276e 100644 --- a/tests/core/test_alembic_migrations.py +++ b/tests/core/test_alembic_migrations.py @@ -215,6 +215,51 @@ def test_alembic_upgrade_head_adds_latest_schema(tmp_path, monkeypatch): if index.get("unique") } assert "uq_webbridge_tab_bindings_pairing_session" in binding_unique_indexes + assert {"remote_connections", "remote_pairings"} <= set( + inspector.get_table_names() + ) + remote_connection_columns = { + column["name"] for column in inspector.get_columns("remote_connections") + } + assert { + "id", + "adapter", + "label", + "enabled", + "adapter_principal_id", + "adapter_username", + "created_at", + "updated_at", + } <= remote_connection_columns + remote_pairing_columns = { + column["name"] for column in inspector.get_columns("remote_pairings") + } + assert { + "id", + "connection_id", + "principal_id", + "destination_id", + "label", + "display", + "active_session_id", + "created_at", + "last_seen_at", + } <= remote_pairing_columns + remote_pairing_fks = inspector.get_foreign_keys("remote_pairings") + connection_fk = next( + fk for fk in remote_pairing_fks if fk["referred_table"] == "remote_connections" + ) + assert connection_fk["options"].get("ondelete", "").upper() == "CASCADE" + session_fk = next( + fk for fk in remote_pairing_fks if fk["referred_table"] == "chat_sessions" + ) + assert session_fk["options"].get("ondelete", "").upper() == "SET NULL" + remote_pairing_unique = { + tuple(sorted(constraint["column_names"])) + for constraint in inspector.get_unique_constraints("remote_pairings") + } + assert ("connection_id", "principal_id") in remote_pairing_unique + assert ("connection_id", "destination_id") in remote_pairing_unique with engine.connect() as conn: version = conn.execute( sa.text("SELECT version_num FROM alembic_version") diff --git a/tests/core/test_credential_store.py b/tests/core/test_credential_store.py new file mode 100644 index 00000000..7c5fb86b --- /dev/null +++ b/tests/core/test_credential_store.py @@ -0,0 +1,69 @@ +from __future__ import annotations + +from types import SimpleNamespace + +import pytest + +from app.core.credential_store import CredentialStore, CredentialStoreError + + +def test_keyed_store_keeps_connection_credentials_isolated(monkeypatch) -> None: + values: dict[tuple[str, str], str] = {} + + fake_keyring = SimpleNamespace( + get_password=lambda service, account: values.get((service, account)), + set_password=lambda service, account, value: values.__setitem__( + (service, account), value + ), + delete_password=lambda service, account: values.pop((service, account)), + ) + monkeypatch.setitem(__import__("sys").modules, "keyring", fake_keyring) + + first = CredentialStore(service="EvoFlux Remote", account="connection:first") + second = CredentialStore(service="EvoFlux Remote", account="connection:second") + + first.save("first-secret") + second.save("second-secret") + + assert first.load() == "first-secret" + assert second.load() == "second-secret" + + +def test_keyed_store_wraps_save_failure_without_echoing_secret(monkeypatch) -> None: + def fail_save(service: str, account: str, value: str) -> None: + del service, account, value + raise RuntimeError("backend failed") + + fake_keyring = SimpleNamespace(set_password=fail_save) + monkeypatch.setitem(__import__("sys").modules, "keyring", fake_keyring) + + store = CredentialStore(service="EvoFlux Remote", account="connection:first") + with pytest.raises(CredentialStoreError) as exc_info: + store.save("must-not-appear") + + assert str(exc_info.value) == "The credential could not be saved to the operating system credential vault." + assert "must-not-appear" not in str(exc_info.value) + + +def test_keyed_store_treats_missing_credential_as_successful_delete(monkeypatch) -> None: + class PasswordDeleteError(Exception): + pass + + def missing(service: str, account: str) -> None: + del service, account + raise PasswordDeleteError + + fake_keyring = SimpleNamespace( + delete_password=missing, + errors=SimpleNamespace(PasswordDeleteError=PasswordDeleteError), + ) + monkeypatch.setitem(__import__("sys").modules, "keyring", fake_keyring) + monkeypatch.setitem( + __import__("sys").modules, + "keyring.errors", + fake_keyring.errors, + ) + + CredentialStore( + service="EvoFlux Remote", account="connection:missing" + ).delete() diff --git a/tests/remote/test_models.py b/tests/remote/test_models.py new file mode 100644 index 00000000..1c773789 --- /dev/null +++ b/tests/remote/test_models.py @@ -0,0 +1,43 @@ +from __future__ import annotations + +from uuid import uuid4 + +import sqlalchemy as sa + +from app.models.remote import RemoteConnection, RemotePairing + + +def test_remote_pairing_keeps_authorization_and_destination_separate() -> None: + pairing = RemotePairing( + connection_id=uuid4(), + principal_id="telegram-user-1", + destination_id="telegram-chat-9", + label="My phone", + ) + + assert pairing.principal_id == "telegram-user-1" + assert pairing.destination_id == "telegram-chat-9" + + +def test_remote_schema_is_connection_aware_without_v1_singleton_constraint() -> None: + connection_table = RemoteConnection.__table__ + pairing_table = RemotePairing.__table__ + + assert connection_table.name == "remote_connections" + assert pairing_table.name == "remote_pairings" + assert "connection_id" in pairing_table.c + + connection_unique_columns = { + tuple(column.name for column in constraint.columns) + for constraint in connection_table.constraints + if isinstance(constraint, sa.UniqueConstraint) + } + pairing_unique_columns = { + tuple(column.name for column in constraint.columns) + for constraint in pairing_table.constraints + if isinstance(constraint, sa.UniqueConstraint) + } + + assert ("adapter",) not in connection_unique_columns + assert ("connection_id", "principal_id") in pairing_unique_columns + assert ("connection_id", "destination_id") in pairing_unique_columns From 3cfb9c57b580e05722ac71eab623e3a732ec9cbf Mon Sep 17 00:00:00 2001 From: manhnguyen24-dev Date: Mon, 14 Sep 2026 14:07:58 +0700 Subject: [PATCH 02/71] feat(remote): Task 2 - remote settings, core contracts, and connection service Adds RemoteSettings (outbound_data_policy/outbound_pii_policy, defaulting to redact/standard) wired into RuntimeSettings and exposed via GET/PUT /api/settings/remote. Adds app/remote/contracts.py with the provider-neutral, connection-aware value types and protocols for the remote-access seam (RemoteAdapterKind, RemoteConnectionState, RemoteErrorClass, RemotePrincipal, RemoteInboundAction, RemoteOutboundMessage, RemoteAdapterStatus, RemoteAdapter, RemoteAdapterFactory) with no Telegram/httpx import anywhere. Adds RemoteConnectionService (create_connection/update_token/set_enabled/ remove/list/get) enforcing the v1 one-connection product limit, validating a bot token before vaulting it, keeping DB transactions free of vault/ network calls with compensating vault cleanup on commit failure, and invalidating a connection's pairing row on bot-identity replacement while leaving it untouched for a same-bot token rotation. Extends OutboundChannel with the "remote" value for later tasks' explicit policy selection. app/conductor/ is untouched. --- app/agent/outbound_redaction.py | 6 +- app/api/routes/settings.py | 35 +++ app/api/schemas/settings.py | 12 + app/core/runtime_settings.py | 18 ++ app/remote/__init__.py | 8 + app/remote/connection_service.py | 259 ++++++++++++++++ app/remote/contracts.py | 225 ++++++++++++++ tests/agent/test_outbound_redaction.py | 34 +++ tests/api/test_settings_routes.py | 53 ++++ tests/remote/__init__.py | 0 tests/remote/test_connection_service.py | 378 ++++++++++++++++++++++++ 11 files changed, 1027 insertions(+), 1 deletion(-) create mode 100644 app/remote/__init__.py create mode 100644 app/remote/connection_service.py create mode 100644 app/remote/contracts.py create mode 100644 tests/remote/__init__.py create mode 100644 tests/remote/test_connection_service.py diff --git a/app/agent/outbound_redaction.py b/app/agent/outbound_redaction.py index 6f1e783f..c424ba23 100644 --- a/app/agent/outbound_redaction.py +++ b/app/agent/outbound_redaction.py @@ -28,7 +28,11 @@ OutboundDataPolicy = Literal["block", "redact", "off"] OutboundPiiPolicy = Literal["off", "standard", "strict"] -OutboundChannel = Literal["model", "web", "mcp", "other"] +#: ``remote`` is the phone-facing Telegram channel (a later task). Its +#: policy is selected explicitly by the caller rather than inherited from +#: the ambient sandbox state the other channels default to, because a +#: remote message is addressed to a device outside the sandboxed run. +OutboundChannel = Literal["model", "web", "mcp", "other", "remote"] @dataclass(frozen=True) diff --git a/app/api/routes/settings.py b/app/api/routes/settings.py index 59b7f1d3..878920a6 100644 --- a/app/api/routes/settings.py +++ b/app/api/routes/settings.py @@ -25,6 +25,7 @@ ConductorSettings, ContextSettings, GitSettings, + RemoteSettings, WebBridgeSettings, load_runtime_settings, load_runtime_settings_report, @@ -54,6 +55,7 @@ TeamSpawnSettingsBody, ProviderVisibleModelsResponse, ProvidersListBody, + RemoteSettingsBody, SandboxSettingsBody, SeedInstallRequest, SeedInstallResponse, @@ -631,6 +633,39 @@ async def save_follow_up_settings(body: FollowUpSettingsBody) -> FollowUpSetting return FollowUpSettingsBody(delivery=cfg.follow_up.delivery) +# Remote access (Settings -> Remote access tab) + + +def _remote_settings_body() -> RemoteSettingsBody: + cfg = load_runtime_settings() + return RemoteSettingsBody( + outbound_data_policy=cfg.remote.outbound_data_policy, + outbound_pii_policy=cfg.remote.outbound_pii_policy, + ) + + +@router.get("/remote") +async def get_remote_settings() -> RemoteSettingsBody: + try: + return _remote_settings_body() + except ValueError as exc: + raise HTTPException(status_code=422, detail=str(exc)) from exc + + +@router.put("/remote") +async def update_remote_settings(body: RemoteSettingsBody) -> RemoteSettingsBody: + try: + cfg = load_runtime_settings() + except ValueError as exc: + raise HTTPException(status_code=422, detail=str(exc)) from exc + cfg.remote = RemoteSettings( + outbound_data_policy=body.outbound_data_policy, + outbound_pii_policy=body.outbound_pii_policy, + ) + save_runtime_settings(cfg) + return _remote_settings_body() + + # Providers (Settings -> Providers tab) diff --git a/app/api/schemas/settings.py b/app/api/schemas/settings.py index 01866980..f013b0fb 100644 --- a/app/api/schemas/settings.py +++ b/app/api/schemas/settings.py @@ -37,6 +37,18 @@ class SandboxSettingsBody(BaseModel): max_output_bytes: int = Field(default=131072, ge=4096, le=1048576) +class RemoteSettingsBody(BaseModel): + """``GET/PUT /api/settings/remote`` — the ``remote`` outbound channel's + redaction policy. Connection enablement, adapter, and pairing state are + not part of this section; they live on the connection record exposed by + ``/api/remote/connections`` (a later task).""" + + model_config = ConfigDict(extra="forbid") + + outbound_data_policy: Literal["block", "redact", "off"] = "redact" + outbound_pii_policy: Literal["off", "standard", "strict"] = "standard" + + class IgnoredSettingBody(BaseModel): """A hand-edited ``settings.yaml`` value that failed validation.""" diff --git a/app/core/runtime_settings.py b/app/core/runtime_settings.py index 642376c9..baee476a 100644 --- a/app/core/runtime_settings.py +++ b/app/core/runtime_settings.py @@ -206,6 +206,23 @@ class BuiltInBrowserSettings(BaseModel): allow_agent_permission_accept: bool = False +class RemoteSettings(BaseModel): + """Explicit outbound-data policy for the ``remote`` channel. + + Connection enablement, adapter kind, and bot identity live on the + ``RemoteConnection`` database record (``app/models/remote.py``), not + here — this section only carries the redaction policy applied to every + user- and agent-derived field before it reaches a paired phone. The + default is the safe one: redaction and standard PII masking are on, + unlike the sandbox's own outbound policy, which defaults off. + """ + + model_config = ConfigDict(extra="ignore") + + outbound_data_policy: Literal["block", "redact", "off"] = "redact" + outbound_pii_policy: Literal["off", "standard", "strict"] = "standard" + + class ConductorSettings(BaseModel): """Connection and enforcement policy for the organization control plane.""" @@ -294,6 +311,7 @@ class RuntimeSettings(BaseModel): conductor: ConductorSettings = Field(default_factory=ConductorSettings) team_spawn: TeamSpawnModeSettings = Field(default_factory=TeamSpawnModeSettings) follow_up: FollowUpSettings = Field(default_factory=FollowUpSettings) + remote: RemoteSettings = Field(default_factory=RemoteSettings) def follow_up_delivery_default() -> str: diff --git a/app/remote/__init__.py b/app/remote/__init__.py new file mode 100644 index 00000000..0f613f91 --- /dev/null +++ b/app/remote/__init__.py @@ -0,0 +1,8 @@ +"""Connection-aware core for outbound-only remote access (e.g. Telegram). + +Nothing in this package is imported unless a connection is configured and +enabled. Adapter-specific modules (``app/remote/telegram/``, added in a later +task) own provider payload translation; everything here is provider-neutral. +""" + +from __future__ import annotations diff --git a/app/remote/connection_service.py b/app/remote/connection_service.py new file mode 100644 index 00000000..b1fde14c --- /dev/null +++ b/app/remote/connection_service.py @@ -0,0 +1,259 @@ +"""Durable connection-record coordination: validate, vault, persist, limit. + +Keeps the v1 one-connection product limit, credential custody, and bot +identity binding in one narrow service so HTTP routes (a later task) stay +thin and the Telegram adapter (a later task) never touches ``settings.yaml``, +the database, or the credential vault directly. + +Per the spec's concurrency contract, a database transaction here never +performs network or vault I/O: a token is validated against the adapter and +saved to the OS credential vault *before* the connection row is inserted or +updated, with a compensating vault write if the database commit then fails. +""" + +from __future__ import annotations + +from collections.abc import Callable +from uuid import UUID + +from sqlmodel import select +from sqlmodel.ext.asyncio.session import AsyncSession + +from app.core.credential_store import ( + CredentialStore, + CredentialStoreError, + CredentialStoreProtocol, +) +from app.models.remote import RemoteConnection, RemotePairing +from app.remote.contracts import ( + RemoteAdapterFactory, + RemoteAdapterKind, + RemoteAdapterValidationError, +) + +#: Vault service name every remote connection's credential is stored under. +#: The account key is derived per connection as ``connection:`` and +#: never appears in an API response. +CREDENTIAL_VAULT_SERVICE = "EvoFlux Remote" + +CredentialStoreFactory = Callable[[UUID], CredentialStoreProtocol] + +__all__ = [ + "CREDENTIAL_VAULT_SERVICE", + "CredentialStoreFactory", + "RemoteAdapterValidationError", + "RemoteConnectionConflictError", + "RemoteConnectionError", + "RemoteConnectionNotFoundError", + "RemoteConnectionService", + "RemoteCredentialError", + "default_credential_store_factory", +] + + +def default_credential_store_factory(connection_id: UUID) -> CredentialStoreProtocol: + """The production vault-account keying: ``connection:``.""" + return CredentialStore( + service=CREDENTIAL_VAULT_SERVICE, account=f"connection:{connection_id}" + ) + + +class RemoteConnectionError(Exception): + """Base class for :class:`RemoteConnectionService` domain errors.""" + + +class RemoteConnectionConflictError(RemoteConnectionError): + """A second connection was requested. + + AC-3: v1 permits exactly one configured connection. This is a + service-level product limit, not a database uniqueness constraint, so a + later release can lift it without a migration. + """ + + +class RemoteConnectionNotFoundError(RemoteConnectionError): + """An operation named a connection ID that does not exist.""" + + +class RemoteCredentialError(RemoteConnectionError): + """The OS credential vault could not complete an operation. + + Never carries the token or any vault-internal detail beyond the + underlying :class:`~app.core.credential_store.CredentialStoreError` + message, which is itself already safe (AC-5). + """ + + +class RemoteConnectionService: + """Coordinates connection lifecycle across the database, the OS + credential vault, and adapter-identity validation.""" + + def __init__( + self, + *, + adapter_factory: RemoteAdapterFactory, + credential_store_factory: CredentialStoreFactory | None = None, + ) -> None: + self._adapter_factory = adapter_factory + self._credential_store_factory = ( + credential_store_factory or default_credential_store_factory + ) + + def _store(self, connection_id: UUID) -> CredentialStoreProtocol: + return self._credential_store_factory(connection_id) + + async def list(self, session: AsyncSession) -> list[RemoteConnection]: + result = await session.exec(select(RemoteConnection)) + return list(result.all()) + + async def get( + self, session: AsyncSession, connection_id: UUID + ) -> RemoteConnection | None: + return await session.get(RemoteConnection, connection_id) + + async def create_connection( + self, session: AsyncSession, *, token: str, label: str + ) -> RemoteConnection: + """Validate *token*, vault it, then persist a new connection. + + Raises :class:`RemoteConnectionConflictError` if a connection + already exists, + :class:`~app.remote.contracts.RemoteAdapterValidationError` if the + token does not resolve to a bot identity, or + :class:`RemoteCredentialError` if the vault save fails. In every + failure case, no connection record is created. + """ + if await self.list(session): + raise RemoteConnectionConflictError( + "This installation already has a configured remote connection." + ) + + identity = await self._adapter_factory.validate_token( + RemoteAdapterKind.TELEGRAM, token + ) + + connection = RemoteConnection( + adapter=identity.adapter.value, + label=label, + enabled=False, + adapter_principal_id=identity.principal_id, + adapter_username=identity.username, + ) + + store = self._store(connection.id) + try: + store.save(token) + except CredentialStoreError as exc: + raise RemoteCredentialError(str(exc)) from exc + + try: + session.add(connection) + await session.commit() + except BaseException: + await session.rollback() + _delete_best_effort(store) + raise + + await session.refresh(connection) + return connection + + async def update_token( + self, session: AsyncSession, connection_id: UUID, *, token: str + ) -> RemoteConnection: + """Validate and atomically replace a connection's bot token. + + A new identity whose ``principal_id`` differs from the one already + stored (a different bot) invalidates the existing pairing row before + the new credential becomes active (AC-6, AC-10). A new identity for + the *same* bot leaves any existing pairing untouched — only the + decorative username may change. + """ + connection = await self.get(session, connection_id) + if connection is None: + raise RemoteConnectionNotFoundError( + f"Remote connection {connection_id} does not exist." + ) + + identity = await self._adapter_factory.validate_token( + RemoteAdapterKind.TELEGRAM, token + ) + + store = self._store(connection_id) + try: + previous_token = store.load() + except CredentialStoreError: + previous_token = None + + try: + store.save(token) + except CredentialStoreError as exc: + raise RemoteCredentialError(str(exc)) from exc + + different_bot = identity.principal_id != connection.adapter_principal_id + connection.adapter_principal_id = identity.principal_id + connection.adapter_username = identity.username + + try: + if different_bot: + existing_pairings = await session.exec( + select(RemotePairing).where( + RemotePairing.connection_id == connection_id + ) + ) + for pairing in existing_pairings.all(): + await session.delete(pairing) + session.add(connection) + await session.commit() + except BaseException: + await session.rollback() + if previous_token is not None: + _save_best_effort(store, previous_token) + raise + + await session.refresh(connection) + return connection + + async def set_enabled( + self, session: AsyncSession, connection_id: UUID, *, enabled: bool + ) -> RemoteConnection: + connection = await self.get(session, connection_id) + if connection is None: + raise RemoteConnectionNotFoundError( + f"Remote connection {connection_id} does not exist." + ) + connection.enabled = enabled + session.add(connection) + await session.commit() + await session.refresh(connection) + return connection + + async def remove(self, session: AsyncSession, connection_id: UUID) -> None: + """Delete the connection (cascading its pairing) and its vault entry.""" + connection = await self.get(session, connection_id) + if connection is None: + raise RemoteConnectionNotFoundError( + f"Remote connection {connection_id} does not exist." + ) + + await session.delete(connection) + await session.commit() + + store = self._store(connection_id) + try: + store.delete() + except CredentialStoreError as exc: + raise RemoteCredentialError(str(exc)) from exc + + +def _delete_best_effort(store: CredentialStoreProtocol) -> None: + try: + store.delete() + except CredentialStoreError: + pass + + +def _save_best_effort(store: CredentialStoreProtocol, token: str) -> None: + try: + store.save(token) + except CredentialStoreError: + pass diff --git a/app/remote/contracts.py b/app/remote/contracts.py new file mode 100644 index 00000000..e703f900 --- /dev/null +++ b/app/remote/contracts.py @@ -0,0 +1,225 @@ +"""Provider-neutral value types and protocols for the remote-access seam. + +Every value here is connection-aware (AC-4): pairings, credential keys, +inbound source keys, callback tokens, queue items, and runtime status all +carry a ``connection_id`` so a later multi-connection release does not need +to rekey anything. Nothing in this module imports an adapter-specific +(Telegram) payload type — that translation happens only inside +``app/remote/telegram/`` and never escapes it. +""" + +from __future__ import annotations + +from dataclasses import dataclass, field +from datetime import datetime +from enum import StrEnum +from typing import Protocol +from uuid import UUID + + +class RemoteAdapterKind(StrEnum): + """Bounded set of supported remote transports. Telegram is the only one + shipped in v1; the enum exists so a later adapter needs no schema + migration, only a new member.""" + + TELEGRAM = "telegram" + + +class RemoteConnectionState(StrEnum): + """Runtime lifecycle of one connection's adapter, per the Observability + contract. Distinct from :class:`RemoteErrorClass`, which names the last + *safe* error independently of the current state.""" + + DISABLED = "disabled" + STARTING = "starting" + PAIRING = "pairing" + POLLING = "polling" + BACKOFF = "backoff" + RATE_LIMITED = "rate_limited" + USED_ELSEWHERE = "used_elsewhere" + INVALID_TOKEN = "invalid_token" + PHONE_UNREACHABLE = "phone_unreachable" + CREDENTIAL_MISSING = "credential_missing" + ERROR = "error" + + +class RemoteErrorClass(StrEnum): + """Safe, bounded classification of the last adapter error. Never a raw + provider error string — those can carry tokens or update payloads.""" + + NONE = "none" + INVALID_TOKEN = "invalid_token" + USED_ELSEWHERE = "used_elsewhere" + RATE_LIMITED = "rate_limited" + TRANSPORT = "transport" + PHONE_UNREACHABLE = "phone_unreachable" + CREDENTIAL_MISSING = "credential_missing" + UNKNOWN = "unknown" + + +class RemoteInboundActionKind(StrEnum): + """What kind of update produced a :class:`RemoteInboundAction`.""" + + TEXT = "text" + CALLBACK = "callback" + PAIRING_START = "pairing_start" + + +class RemoteOutboundPriority(StrEnum): + """Which bounded, non-blocking queue an outbound message belongs to. + + ``HIGH`` carries gates and terminal completion notices; losing one is a + delivery failure the status surface must report. ``INFORMATIONAL`` + carries lifecycle/admission chatter where the oldest item is dropped + under pressure instead of blocking the producing turn. + """ + + HIGH = "high" + INFORMATIONAL = "informational" + + +@dataclass(frozen=True) +class ValidatedRemoteIdentity: + """The immutable bot identity returned by a successful ``getMe``-style + validation, before any persistence happens.""" + + adapter: RemoteAdapterKind + principal_id: str + username: str + + +class RemoteAdapterValidationError(Exception): + """Raised by :meth:`RemoteAdapterFactory.validate_token` when the token + does not resolve to a usable bot identity. Never carries the token.""" + + +class RemoteAdapterFactory(Protocol): + """Validates a credential against the adapter's identity endpoint. + + Kept as a narrow protocol so ``app/remote`` service-level code (and its + tests) never import or call a real Telegram client — a later task + supplies the concrete implementation. + """ + + async def validate_token( + self, adapter: RemoteAdapterKind, token: str + ) -> ValidatedRemoteIdentity: ... + + +@dataclass(frozen=True) +class RemotePrincipal: + """One paired account. ``principal_id`` authorizes actions; + ``destination_id`` addresses replies. They are stored and compared + separately even though a given adapter may report matching values for a + private chat (spec: "Connect the phone").""" + + connection_id: UUID + principal_id: str + destination_id: str + #: Untrusted, adapter-reported decoration (display name/username). Never + #: used for authorization. + display: str = "" + + +@dataclass(frozen=True) +class RemoteInboundAction: + """One normalized inbound update, already classified by the adapter. + + ``source_key`` is the inbound idempotency key (adapter + connection + + provider update ID, AC-16) so redelivery within a process or a replay + after a crash between admission and offset acknowledgement produces at + most one persisted message. + """ + + connection_id: UUID + kind: RemoteInboundActionKind + principal: RemotePrincipal + source_key: str + text: str | None = None + callback_token: str | None = None + pairing_token: str | None = None + + +@dataclass(frozen=True) +class RemoteButton: + """One inline button. ``token`` is an opaque, connection-owned, + principal-bound capability reference — never a raw session ID, database + ID, path, command, plan, or credential (AC-25).""" + + text: str + token: str + + +@dataclass(frozen=True) +class RemoteOutboundMessage: + """One outbound message bound for a paired destination. + + Plain text only — no parse mode, so model-authored text cannot + manufacture links, mentions, or formatting (AC-24). ``correlation_id`` + lets the owning turn's lifecycle message be found again for editing + instead of appending progress (AC-22). + """ + + connection_id: UUID + destination_id: str + text: str + buttons: tuple[RemoteButton, ...] = field(default_factory=tuple) + correlation_id: str | None = None + priority: RemoteOutboundPriority = RemoteOutboundPriority.INFORMATIONAL + + +@dataclass(frozen=True) +class RemoteAdapterStatus: + """Safe, diagnosable runtime status for one connection (AC-34). + + Never includes raw provider responses, credentials, or tokens. + """ + + connection_id: UUID + state: RemoteConnectionState + last_error_class: RemoteErrorClass = RemoteErrorClass.NONE + last_successful_poll_at: datetime | None = None + paired: bool = False + phone_reachable: bool | None = None + informational_drop_count: int = 0 + high_priority_drop_count: int = 0 + + +class RemoteAdapter(Protocol): + """Lifecycle and delivery surface an adapter (e.g. Telegram) implements. + + An adapter never decides EvoFlux authorization — it only starts/stops + polling, sends/edits messages, and acknowledges callbacks. The owning + ``RemoteService`` (a later task) is the sole authority for pairing, + principal checks, and gate resolution. + """ + + async def start(self) -> None: ... + + async def stop(self) -> None: ... + + async def send(self, message: RemoteOutboundMessage) -> None: ... + + async def edit(self, message: RemoteOutboundMessage) -> None: ... + + async def answer_callback(self, callback_token: str) -> None: ... + + def status(self) -> RemoteAdapterStatus: ... + + +__all__ = [ + "RemoteAdapter", + "RemoteAdapterFactory", + "RemoteAdapterKind", + "RemoteAdapterStatus", + "RemoteAdapterValidationError", + "RemoteButton", + "RemoteConnectionState", + "RemoteErrorClass", + "RemoteInboundAction", + "RemoteInboundActionKind", + "RemoteOutboundMessage", + "RemoteOutboundPriority", + "RemotePrincipal", + "ValidatedRemoteIdentity", +] diff --git a/tests/agent/test_outbound_redaction.py b/tests/agent/test_outbound_redaction.py index 0d004e3f..5d5434aa 100644 --- a/tests/agent/test_outbound_redaction.py +++ b/tests/agent/test_outbound_redaction.py @@ -397,3 +397,37 @@ def test_nested_external_object_keys_are_protected() -> None: assert secret_key not in protected assert "abcdefghijklmnop" not in str(protected) assert report.secret_matches == 1 + + +def test_remote_channel_is_an_explicit_outbound_context( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """AC-23: every remote-bound field passes through the ``remote`` + channel's own policy, selected explicitly by the caller rather than + read from the ambient sandbox state the other channels fall back on.""" + secret = "unusual-remote-credential-value" + monkeypatch.setenv("SAMPLE_API_KEY", secret) + + context = OutboundContext(channel="remote", destination="telegram") + assert context.label == "remote:telegram" + + protected, report = protect_outbound_text( + f"Tool ran with {secret}", + policy="redact", + pii_policy="standard", + context=context, + ) + + assert secret not in protected + assert "[REDACTED:configured-secret]" in protected + assert report.context is context + + +def test_remote_channel_block_policy_reports_the_remote_destination() -> None: + with pytest.raises(OutboundSensitiveDataError, match="remote:telegram"): + protect_outbound_text( + "token: abcdefghijklmnop", + policy="block", + pii_policy="off", + context=OutboundContext(channel="remote", destination="telegram"), + ) diff --git a/tests/api/test_settings_routes.py b/tests/api/test_settings_routes.py index c4798253..4799e045 100644 --- a/tests/api/test_settings_routes.py +++ b/tests/api/test_settings_routes.py @@ -1501,6 +1501,59 @@ def test_webbridge_settings_round_trip(tmp_path, monkeypatch): assert reread.json() == payload +def test_get_remote_settings_defaults_to_redaction_on(tmp_path, monkeypatch): + """AC-23: redaction is the default for the ``remote`` outbound channel, + unlike the sandbox's own outbound policy (which defaults off).""" + from app.core.config import settings + + monkeypatch.setattr(settings, "EVOFLUX_CONFIG_DIR", str(tmp_path)) + client = TestClient(_make_app()) + + response = client.get("/api/settings/remote") + + assert response.status_code == 200 + assert response.json() == { + "outbound_data_policy": "redact", + "outbound_pii_policy": "standard", + } + # GET must not write the file. + assert not (tmp_path / "settings.yaml").exists() + + +def test_remote_settings_round_trip(tmp_path, monkeypatch): + from app.core.config import settings + + monkeypatch.setattr(settings, "EVOFLUX_CONFIG_DIR", str(tmp_path)) + client = TestClient(_make_app()) + + payload = {"outbound_data_policy": "block", "outbound_pii_policy": "strict"} + updated = client.put("/api/settings/remote", json=payload) + + assert updated.status_code == 200 + assert updated.json() == payload + written = (tmp_path / "settings.yaml").read_text(encoding="utf-8") + assert "outbound_data_policy: block" in written + assert "outbound_pii_policy: strict" in written + + reread = client.get("/api/settings/remote") + assert reread.status_code == 200 + assert reread.json() == payload + + +def test_put_remote_settings_rejects_unknown_field(tmp_path, monkeypatch): + from app.core.config import settings + + monkeypatch.setattr(settings, "EVOFLUX_CONFIG_DIR", str(tmp_path)) + client = TestClient(_make_app()) + + response = client.put( + "/api/settings/remote", + json={"outbound_data_policy": "redact", "connection_enabled": True}, + ) + + assert response.status_code == 422 + + def test_save_provider_visible_models_rejects_unknown_provider() -> None: app = _make_app() client = TestClient(app) diff --git a/tests/remote/__init__.py b/tests/remote/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/tests/remote/test_connection_service.py b/tests/remote/test_connection_service.py new file mode 100644 index 00000000..19b9ab39 --- /dev/null +++ b/tests/remote/test_connection_service.py @@ -0,0 +1,378 @@ +"""Tests for app/remote/connection_service.py. + +Exercises the durable half of connection setup — validate, vault, persist, +one-connection limit, bot-identity binding, and pairing invalidation on +bot replacement — without ever calling Telegram. ``FakeAdapterFactory`` +implements the ``RemoteAdapterFactory`` protocol synchronously in-process, +and ``FakeCredentialStore`` stands in for the OS vault. +""" + +from __future__ import annotations + +from uuid import UUID, uuid4 + +import pytest +import pytest_asyncio +from sqlmodel import select + +import app.core.db as db_module +from app.core.credential_store import CredentialStoreError +from app.models.remote import RemoteConnection, RemotePairing +from app.remote.connection_service import ( + RemoteConnectionConflictError, + RemoteConnectionNotFoundError, + RemoteConnectionService, + RemoteCredentialError, +) +from app.remote.contracts import ( + RemoteAdapterKind, + RemoteAdapterValidationError, + ValidatedRemoteIdentity, +) + + +class FakeCredentialStore: + """In-memory stand-in for the OS vault, one instance per connection ID.""" + + def __init__(self) -> None: + self.values: dict[str, str] = {} + self.save_error: Exception | None = None + self.delete_error: Exception | None = None + self.deleted: list[str] = [] + + def load(self) -> str | None: + return self.values.get("token") + + def save(self, credential: str) -> None: + if self.save_error is not None: + raise self.save_error + self.values["token"] = credential + + def delete(self) -> None: + if self.delete_error is not None: + raise self.delete_error + self.deleted.append(self.values.pop("token", "")) + + +class FakeAdapterFactory: + """Synchronous, in-process stand-in for ``RemoteAdapterFactory``.""" + + def __init__(self) -> None: + #: token -> identity it resolves to. Missing tokens are invalid. + self.identities: dict[str, ValidatedRemoteIdentity] = {} + self.calls: list[str] = [] + + async def validate_token( + self, adapter: RemoteAdapterKind, token: str + ) -> ValidatedRemoteIdentity: + self.calls.append(token) + identity = self.identities.get(token) + if identity is None: + raise RemoteAdapterValidationError("Invalid bot token.") + return identity + + +@pytest.fixture +def adapter_factory() -> FakeAdapterFactory: + factory = FakeAdapterFactory() + factory.identities["bot-token-1"] = ValidatedRemoteIdentity( + adapter=RemoteAdapterKind.TELEGRAM, + principal_id="bot-1", + username="my_bot", + ) + factory.identities["bot-token-2-same-bot"] = ValidatedRemoteIdentity( + adapter=RemoteAdapterKind.TELEGRAM, + principal_id="bot-1", + username="my_bot_renamed", + ) + factory.identities["bot-token-3-different-bot"] = ValidatedRemoteIdentity( + adapter=RemoteAdapterKind.TELEGRAM, + principal_id="bot-2", + username="another_bot", + ) + return factory + + +@pytest.fixture +def credential_stores() -> dict[UUID, FakeCredentialStore]: + return {} + + +@pytest.fixture +def service(adapter_factory, credential_stores): + def factory(connection_id: UUID) -> FakeCredentialStore: + return credential_stores.setdefault(connection_id, FakeCredentialStore()) + + return RemoteConnectionService( + adapter_factory=adapter_factory, + credential_store_factory=factory, + ) + + +@pytest_asyncio.fixture +async def session(): + async with db_module.async_session_factory() as db_session: + yield db_session + + +# ── create_connection ─────────────────────────────────────────────────────── + + +@pytest.mark.asyncio +async def test_create_validates_token_before_any_persistence( + session, service, adapter_factory +) -> None: + with pytest.raises(RemoteAdapterValidationError): + await service.create_connection(session, token="unknown-token", label="Phone") + + assert (await session.exec(select(RemoteConnection))).all() == [] + assert adapter_factory.calls == ["unknown-token"] + + +@pytest.mark.asyncio +async def test_create_persists_validated_identity_and_vaults_token( + session, service, credential_stores +) -> None: + connection = await service.create_connection( + session, token="bot-token-1", label="My phone" + ) + + assert connection.adapter == "telegram" + assert connection.adapter_principal_id == "bot-1" + assert connection.adapter_username == "my_bot" + assert connection.label == "My phone" + assert connection.enabled is False + + store = credential_stores[connection.id] + assert store.load() == "bot-token-1" + + rows = (await session.exec(select(RemoteConnection))).all() + assert [row.id for row in rows] == [connection.id] + + +@pytest.mark.asyncio +async def test_create_rejects_second_connection_with_conflict(session, service) -> None: + await service.create_connection(session, token="bot-token-1", label="First") + + with pytest.raises(RemoteConnectionConflictError): + await service.create_connection(session, token="bot-token-1", label="Second") + + rows = (await session.exec(select(RemoteConnection))).all() + assert len(rows) == 1 + + +@pytest.mark.asyncio +async def test_create_rolls_back_when_vault_save_fails( + session, service, credential_stores +) -> None: + # The store doesn't exist yet — pre-seed it under the id the service + # will generate isn't possible, so instead make every store fail by + # patching the factory's default behavior via a poisoned instance + # returned for any id. + poisoned = FakeCredentialStore() + poisoned.save_error = CredentialStoreError("vault unavailable") + service._credential_store_factory = lambda _connection_id: poisoned + + with pytest.raises(RemoteCredentialError): + await service.create_connection(session, token="bot-token-1", label="Phone") + + assert (await session.exec(select(RemoteConnection))).all() == [] + + +@pytest.mark.asyncio +async def test_create_deletes_vaulted_token_when_commit_fails( + session, service, credential_stores, monkeypatch +) -> None: + async def failing_commit() -> None: + raise RuntimeError("db unavailable") + + monkeypatch.setattr(session, "commit", failing_commit) + + with pytest.raises(RuntimeError): + await service.create_connection(session, token="bot-token-1", label="Phone") + + # Compensating cleanup ran: whichever store got the token had it deleted. + (store,) = credential_stores.values() + assert store.load() is None + assert store.deleted == ["bot-token-1"] + + +# ── update_token ───────────────────────────────────────────────────────────── + + +@pytest.mark.asyncio +async def test_update_token_for_same_bot_retains_pairing( + session, service, credential_stores +) -> None: + connection = await service.create_connection( + session, token="bot-token-1", label="Phone" + ) + pairing = RemotePairing( + connection_id=connection.id, + principal_id="telegram-user-1", + destination_id="telegram-chat-1", + label="My phone", + ) + session.add(pairing) + await session.commit() + + updated = await service.update_token( + session, connection.id, token="bot-token-2-same-bot" + ) + + assert updated.adapter_principal_id == "bot-1" + assert updated.adapter_username == "my_bot_renamed" + assert credential_stores[connection.id].load() == "bot-token-2-same-bot" + + remaining = ( + await session.exec( + select(RemotePairing).where(RemotePairing.connection_id == connection.id) + ) + ).all() + assert [row.id for row in remaining] == [pairing.id] + + +@pytest.mark.asyncio +async def test_update_token_for_different_bot_invalidates_pairing( + session, service +) -> None: + connection = await service.create_connection( + session, token="bot-token-1", label="Phone" + ) + pairing = RemotePairing( + connection_id=connection.id, + principal_id="telegram-user-1", + destination_id="telegram-chat-1", + label="My phone", + ) + session.add(pairing) + await session.commit() + + updated = await service.update_token( + session, connection.id, token="bot-token-3-different-bot" + ) + + assert updated.adapter_principal_id == "bot-2" + assert updated.adapter_username == "another_bot" + + remaining = ( + await session.exec( + select(RemotePairing).where(RemotePairing.connection_id == connection.id) + ) + ).all() + assert remaining == [] + + +@pytest.mark.asyncio +async def test_update_token_unknown_connection_raises_not_found( + session, service +) -> None: + with pytest.raises(RemoteConnectionNotFoundError): + await service.update_token(session, uuid4(), token="bot-token-1") + + +@pytest.mark.asyncio +async def test_update_token_rejects_invalid_replacement_without_mutating_connection( + session, service, credential_stores +) -> None: + connection = await service.create_connection( + session, token="bot-token-1", label="Phone" + ) + + with pytest.raises(RemoteAdapterValidationError): + await service.update_token(session, connection.id, token="garbage") + + refreshed = await service.get(session, connection.id) + assert refreshed.adapter_principal_id == "bot-1" + assert credential_stores[connection.id].load() == "bot-token-1" + + +# ── set_enabled / remove ───────────────────────────────────────────────────── + + +@pytest.mark.asyncio +async def test_set_enabled_toggles_the_connection(session, service) -> None: + connection = await service.create_connection( + session, token="bot-token-1", label="Phone" + ) + assert connection.enabled is False + + enabled = await service.set_enabled(session, connection.id, enabled=True) + assert enabled.enabled is True + + disabled = await service.set_enabled(session, connection.id, enabled=False) + assert disabled.enabled is False + + +@pytest.mark.asyncio +async def test_set_enabled_unknown_connection_raises_not_found( + session, service +) -> None: + with pytest.raises(RemoteConnectionNotFoundError): + await service.set_enabled(session, uuid4(), enabled=True) + + +@pytest.mark.asyncio +async def test_remove_deletes_connection_pairing_and_vault_value( + session, service, credential_stores +) -> None: + connection = await service.create_connection( + session, token="bot-token-1", label="Phone" + ) + pairing = RemotePairing( + connection_id=connection.id, + principal_id="telegram-user-1", + destination_id="telegram-chat-1", + label="My phone", + ) + session.add(pairing) + await session.commit() + + await service.remove(session, connection.id) + + assert (await session.exec(select(RemoteConnection))).all() == [] + assert (await session.exec(select(RemotePairing))).all() == [] + assert credential_stores[connection.id].load() is None + assert credential_stores[connection.id].deleted == ["bot-token-1"] + + +@pytest.mark.asyncio +async def test_remove_unknown_connection_raises_not_found(session, service) -> None: + with pytest.raises(RemoteConnectionNotFoundError): + await service.remove(session, uuid4()) + + +@pytest.mark.asyncio +async def test_remove_reports_vault_deletion_failure( + session, service, credential_stores +) -> None: + connection = await service.create_connection( + session, token="bot-token-1", label="Phone" + ) + credential_stores[connection.id].delete_error = CredentialStoreError( + "vault unavailable" + ) + + with pytest.raises(RemoteCredentialError): + await service.remove(session, connection.id) + + # The database record is still gone even though the vault delete failed. + assert (await session.exec(select(RemoteConnection))).all() == [] + + +# ── list / get ─────────────────────────────────────────────────────────────── + + +@pytest.mark.asyncio +async def test_list_and_get_reflect_persisted_connections(session, service) -> None: + assert await service.list(session) == [] + assert await service.get(session, uuid4()) is None + + connection = await service.create_connection( + session, token="bot-token-1", label="Phone" + ) + + assert [row.id for row in await service.list(session)] == [connection.id] + fetched = await service.get(session, connection.id) + assert fetched is not None + assert fetched.id == connection.id From f213c71f9984959bc124dcd4ee1507621bd23c01 Mon Sep 17 00:00:00 2001 From: manhnguyen24-dev Date: Mon, 14 Sep 2026 14:13:56 +0700 Subject: [PATCH 03/71] fix(remote): delete vault credential before the connection row in remove() MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review finding on Task 2: remove() deleted and committed the DB row before attempting the vault delete, so a vault-delete failure permanently stranded the bot token in the OS credential store with no remaining row naming its account key. Reorders to vault-first, DB-second — the same pattern create_connection/update_token already use — so a vault failure now leaves the row intact (safely retryable) instead of orphaning the secret. Updates test_remove_reports_vault_deletion_failure to assert the row survives a vault-delete failure, and adds a retry-after-recovery test proving remove() can be called again once the vault is reachable. --- app/remote/connection_service.py | 20 ++++++++++++--- tests/remote/test_connection_service.py | 33 +++++++++++++++++++++++-- 2 files changed, 47 insertions(+), 6 deletions(-) diff --git a/app/remote/connection_service.py b/app/remote/connection_service.py index b1fde14c..435fc33b 100644 --- a/app/remote/connection_service.py +++ b/app/remote/connection_service.py @@ -228,22 +228,34 @@ async def set_enabled( return connection async def remove(self, session: AsyncSession, connection_id: UUID) -> None: - """Delete the connection (cascading its pairing) and its vault entry.""" + """Delete the connection's vault entry, then the connection + (cascading its pairing). + + The vault entry is deleted *first*, deliberately mirroring + :meth:`create_connection` and :meth:`update_token`'s vault-before- + commit ordering. A DB row that outlives its vault entry is a safe, + recoverable state — the row still names the connection, so the user + can retry ``remove`` (or ``set_enabled(False)``) and nothing is ever + orphaned. The reverse order would delete the only reference to the + vault account (``connection:``) before confirming the secret was + actually cleared, permanently stranding a live bot token in the OS + vault if the vault delete then failed. + """ connection = await self.get(session, connection_id) if connection is None: raise RemoteConnectionNotFoundError( f"Remote connection {connection_id} does not exist." ) - await session.delete(connection) - await session.commit() - store = self._store(connection_id) try: store.delete() except CredentialStoreError as exc: raise RemoteCredentialError(str(exc)) from exc + await session.delete(connection) + await session.commit() + def _delete_best_effort(store: CredentialStoreProtocol) -> None: try: diff --git a/tests/remote/test_connection_service.py b/tests/remote/test_connection_service.py index 19b9ab39..c928821f 100644 --- a/tests/remote/test_connection_service.py +++ b/tests/remote/test_connection_service.py @@ -343,9 +343,14 @@ async def test_remove_unknown_connection_raises_not_found(session, service) -> N @pytest.mark.asyncio -async def test_remove_reports_vault_deletion_failure( +async def test_remove_reports_vault_deletion_failure_without_orphaning_the_row( session, service, credential_stores ) -> None: + """A vault-delete failure must never delete the connection row first — + that would strand the vault's ``connection:`` secret with no + remaining reference anywhere in the app. The vault is deleted before the + row, so a failure here leaves the row intact and the operation safely + retryable.""" connection = await service.create_connection( session, token="bot-token-1", label="Phone" ) @@ -356,8 +361,32 @@ async def test_remove_reports_vault_deletion_failure( with pytest.raises(RemoteCredentialError): await service.remove(session, connection.id) - # The database record is still gone even though the vault delete failed. + # Not orphaned: the row survives, so the vault account is still named + # and remove() can be retried once the vault is reachable again. + rows = (await session.exec(select(RemoteConnection))).all() + assert [row.id for row in rows] == [connection.id] + + +@pytest.mark.asyncio +async def test_remove_retried_after_vault_recovers_deletes_everything( + session, service, credential_stores +) -> None: + connection = await service.create_connection( + session, token="bot-token-1", label="Phone" + ) + store = credential_stores[connection.id] + store.delete_error = CredentialStoreError("vault unavailable") + + with pytest.raises(RemoteCredentialError): + await service.remove(session, connection.id) + + # The vault recovers (e.g. the OS keychain becomes reachable again) and + # the same remove() call is retried without needing any repair step. + store.delete_error = None + await service.remove(session, connection.id) + assert (await session.exec(select(RemoteConnection))).all() == [] + assert store.load() is None # ── list / get ─────────────────────────────────────────────────────────────── From cf0e71cfcfe507bd33387fdb73f42957b8b2158e Mon Sep 17 00:00:00 2001 From: manhnguyen24-dev Date: Mon, 14 Sep 2026 14:35:52 +0700 Subject: [PATCH 04/71] feat(remote): Task 3 - Telegram Bot API client and adapter lifecycle Adds a Telegram-specific HTTP client (getMe/deleteWebhook/getUpdates/ send_text/edit_text/answer_callback/set_commands) and a TelegramAdapter polling lifecycle, isolated from connection_service.py and Conductor and fully testable against httpx.MockTransport. - Bounded pydantic models for the subset of the Bot API wire format used. - Safe error classes (TelegramApiError/TelegramTransportError/ TelegramMalformedResponseError/TelegramCallbackDataError) that never carry the request URL or bot token, backed by tests sweeping every error path. - Adapter mirrors app/conductor/service.py's start/stop shape: one owner task, an asyncio.Event for interruptible backoff/rate-limit sleeps, and task cancellation to interrupt a genuinely in-flight long poll. - Implements the spec's Telegram error taxonomy: webhook conflict cleared once and retried immediately, concurrent-consumer conflict -> bounded backoff in used_elsewhere, invalid token terminal for the current start(), 429 honors retry_after verbatim, transport/unknown failures -> exponential backoff with jitter, and phone-unreachable delivery failures never affect the inbound poll loop. - Never sets parse_mode; enforces the 1-64 byte callback_data contract before sending; deletes any webhook and drops pending updates before the first getUpdates call. 53 tests in tests/remote/telegram, ruff and ty check clean on the touched files. --- app/remote/telegram/__init__.py | 10 + app/remote/telegram/adapter.py | 486 +++++++++++++++++++ app/remote/telegram/client.py | 303 ++++++++++++ app/remote/telegram/models.py | 134 ++++++ tests/remote/telegram/__init__.py | 0 tests/remote/telegram/test_adapter.py | 657 ++++++++++++++++++++++++++ tests/remote/telegram/test_client.py | 446 +++++++++++++++++ 7 files changed, 2036 insertions(+) create mode 100644 app/remote/telegram/__init__.py create mode 100644 app/remote/telegram/adapter.py create mode 100644 app/remote/telegram/client.py create mode 100644 app/remote/telegram/models.py create mode 100644 tests/remote/telegram/__init__.py create mode 100644 tests/remote/telegram/test_adapter.py create mode 100644 tests/remote/telegram/test_client.py diff --git a/app/remote/telegram/__init__.py b/app/remote/telegram/__init__.py new file mode 100644 index 00000000..74e18d58 --- /dev/null +++ b/app/remote/telegram/__init__.py @@ -0,0 +1,10 @@ +"""Telegram Bot API transport and adapter lifecycle. + +Everything that knows the Telegram wire format — request/response models, +the HTTP client, and the polling adapter — lives in this package. Generic +remote-access code (``app/remote/contracts.py``, a later +``RemoteService``) never imports from here; only this package imports the +provider-neutral types in ``app/remote/contracts.py``. +""" + +from __future__ import annotations diff --git a/app/remote/telegram/adapter.py b/app/remote/telegram/adapter.py new file mode 100644 index 00000000..a9ffa4a1 --- /dev/null +++ b/app/remote/telegram/adapter.py @@ -0,0 +1,486 @@ +"""Telegram adapter lifecycle: long-poll ownership, offset bookkeeping, and +Telegram error-taxonomy -> connection-state translation. + +Modeled on ``app/conductor/service.py``'s ``start``/``stop`` shape (read for +pattern inspiration only — never imported from, never modified): one owner +``asyncio.Task`` runs the poll loop, and an ``asyncio.Event`` makes both the +long poll and any backoff/rate-limit sleep interruptible so ``stop()`` never +waits out the configured poll timeout or a retry delay (AC-13). Genuine +promptness during an in-flight long-poll HTTP call additionally requires +cancelling the task itself (setting an event cannot interrupt an httpx +request that isn't awaiting that event) — again mirroring conductor's +``stop()``. + +This module owns Bot API error classification (AC-12): webhook conflicts are +cleared once and retried immediately; a concurrent ``getUpdates`` consumer is +``used_elsewhere`` with bounded backoff; an invalid/revoked token is terminal +for the current ``start()`` call; ``429`` honors ``retry_after`` verbatim; +transport/5xx failures use exponential backoff with jitter; and an +unreachable paired chat only affects delivery status (``phone_reachable``), +never the inbound poll loop — inbound polling and outbound delivery are +independent failure domains. +""" + +from __future__ import annotations + +import asyncio +import random +from collections import OrderedDict +from collections.abc import Awaitable, Callable, Sequence +from datetime import UTC, datetime +from uuid import UUID + +import httpx +from loguru import logger + +from app.remote.contracts import ( + RemoteAdapterStatus, + RemoteConnectionState, + RemoteErrorClass, + RemoteInboundAction, + RemoteInboundActionKind, + RemoteOutboundMessage, + RemotePrincipal, +) +from app.remote.telegram.client import ( + TelegramApiError, + TelegramClient, + TelegramMalformedResponseError, + TelegramTransportError, +) +from app.remote.telegram.models import TelegramUpdate + +#: Invoked for every classified inbound action (text, callback, or pairing +#: start). The adapter advances its offset past an update only after this +#: awaitable completes without raising — see ``_dispatch``. Its return value +#: is not interpreted by the adapter; a later task (interactive ingress +#: integration) may attach meaning to it. +RemoteActionHandler = Callable[[RemoteInboundAction], Awaitable[object]] + +#: ``jitter(low, high)`` -> a float in that range. Defaults to +#: ``random.uniform``; tests inject a deterministic function. +JitterFn = Callable[[float, float], float] + +#: Injectable clock for ``last_successful_poll_at``. +ClockFn = Callable[[], datetime] + +DEFAULT_POLL_TIMEOUT_SECONDS = 50 +DEFAULT_BACKOFF_BASE_SECONDS = 1.0 +DEFAULT_BACKOFF_MAX_SECONDS = 60.0 +DEFAULT_RATE_LIMIT_FALLBACK_SECONDS = 1 + +#: Bound on how many un-acknowledged callback tokens the adapter remembers +#: (opaque callback token -> raw Telegram callback_query id) so a burst of +#: unanswered callbacks cannot grow this mapping unboundedly. Ephemeral by +#: design, like every other in-memory interaction token (spec: "Remote +#: interaction contract"). +MAX_PENDING_CALLBACK_IDS = 512 + + +def _default_clock() -> datetime: + return datetime.now(UTC) + + +class TelegramAdapter: + """Owns Telegram long-polling lifecycle and Bot API delivery for one + remote connection. + + Constructed from a bot token (never persisted here — the OS vault and + connection record are a different layer's job) and an ``on_action`` + callback that receives every normalized inbound action. + """ + + def __init__( + self, + *, + connection_id: UUID, + token: str, + on_action: RemoteActionHandler, + http_client: httpx.AsyncClient | None = None, + poll_timeout_seconds: int = DEFAULT_POLL_TIMEOUT_SECONDS, + backoff_base_seconds: float = DEFAULT_BACKOFF_BASE_SECONDS, + backoff_max_seconds: float = DEFAULT_BACKOFF_MAX_SECONDS, + jitter: JitterFn = random.uniform, + clock: ClockFn = _default_clock, + ) -> None: + self._connection_id = connection_id + self._client = TelegramClient(token, http_client=http_client) + self._on_action = on_action + self._poll_timeout_seconds = poll_timeout_seconds + self._backoff_base_seconds = backoff_base_seconds + self._backoff_max_seconds = backoff_max_seconds + self._jitter = jitter + self._clock = clock + + self._stop_event = asyncio.Event() + self._task: asyncio.Task[None] | None = None + + self._state = RemoteConnectionState.DISABLED + self._last_error_class = RemoteErrorClass.NONE + self._last_successful_poll_at: datetime | None = None + self._phone_reachable: bool | None = None + + #: correlation_id -> (chat_id, message_id), so ``edit()`` can find + #: the message it was asked to update. Ephemeral by design (spec: + #: "progress-message IDs ... are deliberately ephemeral"). + self._sent_messages: dict[str, tuple[int, int]] = {} + #: opaque callback token -> raw Telegram callback_query id. + self._pending_callback_ids: OrderedDict[str, str] = OrderedDict() + + # ------------------------------------------------------------------ + # Lifecycle + # ------------------------------------------------------------------ + + async def start(self) -> None: + """Start polling. Safe to call repeatedly while already running.""" + if self._task is not None and not self._task.done(): + return + self._stop_event.clear() + self._state = RemoteConnectionState.STARTING + self._task = asyncio.create_task( + self._run(), name=f"telegram-poll-{self._connection_id}" + ) + + async def stop(self) -> None: + """Stop polling promptly and close the HTTP client. Safe to call + repeatedly, including before ``start()`` was ever called. + + Setting the stop event resolves an in-progress backoff/rate-limit + sleep instantly; cancelling the task is additionally required to + interrupt a genuinely in-flight long-poll HTTP call, which is not + awaiting that event. + """ + self._stop_event.set() + task, self._task = self._task, None + if task is not None and task is not asyncio.current_task() and not task.done(): + task.cancel() + await asyncio.gather(task, return_exceptions=True) + await self._client.aclose() + self._state = RemoteConnectionState.DISABLED + + def status(self) -> RemoteAdapterStatus: + """Safe, diagnosable runtime status (AC-34). + + ``phone_unreachable`` is reported as an overlay on top of an + otherwise-healthy ``polling`` state — a delivery failure never + overrides a *worse* poll-loop state (backoff, used_elsewhere, + invalid_token, ...), matching "inbound polling and outbound + delivery are independent failure domains" while still using one + connection-state enum for display. + """ + state = self._state + if state == RemoteConnectionState.POLLING and self._phone_reachable is False: + state = RemoteConnectionState.PHONE_UNREACHABLE + return RemoteAdapterStatus( + connection_id=self._connection_id, + state=state, + last_error_class=self._last_error_class, + last_successful_poll_at=self._last_successful_poll_at, + phone_reachable=self._phone_reachable, + ) + + # ------------------------------------------------------------------ + # Outbound delivery + # ------------------------------------------------------------------ + + async def send(self, message: RemoteOutboundMessage) -> None: + try: + sent = await self._client.send_text( + chat_id=message.destination_id, + text=message.text, + buttons=message.buttons, + ) + except TelegramApiError as exc: + self._record_delivery_failure(exc) + raise + self._record_delivery_success() + if message.correlation_id is not None: + self._sent_messages[message.correlation_id] = (sent.chat.id, sent.message_id) + + async def edit(self, message: RemoteOutboundMessage) -> None: + target = ( + self._sent_messages.get(message.correlation_id) + if message.correlation_id is not None + else None + ) + if target is None: + # Nothing recorded to edit (e.g. after a restart — progress + # message IDs are ephemeral by design). Not this adapter's call + # whether that matters; it simply has nothing to correct. + return + chat_id, message_id = target + try: + await self._client.edit_text( + chat_id=chat_id, + message_id=message_id, + text=message.text, + buttons=message.buttons, + ) + except TelegramApiError as exc: + self._record_delivery_failure(exc) + raise + self._record_delivery_success() + + async def answer_callback(self, callback_token: str) -> None: + raw_id = self._pending_callback_ids.pop(callback_token, None) + if raw_id is None: + # Expired/unknown token (e.g. after a restart) — nothing to + # acknowledge at the transport level. Not an error: the caller + # (a later task) is responsible for telling the user their + # action expired. + return + await self._client.answer_callback(raw_id) + + def _record_delivery_failure(self, exc: TelegramApiError) -> None: + if exc.error_code == 403: + self._phone_reachable = False + self._last_error_class = RemoteErrorClass.PHONE_UNREACHABLE + + def _record_delivery_success(self) -> None: + self._phone_reachable = True + if self._last_error_class == RemoteErrorClass.PHONE_UNREACHABLE: + self._last_error_class = RemoteErrorClass.NONE + + # ------------------------------------------------------------------ + # Poll loop + # ------------------------------------------------------------------ + + async def _run(self) -> None: + try: + if not await self._ensure_webhook_deleted(): + return + self._state = RemoteConnectionState.POLLING + offset: int | None = None + attempt = 0 + while not self._stop_event.is_set(): + try: + updates = await self._client.get_updates( + offset=offset, timeout=self._poll_timeout_seconds + ) + except TelegramApiError as exc: + outcome = await self._handle_get_updates_error(exc, attempt) + if outcome is None: + return + attempt = outcome + continue + except (TelegramTransportError, TelegramMalformedResponseError): + attempt += 1 + self._state = RemoteConnectionState.BACKOFF + self._last_error_class = RemoteErrorClass.TRANSPORT + await self._interruptible_backoff(attempt) + continue + + attempt = 0 + self._state = RemoteConnectionState.POLLING + self._last_error_class = RemoteErrorClass.NONE + self._last_successful_poll_at = self._clock() + offset = await self._dispatch(updates, offset) + except asyncio.CancelledError: + raise + except Exception: + self._state = RemoteConnectionState.ERROR + self._last_error_class = RemoteErrorClass.UNKNOWN + logger.error( + "telegram_adapter_poll_loop_crashed connection_id={}", + self._connection_id, + ) + + async def _ensure_webhook_deleted(self) -> bool: + """AC-11: remove any webhook and drop pending updates once, before + the first ``getUpdates`` call. Retries through transport/unknown-API + failures; an invalid token here is terminal, same as in the main + loop.""" + attempt = 0 + while not self._stop_event.is_set(): + try: + await self._client.delete_webhook(drop_pending_updates=True) + return True + except TelegramApiError as exc: + if exc.error_code == 401: + self._state = RemoteConnectionState.INVALID_TOKEN + self._last_error_class = RemoteErrorClass.INVALID_TOKEN + return False + attempt += 1 + self._state = RemoteConnectionState.BACKOFF + self._last_error_class = RemoteErrorClass.UNKNOWN + await self._interruptible_backoff(attempt) + except (TelegramTransportError, TelegramMalformedResponseError): + attempt += 1 + self._state = RemoteConnectionState.BACKOFF + self._last_error_class = RemoteErrorClass.TRANSPORT + await self._interruptible_backoff(attempt) + return False + + async def _handle_get_updates_error( + self, exc: TelegramApiError, attempt: int + ) -> int | None: + """Returns the next ``attempt`` count, or ``None`` if the caller + should stop polling entirely (invalid token).""" + if exc.error_code == 401: + self._state = RemoteConnectionState.INVALID_TOKEN + self._last_error_class = RemoteErrorClass.INVALID_TOKEN + return None + + if exc.error_code == 409: + description = (exc.description or "").lower() + if "webhook" in description: + # Cleared once, then retried immediately — not a backoff + # state (spec: "Webhook conflict is cleared once"). + try: + await self._client.delete_webhook(drop_pending_updates=True) + except ( + TelegramApiError, + TelegramTransportError, + TelegramMalformedResponseError, + ): + pass + return 0 + # A concurrent getUpdates consumer — bounded backoff, never a + # tight retry loop. + self._state = RemoteConnectionState.USED_ELSEWHERE + self._last_error_class = RemoteErrorClass.USED_ELSEWHERE + new_attempt = attempt + 1 + await self._interruptible_backoff(new_attempt) + return new_attempt + + if exc.error_code == 429: + self._state = RemoteConnectionState.RATE_LIMITED + self._last_error_class = RemoteErrorClass.RATE_LIMITED + retry_after = ( + exc.retry_after + if exc.retry_after is not None + else DEFAULT_RATE_LIMIT_FALLBACK_SECONDS + ) + # Honor Telegram's retry_after verbatim — not our own schedule. + await self._interruptible_sleep(float(retry_after)) + return attempt + + # Unknown API error: generic bounded exponential backoff. + self._state = RemoteConnectionState.BACKOFF + self._last_error_class = RemoteErrorClass.UNKNOWN + new_attempt = attempt + 1 + await self._interruptible_backoff(new_attempt) + return new_attempt + + async def _dispatch( + self, updates: Sequence[TelegramUpdate], offset: int | None + ) -> int | None: + """Process *updates* in update-ID order. Classification is + sequential to preserve offset ordering (spec: "Concurrency, failure, + recovery, and idempotency"). The offset advances past an update only + once it has been safely classified and, for a dispatched action, + once ``on_action`` has completed without raising — a handler failure + stops this batch so the failed update is retried on the next poll + rather than silently skipped.""" + for update in sorted(updates, key=lambda item: item.update_id): + action = self._classify(update) + if action is not None: + try: + await self._on_action(action) + except Exception: + logger.warning( + "telegram_inbound_action_handler_failed " + "connection_id={} update_id={}", + self._connection_id, + update.update_id, + ) + return offset + offset = update.update_id + 1 + return offset + + def _classify(self, update: TelegramUpdate) -> RemoteInboundAction | None: + source_key = f"telegram:{self._connection_id}:{update.update_id}" + + callback_query = update.callback_query + if callback_query is not None: + if not callback_query.data: + return None + self._remember_callback(callback_query.data, callback_query.id) + chat_id = ( + callback_query.message.chat.id + if callback_query.message is not None + else callback_query.from_user.id + ) + principal = RemotePrincipal( + connection_id=self._connection_id, + principal_id=str(callback_query.from_user.id), + destination_id=str(chat_id), + display=( + callback_query.from_user.username + or callback_query.from_user.first_name + or "" + ), + ) + return RemoteInboundAction( + connection_id=self._connection_id, + kind=RemoteInboundActionKind.CALLBACK, + principal=principal, + source_key=source_key, + callback_token=callback_query.data, + ) + + message = update.message + if message is None or message.text is None: + return None # media/service message — unsupported, ignored + if message.chat.type != "private": + return None # group/channel — never addressable + if message.from_user is None or message.from_user.is_bot: + return None # bot-authored or unattributable — ignored + + principal = RemotePrincipal( + connection_id=self._connection_id, + principal_id=str(message.from_user.id), + destination_id=str(message.chat.id), + display=message.from_user.username or message.from_user.first_name or "", + ) + text = message.text + if text == "/start" or text.startswith("/start "): + payload = text[len("/start ") :].strip() if " " in text else "" + return RemoteInboundAction( + connection_id=self._connection_id, + kind=RemoteInboundActionKind.PAIRING_START, + principal=principal, + source_key=source_key, + pairing_token=payload or None, + ) + return RemoteInboundAction( + connection_id=self._connection_id, + kind=RemoteInboundActionKind.TEXT, + principal=principal, + source_key=source_key, + text=text, + ) + + def _remember_callback(self, token: str, raw_callback_query_id: str) -> None: + self._pending_callback_ids[token] = raw_callback_query_id + self._pending_callback_ids.move_to_end(token) + while len(self._pending_callback_ids) > MAX_PENDING_CALLBACK_IDS: + self._pending_callback_ids.popitem(last=False) + + # ------------------------------------------------------------------ + # Interruptible waits + # ------------------------------------------------------------------ + + async def _interruptible_backoff(self, attempt: int) -> None: + cap = min( + self._backoff_max_seconds, + self._backoff_base_seconds * (2 ** (attempt - 1)), + ) + delay = self._jitter(0.0, cap) if cap > 0 else 0.0 + await self._interruptible_sleep(delay) + + async def _interruptible_sleep(self, seconds: float) -> None: + try: + await asyncio.wait_for(self._stop_event.wait(), timeout=max(0.0, seconds)) + except TimeoutError: + pass + + +__all__ = [ + "DEFAULT_BACKOFF_BASE_SECONDS", + "DEFAULT_BACKOFF_MAX_SECONDS", + "DEFAULT_POLL_TIMEOUT_SECONDS", + "MAX_PENDING_CALLBACK_IDS", + "RemoteActionHandler", + "TelegramAdapter", +] diff --git a/app/remote/telegram/client.py b/app/remote/telegram/client.py new file mode 100644 index 00000000..1c3c7793 --- /dev/null +++ b/app/remote/telegram/client.py @@ -0,0 +1,303 @@ +"""Telegram Bot API HTTP client. + +Owns the ``httpx.AsyncClient``, the ``https://api.telegram.org/bot/`` +request shape, and translation of Bot API responses into safe internal +types. No exception this module raises — and no log line a caller should +ever write from one — includes the request URL, because the URL embeds the +bot token as a path segment. Every error carries only Telegram's +``error_code``/``description`` (already token-free — the token lives in the +URL, never the body) or the *type name* of a transport failure. +""" + +from __future__ import annotations + +from collections.abc import Sequence +from typing import Any, TypeVar + +import httpx +from pydantic import TypeAdapter, ValidationError + +from app.remote.contracts import RemoteButton +from app.remote.telegram.models import ( + TelegramMessage, + TelegramResponse, + TelegramUpdate, + TelegramUser, +) + +TELEGRAM_API_BASE = "https://api.telegram.org" + +#: Telegram's inclusive byte-length contract for one button's callback_data. +CALLBACK_DATA_MIN_BYTES = 1 +CALLBACK_DATA_MAX_BYTES = 64 + +#: Only these update kinds are ever requested (spec: "Telegram update +#: contract") — no edited messages, channel posts, or other update kinds. +ALLOWED_UPDATE_KINDS: tuple[str, ...] = ("message", "callback_query") + +#: Extra seconds of HTTP read-timeout headroom over the server-side +#: long-poll `timeout` so the client never times out before Telegram does. +_LONG_POLL_TIMEOUT_MARGIN_SECONDS = 10.0 +_DEFAULT_TIMEOUT_SECONDS = 30.0 + +T = TypeVar("T") + + +class TelegramClientError(Exception): + """Base class for every error this client raises. + + Never carries the request URL (which embeds the bot token) or the bot + token itself. + """ + + +class TelegramApiError(TelegramClientError): + """The Bot API responded with ``ok: false``. + + Carries only Telegram's own ``error_code``/``description`` (safe — the + token lives in the URL, never the response body) and any ``retry_after`` + Telegram supplied in ``parameters``. Adapter-level code classifies this + into the spec's error taxonomy (webhook conflict, used-elsewhere, + invalid token, rate limit, ...). + """ + + def __init__( + self, + *, + error_code: int | None, + description: str | None, + retry_after: int | None = None, + ) -> None: + self.error_code = error_code + self.description = description or "" + self.retry_after = retry_after + message = "Telegram API error" + if error_code is not None: + message += f" {error_code}" + if self.description: + message += f": {self.description}" + super().__init__(message) + + +class TelegramTransportError(TelegramClientError): + """A network-level failure talking to the Bot API. + + Carries only the underlying exception's type name — never the + exception's own message, which for some httpx errors includes the + request URL. + """ + + def __init__(self, *, cause_type: str) -> None: + self.cause_type = cause_type + super().__init__(f"Telegram request failed ({cause_type}).") + + +class TelegramMalformedResponseError(TelegramClientError): + """The Bot API response body was not valid JSON, or did not match the + expected envelope shape. Never echoes the raw response body, which + could (in principle) reflect request content back.""" + + +class TelegramCallbackDataError(TelegramClientError, ValueError): + """A ``callback_data`` payload violates Telegram's 1-64 byte contract. + + Raised before any request is sent, so a caller never has to distinguish + "rejected locally" from "rejected by Telegram after the fact". + """ + + +def _validate_callback_data(token: str) -> None: + size = len(token.encode("utf-8")) + if not (CALLBACK_DATA_MIN_BYTES <= size <= CALLBACK_DATA_MAX_BYTES): + raise TelegramCallbackDataError( + "callback_data must be " + f"{CALLBACK_DATA_MIN_BYTES}-{CALLBACK_DATA_MAX_BYTES} bytes; got {size}." + ) + + +def _build_reply_markup(buttons: Sequence[RemoteButton]) -> dict[str, Any] | None: + if not buttons: + return None + for button in buttons: + _validate_callback_data(button.token) + return { + "inline_keyboard": [ + [{"text": button.text, "callback_data": button.token}] for button in buttons + ] + } + + +class TelegramClient: + """Thin, provider-specific translation over the Telegram Bot API. + + Constructed from a bot token; an ``httpx.AsyncClient`` can be injected + (tests use ``httpx.MockTransport``) or is otherwise created and owned — + and closed — by this client. + """ + + def __init__(self, token: str, *, http_client: httpx.AsyncClient | None = None) -> None: + if not token: + raise ValueError("A Telegram bot token is required.") + self._token = token + self._owns_http = http_client is None + self._http = http_client or httpx.AsyncClient( + timeout=httpx.Timeout(_DEFAULT_TIMEOUT_SECONDS) + ) + + async def aclose(self) -> None: + if self._owns_http: + await self._http.aclose() + + def _url(self, method: str) -> str: + return f"{TELEGRAM_API_BASE}/bot{self._token}/{method}" + + async def _call( + self, + method: str, + payload: dict[str, Any], + *, + result_model: type[T], + timeout: float | None = None, + ) -> T: + try: + response = await self._http.post( + self._url(method), + json=payload, + timeout=( + httpx.Timeout(timeout) if timeout is not None else httpx.USE_CLIENT_DEFAULT + ), + ) + except httpx.HTTPError as exc: + raise TelegramTransportError(cause_type=type(exc).__name__) from None + + try: + body = response.json() + except ValueError: + raise TelegramMalformedResponseError( + f"Telegram {method} response was not valid JSON." + ) from None + + # Validated generically first (``Any`` is a real type expression, so + # this subscript is fine for a static checker); the payload-specific + # shape is validated separately below via ``TypeAdapter``, which + # takes a plain runtime value rather than a static subscript. + try: + envelope = TelegramResponse[Any].model_validate(body) + except ValidationError: + raise TelegramMalformedResponseError( + f"Telegram {method} response did not match the expected shape." + ) from None + + if not envelope.ok: + retry_after = envelope.parameters.retry_after if envelope.parameters else None + raise TelegramApiError( + error_code=envelope.error_code, + description=envelope.description, + retry_after=retry_after, + ) + + if envelope.result is None: + raise TelegramMalformedResponseError( + f"Telegram {method} response had no result." + ) + try: + return TypeAdapter(result_model).validate_python(envelope.result) + except ValidationError: + raise TelegramMalformedResponseError( + f"Telegram {method} response did not match the expected shape." + ) from None + + # -- Bot API methods -------------------------------------------------- + + async def get_me(self) -> TelegramUser: + return await self._call("getMe", {}, result_model=TelegramUser) + + async def delete_webhook(self, *, drop_pending_updates: bool = True) -> None: + await self._call( + "deleteWebhook", + {"drop_pending_updates": drop_pending_updates}, + result_model=bool, + ) + + async def get_updates( + self, + *, + offset: int | None, + timeout: int, + allowed_updates: Sequence[str] = ALLOWED_UPDATE_KINDS, + ) -> list[TelegramUpdate]: + payload: dict[str, Any] = { + "timeout": timeout, + "allowed_updates": list(allowed_updates), + } + if offset is not None: + payload["offset"] = offset + return await self._call( + "getUpdates", + payload, + result_model=list[TelegramUpdate], + timeout=float(timeout) + _LONG_POLL_TIMEOUT_MARGIN_SECONDS, + ) + + async def send_text( + self, + *, + chat_id: str | int, + text: str, + buttons: Sequence[RemoteButton] = (), + ) -> TelegramMessage: + # No parse_mode, ever (AC-24): model/agent text must never be + # interpreted as Telegram markup. + markup = _build_reply_markup(buttons) + payload: dict[str, Any] = {"chat_id": chat_id, "text": text} + if markup is not None: + payload["reply_markup"] = markup + return await self._call("sendMessage", payload, result_model=TelegramMessage) + + async def edit_text( + self, + *, + chat_id: str | int, + message_id: int, + text: str, + buttons: Sequence[RemoteButton] = (), + ) -> TelegramMessage: + markup = _build_reply_markup(buttons) + payload: dict[str, Any] = { + "chat_id": chat_id, + "message_id": message_id, + "text": text, + } + if markup is not None: + payload["reply_markup"] = markup + return await self._call("editMessageText", payload, result_model=TelegramMessage) + + async def answer_callback( + self, callback_query_id: str, *, text: str | None = None + ) -> None: + payload: dict[str, Any] = {"callback_query_id": callback_query_id} + if text is not None: + payload["text"] = text + await self._call("answerCallbackQuery", payload, result_model=bool) + + async def set_commands(self, commands: Sequence[tuple[str, str]]) -> None: + payload = { + "commands": [ + {"command": command, "description": description} + for command, description in commands + ] + } + await self._call("setMyCommands", payload, result_model=bool) + + +__all__ = [ + "ALLOWED_UPDATE_KINDS", + "CALLBACK_DATA_MAX_BYTES", + "CALLBACK_DATA_MIN_BYTES", + "TelegramApiError", + "TelegramCallbackDataError", + "TelegramClient", + "TelegramClientError", + "TelegramMalformedResponseError", + "TelegramTransportError", +] diff --git a/app/remote/telegram/models.py b/app/remote/telegram/models.py new file mode 100644 index 00000000..7710bb08 --- /dev/null +++ b/app/remote/telegram/models.py @@ -0,0 +1,134 @@ +"""Bounded pydantic models for the subset of the Telegram Bot API wire +format this adapter uses. + +Every model ignores unknown fields (``extra="ignore"``) because Telegram's +API is additive and this adapter only ever reads a handful of fields from a +much larger payload. Nothing here is imported outside ``app/remote/telegram/``. +""" + +from __future__ import annotations + +from typing import Generic, TypeVar + +from pydantic import BaseModel, ConfigDict, Field + +T = TypeVar("T") + + +class TelegramUser(BaseModel): + """https://core.telegram.org/bots/api#user""" + + model_config = ConfigDict(extra="ignore") + + id: int + is_bot: bool = False + username: str | None = None + first_name: str | None = None + + +class TelegramChat(BaseModel): + """https://core.telegram.org/bots/api#chat""" + + model_config = ConfigDict(extra="ignore") + + id: int + type: str + + +class TelegramMessage(BaseModel): + """https://core.telegram.org/bots/api#message + + Only the fields this adapter reads or needs to echo back (to address an + edit) are modeled. Media, entities, and formatting fields are + deliberately absent: this adapter never sends or interprets them. + """ + + model_config = ConfigDict(extra="ignore", populate_by_name=True) + + message_id: int + date: int + chat: TelegramChat + from_user: TelegramUser | None = Field(default=None, alias="from") + text: str | None = None + + +class TelegramCallbackQuery(BaseModel): + """https://core.telegram.org/bots/api#callbackquery""" + + model_config = ConfigDict(extra="ignore", populate_by_name=True) + + id: str + from_user: TelegramUser = Field(alias="from") + message: TelegramMessage | None = None + data: str | None = None + + +class TelegramUpdate(BaseModel): + """https://core.telegram.org/bots/api#update + + Only ``message`` and ``callback_query`` are modeled because the adapter + requests ``allowed_updates=["message", "callback_query"]`` and Telegram + never delivers any other update kind once that filter is set. + """ + + model_config = ConfigDict(extra="ignore") + + update_id: int + message: TelegramMessage | None = None + callback_query: TelegramCallbackQuery | None = None + + +class TelegramInlineKeyboardButton(BaseModel): + """https://core.telegram.org/bots/api#inlinekeyboardbutton + + ``callback_data`` is always an opaque, connection-owned capability token + minted by the (later) remote service — never a raw session ID, path, or + command (spec: "Remote interaction contract"). + """ + + model_config = ConfigDict(extra="ignore") + + text: str + callback_data: str + + +class TelegramInlineKeyboardMarkup(BaseModel): + """https://core.telegram.org/bots/api#inlinekeyboardmarkup""" + + model_config = ConfigDict(extra="ignore") + + inline_keyboard: list[list[TelegramInlineKeyboardButton]] + + +class TelegramResponseParameters(BaseModel): + """https://core.telegram.org/bots/api#responseparameters""" + + model_config = ConfigDict(extra="ignore") + + retry_after: int | None = None + migrate_to_chat_id: int | None = None + + +class TelegramResponse(BaseModel, Generic[T]): + """The envelope every Bot API method response is wrapped in.""" + + model_config = ConfigDict(extra="ignore") + + ok: bool + result: T | None = None + error_code: int | None = None + description: str | None = None + parameters: TelegramResponseParameters | None = None + + +__all__ = [ + "TelegramCallbackQuery", + "TelegramChat", + "TelegramInlineKeyboardButton", + "TelegramInlineKeyboardMarkup", + "TelegramMessage", + "TelegramResponse", + "TelegramResponseParameters", + "TelegramUpdate", + "TelegramUser", +] diff --git a/tests/remote/telegram/__init__.py b/tests/remote/telegram/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/tests/remote/telegram/test_adapter.py b/tests/remote/telegram/test_adapter.py new file mode 100644 index 00000000..7b75639e --- /dev/null +++ b/tests/remote/telegram/test_adapter.py @@ -0,0 +1,657 @@ +"""Tests for app/remote/telegram/adapter.py — poll lifecycle, Telegram error +taxonomy -> connection-state translation, and normalized inbound delivery. + +``ScriptedTransport`` is a small in-process fake Bot API: it queues one +response (or exception) per method name and records every call, so tests +can script conflict/rate-limit/transport sequences and assert on offsets, +state, and timing without any real network or real sleeping. +""" + +from __future__ import annotations + +import asyncio +import json +import time +from uuid import uuid4 + +import httpx +import pytest + +from app.remote.contracts import ( + RemoteConnectionState, + RemoteErrorClass, + RemoteInboundActionKind, + RemoteOutboundMessage, +) +from app.remote.telegram.adapter import TelegramAdapter + +TOKEN = "123456:AAFakeTokenValueThatMustNeverAppearInLogs" + + +def _ok(result) -> httpx.Response: + return httpx.Response(200, json={"ok": True, "result": result}) + + +def _err(status: int, error_code: int, description: str, *, retry_after: int | None = None): + body: dict[str, object] = {"ok": False, "error_code": error_code, "description": description} + if retry_after is not None: + body["parameters"] = {"retry_after": retry_after} + return httpx.Response(status, json=body) + + +class ScriptedTransport: + """Queues responses/exceptions per Bot API method name. + + ``queue(method, *items)`` appends; each call to that method pops the + next item (a response is returned, an exception instance is raised). + Once a method's queue is empty, a default response is served forever + (empty ``getUpdates``, ``ok: true`` for everything else) so a test only + needs to script the calls it cares about. + """ + + def __init__(self) -> None: + self.responses: dict[str, list[object]] = {} + self._forever: dict[str, object] = {} + self.calls: list[tuple[str, dict]] = [] + + def queue(self, method: str, *items: object) -> None: + self.responses.setdefault(method, []).extend(items) + + def fail_forever(self, method: str, item: object) -> None: + """Always serve *item* for *method* once its one-shot queue (if any) + is drained — for tests that must observe a state persisting across + a wall-clock window without racing a scripted recovery.""" + self._forever[method] = item + + async def handler(self, request: httpx.Request) -> httpx.Response: + method = request.url.path.rsplit("/", 1)[-1] + payload = json.loads(request.content) if request.content else {} + self.calls.append((method, payload)) + pending = self.responses.get(method) + if pending: + item = pending.pop(0) + if isinstance(item, Exception): + raise item + return item + forever = self._forever.get(method) + if forever is not None: + if isinstance(forever, Exception): + raise forever + return forever + if method == "getUpdates": + # Real Telegram blocks for up to `timeout` seconds before + # returning an empty result, which naturally throttles the poll + # loop. A mock transport resolves instantly, so without a small + # real yield here a scripted-empty poll loop would spin as a + # tight, non-yielding busy loop and starve the event loop + # (including the test's own `asyncio.sleep` deadlines). + await asyncio.sleep(0.01) + return _ok([]) + return _ok(True) + + def call_count(self, method: str) -> int: + return sum(1 for name, _ in self.calls if name == method) + + +def _make_adapter( + transport: ScriptedTransport, + *, + on_action=None, + backoff_base_seconds: float = 0.01, + backoff_max_seconds: float = 0.05, + jitter=lambda lo, hi: hi, + **kwargs, +) -> TelegramAdapter: + http_client = httpx.AsyncClient(transport=httpx.MockTransport(transport.handler)) + calls: list[object] = [] + + async def default_on_action(action): + calls.append(action) + return None + + adapter = TelegramAdapter( + connection_id=uuid4(), + token=TOKEN, + on_action=on_action or default_on_action, + http_client=http_client, + backoff_base_seconds=backoff_base_seconds, + backoff_max_seconds=backoff_max_seconds, + jitter=jitter, + **kwargs, + ) + adapter.received = calls # type: ignore[attr-defined] + return adapter + + +async def _run_briefly(adapter: TelegramAdapter, seconds: float = 0.1) -> None: + await adapter.start() + await asyncio.sleep(seconds) + await adapter.stop() + + +# --------------------------------------------------------------------------- +# Startup sequence (AC-11) +# --------------------------------------------------------------------------- + + +class TestStartupSequence: + @pytest.mark.asyncio + async def test_deletes_webhook_with_drop_pending_updates_before_first_poll(self): + transport = ScriptedTransport() + adapter = _make_adapter(transport) + await _run_briefly(adapter) + + method_order = [name for name, _ in transport.calls] + assert "deleteWebhook" in method_order + assert method_order.index("deleteWebhook") < method_order.index("getUpdates") + _, payload = next(c for c in transport.calls if c[0] == "deleteWebhook") + assert payload["drop_pending_updates"] is True + + @pytest.mark.asyncio + async def test_requests_only_message_and_callback_query_updates(self): + transport = ScriptedTransport() + adapter = _make_adapter(transport) + await _run_briefly(adapter) + + _, payload = next(c for c in transport.calls if c[0] == "getUpdates") + assert payload["allowed_updates"] == ["message", "callback_query"] + + +# --------------------------------------------------------------------------- +# Update classification, ordering, and offset advancement +# --------------------------------------------------------------------------- + + +def _text_update(update_id: int, *, chat_id: int = 100, user_id: int = 200, text: str = "hi"): + return { + "update_id": update_id, + "message": { + "message_id": update_id, + "date": 1, + "chat": {"id": chat_id, "type": "private"}, + "from": {"id": user_id, "is_bot": False, "username": "alice"}, + "text": text, + }, + } + + +class TestClassificationAndOffsets: + @pytest.mark.asyncio + async def test_out_of_order_updates_are_processed_in_update_id_order(self): + transport = ScriptedTransport() + transport.queue( + "getUpdates", + _ok([_text_update(2, text="second"), _text_update(1, text="first")]), + ) + adapter = _make_adapter(transport) + await _run_briefly(adapter) + + assert [action.text for action in adapter.received] == ["first", "second"] + + @pytest.mark.asyncio + async def test_accepted_offsets_advance_the_next_getupdates_call(self): + transport = ScriptedTransport() + transport.queue("getUpdates", _ok([_text_update(5)])) + adapter = _make_adapter(transport) + await _run_briefly(adapter) + + get_updates_payloads = [p for name, p in transport.calls if name == "getUpdates"] + assert "offset" not in get_updates_payloads[0] + assert get_updates_payloads[1]["offset"] == 6 + + @pytest.mark.asyncio + async def test_handler_failure_does_not_advance_past_the_failed_update(self): + transport = ScriptedTransport() + transport.queue("getUpdates", _ok([_text_update(9)])) + + async def failing_on_action(action): + raise RuntimeError("boom") + + adapter = _make_adapter(transport, on_action=failing_on_action) + await _run_briefly(adapter) + + get_updates_payloads = [p for name, p in transport.calls if name == "getUpdates"] + # Second call must not have advanced past update 9 — it stays + # unacknowledged so it is safely redelivered. + assert "offset" not in get_updates_payloads[1] + + @pytest.mark.asyncio + async def test_private_text_message_classified_as_text_action(self): + transport = ScriptedTransport() + transport.queue("getUpdates", _ok([_text_update(1, text="hello there")])) + adapter = _make_adapter(transport) + await _run_briefly(adapter) + + (action,) = adapter.received + assert action.kind == RemoteInboundActionKind.TEXT + assert action.text == "hello there" + assert action.principal.principal_id == "200" + assert action.principal.destination_id == "100" + assert action.source_key.endswith(":1") + + @pytest.mark.asyncio + async def test_start_command_with_payload_classified_as_pairing_start(self): + transport = ScriptedTransport() + transport.queue("getUpdates", _ok([_text_update(1, text="/start abc123token")])) + adapter = _make_adapter(transport) + await _run_briefly(adapter) + + (action,) = adapter.received + assert action.kind == RemoteInboundActionKind.PAIRING_START + assert action.pairing_token == "abc123token" + + @pytest.mark.asyncio + async def test_bare_start_command_classified_as_pairing_start_with_no_token(self): + transport = ScriptedTransport() + transport.queue("getUpdates", _ok([_text_update(1, text="/start")])) + adapter = _make_adapter(transport) + await _run_briefly(adapter) + + (action,) = adapter.received + assert action.kind == RemoteInboundActionKind.PAIRING_START + assert action.pairing_token is None + + @pytest.mark.asyncio + async def test_group_chat_message_is_ignored(self): + transport = ScriptedTransport() + update = _text_update(1) + update["message"]["chat"]["type"] = "group" + transport.queue("getUpdates", _ok([update])) + adapter = _make_adapter(transport) + await _run_briefly(adapter) + + assert adapter.received == [] + + @pytest.mark.asyncio + async def test_bot_authored_message_is_ignored(self): + transport = ScriptedTransport() + update = _text_update(1) + update["message"]["from"]["is_bot"] = True + transport.queue("getUpdates", _ok([update])) + adapter = _make_adapter(transport) + await _run_briefly(adapter) + + assert adapter.received == [] + + @pytest.mark.asyncio + async def test_media_only_message_with_no_text_is_ignored(self): + transport = ScriptedTransport() + update = _text_update(1) + update["message"]["text"] = None + transport.queue("getUpdates", _ok([update])) + adapter = _make_adapter(transport) + await _run_briefly(adapter) + + assert adapter.received == [] + + @pytest.mark.asyncio + async def test_callback_query_classified_with_opaque_token(self): + transport = ScriptedTransport() + transport.queue( + "getUpdates", + _ok( + [ + { + "update_id": 1, + "callback_query": { + "id": "raw-cbq-id-1", + "from": {"id": 200, "is_bot": False, "username": "alice"}, + "message": { + "message_id": 42, + "date": 1, + "chat": {"id": 100, "type": "private"}, + }, + "data": "opaque-token-1", + }, + } + ] + ), + ) + adapter = _make_adapter(transport) + await _run_briefly(adapter) + + (action,) = adapter.received + assert action.kind == RemoteInboundActionKind.CALLBACK + assert action.callback_token == "opaque-token-1" + assert action.principal.destination_id == "100" + + @pytest.mark.asyncio + async def test_callback_query_without_data_is_ignored(self): + transport = ScriptedTransport() + transport.queue( + "getUpdates", + _ok( + [ + { + "update_id": 1, + "callback_query": { + "id": "raw-cbq-id-1", + "from": {"id": 200, "is_bot": False}, + "data": None, + }, + } + ] + ), + ) + adapter = _make_adapter(transport) + await _run_briefly(adapter) + assert adapter.received == [] + + +# --------------------------------------------------------------------------- +# answer_callback: opaque token -> raw callback_query id +# --------------------------------------------------------------------------- + + +class TestAnswerCallback: + @pytest.mark.asyncio + async def test_answer_callback_resolves_opaque_token_to_raw_callback_id(self): + transport = ScriptedTransport() + transport.queue( + "getUpdates", + _ok( + [ + { + "update_id": 1, + "callback_query": { + "id": "raw-cbq-id-42", + "from": {"id": 200, "is_bot": False}, + "message": { + "message_id": 1, + "date": 1, + "chat": {"id": 100, "type": "private"}, + }, + "data": "opaque-token-42", + }, + } + ] + ), + ) + adapter = _make_adapter(transport) + await adapter.start() + await asyncio.sleep(0.1) + await adapter.answer_callback("opaque-token-42") + await adapter.stop() + + _, payload = next(c for c in transport.calls if c[0] == "answerCallbackQuery") + assert payload["callback_query_id"] == "raw-cbq-id-42" + + @pytest.mark.asyncio + async def test_answer_callback_for_unknown_token_is_a_safe_noop(self): + transport = ScriptedTransport() + adapter = _make_adapter(transport) + await adapter.answer_callback("never-seen-token") # must not raise + assert transport.call_count("answerCallbackQuery") == 0 + + +# --------------------------------------------------------------------------- +# Telegram error taxonomy -> connection state (AC-12) +# --------------------------------------------------------------------------- + + +class TestErrorTaxonomy: + @pytest.mark.asyncio + async def test_webhook_conflict_is_cleared_once_and_retried_immediately(self): + transport = ScriptedTransport() + transport.queue( + "getUpdates", + _err(409, 409, "Conflict: can't use getUpdates method while webhook is active"), + ) + adapter = _make_adapter(transport) + start = time.monotonic() + await _run_briefly(adapter, seconds=0.1) + elapsed = time.monotonic() - start + + # Cleared once: deleteWebhook is called again (startup + recovery). + assert transport.call_count("deleteWebhook") >= 2 + # Not a backoff state: recovers to polling promptly. + assert elapsed < 1.0 + + @pytest.mark.asyncio + async def test_used_elsewhere_conflict_sets_state_and_backs_off(self): + transport = ScriptedTransport() + transport.fail_forever( + "getUpdates", + _err( + 409, + 409, + "Conflict: terminated by other getUpdates request; make sure " + "only one bot instance is running", + ), + ) + adapter = _make_adapter(transport, backoff_max_seconds=0.02) + + await adapter.start() + await asyncio.sleep(0.05) + status = adapter.status() + await adapter.stop() + + assert status.state == RemoteConnectionState.USED_ELSEWHERE + assert status.last_error_class == RemoteErrorClass.USED_ELSEWHERE + + @pytest.mark.asyncio + async def test_invalid_token_stops_polling_permanently_for_this_start(self): + transport = ScriptedTransport() + transport.queue("getUpdates", _err(401, 401, "Unauthorized")) + adapter = _make_adapter(transport) + + await adapter.start() + await asyncio.sleep(0.1) + status = adapter.status() + calls_after_first_wait = transport.call_count("getUpdates") + await asyncio.sleep(0.1) + calls_after_second_wait = transport.call_count("getUpdates") + await adapter.stop() + + assert status.state == RemoteConnectionState.INVALID_TOKEN + assert status.last_error_class == RemoteErrorClass.INVALID_TOKEN + # Terminal: no further getUpdates attempts, ever, for this start(). + assert calls_after_first_wait == calls_after_second_wait == 1 + + @pytest.mark.asyncio + async def test_rate_limit_honors_retry_after_verbatim(self): + transport = ScriptedTransport() + transport.fail_forever( + "getUpdates", _err(429, 429, "Too Many Requests", retry_after=7) + ) + adapter = _make_adapter(transport) + + sleeps: list[float] = [] + + async def spy(seconds: float) -> None: + sleeps.append(seconds) + # Yield control without a real delay so the loop can retry + # (still forever-429) without the test waiting out real seconds. + await asyncio.sleep(0) + + adapter._interruptible_sleep = spy # type: ignore[method-assign] + + await adapter.start() + await asyncio.sleep(0.05) + status = adapter.status() + await adapter.stop() + + assert status.state == RemoteConnectionState.RATE_LIMITED + assert sleeps and all(seconds == 7.0 for seconds in sleeps) + + @pytest.mark.asyncio + async def test_transport_failure_backs_off(self): + transport = ScriptedTransport() + transport.fail_forever("getUpdates", httpx.ConnectError("boom")) + adapter = _make_adapter(transport) + + await adapter.start() + await asyncio.sleep(0.05) + status = adapter.status() + await adapter.stop() + + assert status.state == RemoteConnectionState.BACKOFF + assert status.last_error_class == RemoteErrorClass.TRANSPORT + + @pytest.mark.asyncio + async def test_successful_poll_after_backoff_recovers_to_polling(self): + transport = ScriptedTransport() + transport.queue("getUpdates", httpx.ConnectError("boom")) + adapter = _make_adapter(transport) + + await adapter.start() + await asyncio.sleep(0.15) + status = adapter.status() + await adapter.stop() + + assert status.state == RemoteConnectionState.POLLING + assert status.last_error_class == RemoteErrorClass.NONE + assert status.last_successful_poll_at is not None + + +# --------------------------------------------------------------------------- +# Delivery: phone_unreachable is independent of inbound polling (AC-12) +# --------------------------------------------------------------------------- + + +class TestDeliveryIndependentOfPolling: + @pytest.mark.asyncio + async def test_send_failure_sets_phone_unreachable_without_crashing_poll_loop(self): + transport = ScriptedTransport() + transport.queue( + "sendMessage", _err(403, 403, "Forbidden: bot was blocked by the user") + ) + adapter = _make_adapter(transport) + + await adapter.start() + await asyncio.sleep(0.05) + + from app.remote.telegram.client import TelegramApiError + + with pytest.raises(TelegramApiError): + await adapter.send( + RemoteOutboundMessage( + connection_id=uuid4(), destination_id="100", text="hi" + ) + ) + + status = adapter.status() + await adapter.stop() + + assert status.phone_reachable is False + assert status.last_error_class == RemoteErrorClass.PHONE_UNREACHABLE + # Inbound polling is unaffected — still healthy. + assert status.state == RemoteConnectionState.PHONE_UNREACHABLE + + @pytest.mark.asyncio + async def test_successful_send_marks_phone_reachable(self): + transport = ScriptedTransport() + transport.queue( + "sendMessage", + _ok({"message_id": 1, "date": 1, "chat": {"id": 100, "type": "private"}}), + ) + adapter = _make_adapter(transport) + await adapter.start() + await asyncio.sleep(0.02) + + await adapter.send( + RemoteOutboundMessage(connection_id=uuid4(), destination_id="100", text="hi") + ) + status = adapter.status() + await adapter.stop() + + assert status.phone_reachable is True + assert status.state == RemoteConnectionState.POLLING + + +# --------------------------------------------------------------------------- +# Prompt shutdown (AC-13) +# --------------------------------------------------------------------------- + + +class TestPromptShutdown: + @pytest.mark.asyncio + async def test_stop_interrupts_backoff_promptly(self): + transport = ScriptedTransport() + transport.queue("getUpdates", httpx.ConnectError("boom")) + adapter = _make_adapter( + transport, backoff_base_seconds=30.0, backoff_max_seconds=30.0 + ) + + await adapter.start() + await asyncio.sleep(0.05) # let it enter the (real) 30s backoff sleep + + start = time.monotonic() + await adapter.stop() + elapsed = time.monotonic() - start + + assert elapsed < 2.0 + + @pytest.mark.asyncio + async def test_stop_interrupts_an_in_flight_long_poll_promptly(self): + transport = ScriptedTransport() + + async def slow_get_updates(request: httpx.Request) -> httpx.Response: + method = request.url.path.rsplit("/", 1)[-1] + transport.calls.append((method, {})) + if method == "getUpdates": + await asyncio.sleep(100) # never resolves within test time + return _ok(True) + + http_client = httpx.AsyncClient(transport=httpx.MockTransport(slow_get_updates)) + adapter = TelegramAdapter( + connection_id=uuid4(), + token=TOKEN, + on_action=lambda action: _noop(), + http_client=http_client, + ) + + await adapter.start() + await asyncio.sleep(0.05) # let it enter the in-flight getUpdates call + + start = time.monotonic() + await adapter.stop() + elapsed = time.monotonic() - start + + assert elapsed < 2.0 + + @pytest.mark.asyncio + async def test_duplicate_start_is_a_noop(self): + transport = ScriptedTransport() + adapter = _make_adapter(transport) + await adapter.start() + first_task = adapter._task + await adapter.start() + assert adapter._task is first_task + await adapter.stop() + + @pytest.mark.asyncio + async def test_duplicate_stop_is_safe(self): + transport = ScriptedTransport() + adapter = _make_adapter(transport) + await adapter.start() + await asyncio.sleep(0.02) + await adapter.stop() + await adapter.stop() # must not raise + + @pytest.mark.asyncio + async def test_stop_before_start_is_safe(self): + transport = ScriptedTransport() + adapter = _make_adapter(transport) + await adapter.stop() # must not raise + + +async def _noop() -> None: + return None + + +# --------------------------------------------------------------------------- +# status() never leaks provider payloads or the token +# --------------------------------------------------------------------------- + + +class TestStatusIsSafe: + @pytest.mark.asyncio + async def test_status_never_contains_the_token(self): + transport = ScriptedTransport() + transport.queue("getUpdates", _err(401, 401, "Unauthorized")) + adapter = _make_adapter(transport) + await _run_briefly(adapter) + status = adapter.status() + assert TOKEN not in repr(status) + assert TOKEN not in str(status) diff --git a/tests/remote/telegram/test_client.py b/tests/remote/telegram/test_client.py new file mode 100644 index 00000000..e4a6bdda --- /dev/null +++ b/tests/remote/telegram/test_client.py @@ -0,0 +1,446 @@ +"""Tests for app/remote/telegram/client.py — Bot API translation and safe +error classification. + +Uses ``httpx.MockTransport`` (the established pattern in this repo, see +``tests/agent/providers/codex/test_oauth.py``) so every test runs against a +fake transport instead of the network. The bot token is embedded in every +request URL by Telegram's own wire shape +(``https://api.telegram.org/bot/``); several tests exist +purely to prove that URL — and the token inside it — never leaks into an +exception message. +""" + +from __future__ import annotations + +import httpx +import pytest + +from app.remote.contracts import RemoteButton +from app.remote.telegram.client import ( + TelegramApiError, + TelegramCallbackDataError, + TelegramClient, + TelegramMalformedResponseError, + TelegramTransportError, +) +from app.remote.telegram.models import TelegramMessage, TelegramUpdate, TelegramUser + +TOKEN = "123456:AAFakeTokenValueThatMustNeverAppearInLogs" + + +def _client(handler) -> TelegramClient: + transport = httpx.MockTransport(handler) + http_client = httpx.AsyncClient(transport=transport) + return TelegramClient(TOKEN, http_client=http_client) + + +def _ok(result) -> httpx.Response: + return httpx.Response(200, json={"ok": True, "result": result}) + + +def _err(status: int, error_code: int, description: str, *, retry_after: int | None = None) -> httpx.Response: + body: dict[str, object] = {"ok": False, "error_code": error_code, "description": description} + if retry_after is not None: + body["parameters"] = {"retry_after": retry_after} + return httpx.Response(status, json=body) + + +# --------------------------------------------------------------------------- +# Successful calls +# --------------------------------------------------------------------------- + + +class TestGetMe: + @pytest.mark.asyncio + async def test_returns_bot_identity(self): + def handler(request: httpx.Request) -> httpx.Response: + assert request.url.path.endswith("/getMe") + return _ok({"id": 42, "is_bot": True, "username": "my_bot"}) + + client = _client(handler) + user = await client.get_me() + assert isinstance(user, TelegramUser) + assert user.id == 42 + assert user.username == "my_bot" + await client.aclose() + + +class TestDeleteWebhook: + @pytest.mark.asyncio + async def test_sends_drop_pending_updates_true_by_default(self): + captured: dict[str, object] = {} + + def handler(request: httpx.Request) -> httpx.Response: + captured["body"] = request.content + return _ok(True) + + client = _client(handler) + await client.delete_webhook() + assert b'"drop_pending_updates": true' in captured["body"] or ( + b'"drop_pending_updates":true' in captured["body"] + ) + await client.aclose() + + @pytest.mark.asyncio + async def test_can_send_drop_pending_updates_false(self): + captured: dict[str, object] = {} + + def handler(request: httpx.Request) -> httpx.Response: + captured["body"] = request.content + return _ok(True) + + client = _client(handler) + await client.delete_webhook(drop_pending_updates=False) + assert b"false" in captured["body"] + await client.aclose() + + +class TestGetUpdates: + @pytest.mark.asyncio + async def test_requests_only_message_and_callback_query(self): + captured: dict[str, object] = {} + + def handler(request: httpx.Request) -> httpx.Response: + import json + + captured["payload"] = json.loads(request.content) + return _ok([]) + + client = _client(handler) + await client.get_updates(offset=None, timeout=50) + assert captured["payload"]["allowed_updates"] == ["message", "callback_query"] + await client.aclose() + + @pytest.mark.asyncio + async def test_passes_offset_and_timeout(self): + captured: dict[str, object] = {} + + def handler(request: httpx.Request) -> httpx.Response: + import json + + captured["payload"] = json.loads(request.content) + return _ok([]) + + client = _client(handler) + await client.get_updates(offset=99, timeout=5) + assert captured["payload"]["offset"] == 99 + assert captured["payload"]["timeout"] == 5 + await client.aclose() + + @pytest.mark.asyncio + async def test_omits_offset_when_none(self): + captured: dict[str, object] = {} + + def handler(request: httpx.Request) -> httpx.Response: + import json + + captured["payload"] = json.loads(request.content) + return _ok([]) + + client = _client(handler) + await client.get_updates(offset=None, timeout=5) + assert "offset" not in captured["payload"] + await client.aclose() + + @pytest.mark.asyncio + async def test_parses_updates_in_response_order(self): + def handler(request: httpx.Request) -> httpx.Response: + return _ok( + [ + { + "update_id": 1, + "message": { + "message_id": 10, + "date": 1, + "chat": {"id": 555, "type": "private"}, + "from": {"id": 777, "is_bot": False}, + "text": "hello", + }, + }, + {"update_id": 2, "message": None}, + ] + ) + + client = _client(handler) + updates = await client.get_updates(offset=None, timeout=1) + assert [u.update_id for u in updates] == [1, 2] + assert isinstance(updates[0], TelegramUpdate) + assert updates[0].message.text == "hello" + assert updates[0].message.chat.id == 555 + assert updates[0].message.from_user.id == 777 + await client.aclose() + + +class TestSendEditAnswer: + @pytest.mark.asyncio + async def test_send_text_never_includes_parse_mode(self): + captured: dict[str, object] = {} + + def handler(request: httpx.Request) -> httpx.Response: + import json + + captured["payload"] = json.loads(request.content) + return _ok( + { + "message_id": 5, + "date": 1, + "chat": {"id": 1, "type": "private"}, + } + ) + + client = _client(handler) + message = await client.send_text(chat_id=1, text="hello world") + assert "parse_mode" not in captured["payload"] + assert captured["payload"]["text"] == "hello world" + assert isinstance(message, TelegramMessage) + assert message.message_id == 5 + await client.aclose() + + @pytest.mark.asyncio + async def test_send_text_with_buttons_builds_inline_keyboard(self): + captured: dict[str, object] = {} + + def handler(request: httpx.Request) -> httpx.Response: + import json + + captured["payload"] = json.loads(request.content) + return _ok({"message_id": 6, "date": 1, "chat": {"id": 1, "type": "private"}}) + + client = _client(handler) + await client.send_text( + chat_id=1, + text="Approve?", + buttons=[RemoteButton(text="Allow", token="tok-1"), RemoteButton(text="Deny", token="tok-2")], + ) + markup = captured["payload"]["reply_markup"] + assert markup["inline_keyboard"] == [ + [{"text": "Allow", "callback_data": "tok-1"}], + [{"text": "Deny", "callback_data": "tok-2"}], + ] + await client.aclose() + + @pytest.mark.asyncio + async def test_send_text_rejects_callback_data_over_64_bytes_before_sending(self): + called = False + + def handler(request: httpx.Request) -> httpx.Response: + nonlocal called + called = True + return _ok({}) + + client = _client(handler) + with pytest.raises(TelegramCallbackDataError): + await client.send_text( + chat_id=1, + text="hi", + buttons=[RemoteButton(text="x", token="a" * 65)], + ) + assert called is False + await client.aclose() + + @pytest.mark.asyncio + async def test_send_text_rejects_empty_callback_data_before_sending(self): + def handler(request: httpx.Request) -> httpx.Response: + return _ok({}) + + client = _client(handler) + with pytest.raises(TelegramCallbackDataError): + await client.send_text( + chat_id=1, text="hi", buttons=[RemoteButton(text="x", token="")] + ) + await client.aclose() + + @pytest.mark.asyncio + async def test_send_text_accepts_exactly_64_byte_callback_data(self): + def handler(request: httpx.Request) -> httpx.Response: + return _ok({"message_id": 1, "date": 1, "chat": {"id": 1, "type": "private"}}) + + client = _client(handler) + await client.send_text( + chat_id=1, text="hi", buttons=[RemoteButton(text="x", token="a" * 64)] + ) + await client.aclose() + + @pytest.mark.asyncio + async def test_edit_text_targets_chat_and_message_id(self): + captured: dict[str, object] = {} + + def handler(request: httpx.Request) -> httpx.Response: + import json + + captured["payload"] = json.loads(request.content) + assert request.url.path.endswith("/editMessageText") + return _ok({"message_id": 5, "date": 1, "chat": {"id": 1, "type": "private"}}) + + client = _client(handler) + await client.edit_text(chat_id=1, message_id=5, text="updated") + assert captured["payload"]["chat_id"] == 1 + assert captured["payload"]["message_id"] == 5 + assert captured["payload"]["text"] == "updated" + assert "parse_mode" not in captured["payload"] + await client.aclose() + + @pytest.mark.asyncio + async def test_answer_callback_posts_callback_query_id(self): + captured: dict[str, object] = {} + + def handler(request: httpx.Request) -> httpx.Response: + import json + + captured["payload"] = json.loads(request.content) + assert request.url.path.endswith("/answerCallbackQuery") + return _ok(True) + + client = _client(handler) + await client.answer_callback("cbq-1") + assert captured["payload"]["callback_query_id"] == "cbq-1" + assert "text" not in captured["payload"] + await client.aclose() + + @pytest.mark.asyncio + async def test_set_commands_sends_command_description_pairs(self): + captured: dict[str, object] = {} + + def handler(request: httpx.Request) -> httpx.Response: + import json + + captured["payload"] = json.loads(request.content) + assert request.url.path.endswith("/setMyCommands") + return _ok(True) + + client = _client(handler) + await client.set_commands([("start", "Start"), ("help", "Help")]) + assert captured["payload"]["commands"] == [ + {"command": "start", "description": "Start"}, + {"command": "help", "description": "Help"}, + ] + await client.aclose() + + +# --------------------------------------------------------------------------- +# Safe error classification +# --------------------------------------------------------------------------- + + +class TestApiErrors: + @pytest.mark.asyncio + async def test_invalid_token_401(self): + def handler(request: httpx.Request) -> httpx.Response: + return _err(401, 401, "Unauthorized") + + client = _client(handler) + with pytest.raises(TelegramApiError) as excinfo: + await client.get_me() + assert excinfo.value.error_code == 401 + assert TOKEN not in str(excinfo.value) + await client.aclose() + + @pytest.mark.asyncio + async def test_conflict_409_webhook_active(self): + def handler(request: httpx.Request) -> httpx.Response: + return _err(409, 409, "Conflict: can't use getUpdates method while webhook is active") + + client = _client(handler) + with pytest.raises(TelegramApiError) as excinfo: + await client.get_updates(offset=None, timeout=1) + assert excinfo.value.error_code == 409 + assert "webhook" in excinfo.value.description.lower() + assert TOKEN not in str(excinfo.value) + await client.aclose() + + @pytest.mark.asyncio + async def test_conflict_409_used_elsewhere(self): + def handler(request: httpx.Request) -> httpx.Response: + return _err( + 409, + 409, + "Conflict: terminated by other getUpdates request; make sure that only one bot instance is running", + ) + + client = _client(handler) + with pytest.raises(TelegramApiError) as excinfo: + await client.get_updates(offset=None, timeout=1) + assert excinfo.value.error_code == 409 + assert TOKEN not in str(excinfo.value) + await client.aclose() + + @pytest.mark.asyncio + async def test_rate_limited_429_carries_retry_after(self): + def handler(request: httpx.Request) -> httpx.Response: + return _err(429, 429, "Too Many Requests: retry later", retry_after=17) + + client = _client(handler) + with pytest.raises(TelegramApiError) as excinfo: + await client.get_updates(offset=None, timeout=1) + assert excinfo.value.retry_after == 17 + assert TOKEN not in str(excinfo.value) + await client.aclose() + + @pytest.mark.asyncio + async def test_chat_unreachable_403(self): + def handler(request: httpx.Request) -> httpx.Response: + return _err(403, 403, "Forbidden: bot was blocked by the user") + + client = _client(handler) + with pytest.raises(TelegramApiError) as excinfo: + await client.send_text(chat_id=1, text="hi") + assert excinfo.value.error_code == 403 + assert TOKEN not in str(excinfo.value) + await client.aclose() + + @pytest.mark.asyncio + async def test_malformed_json_response(self): + def handler(request: httpx.Request) -> httpx.Response: + return httpx.Response(200, content=b"not json at all") + + client = _client(handler) + with pytest.raises(TelegramMalformedResponseError) as excinfo: + await client.get_me() + assert TOKEN not in str(excinfo.value) + await client.aclose() + + @pytest.mark.asyncio + async def test_malformed_shape_response(self): + def handler(request: httpx.Request) -> httpx.Response: + # Valid JSON, but missing the required "ok" field entirely. + return httpx.Response(200, json={"surprise": True}) + + client = _client(handler) + with pytest.raises(TelegramMalformedResponseError) as excinfo: + await client.get_me() + assert TOKEN not in str(excinfo.value) + await client.aclose() + + @pytest.mark.asyncio + async def test_transport_failure_never_leaks_url(self): + def handler(request: httpx.Request) -> httpx.Response: + raise httpx.ConnectError("boom", request=request) + + client = _client(handler) + with pytest.raises(TelegramTransportError) as excinfo: + await client.get_me() + assert TOKEN not in str(excinfo.value) + assert "api.telegram.org" not in str(excinfo.value) + await client.aclose() + + @pytest.mark.asyncio + async def test_no_exception_message_ever_contains_the_bot_token(self): + # Belt-and-suspenders sweep across every error path this client + # defines — the token must never leak, regardless of failure mode. + scenarios = [ + _err(401, 401, "Unauthorized"), + _err(409, 409, "Conflict: webhook is active"), + _err(429, 429, "Too Many Requests", retry_after=3), + _err(403, 403, "Forbidden: bot was blocked by the user"), + ] + for response in scenarios: + + def handler(request: httpx.Request, _response=response) -> httpx.Response: + return _response + + client = _client(handler) + with pytest.raises(TelegramApiError) as excinfo: + await client.get_me() + assert TOKEN not in str(excinfo.value) + assert "api.telegram.org" not in str(excinfo.value) + await client.aclose() From 946384886b2761d31240a875446ce9328c153cda Mon Sep 17 00:00:00 2001 From: manhnguyen24-dev Date: Mon, 14 Sep 2026 14:43:10 +0700 Subject: [PATCH 05/71] fix(remote): answer_callback records delivery failure like send/edit Code review found that TelegramAdapter.answer_callback called the client with no try/except, while send/edit both catch TelegramApiError and call _record_delivery_failure. The spec's taxonomy groups all three surfaces under one phone-unreachable delivery-status requirement, independent of poll-loop health, so answer_callback now matches send/edit: it records delivery failure/success around the underlying call and re-raises on failure, same as the other two. Adds two adapter tests parallel to the existing send-failure/send-success coverage, proving an unreachable-chat 403 on answerCallbackQuery sets phone_reachable/last_error_class without touching poll-loop state, and a successful answer marks phone_reachable again. --- app/remote/telegram/adapter.py | 7 ++- tests/remote/telegram/test_adapter.py | 81 +++++++++++++++++++++++++++ 2 files changed, 87 insertions(+), 1 deletion(-) diff --git a/app/remote/telegram/adapter.py b/app/remote/telegram/adapter.py index a9ffa4a1..c1eedd98 100644 --- a/app/remote/telegram/adapter.py +++ b/app/remote/telegram/adapter.py @@ -229,7 +229,12 @@ async def answer_callback(self, callback_token: str) -> None: # (a later task) is responsible for telling the user their # action expired. return - await self._client.answer_callback(raw_id) + try: + await self._client.answer_callback(raw_id) + except TelegramApiError as exc: + self._record_delivery_failure(exc) + raise + self._record_delivery_success() def _record_delivery_failure(self, exc: TelegramApiError) -> None: if exc.error_code == 403: diff --git a/tests/remote/telegram/test_adapter.py b/tests/remote/telegram/test_adapter.py index 7b75639e..a5653c39 100644 --- a/tests/remote/telegram/test_adapter.py +++ b/tests/remote/telegram/test_adapter.py @@ -558,6 +558,87 @@ async def test_successful_send_marks_phone_reachable(self): assert status.phone_reachable is True assert status.state == RemoteConnectionState.POLLING + @pytest.mark.asyncio + async def test_answer_callback_failure_sets_phone_unreachable_without_crashing_poll_loop( + self, + ): + transport = ScriptedTransport() + transport.queue( + "getUpdates", + _ok( + [ + { + "update_id": 1, + "callback_query": { + "id": "raw-cbq-id-99", + "from": {"id": 200, "is_bot": False}, + "message": { + "message_id": 1, + "date": 1, + "chat": {"id": 100, "type": "private"}, + }, + "data": "opaque-token-99", + }, + } + ] + ), + ) + transport.queue( + "answerCallbackQuery", + _err(403, 403, "Forbidden: bot was blocked by the user"), + ) + adapter = _make_adapter(transport) + + await adapter.start() + await asyncio.sleep(0.05) # let the poll loop classify the callback + + from app.remote.telegram.client import TelegramApiError + + with pytest.raises(TelegramApiError): + await adapter.answer_callback("opaque-token-99") + + status = adapter.status() + await adapter.stop() + + assert status.phone_reachable is False + assert status.last_error_class == RemoteErrorClass.PHONE_UNREACHABLE + # Inbound polling is unaffected — still healthy. + assert status.state == RemoteConnectionState.PHONE_UNREACHABLE + + @pytest.mark.asyncio + async def test_successful_answer_callback_marks_phone_reachable(self): + transport = ScriptedTransport() + transport.queue( + "getUpdates", + _ok( + [ + { + "update_id": 1, + "callback_query": { + "id": "raw-cbq-id-100", + "from": {"id": 200, "is_bot": False}, + "message": { + "message_id": 1, + "date": 1, + "chat": {"id": 100, "type": "private"}, + }, + "data": "opaque-token-100", + }, + } + ] + ), + ) + adapter = _make_adapter(transport) + await adapter.start() + await asyncio.sleep(0.05) + + await adapter.answer_callback("opaque-token-100") + status = adapter.status() + await adapter.stop() + + assert status.phone_reachable is True + assert status.state == RemoteConnectionState.POLLING + # --------------------------------------------------------------------------- # Prompt shutdown (AC-13) From 1a0d5f7965794712b9b1c1f12db9efd065681e44 Mon Sep 17 00:00:00 2001 From: manhnguyen24-dev Date: Mon, 14 Sep 2026 14:50:52 +0700 Subject: [PATCH 06/71] feat(remote): Task 4 - one-tap pairing and principal authorization Add PairingService (app/remote/pairing.py): issues single-use pairing tokens (secrets.token_urlsafe(16), 128 bits, 22 chars, Telegram-safe [A-Za-z0-9_-] alphabet, ten-minute monotonic expiry, in-memory only), binds a RemotePrincipal to a RemotePairing row only once token validity, private-chat-ness, non-bot-sender, connection match, and the one- pairing-per-connection limit all pass, and authorizes/deauthorizes inbound principals with no caching lag after unpair (AC-7..AC-10). Design choice: issue_link stays a pure in-memory operation with no DB access; the one-pairing-per-connection limit is enforced in consume() instead, so re-pairing requires an explicit unpair first (matching the spec's separate Connect phone / Unpair phone actions). Every consume() failure returns the identical None and burns the token only on success, so a legitimate retry (e.g. group chat -> private chat) still works. Rate limiting reuses the sliding-window algorithm already proven in app/services/webbridge_pairing_service.py, replicated as a small private helper to avoid a cross-feature import for a generic utility. --- app/remote/pairing.py | 335 ++++++++++++++++++++++ tests/remote/test_pairing.py | 522 +++++++++++++++++++++++++++++++++++ 2 files changed, 857 insertions(+) create mode 100644 app/remote/pairing.py create mode 100644 tests/remote/test_pairing.py diff --git a/app/remote/pairing.py b/app/remote/pairing.py new file mode 100644 index 00000000..13df4925 --- /dev/null +++ b/app/remote/pairing.py @@ -0,0 +1,335 @@ +"""One-tap pairing and principal authorization (AC-7, AC-8, AC-9, AC-10). + +``PairingService`` is the transport-neutral home for: + +- minting the single-use pairing token behind **Connect phone**'s QR code + and ``https://t.me/?start=`` deep link (AC-7); +- binding a channel-attested principal/destination to a connection once + every check passes, and only then (AC-8); +- silencing every failure behind one indistinguishable refusal shape, with + per-principal and connection-wide rate limiting so a flood of bad + attempts cannot be used as a response/spam amplifier (AC-9); +- authorizing subsequent inbound actions against the live pairing row, with + no caching lag after ``unpair`` (AC-10). + +Nothing here imports a Telegram payload type — a later task's adapter +translates a raw update into a :class:`~app.remote.contracts.RemotePrincipal` +and booleans (``is_private_chat``, ``is_bot_sender``) before calling +``consume``. + +Design choice — one pairing per connection (v1 product limit) +---------------------------------------------------------------- +The spec's UI exposes **Connect phone** and a separate **Unpair phone** +action, and states "The UI can mint a replacement [token] without changing +the connection or bot token" for a lost/expired token. Read together, that +implies ``issue_link`` should stay a cheap, always-available, in-memory +operation — it never touches the database and never needs to know whether a +pairing already exists. The one-pairing-per-connection limit is instead +enforced at the single point a :class:`~app.models.remote.RemotePairing` row +would actually be written: :meth:`PairingService.consume`. If a connection +already has an active pairing, ``consume`` refuses — using the exact same +refusal shape as every other failure — rather than silently replacing it. +Re-pairing therefore requires an explicit ``unpair`` first, matching the +UI's two distinct actions. + +Token custody +------------- +A pairing token is generated with ``secrets.token_urlsafe(16)`` (128 bits of +entropy, a strict subset of Telegram's ``[A-Za-z0-9_-]`` ``start``-parameter +alphabet, 22 characters — comfortably under the 64-character limit). It +lives only in an in-process dict guarded by a lock, with a ten-minute +monotonic expiry, and is removed the instant it is either successfully +consumed or found expired/invalid. It is never written to the database and +never logged. +""" + +from __future__ import annotations + +import secrets +import threading +import time +from collections import deque +from dataclasses import dataclass +from datetime import datetime, timedelta, timezone +from uuid import UUID + +from sqlmodel import select +from sqlmodel.ext.asyncio.session import AsyncSession + +from app.models.remote import RemoteConnection, RemotePairing +from app.remote.contracts import RemotePrincipal + +__all__ = [ + "DEFAULT_CONNECTION_RATE_LIMIT", + "DEFAULT_PER_PRINCIPAL_RATE_LIMIT", + "DEFAULT_RATE_LIMIT_WINDOW_SECONDS", + "PAIRING_TOKEN_TTL_SECONDS", + "PairingLink", + "PairingService", +] + +#: AC-7: the pairing token expires after ten minutes. +PAIRING_TOKEN_TTL_SECONDS = 600.0 + +#: AC-9 defaults: generous enough for a legitimate retry (e.g. a corrected +#: private-chat attempt) but bounded so pairing attempts cannot be used as a +#: response/spam amplifier. Callers may override per-instance. +DEFAULT_RATE_LIMIT_WINDOW_SECONDS = 60.0 +DEFAULT_PER_PRINCIPAL_RATE_LIMIT = 5 +DEFAULT_CONNECTION_RATE_LIMIT = 20 + +_MAX_LABEL_LENGTH = 120 + + +@dataclass(frozen=True) +class PairingLink: + """Returned by :meth:`PairingService.issue_link`. + + ``url`` is the fully-formed deep link + (``https://t.me/?start=``). ``qr_payload`` is what + the UI should encode into the QR code; for a Telegram deep link that is + the identical URL, since scanning it must resolve to the same Start + action as tapping **Open Telegram**. ``expires_at`` is a wall-clock UTC + timestamp for display only — the token's actual liveness check uses an + internal monotonic clock. + """ + + url: str + qr_payload: str + expires_at: datetime + + +class _SlidingWindowRateLimiter: + """Per-key sliding-window limiter. + + Same algorithm as + ``app.services.webbridge_pairing_service.WebBridgeRateLimiter``, kept as + a small private copy here rather than imported: it is a generic, + self-contained utility with no WebBridge-specific concept in it, and + keeping it inside ``app/remote`` avoids a cross-feature dependency on an + unrelated module for a dozen lines of logic. + """ + + def __init__(self, *, window_seconds: float) -> None: + if window_seconds <= 0: + raise ValueError("window_seconds must be positive") + self._window_seconds = window_seconds + self._events: dict[str, deque[float]] = {} + self._lock = threading.Lock() + + def allow(self, key: str, limit: int, *, now: float | None = None) -> bool: + timestamp = time.monotonic() if now is None else now + cutoff = timestamp - self._window_seconds + with self._lock: + events = self._events.setdefault(key, deque()) + while events and events[0] <= cutoff: + events.popleft() + if len(events) >= limit: + return False + events.append(timestamp) + return True + + +@dataclass +class _PendingToken: + connection_id: UUID + expires_at: float # monotonic seconds + + +class PairingService: + """Issues one-tap pairing links and authorizes paired principals.""" + + def __init__( + self, + *, + token_ttl_seconds: float = PAIRING_TOKEN_TTL_SECONDS, + per_principal_rate_limit: int = DEFAULT_PER_PRINCIPAL_RATE_LIMIT, + connection_rate_limit: int = DEFAULT_CONNECTION_RATE_LIMIT, + rate_limit_window_seconds: float = DEFAULT_RATE_LIMIT_WINDOW_SECONDS, + ) -> None: + if token_ttl_seconds <= 0: + raise ValueError("token_ttl_seconds must be positive") + self._token_ttl_seconds = token_ttl_seconds + self._per_principal_rate_limit = per_principal_rate_limit + self._connection_rate_limit = connection_rate_limit + self._tokens: dict[str, _PendingToken] = {} + self._tokens_lock = threading.Lock() + self._rate_limiter = _SlidingWindowRateLimiter( + window_seconds=rate_limit_window_seconds + ) + + # ── issue_link ─────────────────────────────────────────────────────── + + def issue_link( + self, connection: RemoteConnection, *, now: float | None = None + ) -> PairingLink: + """Mint a single-use pairing token and return its deep link. + + Pure in-memory operation (no database access): it can always be + called to produce a fresh link, including as a replacement for a + lost or expired token, without any connection-state check. See the + module docstring for why the one-pairing-per-connection limit is + enforced in :meth:`consume` instead. + """ + issued_at = time.monotonic() if now is None else now + token = secrets.token_urlsafe(16) + with self._tokens_lock: + self._tokens[token] = _PendingToken( + connection_id=connection.id, + expires_at=issued_at + self._token_ttl_seconds, + ) + url = f"https://t.me/{connection.adapter_username}?start={token}" + expires_at = datetime.now(timezone.utc) + timedelta( + seconds=self._token_ttl_seconds + ) + return PairingLink(url=url, qr_payload=url, expires_at=expires_at) + + # ── consume ────────────────────────────────────────────────────────── + + async def consume( + self, + session: AsyncSession, + token: str, + principal: RemotePrincipal, + *, + is_private_chat: bool, + is_bot_sender: bool, + now: float | None = None, + ) -> RemotePairing | None: + """Attempt to bind *principal* using *token*. + + Returns the persisted :class:`~app.models.remote.RemotePairing` on + success, or ``None`` on any failure: an invalid, expired, or + already-used token; a token issued for a different connection; a + non-private chat; a bot-authored sender; a connection that already + has an active pairing; or a rate limit. Every failure path returns + the identical ``None`` and writes nothing — a caller cannot infer + *why* an attempt failed from the return value alone (AC-8, AC-9). + + A rejected attempt never consumes the token — only a *successful* + bind does — so a legitimate retry from a corrected context (for + example a private chat after a group-chat attempt) can still + succeed before the token's real expiry. + """ + timestamp = time.monotonic() if now is None else now + + if not self._rate_limiter.allow( + f"pairing:principal:{principal.principal_id}", + self._per_principal_rate_limit, + now=timestamp, + ): + return None + if not self._rate_limiter.allow( + f"pairing:connection:{principal.connection_id}", + self._connection_rate_limit, + now=timestamp, + ): + return None + + with self._tokens_lock: + pending = self._tokens.get(token) + if pending is None or pending.expires_at <= timestamp: + return None + if pending.connection_id != principal.connection_id: + return None + if not is_private_chat or is_bot_sender: + return None + + existing = ( + await session.exec( + select(RemotePairing).where( + RemotePairing.connection_id == principal.connection_id + ) + ) + ).first() + if existing is not None: + return None + + # Every check passed: burn the token now, then persist the binding. + with self._tokens_lock: + self._tokens.pop(token, None) + + display = principal.display[:_MAX_LABEL_LENGTH] + pairing = RemotePairing( + connection_id=principal.connection_id, + principal_id=principal.principal_id, + destination_id=principal.destination_id, + label=display or "Paired device", + display=display, + ) + session.add(pairing) + await session.commit() + await session.refresh(pairing) + return pairing + + # ── authorize ──────────────────────────────────────────────────────── + + async def authorize( + self, + session: AsyncSession, + *, + connection_id: UUID, + principal_id: str, + now: float | None = None, + ) -> RemotePairing | None: + """Authorize an inbound action for *principal_id* on *connection_id*. + + Reads the pairing row fresh from the database on every call — there + is no cache to go stale, so a pairing deleted by :meth:`unpair` is + unauthorized on the very next call (AC-10). Also rate-limited, + per-principal and connection-wide (AC-9), returning ``None`` (the + same refusal as "no such pairing") when the limit is exceeded. + """ + timestamp = time.monotonic() if now is None else now + if not self._rate_limiter.allow( + f"authorize:principal:{principal_id}", + self._per_principal_rate_limit, + now=timestamp, + ): + return None + if not self._rate_limiter.allow( + f"authorize:connection:{connection_id}", + self._connection_rate_limit, + now=timestamp, + ): + return None + + pairing = ( + await session.exec( + select(RemotePairing).where( + RemotePairing.connection_id == connection_id, + RemotePairing.principal_id == principal_id, + ) + ) + ).first() + if pairing is None: + return None + pairing.last_seen_at = datetime.now(timezone.utc) + session.add(pairing) + await session.commit() + await session.refresh(pairing) + return pairing + + # ── unpair ─────────────────────────────────────────────────────────── + + async def unpair(self, session: AsyncSession, connection_id: UUID) -> bool: + """Delete *connection_id*'s pairing row(s), if any (AC-10). + + The delete is committed before returning, so a subsequent + :meth:`authorize` call for the former principal fails immediately — + there is no in-memory cache to invalidate. Returns ``True`` if a row + was deleted. + """ + rows = ( + await session.exec( + select(RemotePairing).where( + RemotePairing.connection_id == connection_id + ) + ) + ).all() + if not rows: + return False + for row in rows: + await session.delete(row) + await session.commit() + return True diff --git a/tests/remote/test_pairing.py b/tests/remote/test_pairing.py new file mode 100644 index 00000000..64abab9a --- /dev/null +++ b/tests/remote/test_pairing.py @@ -0,0 +1,522 @@ +"""Tests for app/remote/pairing.py. + +Exercises AC-7 (token custody), AC-8 (pairing authorization), AC-9 (silence +and rate limits), and AC-10 (immediate revocation) without ever touching a +real Telegram transport. ``is_private_chat``/``is_bot_sender`` stand in for +what a later task's Telegram adapter would classify from a raw update. +""" + +from __future__ import annotations + +import re +from urllib.parse import parse_qs, urlparse +from uuid import uuid4 + +import pytest +import pytest_asyncio +from sqlmodel import select + +import app.core.db as db_module +from app.models.remote import RemoteConnection, RemotePairing +from app.remote.contracts import RemotePrincipal +from app.remote.pairing import PairingLink, PairingService + +TOKEN_PATTERN = re.compile(r"[A-Za-z0-9_-]{22,64}") + + +def _extract_token(link: PairingLink) -> str: + return parse_qs(urlparse(link.url).query)["start"][0] + + +@pytest_asyncio.fixture +async def session(): + async with db_module.async_session_factory() as db_session: + yield db_session + + +@pytest_asyncio.fixture +async def connection(session) -> RemoteConnection: + row = RemoteConnection( + adapter="telegram", + label="My phone", + enabled=True, + adapter_principal_id="bot-1", + adapter_username="my_evoflux_bot", + ) + session.add(row) + await session.commit() + await session.refresh(row) + return row + + +@pytest_asyncio.fixture +async def other_connection(session) -> RemoteConnection: + row = RemoteConnection( + adapter="telegram", + label="Other install", + enabled=True, + adapter_principal_id="bot-2", + adapter_username="other_bot", + ) + session.add(row) + await session.commit() + await session.refresh(row) + return row + + +@pytest.fixture +def service() -> PairingService: + return PairingService() + + +def _principal(connection_id, *, principal_id="tg-user-1", destination_id="tg-chat-1", display="Alice") -> RemotePrincipal: + return RemotePrincipal( + connection_id=connection_id, + principal_id=principal_id, + destination_id=destination_id, + display=display, + ) + + +# ── issue_link (AC-7) ──────────────────────────────────────────────────── + + +def test_issue_link_token_is_url_safe_bounded_and_matches_username( + service, connection +) -> None: + link = service.issue_link(connection) + + assert link.url == f"https://t.me/my_evoflux_bot?start={_extract_token(link)}" + assert link.qr_payload == link.url + + token = _extract_token(link) + assert TOKEN_PATTERN.fullmatch(token) + assert len(token) <= 64 + # secrets.token_urlsafe(16) => 128 bits of entropy, 22 chars. + assert len(token) >= 22 + + +@pytest.mark.asyncio +async def test_issue_link_never_touches_the_database(service, connection, session) -> None: + service.issue_link(connection) + + rows = (await session.exec(select(RemotePairing))).all() + assert rows == [] + + +@pytest.mark.asyncio +async def test_issued_token_is_single_use(service, connection, session) -> None: + link = service.issue_link(connection) + token = _extract_token(link) + principal = _principal(connection.id) + + pairing = await service.consume( + session, token, principal, is_private_chat=True, is_bot_sender=False + ) + assert pairing is not None + + second = await service.consume( + session, token, principal, is_private_chat=True, is_bot_sender=False + ) + assert second is None + + +# ── consume: success path (AC-8) ───────────────────────────────────────── + + +@pytest.mark.asyncio +async def test_consume_persists_principal_and_destination_separately( + service, connection, session +) -> None: + link = service.issue_link(connection) + token = _extract_token(link) + principal = _principal( + connection.id, + principal_id="tg-user-42", + destination_id="tg-chat-99", + display="Bob", + ) + + pairing = await service.consume( + session, token, principal, is_private_chat=True, is_bot_sender=False + ) + + assert pairing is not None + assert pairing.principal_id == "tg-user-42" + assert pairing.destination_id == "tg-chat-99" + assert pairing.principal_id != pairing.destination_id + assert pairing.connection_id == connection.id + + rows = (await session.exec(select(RemotePairing))).all() + assert [row.id for row in rows] == [pairing.id] + + +# ── consume: expiry (AC-7) ──────────────────────────────────────────────── + + +@pytest.mark.asyncio +async def test_consume_rejects_expired_token(service, connection, session) -> None: + link = service.issue_link(connection, now=1_000.0) + token = _extract_token(link) + principal = _principal(connection.id) + + result = await service.consume( + session, + token, + principal, + is_private_chat=True, + is_bot_sender=False, + now=1_000.0 + 600.0 + 1.0, # just past the ten-minute expiry + ) + + assert result is None + + +@pytest.mark.asyncio +async def test_consume_accepts_token_right_before_expiry( + service, connection, session +) -> None: + link = service.issue_link(connection, now=1_000.0) + token = _extract_token(link) + principal = _principal(connection.id) + + result = await service.consume( + session, + token, + principal, + is_private_chat=True, + is_bot_sender=False, + now=1_000.0 + 599.0, + ) + + assert result is not None + + +# ── consume: silence and refusal shape (AC-9) ──────────────────────────── + + +@pytest.mark.asyncio +async def test_consume_unknown_token_is_refused_silently( + service, connection, session +) -> None: + principal = _principal(connection.id) + result = await service.consume( + session, "not-a-real-token", principal, is_private_chat=True, is_bot_sender=False + ) + assert result is None + + +@pytest.mark.asyncio +async def test_consume_rejects_group_chat_without_burning_token( + service, connection, session +) -> None: + link = service.issue_link(connection) + token = _extract_token(link) + principal = _principal(connection.id) + + group_attempt = await service.consume( + session, token, principal, is_private_chat=False, is_bot_sender=False + ) + assert group_attempt is None + + # A legitimate retry from a private chat still succeeds with the same + # token: a rejected attempt must not burn it. + retry = await service.consume( + session, token, principal, is_private_chat=True, is_bot_sender=False + ) + assert retry is not None + + +@pytest.mark.asyncio +async def test_consume_rejects_bot_sender_without_burning_token( + service, connection, session +) -> None: + link = service.issue_link(connection) + token = _extract_token(link) + principal = _principal(connection.id) + + bot_attempt = await service.consume( + session, token, principal, is_private_chat=True, is_bot_sender=True + ) + assert bot_attempt is None + + retry = await service.consume( + session, token, principal, is_private_chat=True, is_bot_sender=False + ) + assert retry is not None + + +@pytest.mark.asyncio +async def test_consume_rejects_token_issued_for_a_different_connection( + service, connection, other_connection, session +) -> None: + link = service.issue_link(connection) + token = _extract_token(link) + wrong_principal = _principal(other_connection.id) + + result = await service.consume( + session, token, wrong_principal, is_private_chat=True, is_bot_sender=False + ) + assert result is None + + # The token remains valid for the connection it was actually issued for. + right_principal = _principal(connection.id) + retry = await service.consume( + session, token, right_principal, is_private_chat=True, is_bot_sender=False + ) + assert retry is not None + + +@pytest.mark.asyncio +async def test_consume_enforces_one_pairing_per_connection( + service, connection, session +) -> None: + first_link = service.issue_link(connection) + first_token = _extract_token(first_link) + first_principal = _principal(connection.id, principal_id="tg-user-1", destination_id="tg-chat-1") + + first = await service.consume( + session, first_token, first_principal, is_private_chat=True, is_bot_sender=False + ) + assert first is not None + + second_link = service.issue_link(connection) + second_token = _extract_token(second_link) + second_principal = _principal(connection.id, principal_id="tg-user-2", destination_id="tg-chat-2") + + second = await service.consume( + session, second_token, second_principal, is_private_chat=True, is_bot_sender=False + ) + assert second is None + + rows = (await session.exec(select(RemotePairing))).all() + assert [row.principal_id for row in rows] == ["tg-user-1"] + + # Unpairing frees the connection for a fresh pairing, including with the + # still-unexpired second token (a rejected attempt did not burn it). + await service.unpair(session, connection.id) + retry = await service.consume( + session, second_token, second_principal, is_private_chat=True, is_bot_sender=False + ) + assert retry is not None + assert retry.principal_id == "tg-user-2" + + +@pytest.mark.asyncio +async def test_refusals_are_uniform_regardless_of_reason( + service, connection, other_connection, session +) -> None: + """AC-9: an unpaired sender must not be able to distinguish *why* an + attempt failed from the response shape. Every failure mode here returns + the identical ``None``.""" + link = service.issue_link(connection) + token = _extract_token(link) + + unknown_token_result = await service.consume( + session, "garbage", _principal(connection.id), is_private_chat=True, is_bot_sender=False + ) + group_chat_result = await service.consume( + session, token, _principal(connection.id), is_private_chat=False, is_bot_sender=False + ) + bot_sender_result = await service.consume( + session, token, _principal(connection.id), is_private_chat=True, is_bot_sender=True + ) + wrong_connection_result = await service.consume( + session, token, _principal(other_connection.id), is_private_chat=True, is_bot_sender=False + ) + + assert ( + unknown_token_result + is group_chat_result + is bot_sender_result + is wrong_connection_result + is None + ) + + +# ── rate limiting (AC-9) ────────────────────────────────────────────────── + + +@pytest.mark.asyncio +async def test_consume_enforces_per_principal_rate_limit(connection, session) -> None: + limited_service = PairingService(per_principal_rate_limit=1) + link = limited_service.issue_link(connection) + token = _extract_token(link) + principal = _principal(connection.id) + + # First attempt consumes the rate-limit budget (even though it also + # fails on chat type, the limiter must have already counted it). + await limited_service.consume( + session, token, principal, is_private_chat=False, is_bot_sender=False, now=1.0 + ) + second = await limited_service.consume( + session, token, principal, is_private_chat=True, is_bot_sender=False, now=1.0 + ) + + assert second is None + + +@pytest.mark.asyncio +async def test_consume_enforces_connection_wide_rate_limit( + connection, session +) -> None: + limited_service = PairingService(connection_rate_limit=1) + link = limited_service.issue_link(connection) + token = _extract_token(link) + + await limited_service.consume( + session, + token, + _principal(connection.id, principal_id="user-a"), + is_private_chat=False, + is_bot_sender=False, + now=1.0, + ) + second = await limited_service.consume( + session, + token, + _principal(connection.id, principal_id="user-b"), + is_private_chat=True, + is_bot_sender=False, + now=1.0, + ) + + assert second is None + + +@pytest.mark.asyncio +async def test_consume_rate_limit_window_recovers_over_time( + connection, session +) -> None: + limited_service = PairingService( + per_principal_rate_limit=1, rate_limit_window_seconds=10.0 + ) + link = limited_service.issue_link(connection, now=0.0) + token = _extract_token(link) + principal = _principal(connection.id) + + blocked = await limited_service.consume( + session, token, principal, is_private_chat=False, is_bot_sender=False, now=1.0 + ) + assert blocked is None + + later = await limited_service.consume( + session, token, principal, is_private_chat=True, is_bot_sender=False, now=12.0 + ) + assert later is not None + + +# ── authorize (AC-8, AC-9, AC-10) ───────────────────────────────────────── + + +@pytest.mark.asyncio +async def test_authorize_returns_pairing_for_the_bound_principal( + service, connection, session +) -> None: + link = service.issue_link(connection) + token = _extract_token(link) + principal = _principal(connection.id, principal_id="tg-user-7") + await service.consume( + session, token, principal, is_private_chat=True, is_bot_sender=False + ) + + authorized = await service.authorize( + session, connection_id=connection.id, principal_id="tg-user-7" + ) + assert authorized is not None + assert authorized.principal_id == "tg-user-7" + + +@pytest.mark.asyncio +async def test_authorize_refuses_unpaired_principal( + service, connection, session +) -> None: + result = await service.authorize( + session, connection_id=connection.id, principal_id="nobody" + ) + assert result is None + + +@pytest.mark.asyncio +async def test_authorize_does_not_authorize_destination_id_as_principal( + service, connection, session +) -> None: + """principal_id and destination_id must never be collapsed/defaulted + from one another.""" + link = service.issue_link(connection) + token = _extract_token(link) + principal = _principal( + connection.id, principal_id="tg-user-1", destination_id="tg-chat-1" + ) + await service.consume( + session, token, principal, is_private_chat=True, is_bot_sender=False + ) + + # destination_id must not authorize as if it were the principal_id. + result = await service.authorize( + session, connection_id=connection.id, principal_id="tg-chat-1" + ) + assert result is None + + +@pytest.mark.asyncio +async def test_authorize_is_rate_limited(connection, session) -> None: + limited_service = PairingService(per_principal_rate_limit=1) + link = limited_service.issue_link(connection) + token = _extract_token(link) + principal = _principal(connection.id, principal_id="tg-user-1") + await limited_service.consume( + session, token, principal, is_private_chat=True, is_bot_sender=False, now=1.0 + ) + + first = await limited_service.authorize( + session, connection_id=connection.id, principal_id="tg-user-1", now=2.0 + ) + second = await limited_service.authorize( + session, connection_id=connection.id, principal_id="tg-user-1", now=2.0 + ) + + assert first is not None + assert second is None + + +@pytest.mark.asyncio +async def test_unpair_revokes_authorization_immediately( + service, connection, session +) -> None: + link = service.issue_link(connection) + token = _extract_token(link) + principal = _principal(connection.id, principal_id="tg-user-1") + await service.consume( + session, token, principal, is_private_chat=True, is_bot_sender=False + ) + assert ( + await service.authorize( + session, connection_id=connection.id, principal_id="tg-user-1" + ) + is not None + ) + + deleted = await service.unpair(session, connection.id) + assert deleted is True + + # No caching lag: the very next authorize() call must fail. + result = await service.authorize( + session, connection_id=connection.id, principal_id="tg-user-1" + ) + assert result is None + + rows = (await session.exec(select(RemotePairing))).all() + assert rows == [] + + +@pytest.mark.asyncio +async def test_unpair_on_connection_without_a_pairing_returns_false( + service, connection, session +) -> None: + assert await service.unpair(session, connection.id) is False + + +@pytest.mark.asyncio +async def test_unpair_unknown_connection_returns_false(service, session) -> None: + assert await service.unpair(session, uuid4()) is False From 403bae037ff00cc1bbf464d7f047526ebf6136d8 Mon Sep 17 00:00:00 2001 From: manhnguyen24-dev Date: Mon, 14 Sep 2026 15:01:24 +0700 Subject: [PATCH 07/71] fix(remote): serialize consume()'s check-then-act with an asyncio.Lock PairingService.consume() separated its "no existing pairing" SELECT and its token pop/insert with await points and no lock held across them. Two concurrent consume() calls could both pass the one-pairing-per-connection check before either committed (breaking the v1 limit), or both race past the same since-consumed token toward a duplicate insert (an unhandled IntegrityError instead of the uniform refusal). Add a per-instance asyncio.Lock (same pattern as WebBridgeTicketStore in app/services/webbridge_pairing_service.py) held across the whole existing-pairing-check -> token-pop -> insert sequence, and check tokens.pop()'s return value as defense-in-depth even under the lock. Confirmed the race was real before this fix: running the two new concurrent-consume tests against the pre-fix code hung indefinitely (concurrent unsynchronized use of the same AsyncSession), rather than racing to a clean duplicate-row or IntegrityError outcome. --- app/remote/pairing.py | 91 +++++++++++++++++++++++------------- tests/remote/test_pairing.py | 81 ++++++++++++++++++++++++++++++++ 2 files changed, 139 insertions(+), 33 deletions(-) diff --git a/app/remote/pairing.py b/app/remote/pairing.py index 13df4925..46696e1a 100644 --- a/app/remote/pairing.py +++ b/app/remote/pairing.py @@ -45,6 +45,7 @@ from __future__ import annotations +import asyncio import secrets import threading import time @@ -154,6 +155,18 @@ def __init__( self._connection_rate_limit = connection_rate_limit self._tokens: dict[str, _PendingToken] = {} self._tokens_lock = threading.Lock() + #: Serializes consume()'s whole check-then-act sequence (existing- + #: pairing SELECT through token pop and RemotePairing insert) across + #: concurrent calls. This app is single-process (see e.g. + #: app/services/memory_stream_store.py's module docstring and + #: WebBridgeTicketStore's equivalent per-instance lock in + #: app/services/webbridge_pairing_service.py), so a plain + #: asyncio.Lock — safely held across await points — is the + #: right-sized fix: without it, two concurrent consume() calls can + #: both pass the "no existing pairing" check before either commits + #: (breaking the one-pairing-per-connection limit), or both race + #: past a since-consumed token toward a duplicate insert. + self._consume_lock = asyncio.Lock() self._rate_limiter = _SlidingWindowRateLimiter( window_seconds=rate_limit_window_seconds ) @@ -210,6 +223,11 @@ async def consume( bind does — so a legitimate retry from a corrected context (for example a private chat after a group-chat attempt) can still succeed before the token's real expiry. + + The existing-pairing check, token pop, and insert run as one atomic + critical section under ``self._consume_lock`` so two concurrent + calls cannot both observe "no existing pairing" and both insert, and + cannot both pop the same token and both proceed toward insert. """ timestamp = time.monotonic() if now is None else now @@ -226,41 +244,48 @@ async def consume( ): return None - with self._tokens_lock: - pending = self._tokens.get(token) - if pending is None or pending.expires_at <= timestamp: - return None - if pending.connection_id != principal.connection_id: - return None - if not is_private_chat or is_bot_sender: - return None - - existing = ( - await session.exec( - select(RemotePairing).where( - RemotePairing.connection_id == principal.connection_id + async with self._consume_lock: + with self._tokens_lock: + pending = self._tokens.get(token) + if pending is None or pending.expires_at <= timestamp: + return None + if pending.connection_id != principal.connection_id: + return None + if not is_private_chat or is_bot_sender: + return None + + existing = ( + await session.exec( + select(RemotePairing).where( + RemotePairing.connection_id == principal.connection_id + ) ) + ).first() + if existing is not None: + return None + + # Every check passed: burn the token now, then persist the + # binding. Checking pop()'s return value is correct + # defense-in-depth even under the lock — it is the only thing + # standing between a racing/duplicate consume of the very same + # token and an unhandled IntegrityError from a duplicate insert. + with self._tokens_lock: + popped = self._tokens.pop(token, None) + if popped is None: + return None + + display = principal.display[:_MAX_LABEL_LENGTH] + pairing = RemotePairing( + connection_id=principal.connection_id, + principal_id=principal.principal_id, + destination_id=principal.destination_id, + label=display or "Paired device", + display=display, ) - ).first() - if existing is not None: - return None - - # Every check passed: burn the token now, then persist the binding. - with self._tokens_lock: - self._tokens.pop(token, None) - - display = principal.display[:_MAX_LABEL_LENGTH] - pairing = RemotePairing( - connection_id=principal.connection_id, - principal_id=principal.principal_id, - destination_id=principal.destination_id, - label=display or "Paired device", - display=display, - ) - session.add(pairing) - await session.commit() - await session.refresh(pairing) - return pairing + session.add(pairing) + await session.commit() + await session.refresh(pairing) + return pairing # ── authorize ──────────────────────────────────────────────────────── diff --git a/tests/remote/test_pairing.py b/tests/remote/test_pairing.py index 64abab9a..ca65ba04 100644 --- a/tests/remote/test_pairing.py +++ b/tests/remote/test_pairing.py @@ -8,6 +8,7 @@ from __future__ import annotations +import asyncio import re from urllib.parse import parse_qs, urlparse from uuid import uuid4 @@ -520,3 +521,83 @@ async def test_unpair_on_connection_without_a_pairing_returns_false( @pytest.mark.asyncio async def test_unpair_unknown_connection_returns_false(service, session) -> None: assert await service.unpair(session, uuid4()) is False + + +# ── concurrency: unsynchronized check-then-act race (fix follow-up) ────── + + +@pytest.mark.asyncio +async def test_concurrent_consume_with_different_tokens_only_binds_one_pairing( + service, connection, session +) -> None: + """Two different valid tokens for the same connection, consumed near- + simultaneously via asyncio.gather, must not both pass the + one-pairing-per-connection check before either commits — only one may + succeed, the other must get the uniform refusal.""" + first_link = service.issue_link(connection) + first_token = _extract_token(first_link) + second_link = service.issue_link(connection) + second_token = _extract_token(second_link) + + first_principal = _principal( + connection.id, principal_id="user-a", destination_id="chat-a" + ) + second_principal = _principal( + connection.id, principal_id="user-b", destination_id="chat-b" + ) + + results = await asyncio.gather( + service.consume( + session, + first_token, + first_principal, + is_private_chat=True, + is_bot_sender=False, + ), + service.consume( + session, + second_token, + second_principal, + is_private_chat=True, + is_bot_sender=False, + ), + ) + + successes = [result for result in results if result is not None] + refusals = [result for result in results if result is None] + assert len(successes) == 1 + assert len(refusals) == 1 + + rows = (await session.exec(select(RemotePairing))).all() + assert len(rows) == 1 + + +@pytest.mark.asyncio +async def test_concurrent_consume_with_the_same_token_only_succeeds_once( + service, connection, session +) -> None: + """The same token consumed twice concurrently (e.g. a duplicate inbound + delivery) must yield exactly one success and one uniform refusal — never + an unhandled exception from a duplicate insert.""" + link = service.issue_link(connection) + token = _extract_token(link) + principal = _principal( + connection.id, principal_id="user-a", destination_id="chat-a" + ) + + results = await asyncio.gather( + service.consume( + session, token, principal, is_private_chat=True, is_bot_sender=False + ), + service.consume( + session, token, principal, is_private_chat=True, is_bot_sender=False + ), + ) + + successes = [result for result in results if result is not None] + refusals = [result for result in results if result is None] + assert len(successes) == 1 + assert len(refusals) == 1 + + rows = (await session.exec(select(RemotePairing))).all() + assert len(rows) == 1 From efdd8460a0a6868e50c2bcf17e4cd3a7078aae6e Mon Sep 17 00:00:00 2001 From: manhnguyen24-dev Date: Mon, 14 Sep 2026 15:22:08 +0700 Subject: [PATCH 08/71] feat(remote): Task 5 - Desktop API and lazy runtime lifecycle Adds the authenticated /api/remote/* HTTP surface (connections CRUD, token replace, pairing-links/pairing/status) as thin routes over the existing RemoteConnectionService/PairingService, and app/remote/runtime.py as a process singleton (start/stop/reconcile_connection/status) that lazily constructs a real TelegramAdapter only for an enabled, credentialed connection - every Telegram import stays function-local so an idle installation never pulls app.remote.telegram.* into sys.modules, creates a task, or touches the network (AC-1). Wires remote_runtime.start()/stop() into app/api/app.py's existing optional-service startup/shutdown pattern, alongside Conductor/Scheduler, without touching app/conductor/. Adds RemoteConnectionService.set_label (mirrors set_enabled) so PATCH can rename a connection. --- app/api/app.py | 17 ++ app/api/routes/remote.py | 297 +++++++++++++++++++++ app/api/schemas/remote.py | 142 ++++++++++ app/remote/connection_service.py | 16 ++ app/remote/runtime.py | 281 ++++++++++++++++++++ tests/api/routes/test_remote.py | 432 +++++++++++++++++++++++++++++++ tests/api/test_app_lifespan.py | 83 +++++- tests/remote/test_runtime.py | 334 ++++++++++++++++++++++++ 8 files changed, 1601 insertions(+), 1 deletion(-) create mode 100644 app/api/routes/remote.py create mode 100644 app/api/schemas/remote.py create mode 100644 app/remote/runtime.py create mode 100644 tests/api/routes/test_remote.py create mode 100644 tests/remote/test_runtime.py diff --git a/app/api/app.py b/app/api/app.py index 25344e46..4a5e2738 100644 --- a/app/api/app.py +++ b/app/api/app.py @@ -26,6 +26,7 @@ from app.api.routes.observability import router as observability_router from app.api.routes.plugins import router as plugins_router from app.api.routes.quote import router as quote_router +from app.api.routes.remote import router as remote_router from app.api.routes.scheduler import router as scheduler_router from app.api.routes.settings import router as settings_router from app.api.routes.skills import router as skills_router @@ -147,6 +148,18 @@ async def _start_optional_services(app: FastAPI, process_started: float) -> None logger.error("optional_service_start_failed service=scheduler error={}", exc) _log_startup_timing("scheduler", phase_started, process_started) + phase_started = perf_counter() + try: + # Lazy by design (AC-1): with no enabled, credentialed remote + # connection this imports nothing under app.remote.telegram and + # starts no task — see app/remote/runtime.py. + from app.remote.runtime import remote_runtime + + await remote_runtime.start() + except Exception as exc: # noqa: BLE001 + logger.error("optional_service_start_failed service=remote error={}", exc) + _log_startup_timing("remote", phase_started, process_started) + phase_started = perf_counter() try: from app.core.db import async_session_factory @@ -294,6 +307,9 @@ async def lifespan(app: FastAPI): await dream_scheduler.stop() await task_scheduler.stop() await team_manager.stop() + from app.remote.runtime import remote_runtime + + await remote_runtime.stop() from app.conductor import conductor_service await conductor_service.stop() @@ -396,6 +412,7 @@ def create_app() -> FastAPI: app.include_router(mcp_router, prefix="/api/mcp", tags=["mcp"]) app.include_router(plugins_router, prefix="/api/plugins", tags=["plugins"]) app.include_router(settings_router, prefix="/api/settings", tags=["settings"]) + app.include_router(remote_router, prefix="/api/remote", tags=["remote"]) app.include_router(auth_router, prefix="/api/auth", tags=["auth"]) app.include_router(dream_router, prefix="/api", tags=["dream"]) app.include_router( diff --git a/app/api/routes/remote.py b/app/api/routes/remote.py new file mode 100644 index 00000000..90875310 --- /dev/null +++ b/app/api/routes/remote.py @@ -0,0 +1,297 @@ +"""``/api/remote/*`` — desktop HTTP API for the (v1 single) remote connection. + +Every route here uses the existing desktop authentication +(``DesktopTokenMiddleware`` — wired in ``app/api/app.py`` like every other +route) and no custom credential type (AC-2, AC-33). Handlers only parse/ +validate HTTP shape, call :class:`~app.remote.connection_service.RemoteConnectionService`, +:class:`~app.remote.pairing.PairingService`, and +:data:`~app.remote.runtime.remote_runtime`, and translate the domain errors +those already raise into HTTP responses. No business logic is duplicated +here — connection limits, credential custody, and pairing rules all stay in +their owning service. +""" + +from __future__ import annotations + +import uuid + +from fastapi import APIRouter, Depends, HTTPException +from sqlmodel import select +from sqlmodel.ext.asyncio.session import AsyncSession + +from app.api.schemas.remote import ( + RemoteConnectionCreateRequest, + RemoteConnectionPatchRequest, + RemoteConnectionResponse, + RemoteConnectionStatusBody, + RemoteConnectionTokenReplaceRequest, + RemotePairingLinkResponse, + RemotePairingResponse, +) +from app.core.credential_store import CredentialStoreError +from app.core.db import get_session +from app.models.remote import RemoteConnection, RemotePairing +from app.remote.connection_service import ( + CredentialStoreFactory, + RemoteConnectionConflictError, + RemoteConnectionNotFoundError, + RemoteConnectionService, + RemoteCredentialError, + default_credential_store_factory, +) +from app.remote.contracts import RemoteAdapterValidationError +from app.remote.pairing import PairingService +from app.remote.runtime import TelegramAdapterFactory, remote_runtime + +router = APIRouter() + +# ── Dependencies ────────────────────────────────────────────────────────── +# +# Plain functions (not classes) so tests can override them via FastAPI's +# ``app.dependency_overrides`` — the same pattern ``app/api/routes/scheduler.py`` +# uses for its singleton. ``_credential_store_factory`` is a module-level +# variable rather than a dependency because it is also used outside any +# request (``_token_configured``) — tests monkeypatch it directly. + +_pairing_service = PairingService() +_credential_store_factory: CredentialStoreFactory = default_credential_store_factory + + +def get_connection_service() -> RemoteConnectionService: + return RemoteConnectionService(adapter_factory=TelegramAdapterFactory()) + + +def get_pairing_service() -> PairingService: + return _pairing_service + + +# ── Helpers ─────────────────────────────────────────────────────────────── + + +def _token_configured(connection_id: uuid.UUID) -> bool: + store = _credential_store_factory(connection_id) + try: + return store.load() is not None + except CredentialStoreError: + return False + + +async def _get_pairing( + session: AsyncSession, connection_id: uuid.UUID +) -> RemotePairing | None: + result = await session.exec( + select(RemotePairing).where(RemotePairing.connection_id == connection_id) + ) + return result.first() + + +async def _status_body( + session: AsyncSession, connection_id: uuid.UUID +) -> RemoteConnectionStatusBody: + status = remote_runtime.status(connection_id) + pairing = await _get_pairing(session, connection_id) + return RemoteConnectionStatusBody( + connection_id=status.connection_id, + state=status.state, + last_error_class=status.last_error_class, + last_successful_poll_at=status.last_successful_poll_at, + paired=pairing is not None, + phone_reachable=status.phone_reachable, + informational_drop_count=status.informational_drop_count, + high_priority_drop_count=status.high_priority_drop_count, + ) + + +async def _connection_response( + session: AsyncSession, connection: RemoteConnection +) -> RemoteConnectionResponse: + return RemoteConnectionResponse( + id=connection.id, + adapter=connection.adapter, + label=connection.label, + enabled=connection.enabled, + adapter_principal_id=connection.adapter_principal_id, + adapter_username=connection.adapter_username, + token_configured=_token_configured(connection.id), + created_at=connection.created_at, + updated_at=connection.updated_at, + status=await _status_body(session, connection.id), + ) + + +async def _connection_or_404( + session: AsyncSession, service: RemoteConnectionService, connection_id: uuid.UUID +) -> RemoteConnection: + connection = await service.get(session, connection_id) + if connection is None: + raise HTTPException(status_code=404, detail="Remote connection not found.") + return connection + + +# ── Connections ─────────────────────────────────────────────────────────── + + +@router.get("/connections") +async def list_connections( + session: AsyncSession = Depends(get_session), + service: RemoteConnectionService = Depends(get_connection_service), +) -> list[RemoteConnectionResponse]: + """Zero-or-one v1 connection summary and safe runtime state.""" + connections = await service.list(session) + return [await _connection_response(session, c) for c in connections] + + +@router.post("/connections", status_code=201) +async def create_connection( + body: RemoteConnectionCreateRequest, + session: AsyncSession = Depends(get_session), + service: RemoteConnectionService = Depends(get_connection_service), +) -> RemoteConnectionResponse: + """Validate a write-only token, vault it, and create the connection. + + ``409`` when one already exists (AC-3, v1's one-connection limit). + """ + try: + connection = await service.create_connection( + session, token=body.token, label=body.label + ) + except RemoteConnectionConflictError as exc: + raise HTTPException(status_code=409, detail=str(exc)) from exc + except RemoteAdapterValidationError as exc: + raise HTTPException(status_code=422, detail=str(exc)) from exc + except RemoteCredentialError as exc: + raise HTTPException(status_code=503, detail=str(exc)) from exc + + await remote_runtime.reconcile_connection(connection.id) + return await _connection_response(session, connection) + + +@router.patch("/connections/{connection_id}") +async def patch_connection( + connection_id: uuid.UUID, + body: RemoteConnectionPatchRequest, + session: AsyncSession = Depends(get_session), + service: RemoteConnectionService = Depends(get_connection_service), +) -> RemoteConnectionResponse: + """Change label and/or enabled state. Adapter kind and bot identity are + immutable here — the request schema simply has no field for them.""" + connection = await _connection_or_404(session, service, connection_id) + + if body.label is not None: + connection = await service.set_label(session, connection_id, label=body.label) + if body.enabled is not None: + connection = await service.set_enabled( + session, connection_id, enabled=body.enabled + ) + + await remote_runtime.reconcile_connection(connection_id) + return await _connection_response(session, connection) + + +@router.put("/connections/{connection_id}/token") +async def replace_token( + connection_id: uuid.UUID, + body: RemoteConnectionTokenReplaceRequest, + session: AsyncSession = Depends(get_session), + service: RemoteConnectionService = Depends(get_connection_service), +) -> RemoteConnectionResponse: + """Validate and atomically replace the write-only bot token. + + Re-pairs (invalidates the existing pairing) when the new token resolves + to a different bot — handled entirely inside + ``RemoteConnectionService.update_token`` (AC-6, AC-10). + """ + try: + connection = await service.update_token(session, connection_id, token=body.token) + except RemoteConnectionNotFoundError as exc: + raise HTTPException(status_code=404, detail=str(exc)) from exc + except RemoteAdapterValidationError as exc: + raise HTTPException(status_code=422, detail=str(exc)) from exc + except RemoteCredentialError as exc: + raise HTTPException(status_code=503, detail=str(exc)) from exc + + await remote_runtime.reconcile_connection(connection_id) + return await _connection_response(session, connection) + + +@router.delete("/connections/{connection_id}", status_code=204) +async def remove_connection( + connection_id: uuid.UUID, + session: AsyncSession = Depends(get_session), + service: RemoteConnectionService = Depends(get_connection_service), +) -> None: + """Stop and remove the connection, pairing, tokens, and vault credential.""" + try: + await service.remove(session, connection_id) + except RemoteConnectionNotFoundError as exc: + raise HTTPException(status_code=404, detail=str(exc)) from exc + except RemoteCredentialError as exc: + raise HTTPException(status_code=503, detail=str(exc)) from exc + + await remote_runtime.reconcile_connection(connection_id) + + +# ── Pairing ─────────────────────────────────────────────────────────────── + + +@router.post("/connections/{connection_id}/pairing-links") +async def issue_pairing_link( + connection_id: uuid.UUID, + session: AsyncSession = Depends(get_session), + service: RemoteConnectionService = Depends(get_connection_service), + pairing_service: PairingService = Depends(get_pairing_service), +) -> RemotePairingLinkResponse: + """Mint a single-use deep link and return link, QR payload, and expiry.""" + connection = await _connection_or_404(session, service, connection_id) + link = pairing_service.issue_link(connection) + return RemotePairingLinkResponse( + url=link.url, qr_payload=link.qr_payload, expires_at=link.expires_at + ) + + +@router.get("/connections/{connection_id}/pairing") +async def get_pairing( + connection_id: uuid.UUID, + session: AsyncSession = Depends(get_session), + service: RemoteConnectionService = Depends(get_connection_service), +) -> RemotePairingResponse | None: + """Safe paired-account decoration, or ``null`` when unpaired.""" + await _connection_or_404(session, service, connection_id) + pairing = await _get_pairing(session, connection_id) + if pairing is None: + return None + return RemotePairingResponse( + id=pairing.id, + label=pairing.label, + display=pairing.display, + created_at=pairing.created_at, + last_seen_at=pairing.last_seen_at, + ) + + +@router.delete("/connections/{connection_id}/pairing", status_code=204) +async def revoke_pairing( + connection_id: uuid.UUID, + session: AsyncSession = Depends(get_session), + service: RemoteConnectionService = Depends(get_connection_service), + pairing_service: PairingService = Depends(get_pairing_service), +) -> None: + """Revoke the paired account (AC-10) — a later ``authorize`` call for + the former principal fails immediately, with no cache to invalidate.""" + await _connection_or_404(session, service, connection_id) + await pairing_service.unpair(session, connection_id) + + +# ── Status ──────────────────────────────────────────────────────────────── + + +@router.get("/connections/{connection_id}/status") +async def get_connection_status( + connection_id: uuid.UUID, + session: AsyncSession = Depends(get_session), + service: RemoteConnectionService = Depends(get_connection_service), +) -> RemoteConnectionStatusBody: + """Adapter lifecycle, last safe error, poll time, pairing state, + reachability, and drop counts (AC-34).""" + await _connection_or_404(session, service, connection_id) + return await _status_body(session, connection_id) diff --git a/app/api/schemas/remote.py b/app/api/schemas/remote.py new file mode 100644 index 00000000..5c7c7924 --- /dev/null +++ b/app/api/schemas/remote.py @@ -0,0 +1,142 @@ +"""Pydantic request/response models for ``/api/remote/*``. + +Secret-bearing request models use write-only fields: the ``token`` on +:class:`RemoteConnectionCreateRequest` and +:class:`RemoteConnectionTokenReplaceRequest` is accepted but never echoed +back. Every response model instead reports ``token_configured: bool`` — +never the credential or a fingerprint of it (spec: "Desktop HTTP API"). +None of these models carry an example that looks like a real bot token. +""" + +from __future__ import annotations + +from datetime import datetime +from uuid import UUID + +from pydantic import BaseModel, ConfigDict, Field + +from app.remote.contracts import RemoteConnectionState, RemoteErrorClass + +__all__ = [ + "RemoteConnectionCreateRequest", + "RemoteConnectionPatchRequest", + "RemoteConnectionResponse", + "RemoteConnectionStatusBody", + "RemoteConnectionTokenReplaceRequest", + "RemotePairingLinkResponse", + "RemotePairingResponse", +] + +#: A clearly-fake placeholder — never a shape resembling a real Telegram +#: bot token — so OpenAPI examples cannot be mistaken for a live credential. +_TOKEN_EXAMPLE = "" + + +class RemoteConnectionCreateRequest(BaseModel): + """``POST /api/remote/connections`` body.""" + + model_config = ConfigDict(extra="forbid") + + label: str = Field(min_length=1, max_length=120) + token: str = Field( + min_length=1, + repr=False, + description="Bot token from @BotFather. Write-only — never returned by the API.", + json_schema_extra={"example": _TOKEN_EXAMPLE}, + ) + + +class RemoteConnectionPatchRequest(BaseModel): + """``PATCH /api/remote/connections/{id}`` body. + + Only ``label`` and ``enabled`` are accepted — adapter kind and bot + identity are immutable outside of :class:`RemoteConnectionTokenReplaceRequest` + (``extra="forbid"`` rejects any other field with a clean 422 rather than + silently ignoring it). + """ + + model_config = ConfigDict(extra="forbid") + + label: str | None = Field(default=None, min_length=1, max_length=120) + enabled: bool | None = None + + +class RemoteConnectionTokenReplaceRequest(BaseModel): + """``PUT /api/remote/connections/{id}/token`` body.""" + + model_config = ConfigDict(extra="forbid") + + token: str = Field( + min_length=1, + repr=False, + description="Replacement bot token. Write-only — never returned by the API.", + json_schema_extra={"example": _TOKEN_EXAMPLE}, + ) + + +class RemoteConnectionStatusBody(BaseModel): + """Safe, diagnosable connection status (AC-34). + + Mirrors :class:`app.remote.contracts.RemoteAdapterStatus` field-for-field + but is this module's own response shape — never the dataclass directly — + so a later change to the internal contract cannot silently change the + wire shape. + """ + + model_config = ConfigDict(extra="forbid") + + connection_id: UUID + state: RemoteConnectionState + last_error_class: RemoteErrorClass + last_successful_poll_at: datetime | None + paired: bool + phone_reachable: bool | None + informational_drop_count: int + high_priority_drop_count: int + + +class RemoteConnectionResponse(BaseModel): + """``GET/POST/PATCH/PUT .../connections[...]`` response shape. + + Deliberately has no ``token`` field at all — only ``token_configured``. + """ + + model_config = ConfigDict(extra="forbid") + + id: UUID + adapter: str + label: str + enabled: bool + adapter_principal_id: str + adapter_username: str + token_configured: bool + created_at: datetime + updated_at: datetime + status: RemoteConnectionStatusBody + + +class RemotePairingLinkResponse(BaseModel): + """``POST /api/remote/connections/{id}/pairing-links`` response.""" + + model_config = ConfigDict(extra="forbid") + + url: str + qr_payload: str + expires_at: datetime + + +class RemotePairingResponse(BaseModel): + """``GET /api/remote/connections/{id}/pairing`` response when paired. + + Only safe, untrusted decoration — never the raw provider chat/user ID + beyond what is already the ``principal``/``destination`` the rest of the + system treats as opaque identifiers. + """ + + model_config = ConfigDict(extra="forbid") + + id: UUID + label: str + display: str + created_at: datetime + last_seen_at: datetime diff --git a/app/remote/connection_service.py b/app/remote/connection_service.py index 435fc33b..71c1d838 100644 --- a/app/remote/connection_service.py +++ b/app/remote/connection_service.py @@ -227,6 +227,22 @@ async def set_enabled( await session.refresh(connection) return connection + async def set_label( + self, session: AsyncSession, connection_id: UUID, *, label: str + ) -> RemoteConnection: + """Rename a connection. Purely local metadata — never touches the + vault, adapter identity, or pairing (mirrors :meth:`set_enabled`).""" + connection = await self.get(session, connection_id) + if connection is None: + raise RemoteConnectionNotFoundError( + f"Remote connection {connection_id} does not exist." + ) + connection.label = label + session.add(connection) + await session.commit() + await session.refresh(connection) + return connection + async def remove(self, session: AsyncSession, connection_id: UUID) -> None: """Delete the connection's vault entry, then the connection (cascading its pairing). diff --git a/app/remote/runtime.py b/app/remote/runtime.py new file mode 100644 index 00000000..f47cd32c --- /dev/null +++ b/app/remote/runtime.py @@ -0,0 +1,281 @@ +"""Process singleton owning the remote connection's lazy adapter lifecycle. + +AC-1 ("off and free by default") is the load-bearing contract of this +module: with no enabled, credentialed connection, nothing here ever +imports ``app.remote.telegram.adapter`` or ``app.remote.telegram.client``, +creates an ``asyncio.Task``, or makes a network call. Every reference to +either Telegram module is therefore a *function-local* import inside a +factory that only runs once a connection is actually enabled and +credentialed — never a module-level import here. + +:data:`remote_runtime` is constructed once per process and owns at most one +live :class:`~app.remote.contracts.RemoteAdapter` — the v1 product limit is +one connection (AC-3), so there is never more than one to own. +""" + +from __future__ import annotations + +import asyncio +from collections.abc import Awaitable, Callable +from uuid import UUID + +from loguru import logger + +from app.core.credential_store import CredentialStoreError +from app.remote.connection_service import ( + CredentialStoreFactory, + RemoteConnectionService, + default_credential_store_factory, +) +from app.remote.contracts import ( + RemoteAdapter, + RemoteAdapterKind, + RemoteAdapterStatus, + RemoteAdapterValidationError, + RemoteConnectionState, + RemoteInboundAction, + ValidatedRemoteIdentity, +) + +__all__ = [ + "AdapterConstructor", + "RemoteActionHandler", + "RemoteRuntime", + "TelegramAdapterFactory", + "remote_runtime", +] + +#: Invoked for every classified inbound action the adapter dispatches. See +#: :class:`app.remote.telegram.adapter.RemoteActionHandler` — redefined here +#: (rather than imported) so this module never imports anything under +#: ``app.remote.telegram`` at module scope. +RemoteActionHandler = Callable[[RemoteInboundAction], Awaitable[object]] + +#: Builds one connection's live adapter from its token. The production +#: implementation (:func:`_construct_telegram_adapter`) imports +#: ``app.remote.telegram.adapter`` lazily, inside the function body, so +#: merely *referencing* this type or constructing a :class:`RemoteRuntime` +#: never triggers that import. +AdapterConstructor = Callable[[UUID, str, RemoteActionHandler], RemoteAdapter] + + +class TelegramAdapterFactory: + """Production ``RemoteAdapterFactory`` (see ``app.remote.contracts``). + + Validates a candidate bot token by calling Telegram's ``getMe`` — the + only network call this factory ever makes, and only when a caller + (``RemoteConnectionService.create_connection``/``update_token``, reached + from ``POST``/``PUT /api/remote/connections...``) actually invokes + :meth:`validate_token`. ``app.remote.telegram.client`` is imported + lazily inside this method so constructing this factory, or importing + this module, never pulls it into ``sys.modules`` (AC-1). + """ + + async def validate_token( + self, adapter: RemoteAdapterKind, token: str + ) -> ValidatedRemoteIdentity: + from app.remote.telegram.client import ( + TelegramApiError, + TelegramClient, + TelegramMalformedResponseError, + TelegramTransportError, + ) + + client = TelegramClient(token) + try: + me = await client.get_me() + except ( + TelegramApiError, + TelegramTransportError, + TelegramMalformedResponseError, + ) as exc: + # Never include the token or the raw provider error (AC-5). + raise RemoteAdapterValidationError( + "The bot token could not be validated with Telegram." + ) from exc + finally: + await client.aclose() + + if not me.is_bot: + raise RemoteAdapterValidationError( + "The token must belong to a bot account, not a user account." + ) + + return ValidatedRemoteIdentity( + adapter=adapter, principal_id=str(me.id), username=me.username or "" + ) + + +def _default_connection_service() -> RemoteConnectionService: + """The production ``RemoteConnectionService``. + + ``TelegramAdapterFactory()`` construction does not itself import + Telegram — only a subsequent ``validate_token`` call does — so building + this service here is safe even when no connection is configured. + """ + return RemoteConnectionService(adapter_factory=TelegramAdapterFactory()) + + +def _construct_telegram_adapter( + connection_id: UUID, token: str, on_action: RemoteActionHandler +) -> RemoteAdapter: + """Build the real Telegram adapter for one enabled, credentialed + connection. + + This is the one place in this module that imports + ``app.remote.telegram.adapter`` — and it happens only when + :meth:`RemoteRuntime._start_locked` has already confirmed a connection + is enabled and its vault credential is present (AC-1). + """ + from app.remote.telegram.adapter import TelegramAdapter + + return TelegramAdapter(connection_id=connection_id, token=token, on_action=on_action) + + +class RemoteRuntime: + """Owns the lifecycle of at most one live remote adapter. + + Every public method is safe to call at any time, including before any + connection exists: ``start``/``reconcile_connection`` are no-ops unless + the current connection is both ``enabled`` and has a vault credential, + and ``stop``/``status`` never raise even when nothing is running. + + Constructor parameters exist purely for test injection (mirroring + :class:`~app.remote.connection_service.RemoteConnectionService`'s own + ``credential_store_factory`` pattern) — production code always + constructs the module-level :data:`remote_runtime` with its defaults. + """ + + def __init__( + self, + *, + connection_service_factory: Callable[[], RemoteConnectionService] | None = None, + credential_store_factory: CredentialStoreFactory | None = None, + adapter_constructor: AdapterConstructor | None = None, + ) -> None: + self._connection_service_factory = ( + connection_service_factory or _default_connection_service + ) + self._credential_store_factory = ( + credential_store_factory or default_credential_store_factory + ) + self._adapter_constructor = adapter_constructor or _construct_telegram_adapter + + #: Serializes start/stop/reconcile so concurrent calls (e.g. two + #: rapid route mutations) cannot both observe "nothing running" and + #: both start an adapter, or interleave a stop with a start. + self._lock = asyncio.Lock() + self._adapter: RemoteAdapter | None = None + self._connection_id: UUID | None = None + + async def start(self) -> None: + """Start the current connection's adapter, if any (AC-1). + + Called once from the app lifespan. A no-op when no connection + exists, the connection is disabled, its vault credential is + missing, or an adapter is already running. + """ + async with self._lock: + if self._adapter is not None: + return + await self._start_locked() + + async def stop(self) -> None: + """Stop the running adapter, if any. Idempotent (AC-13) — always + safe to call, including before ``start()`` was ever called.""" + async with self._lock: + await self._stop_locked() + + async def reconcile_connection(self, connection_id: UUID) -> None: + """Re-evaluate runtime state after a connection mutation. + + Called by the HTTP routes after any create, enable/disable, token + replacement, or removal so the effect is immediate rather than + requiring a process restart. v1 permits at most one connection + (AC-3), so the correct reaction to *any* mutation is always the + same: stop whatever is currently running, then re-evaluate the + current database state from scratch. If that state is still (or + newly) enabled and credentialed, a fresh adapter starts — bound to + a replaced token when one was just rotated; otherwise nothing + restarts. + """ + logger.debug("remote_runtime_reconcile connection_id={}", connection_id) + async with self._lock: + await self._stop_locked() + await self._start_locked() + + def status(self, connection_id: UUID) -> RemoteAdapterStatus: + """Safe, diagnosable status for *connection_id* (AC-34). + + Returns the live adapter's status when it is the one currently + running; otherwise a ``disabled`` shape naming *connection_id*. + Never raises and never imports or constructs anything + Telegram-specific. + """ + if self._adapter is not None and self._connection_id == connection_id: + return self._adapter.status() + return RemoteAdapterStatus( + connection_id=connection_id, state=RemoteConnectionState.DISABLED + ) + + # ------------------------------------------------------------------ + # Internal — callers must hold ``self._lock``. + # ------------------------------------------------------------------ + + async def _start_locked(self) -> None: + from app.core.db import async_session_factory + + async with async_session_factory() as session: + connections = await self._connection_service_factory().list(session) + connection = connections[0] if connections else None + if connection is None or not connection.enabled: + return + + store = self._credential_store_factory(connection.id) + try: + token = store.load() + except CredentialStoreError as exc: + logger.error( + "remote_runtime_credential_load_failed connection_id={} error={}", + connection.id, + exc, + ) + return + if not token: + logger.warning( + "remote_runtime_credential_missing connection_id={}", connection.id + ) + return + + adapter = self._adapter_constructor(connection.id, token, self._handle_action) + await adapter.start() + self._adapter = adapter + self._connection_id = connection.id + + async def _stop_locked(self) -> None: + adapter, self._adapter = self._adapter, None + self._connection_id = None + if adapter is not None: + await adapter.stop() + + async def _handle_action(self, action: RemoteInboundAction) -> None: + """Placeholder inbound dispatch. + + This task (Desktop API and lazy runtime lifecycle) is scoped to + AC-1, AC-2, AC-3, AC-5, AC-7, AC-10, AC-12, AC-13, AC-33, and AC-34 + — none of which require acting on inbound Telegram updates. A later + task supplies the real ``RemoteInboundService`` (natural-language + ingress and pairing consumption, AC-8/AC-14+) that this handler + will delegate to. Until then, inbound actions are received — so the + adapter's poll loop and offset bookkeeping run correctly end to + end — and safely dropped, rather than duplicating business logic + that belongs to ``PairingService``/a later inbound service here. + """ + logger.debug( + "remote_inbound_action_dropped connection_id={} kind={}", + action.connection_id, + action.kind, + ) + + +remote_runtime = RemoteRuntime() diff --git a/tests/api/routes/test_remote.py b/tests/api/routes/test_remote.py new file mode 100644 index 00000000..7078b524 --- /dev/null +++ b/tests/api/routes/test_remote.py @@ -0,0 +1,432 @@ +"""Tests for app/api/routes/remote.py — the ``/api/remote/*`` desktop API. + +Route handlers are exercised against an isolated ``FastAPI()`` app carrying +only this router, with ``get_connection_service`` overridden to a fake +adapter-validation/vault-free `RemoteConnectionService` (mirroring +``tests/remote/test_connection_service.py``'s fakes) and +``remote_runtime``'s ``reconcile_connection``/``status`` monkeypatched so no +test here depends on — or re-tests — the runtime's own lifecycle logic +(covered separately by ``tests/remote/test_runtime.py``). A dedicated test +at the bottom uses the real ``create_app()`` to prove these routes sit +behind the existing desktop-token middleware like every other route. +""" + +from __future__ import annotations + +import re +from unittest.mock import AsyncMock +from uuid import UUID, uuid4 + +import pytest +import pytest_asyncio +from fastapi import FastAPI +from fastapi.testclient import TestClient + +import app.core.db as db_module +from app.api.routes import remote as remote_routes +from app.models.remote import RemotePairing +from app.remote.connection_service import RemoteConnectionService +from app.remote.contracts import ( + RemoteAdapterKind, + RemoteAdapterStatus, + RemoteAdapterValidationError, + RemoteConnectionState, + ValidatedRemoteIdentity, +) + +#: Telegram bot tokens look like ``123456789:AAExampleShapeOnly``. Used only +#: to assert our OpenAPI example never resembles a real one. +_TELEGRAM_TOKEN_SHAPE = re.compile(r"^\d+:[A-Za-z0-9_-]+$") + + +class FakeCredentialStore: + def __init__(self) -> None: + self.value: str | None = None + + def load(self) -> str | None: + return self.value + + def save(self, credential: str) -> None: + self.value = credential + + def delete(self) -> None: + self.value = None + + +class FakeAdapterFactory: + def __init__(self) -> None: + self.identities: dict[str, ValidatedRemoteIdentity] = {} + + async def validate_token( + self, adapter: RemoteAdapterKind, token: str + ) -> ValidatedRemoteIdentity: + identity = self.identities.get(token) + if identity is None: + raise RemoteAdapterValidationError("Invalid bot token.") + return identity + + +@pytest.fixture +def credential_stores() -> dict[UUID, FakeCredentialStore]: + return {} + + +@pytest.fixture +def adapter_factory() -> FakeAdapterFactory: + factory = FakeAdapterFactory() + factory.identities["bot-token-1"] = ValidatedRemoteIdentity( + adapter=RemoteAdapterKind.TELEGRAM, principal_id="bot-1", username="my_bot" + ) + factory.identities["bot-token-2-same-bot"] = ValidatedRemoteIdentity( + adapter=RemoteAdapterKind.TELEGRAM, principal_id="bot-1", username="my_bot_renamed" + ) + return factory + + +@pytest.fixture +def app(adapter_factory, credential_stores, monkeypatch) -> FastAPI: + def credential_store_factory(connection_id: UUID) -> FakeCredentialStore: + return credential_stores.setdefault(connection_id, FakeCredentialStore()) + + def connection_service() -> RemoteConnectionService: + return RemoteConnectionService( + adapter_factory=adapter_factory, + credential_store_factory=credential_store_factory, + ) + + monkeypatch.setattr(remote_routes, "_credential_store_factory", credential_store_factory) + monkeypatch.setattr( + remote_routes.remote_runtime, "reconcile_connection", AsyncMock() + ) + monkeypatch.setattr( + remote_routes.remote_runtime, + "status", + lambda connection_id: RemoteAdapterStatus( + connection_id=connection_id, state=RemoteConnectionState.DISABLED + ), + ) + + fastapi_app = FastAPI() + fastapi_app.include_router(remote_routes.router, prefix="/api/remote") + fastapi_app.dependency_overrides[remote_routes.get_connection_service] = ( + connection_service + ) + return fastapi_app + + +@pytest.fixture +def client(app: FastAPI) -> TestClient: + return TestClient(app) + + +@pytest_asyncio.fixture +async def db_session(): + async with db_module.async_session_factory() as session: + yield session + + +def _create(client: TestClient, *, label: str = "My phone", token: str = "bot-token-1"): + return client.post("/api/remote/connections", json={"label": label, "token": token}) + + +# ── list / create ──────────────────────────────────────────────────────── + + +def test_list_connections_empty(client: TestClient) -> None: + resp = client.get("/api/remote/connections") + assert resp.status_code == 200 + assert resp.json() == [] + + +def test_create_connection_success(client: TestClient) -> None: + resp = _create(client) + assert resp.status_code == 201 + body = resp.json() + assert body["label"] == "My phone" + assert body["adapter"] == "telegram" + assert body["adapter_principal_id"] == "bot-1" + assert body["adapter_username"] == "my_bot" + assert body["enabled"] is False + assert body["token_configured"] is True + assert "token" not in body + assert body["status"]["state"] == "disabled" + remote_routes.remote_runtime.reconcile_connection.assert_awaited_once_with( + UUID(body["id"]) + ) + + +def test_create_connection_invalid_token_is_422(client: TestClient) -> None: + resp = _create(client, token="not-a-real-token") + assert resp.status_code == 422 + remote_routes.remote_runtime.reconcile_connection.assert_not_awaited() + + +def test_create_second_connection_conflicts_409(client: TestClient) -> None: + first = _create(client) + assert first.status_code == 201 + + second = _create(client, label="Second phone", token="bot-token-2-same-bot") + assert second.status_code == 409 + + +def test_list_connections_returns_created(client: TestClient) -> None: + _create(client) + resp = client.get("/api/remote/connections") + assert resp.status_code == 200 + body = resp.json() + assert len(body) == 1 + assert body[0]["label"] == "My phone" + + +# ── patch ──────────────────────────────────────────────────────────────── + + +def test_patch_updates_label_and_enabled(client: TestClient) -> None: + connection_id = _create(client).json()["id"] + + resp = client.patch( + f"/api/remote/connections/{connection_id}", + json={"label": "Renamed", "enabled": True}, + ) + + assert resp.status_code == 200 + body = resp.json() + assert body["label"] == "Renamed" + assert body["enabled"] is True + remote_routes.remote_runtime.reconcile_connection.assert_awaited_with( + UUID(connection_id) + ) + + +def test_patch_rejects_unknown_field_422(client: TestClient) -> None: + connection_id = _create(client).json()["id"] + + resp = client.patch( + f"/api/remote/connections/{connection_id}", json={"token": "sneaky-token"} + ) + + assert resp.status_code == 422 + + +def test_patch_missing_connection_404(client: TestClient) -> None: + resp = client.patch(f"/api/remote/connections/{uuid4()}", json={"label": "x"}) + assert resp.status_code == 404 + + +def test_patch_invalid_uuid_422(client: TestClient) -> None: + resp = client.patch("/api/remote/connections/not-a-uuid", json={"label": "x"}) + assert resp.status_code == 422 + + +# ── token replace ──────────────────────────────────────────────────────── + + +def test_replace_token_success(client: TestClient) -> None: + connection_id = _create(client).json()["id"] + + resp = client.put( + f"/api/remote/connections/{connection_id}/token", + json={"token": "bot-token-2-same-bot"}, + ) + + assert resp.status_code == 200 + body = resp.json() + assert body["adapter_username"] == "my_bot_renamed" + assert body["token_configured"] is True + assert "token" not in body + + +def test_replace_token_invalid_is_422(client: TestClient) -> None: + connection_id = _create(client).json()["id"] + + resp = client.put( + f"/api/remote/connections/{connection_id}/token", + json={"token": "not-a-real-token"}, + ) + + assert resp.status_code == 422 + + +def test_replace_token_missing_connection_404(client: TestClient) -> None: + resp = client.put( + f"/api/remote/connections/{uuid4()}/token", json={"token": "bot-token-1"} + ) + assert resp.status_code == 404 + + +# ── remove ─────────────────────────────────────────────────────────────── + + +def test_remove_connection(client: TestClient) -> None: + connection_id = _create(client).json()["id"] + + resp = client.delete(f"/api/remote/connections/{connection_id}") + + assert resp.status_code == 204 + assert client.get("/api/remote/connections").json() == [] + remote_routes.remote_runtime.reconcile_connection.assert_awaited_with( + UUID(connection_id) + ) + + +def test_remove_missing_connection_404(client: TestClient) -> None: + resp = client.delete(f"/api/remote/connections/{uuid4()}") + assert resp.status_code == 404 + + +# ── pairing links ──────────────────────────────────────────────────────── + + +def test_issue_pairing_link(client: TestClient) -> None: + connection_id = _create(client).json()["id"] + + resp = client.post(f"/api/remote/connections/{connection_id}/pairing-links") + + assert resp.status_code == 200 + body = resp.json() + assert body["url"].startswith("https://t.me/my_bot?start=") + assert body["qr_payload"] == body["url"] + assert "expires_at" in body + + +def test_issue_pairing_link_missing_connection_404(client: TestClient) -> None: + resp = client.post(f"/api/remote/connections/{uuid4()}/pairing-links") + assert resp.status_code == 404 + + +# ── pairing read/revoke ────────────────────────────────────────────────── + + +def test_get_pairing_none(client: TestClient) -> None: + connection_id = _create(client).json()["id"] + + resp = client.get(f"/api/remote/connections/{connection_id}/pairing") + + assert resp.status_code == 200 + assert resp.json() is None + + +def test_get_pairing_missing_connection_404(client: TestClient) -> None: + resp = client.get(f"/api/remote/connections/{uuid4()}/pairing") + assert resp.status_code == 404 + + +@pytest.mark.asyncio +async def test_get_pairing_returns_existing_pairing(client: TestClient, db_session) -> None: + connection_id = UUID(_create(client).json()["id"]) + pairing = RemotePairing( + connection_id=connection_id, + principal_id="user-1", + destination_id="user-1", + label="Alice's phone", + display="Alice", + ) + db_session.add(pairing) + await db_session.commit() + + resp = client.get(f"/api/remote/connections/{connection_id}/pairing") + + assert resp.status_code == 200 + body = resp.json() + assert body["label"] == "Alice's phone" + assert body["display"] == "Alice" + + +@pytest.mark.asyncio +async def test_revoke_pairing_removes_it(client: TestClient, db_session) -> None: + connection_id = UUID(_create(client).json()["id"]) + pairing = RemotePairing( + connection_id=connection_id, + principal_id="user-1", + destination_id="user-1", + label="Alice's phone", + display="Alice", + ) + db_session.add(pairing) + await db_session.commit() + + resp = client.delete(f"/api/remote/connections/{connection_id}/pairing") + assert resp.status_code == 204 + + after = client.get(f"/api/remote/connections/{connection_id}/pairing") + assert after.json() is None + + +def test_revoke_pairing_missing_connection_404(client: TestClient) -> None: + resp = client.delete(f"/api/remote/connections/{uuid4()}/pairing") + assert resp.status_code == 404 + + +# ── status ─────────────────────────────────────────────────────────────── + + +def test_get_connection_status(client: TestClient) -> None: + connection_id = _create(client).json()["id"] + + resp = client.get(f"/api/remote/connections/{connection_id}/status") + + assert resp.status_code == 200 + body = resp.json() + assert body["connection_id"] == connection_id + assert body["state"] == "disabled" + assert body["paired"] is False + assert body["last_error_class"] == "none" + + +def test_get_connection_status_missing_connection_404(client: TestClient) -> None: + resp = client.get(f"/api/remote/connections/{uuid4()}/status") + assert resp.status_code == 404 + + +def test_get_connection_status_invalid_uuid_422(client: TestClient) -> None: + resp = client.get("/api/remote/connections/not-a-uuid/status") + assert resp.status_code == 422 + + +# ── OpenAPI: no returned token fields, no realistic example ───────────── + + +def test_openapi_exposes_no_token_in_any_response_schema(app: FastAPI) -> None: + schema = app.openapi() + schemas = schema["components"]["schemas"] + + request_schemas_with_token = { + "RemoteConnectionCreateRequest", + "RemoteConnectionTokenReplaceRequest", + } + for name, definition in schemas.items(): + properties = definition.get("properties", {}) + if "token" not in properties: + continue + assert name in request_schemas_with_token, ( + f"{name} unexpectedly exposes a raw 'token' field" + ) + + assert "token_configured" in schemas["RemoteConnectionResponse"]["properties"] + assert "token" not in schemas["RemoteConnectionResponse"]["properties"] + + +def test_openapi_token_example_is_not_realistic(app: FastAPI) -> None: + schema = app.openapi() + definition = schema["components"]["schemas"]["RemoteConnectionCreateRequest"] + example = definition["properties"]["token"].get("example", "") + assert not _TELEGRAM_TOKEN_SHAPE.match(example) + + +# ── desktop authentication ─────────────────────────────────────────────── + + +def test_remote_routes_require_desktop_token(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setenv("EVOFLUX_DESKTOP_TOKEN", "secret-desktop-token") + from app.api.app import create_app + + real_app_client = TestClient(create_app()) + + unauthenticated = real_app_client.get("/api/remote/connections") + assert unauthenticated.status_code == 401 + + authenticated = real_app_client.get( + "/api/remote/connections", + headers={"Authorization": "Bearer secret-desktop-token"}, + ) + assert authenticated.status_code == 200 diff --git a/tests/api/test_app_lifespan.py b/tests/api/test_app_lifespan.py index 948d4f1f..1196e34a 100644 --- a/tests/api/test_app_lifespan.py +++ b/tests/api/test_app_lifespan.py @@ -25,7 +25,12 @@ def test_app_import_keeps_optional_runtime_modules_lazy() -> None: "print('app.agent.agent_loop.core' in sys.modules); " "print('app.agent.tools.builtin.browser_use_tool' in sys.modules); " "print('app.agent.tools.builtin.webbridge_tool' in sys.modules); " - "print('app.services.code_index.project' in sys.modules)" + "print('app.services.code_index.project' in sys.modules); " + # AC-1: with no enabled connection, importing app.api.app + # (which now registers the /api/remote routes) must never + # pull either Telegram module into sys.modules. + "print('app.remote.telegram.adapter' in sys.modules); " + "print('app.remote.telegram.client' in sys.modules)" ), ], capture_output=True, @@ -41,6 +46,8 @@ def test_app_import_keeps_optional_runtime_modules_lazy() -> None: "False", "False", "True", + "False", + "False", ] @@ -131,3 +138,77 @@ async def test_lifespan_starts_configured_services( app_module.mcp_manager.start.assert_awaited_once() app_module.task_scheduler.start.assert_awaited_once() slim_lifespan.start.assert_awaited_once() + + +def _quiet_optional_services(monkeypatch: pytest.MonkeyPatch) -> None: + """Silence the other optional services so a remote-runtime test isn't + coupled to their behavior.""" + monkeypatch.setattr(app_module.mcp_manager, "start", AsyncMock()) + monkeypatch.setattr( + app_module.task_scheduler, "has_enabled_tasks", AsyncMock(return_value=False) + ) + monkeypatch.setattr(app_module.task_scheduler, "start", AsyncMock()) + + +@pytest.mark.asyncio +async def test_lifespan_starts_remote_runtime( + monkeypatch: pytest.MonkeyPatch, slim_lifespan +) -> None: + """The remote runtime is started alongside the other optional services + (AC-1's lazy behavior itself is proven in tests/remote/test_runtime.py; + this only proves the lifespan actually calls ``start()``).""" + _quiet_optional_services(monkeypatch) + from app.remote.runtime import remote_runtime + + start_mock = AsyncMock() + monkeypatch.setattr(remote_runtime, "start", start_mock) + + app = await _run_lifespan() + + start_mock.assert_awaited_once() + assert app.state.optional_services_ready is True + + +@pytest.mark.asyncio +async def test_lifespan_remote_runtime_start_failure_keeps_health_ready( + monkeypatch: pytest.MonkeyPatch, slim_lifespan +) -> None: + """A remote-runtime startup failure must not fail app startup or health + readiness — it is wrapped the same defensive way every other optional + service is in ``_start_optional_services``.""" + _quiet_optional_services(monkeypatch) + from app.remote.runtime import remote_runtime + + monkeypatch.setattr( + remote_runtime, "start", AsyncMock(side_effect=RuntimeError("boom")) + ) + + app = await _run_lifespan() + + assert app.state.optional_services_ready is True + + +@pytest.mark.asyncio +async def test_lifespan_shutdown_stops_remote_runtime( + monkeypatch: pytest.MonkeyPatch, slim_lifespan +) -> None: + """``remote_runtime.stop()`` runs during shutdown — after the optional + startup task has been awaited/cancelled — placed next to the existing + Conductor/Scheduler cleanup calls.""" + _quiet_optional_services(monkeypatch) + from app.remote.runtime import remote_runtime + + start_mock = AsyncMock() + stop_mock = AsyncMock() + monkeypatch.setattr(remote_runtime, "start", start_mock) + monkeypatch.setattr(remote_runtime, "stop", stop_mock) + + app = FastAPI() + async with app_module.lifespan(app): + await app.state.optional_startup_task + # Still "up": shutdown has not run yet, so stop() must not have + # fired even though startup already completed. + stop_mock.assert_not_awaited() + + start_mock.assert_awaited_once() + stop_mock.assert_awaited_once() diff --git a/tests/remote/test_runtime.py b/tests/remote/test_runtime.py new file mode 100644 index 00000000..521bcb62 --- /dev/null +++ b/tests/remote/test_runtime.py @@ -0,0 +1,334 @@ +"""Tests for app/remote/runtime.py — the lazy-starting remote runtime. + +Exercises ``RemoteRuntime.start/stop/reconcile_connection/status`` through +the process singleton (``remote_runtime``), with its adapter-construction +and credential-store seams monkeypatched to fakes so no real network call, +OS vault write, or Telegram import happens for the "enabled" cases. The +AC-1 test below deliberately uses the *unmodified* singleton against an +empty database to prove the disabled path never imports Telegram. +""" + +from __future__ import annotations + +import sys +from uuid import UUID, uuid4 + +import pytest +import pytest_asyncio + +import app.core.db as db_module +from app.models.remote import RemoteConnection +from app.remote.contracts import RemoteAdapterStatus, RemoteConnectionState +from app.remote.runtime import remote_runtime + + +class FakeCredentialStore: + """In-memory stand-in for one connection's vault entry.""" + + def __init__(self, token: str | None) -> None: + self._token = token + + def load(self) -> str | None: + return self._token + + def save(self, credential: str) -> None: # pragma: no cover - unused here + self._token = credential + + def delete(self) -> None: # pragma: no cover - unused here + self._token = None + + +class FakeAdapter: + """In-memory stand-in for ``RemoteAdapter`` — no network, no task.""" + + def __init__(self, *, connection_id: UUID, token: str) -> None: + self.connection_id = connection_id + self.token = token + self.started = False + self.stopped = False + + async def start(self) -> None: + self.started = True + + async def stop(self) -> None: + self.stopped = True + + async def send(self, message) -> None: # pragma: no cover - unused here + raise NotImplementedError + + async def edit(self, message) -> None: # pragma: no cover - unused here + raise NotImplementedError + + async def answer_callback(self, callback_token: str) -> None: # pragma: no cover + raise NotImplementedError + + def status(self) -> RemoteAdapterStatus: + state = RemoteConnectionState.POLLING if self.started and not self.stopped else ( + RemoteConnectionState.DISABLED + ) + return RemoteAdapterStatus(connection_id=self.connection_id, state=state) + + +@pytest_asyncio.fixture(autouse=True) +async def _reset_runtime(): + """The runtime under test is the real process singleton — make sure no + fake adapter or monkeypatched seam leaks into another test file.""" + yield + await remote_runtime.stop() + + +@pytest_asyncio.fixture +async def session(): + async with db_module.async_session_factory() as db_session: + yield db_session + + +@pytest.fixture +def fake_stores() -> dict[UUID, FakeCredentialStore]: + return {} + + +@pytest.fixture +def fake_adapters() -> list[FakeAdapter]: + return [] + + +@pytest.fixture(autouse=True) +def _patch_seams(monkeypatch, fake_stores, fake_adapters): + """Replace the runtime's Telegram-facing seams with fakes for every + test in this module except the AC-1 one, which restores the real + (default) seams itself to prove the production wiring never imports + Telegram when nothing is configured.""" + + def credential_store_factory(connection_id: UUID) -> FakeCredentialStore: + return fake_stores.setdefault(connection_id, FakeCredentialStore(None)) + + def adapter_constructor(connection_id: UUID, token: str, on_action): + adapter = FakeAdapter(connection_id=connection_id, token=token) + fake_adapters.append(adapter) + return adapter + + monkeypatch.setattr(remote_runtime, "_credential_store_factory", credential_store_factory) + monkeypatch.setattr(remote_runtime, "_adapter_constructor", adapter_constructor) + + +async def _make_connection( + session, *, enabled: bool = True, principal_id: str = "bot-1" +) -> RemoteConnection: + connection = RemoteConnection( + adapter="telegram", + label="My phone", + enabled=enabled, + adapter_principal_id=principal_id, + adapter_username="my_bot", + ) + session.add(connection) + await session.commit() + await session.refresh(connection) + return connection + + +# ── AC-1: off and free by default ─────────────────────────────────────────── + + +@pytest.mark.asyncio +async def test_disabled_start_does_not_import_telegram(monkeypatch) -> None: + # Undo this module's autouse fake-seam patch for this one test — it must + # prove the *real* production wiring (real TelegramAdapterFactory / + # default_credential_store_factory / _construct_telegram_adapter), + # against a genuinely empty connections table, never imports Telegram. + from app.remote.connection_service import default_credential_store_factory + from app.remote.runtime import _construct_telegram_adapter + + monkeypatch.setattr( + remote_runtime, "_credential_store_factory", default_credential_store_factory + ) + monkeypatch.setattr(remote_runtime, "_adapter_constructor", _construct_telegram_adapter) + + sys.modules.pop("app.remote.telegram.adapter", None) + sys.modules.pop("app.remote.telegram.client", None) + + await remote_runtime.start() + + assert "app.remote.telegram.adapter" not in sys.modules + assert "app.remote.telegram.client" not in sys.modules + assert remote_runtime.status(uuid4()).state == RemoteConnectionState.DISABLED + + +@pytest.mark.asyncio +async def test_start_noop_when_no_connection_exists(fake_adapters) -> None: + await remote_runtime.start() + + assert fake_adapters == [] + + +@pytest.mark.asyncio +async def test_start_noop_when_connection_disabled(session, fake_adapters) -> None: + await _make_connection(session, enabled=False) + + await remote_runtime.start() + + assert fake_adapters == [] + + +@pytest.mark.asyncio +async def test_start_noop_when_credential_missing(session, fake_adapters) -> None: + # enabled, but no token was ever saved to (the fake) vault + await _make_connection(session, enabled=True) + + await remote_runtime.start() + + assert fake_adapters == [] + + +# ── start() for an enabled, credentialed connection ───────────────────────── + + +@pytest.mark.asyncio +async def test_start_constructs_and_starts_adapter(session, fake_stores, fake_adapters) -> None: + connection = await _make_connection(session, enabled=True) + fake_stores[connection.id] = FakeCredentialStore("secret-token") + + await remote_runtime.start() + + assert len(fake_adapters) == 1 + adapter = fake_adapters[0] + assert adapter.connection_id == connection.id + assert adapter.token == "secret-token" + assert adapter.started is True + assert remote_runtime.status(connection.id).state == RemoteConnectionState.POLLING + + +@pytest.mark.asyncio +async def test_start_is_idempotent_while_already_running( + session, fake_stores, fake_adapters +) -> None: + connection = await _make_connection(session, enabled=True) + fake_stores[connection.id] = FakeCredentialStore("secret-token") + + await remote_runtime.start() + await remote_runtime.start() + + assert len(fake_adapters) == 1 + + +# ── stop() ─────────────────────────────────────────────────────────────── + + +@pytest.mark.asyncio +async def test_stop_is_safe_before_start_was_ever_called() -> None: + await remote_runtime.stop() # must not raise + + assert remote_runtime.status(uuid4()).state == RemoteConnectionState.DISABLED + + +@pytest.mark.asyncio +async def test_stop_stops_the_running_adapter(session, fake_stores, fake_adapters) -> None: + connection = await _make_connection(session, enabled=True) + fake_stores[connection.id] = FakeCredentialStore("secret-token") + await remote_runtime.start() + + await remote_runtime.stop() + + assert fake_adapters[0].stopped is True + assert remote_runtime.status(connection.id).state == RemoteConnectionState.DISABLED + + +@pytest.mark.asyncio +async def test_stop_is_idempotent(session, fake_stores, fake_adapters) -> None: + connection = await _make_connection(session, enabled=True) + fake_stores[connection.id] = FakeCredentialStore("secret-token") + await remote_runtime.start() + + await remote_runtime.stop() + await remote_runtime.stop() # must not raise a second time + + assert fake_adapters[0].stopped is True + + +# ── reconcile_connection() ─────────────────────────────────────────────── + + +@pytest.mark.asyncio +async def test_reconcile_starts_a_newly_enabled_connection( + session, fake_stores, fake_adapters +) -> None: + connection = await _make_connection(session, enabled=False) + fake_stores[connection.id] = FakeCredentialStore("secret-token") + await remote_runtime.start() + assert fake_adapters == [] + + connection.enabled = True + session.add(connection) + await session.commit() + await remote_runtime.reconcile_connection(connection.id) + + assert len(fake_adapters) == 1 + assert fake_adapters[0].started is True + + +@pytest.mark.asyncio +async def test_reconcile_stops_a_newly_disabled_connection( + session, fake_stores, fake_adapters +) -> None: + connection = await _make_connection(session, enabled=True) + fake_stores[connection.id] = FakeCredentialStore("secret-token") + await remote_runtime.start() + assert len(fake_adapters) == 1 + + connection.enabled = False + session.add(connection) + await session.commit() + await remote_runtime.reconcile_connection(connection.id) + + assert fake_adapters[0].stopped is True + # No second adapter was constructed for the now-disabled connection. + assert len(fake_adapters) == 1 + assert remote_runtime.status(connection.id).state == RemoteConnectionState.DISABLED + + +@pytest.mark.asyncio +async def test_reconcile_restarts_with_a_replaced_token( + session, fake_stores, fake_adapters +) -> None: + connection = await _make_connection(session, enabled=True) + fake_stores[connection.id] = FakeCredentialStore("old-token") + await remote_runtime.start() + assert fake_adapters[0].token == "old-token" + + fake_stores[connection.id] = FakeCredentialStore("new-token") + await remote_runtime.reconcile_connection(connection.id) + + assert fake_adapters[0].stopped is True + assert len(fake_adapters) == 2 + assert fake_adapters[1].token == "new-token" + assert fake_adapters[1].started is True + + +@pytest.mark.asyncio +async def test_reconcile_after_removal_leaves_nothing_running( + session, fake_stores, fake_adapters +) -> None: + connection = await _make_connection(session, enabled=True) + fake_stores[connection.id] = FakeCredentialStore("secret-token") + await remote_runtime.start() + assert len(fake_adapters) == 1 + + await session.delete(await session.get(RemoteConnection, connection.id)) + await session.commit() + await remote_runtime.reconcile_connection(connection.id) + + assert fake_adapters[0].stopped is True + assert len(fake_adapters) == 1 + assert remote_runtime.status(connection.id).state == RemoteConnectionState.DISABLED + + +# ── status() ───────────────────────────────────────────────────────────── + + +@pytest.mark.asyncio +async def test_status_for_unknown_connection_is_disabled() -> None: + status = remote_runtime.status(uuid4()) + + assert status.state == RemoteConnectionState.DISABLED + assert status.last_error_class.value == "none" From 8711b1ee14bc521a553b378cae6d5d857866b856 Mon Sep 17 00:00:00 2001 From: manhnguyen24-dev Date: Mon, 14 Sep 2026 20:14:23 +0700 Subject: [PATCH 09/71] docs(remote): spec rich Telegram responses, live status, and settings Adds documents/plans/remote-telegram-response-ui.md, a proposed design that completes the accepted remote-channel-telegram.md feature with HTML-formatted messages, a typing-indicator status lifecycle, cross-origin completion notifications, a guided project/prompt picker, and a read-mostly /settings view. Explicitly amends AC-24 (parse mode) and the outbound-redaction portion of AC-32/Non-goals, with a cross-reference note added to the original spec. --- .gitignore | 2 + documents/plans/remote-channel-telegram.md | 5 + .../plans/remote-telegram-response-ui.md | 353 ++++++++++++++++++ 3 files changed, 360 insertions(+) create mode 100644 documents/plans/remote-telegram-response-ui.md diff --git a/.gitignore b/.gitignore index fe8d6ac0..7fee66b9 100644 --- a/.gitignore +++ b/.gitignore @@ -279,3 +279,5 @@ desktop/EvoFlux.key.pub MiMo-Code/ # Local dev state. /.local/ + +.superpowers/ diff --git a/documents/plans/remote-channel-telegram.md b/documents/plans/remote-channel-telegram.md index e9114198..a257f910 100644 --- a/documents/plans/remote-channel-telegram.md +++ b/documents/plans/remote-channel-telegram.md @@ -2,6 +2,11 @@ Status: proposed +> **Amended by `documents/plans/remote-telegram-response-ui.md`:** AC-24 (no +> parse mode) and the outbound-data-policy portion of Non-goals/AC-32 are +> revised there. Read that document's amendment note before treating those +> two items as current. + ## Problem and outcome EvoFlux is a local-first desktop application. The Tauri shell starts the diff --git a/documents/plans/remote-telegram-response-ui.md b/documents/plans/remote-telegram-response-ui.md new file mode 100644 index 00000000..39c817a2 --- /dev/null +++ b/documents/plans/remote-telegram-response-ui.md @@ -0,0 +1,353 @@ +# Remote Telegram: rich responses, live status, and settings visibility + +Status: proposed + +**Amends `documents/plans/remote-channel-telegram.md`.** That document remains +normative for everything not listed below. This document changes exactly two +of its accepted contracts and adds new, additive scope on top of the rest: + +- **AC-24** (no Telegram parse mode) is revised to allow HTML parse mode under + a strict escaping rule. See Requirements. +- The **Non-goals** entry forbidding remote changes to "outbound-data policy" + and the matching clause in **AC-32** are narrowed to carve out outbound + redaction policy specifically. Model-provider configuration, sandbox policy, + connection settings, credentials, and `permission_mode` remain forbidden, + unchanged. +- **AC-20** and **AC-22** (event allowlist, quiet lifecycle) are **not** + amended; this document's status-card design is written to satisfy them as + written. + +## Problem and outcome + +Tasks 1-6 of the Telegram remote-access feature are complete; Tasks 7-9 +(stream projection, gate cards, secondary actions) are in progress and +currently send plain, unformatted text with no parse mode, no live status +before completion, and no way to see current model/permission/redaction state +from the phone. The bot's command surface is also narrower than its own +"Advanced actions" design: starting a Coding task requires already knowing +which project you want, with no prompt guidance for someone typing on a phone +keyboard. + +The outcome is a visibly better remote experience within the accepted +feature's existing boundaries: readable HTML-formatted messages instead of +raw text, a live "still working" feel via Telegram's native typing indicator, +completion notices for desktop-started and scheduled/workflow work (finishing +a Goal already stated but not yet built), a guided project-and-prompt picker +for starting new work from a phone, and a read-mostly `/settings` view. Two +narrow, explicit amendments to the accepted spec make the formatting and +redaction-visibility parts possible; everything else is completed within the +existing contract. + +## Goals + +- Render bot messages with Telegram HTML formatting (bold, code blocks, + links) instead of plain text, without weakening the existing anti-injection + guarantee. +- Give a phone-admitted turn a visible "working" feel using Telegram's native + typing indicator, without exceeding the existing one-lifecycle-message + budget or mirroring tool/content deltas. +- Complete the existing Goal of delivering completion notices for + desktop-started top-level sessions, and extend the same delivery to + Workflow/Scheduler runs that produce a user-visible top-level session. +- Let the user choose, per pairing, whether notifications cover every + addressable session or only ones the phone itself started. +- Add a read-mostly `/settings` view covering connection, current model, + permission mode, and outbound redaction policy. +- Allow outbound redaction policy — and only that setting — to be changed + from the phone, as a narrow, explicit amendment. +- Add a guided "pick a project, then pick or type a prompt" flow so starting + a Coding task from a phone needs minimal typing. +- Let the user pull a turn's own full diff or tool log on demand, without + turning the channel into a session browser. + +## Non-goals + +- No change to model-provider configuration, permission mode, sandbox policy, + connection settings, or credentials from the phone — this boundary from the + accepted spec is explicitly preserved, not just left alone by omission. +- No multi-turn session history browsing or transcript export. Drill-down + buttons return only the single most recent completed turn's own output. +- No new "always animate everything" mechanism. Only the typing indicator + animates; there is no per-tool-call progress text, spinner glyph cycling + inside an edited message, or additional lifecycle messages. +- No change to the one-connection/one-pairing v1 product limit, pairing flow, + gate mechanics, or callback-token ownership rules — all unchanged from the + accepted spec. +- No new durable notification log or outbox; notification delivery keeps the + accepted spec's best-effort, non-durable outbound guarantee. + +## User flows and states + +### Receiving a formatted response + +Every outbound message (status, done, error, gate, settings, picker) is built +by one shared rendering layer and sent with Telegram's HTML parse mode. Task +titles, file paths, diffs, and tool output render in ``/`
` blocks;
+labels render in ``; nothing else uses formatting. Every value that did not
+originate as a static string written by `formatting.py` is escaped with
+`html.escape` before it is placed inside any tag, including already-redacted
+agent text — redaction happens first, escaping happens last, in that order.
+
+### Watching a turn run
+
+When a phone-admitted turn is accepted, the bot sends one status message
+containing the task title and starts Telegram's native typing indicator
+(`sendChatAction`, re-issued roughly every 4 seconds, since Telegram clears it
+automatically after about 5). The status message is edited — not resent — on
+each of the existing lifecycle transitions (accepted → queued → running →
+done/error), exactly as today's accepted design already allows; the only
+content change is that the running-state text shows the task title and
+elapsed time and nothing else. No individual tool call, file edit, or content
+delta is ever mirrored into the message, preserving the existing event
+allowlist. The typing indicator stops the moment the turn reaches a terminal
+state, is interrupted, or the adapter shuts down.
+
+Desktop-started sessions and Workflow/Scheduler runs never had a live turn
+observed from the remote side, so they never get a status message or typing
+indicator — they go straight to a single done/error card when the run
+finishes, matching the "no activity chatter" rule that already applies to
+desktop tasks today.
+
+### Seeing the outcome
+
+The done card shows a compact summary: files changed with +/- counts, a tool
+call count, and (when applicable) a bounded test-result excerpt — all sourced
+from the turn's already-persisted, already-redacted final state, not
+reconstructed from streamed deltas. Two buttons, **Full diff** and **Tool
+log**, are attached. Tapping one fetches that same turn's own persisted
+diff/log content (nothing from any other turn or session), redacts it through
+the existing outbound policy, chunks it exactly like today's long-message
+splitting, and sends it as a follow-up message. The buttons use the existing
+opaque, expiring capability-token mechanism and carry no session ID, path, or
+content in their callback data.
+
+The error card shows the error text and a **Tool log** button on the same
+terms; it does not add a remote retry mechanism beyond what already exists.
+
+### Getting notified for work started elsewhere
+
+`RemotePairing` gains a `notify_scope` preference (`all` or `remote_only`,
+default `all`). When `all`, `RemoteProjection` observes every addressable
+top-level session regardless of where it started — completing the accepted
+spec's stated Goal of notifying about desktop-started tasks, which the
+current Task 7 implementation has not yet built. It also observes
+Workflow/Scheduler runs that produce a user-visible top-level session,
+sending the same bounded completion card, with no live status phase. When
+`remote_only`, observation is scoped to `remote_origin`-tagged sessions only,
+matching today's narrower behavior. The preference is changeable from
+`/settings` and takes effect on the next observed event, with no restart.
+
+### Checking settings from the phone
+
+`/settings` renders: the paired connection's label and username; the current
+session's model and permission mode, both as plain read-only text with no
+buttons; the current outbound redaction policy (`strict`/`standard`/`off`)
+with buttons to change it; and the current `notify_scope` with a toggle.
+Changing redaction policy calls the existing `PUT /api/settings/remote`
+contract — `/settings` is a new surface for an existing setting, not a new
+setting. No other value in the card is writable.
+
+### Starting a task with guidance
+
+`/new` (and the "Coding projects" entry in the existing secondary menu) is
+extended: after picking a project, the bot shows a short list of suggested
+prompts for that project — a fixed curated set ("Fix failing tests", "Review
+my changes", "Add a feature…") plus, when a prior session exists for that
+project, a "Continue last session" option — alongside the existing ability to
+just type a free-form message. Selecting a suggestion starts the task with
+that text; typing anything at any point works exactly as it does today.
+Project selection is still bounded to existing authorized Coding projects,
+unchanged from the accepted spec.
+
+## Requirements and acceptance criteria
+
+IDs continue from the accepted spec's AC-37. AC-24 and AC-32 below are
+revisions of the originals; all others are new.
+
+- **AC-24 (revised) — Safe HTML rendering:** Messages are sent with Telegram
+  HTML parse mode. Every field not authored as a static string inside
+  `app/remote/formatting.py` is passed through `html.escape` before
+  interpolation, applied after outbound redaction. Tests prove that
+  adversarial content — literal `<`, `>`, `&`, and strings that resemble tags
+  — can never alter the rendered message structure, add a link, or add a
+  mention. Splitting stays within Telegram's 4096-character limit and remains
+  Unicode-safe.
+- **AC-32 (revised) — No remote secrets or settings writes, redaction
+  excepted:** No Telegram command, menu action, or natural-language shortcut
+  accepts a credential value or changes connection/provider/sandbox settings
+  or `permission_mode`. Outbound redaction policy (`outbound_data_policy`,
+  `outbound_pii_policy`) is the sole exception and may be changed only through
+  `/settings` calling the existing `PUT /api/settings/remote` contract. Status
+  output contains no environment values or secret presence details beyond the
+  current connection's configured state.
+- **AC-38 — Bounded lifecycle liveliness:** A phone-admitted turn's status
+  message is edited only on accepted/queued/running/done/error transitions,
+  never more often. A repeating `sendChatAction(typing)` runs only while that
+  same turn is unresolved and is never counted as, or substitutes for, a
+  message. Running-state text contains only the task title and elapsed time;
+  no tool call, file path, or content delta is ever mirrored into it.
+- **AC-39 — Bounded on-demand detail:** "Full diff" and "Tool log" return
+  only the current turn's own already-persisted, already-redacted output,
+  chunked like any other outbound message, expiring on the same TTL as other
+  capability tokens. They never return another turn's or another session's
+  content, and no new durable content store is introduced.
+- **AC-40 — Guided task start:** The project-picker/prompt-suggestion flow
+  offers only existing authorized Coding projects (unchanged authorization
+  boundary) plus a curated static prompt set and, when applicable, one
+  dynamic "Continue last session" suggestion. Free-form text remains accepted
+  at every step; no suggestion is mandatory.
+- **AC-41 — Read-only model and permission visibility:** `/settings` displays
+  the current session's model and permission mode as plain text. No command,
+  button, or callback in the entire remote surface can change either value.
+- **AC-42 — Notification scope preference:** `RemotePairing.notify_scope`
+  (`all` default, `remote_only`) governs whether `RemoteProjection` observes
+  every addressable top-level session or only `remote_origin`-tagged ones.
+  Changing it via `/settings` takes effect on the next observed event with no
+  restart required.
+- **AC-43 — Cross-origin completion delivery:** With `notify_scope=all`, a
+  desktop-started top-level session and a Workflow/Scheduler run that
+  produces a user-visible top-level session both deliver the same bounded
+  completion/error card a phone-started turn would get. Neither ever receives
+  a live status message or typing indicator, since no turn was observed from
+  the remote side for either.
+- **AC-44 — Redaction visibility and control:** `/settings` shows the current
+  `outbound_data_policy`/`outbound_pii_policy` value and offers buttons to
+  change it, calling the existing settings service; the displayed value and
+  the enforced value never diverge.
+
+## API, event, tool, and UI contracts
+
+### New module
+
+`app/remote/formatting.py` — the single place literal HTML tags are written.
+Exposes one escaping helper and one builder function per card type (`status`,
+`done`, `error`, `gate`, `settings`, `project_picker`, `prompt_suggestions`),
+each returning `(html_text: str, buttons: list[RemoteButton] | None)`.
+`outbound.py`, `gates.py`, and `actions.py` call these builders instead of
+constructing text/redaction calls themselves, retiring the duplicated
+`_redact_text` helpers in favor of one redact-then-escape pipeline.
+
+### Telegram client
+
+`TelegramClient.send_text`/`edit_text` always pass `parse_mode="HTML"`.
+`TelegramClient` gains `send_chat_action(chat_id, action="typing")`, a thin
+wrapper over the Bot API's `sendChatAction`.
+
+### Commands
+
+`_SLASH_COMMANDS` in `actions.py` gains `settings`. `/new` and the existing
+Coding-project entry in the secondary menu route through the new
+project-picker/prompt-suggestion builders before falling through to today's
+session-creation call. Drill-down buttons register three new capability
+action codes (`diff`, `toollog`, `notify_scope`, `redaction`) in the existing
+opaque-token dispatch used by Tasks 8-9 — no new token mechanism.
+
+### Stream observation
+
+`RemoteProjection.observe` (outbound.py) changes its session filter from
+"tagged `remote_origin`" to "addressable top-level session, and (tagged
+`remote_origin` OR pairing's `notify_scope == "all"`)". A second, similarly
+gated hook is added where Workflow/Scheduler run completion already publishes
+its own terminal event (exact integration point to confirm during planning —
+if no such event currently reaches `memory_stream_store`, one is added
+following the existing `desktop_notification` pattern rather than inventing a
+parallel channel).
+
+## Data model, migration, and retention
+
+One migration adds `notify_scope` (bounded enum, default `all`) to
+`remote_pairings`. No other schema change. Redaction policy already persists
+via existing settings storage; model and permission mode are read from
+existing session/team configuration, not duplicated.
+
+Per the accepted spec's retention model, the in-memory `status_message_id`
+and lifecycle state per turn remain ephemeral (already anticipated as
+"progress-message IDs" in the accepted spec's retention section). Diff/tool-log
+content shown via drill-down is read from existing persisted turn data under
+existing session retention — no new content store, no new retention policy.
+
+## Permissions, security, privacy, and trust
+
+The HTML-escaping rule in AC-24 (revised) is the load-bearing safety property
+for the entire formatting change: it replaces "no parse mode" with "no
+unescaped interpolation," which must hold for every card, including error
+text and tool-log content, since those can contain arbitrary agent- or
+tool-produced strings. `formatting.py`'s tests are the primary evidence for
+this guarantee, not the individual call sites.
+
+The redaction-policy carve-out (AC-32 revised) is deliberately narrow: it
+changes how aggressively outbound content is *hidden*, never what the phone
+can *cause* the installation to do. It cannot be used to weaken any other
+boundary — model, permission mode, sandbox, and connection configuration stay
+exactly as forbidden as before.
+
+Drill-down content passes through the same outbound redaction pipeline as
+every other field; a `block` policy decision produces the same fixed
+withheld-content stub used elsewhere, not a bypass.
+
+## Concurrency, failure, recovery, and idempotency
+
+The typing-indicator timer is owned by the same per-turn lifecycle that owns
+the status message; it is cancelled wherever that lifecycle already tears
+down today (completion, error, interrupt, adapter shutdown, pairing removal),
+so no new failure mode is introduced — a missed `sendChatAction` call is
+logged and ignored, never retried aggressively, since Telegram's own indicator
+timeout already bounds the damage of a missed refresh.
+
+A drill-down tap for a turn whose persisted diff/log is no longer available
+(pruned, or the session was deleted) returns the same friendly "no longer
+available" reply used for other expired-capability cases, not a silent
+failure or a stack trace.
+
+Cross-origin notification (AC-43) reuses the existing bounded, non-blocking
+observer contract (AC-19) unchanged; widening which sessions are observed
+does not change how observation is performed.
+
+## Observability and diagnostics
+
+Status/metrics gain: `notify_scope` distribution across active pairings,
+typing-indicator send success/failure counts, and drill-down button
+usage/expiry counts. None of these labels carry session, path, or content
+data, consistent with the accepted spec's existing metric-label rules.
+
+## Compatibility, rollout, and rollback
+
+Additive on top of Tasks 1-6 (complete) and layered into Tasks 7-9 (in
+progress, not yet shipped) rather than reopening finished work. Existing
+pairings default to `notify_scope=all` on migration, which is a behavior
+change from today's `remote_origin`-only projection — called out explicitly
+since it is the one default-on behavior change in this document; a user who
+wants the narrower, current behavior switches to `remote_only` in
+`/settings`. Everything else is opt-in by construction (buttons a user must
+tap) or purely presentational (HTML formatting, typing indicator).
+
+Rollback is the same disable/remove path as the accepted spec; no new
+irreversible state is created.
+
+## Verification matrix
+
+| AC | Evidence |
+|---|---|
+| AC-24 (revised) | `formatting.py` escaping unit tests with adversarial input; golden-output tests per card type; Unicode/4096-boundary splitting tests |
+| AC-32 (revised), AC-44 | `/settings` redaction-toggle round-trip tests against the existing settings service; refusal tests proving every other listed setting stays unwritable |
+| AC-38 | `RemoteProjection` lifecycle tests asserting exact edit count/timing and typing-indicator start/stop boundaries; AC-20 regression test proving no tool/content delta ever appears in status text |
+| AC-39 | Drill-down capability-token tests: correct turn scoping, redaction applied, expiry, and refusal of cross-turn/cross-session access |
+| AC-40 | Project-picker/prompt-suggestion flow tests: authorized-project-only listing, free-form fallback, dynamic suggestion presence/absence |
+| AC-41 | Inspection/dispatch test proving no code path can mutate model or permission mode from any remote command |
+| AC-42, AC-43 | `notify_scope` filtering tests across remote-origin, desktop-origin, and workflow/scheduler-origin sessions; no-status-message assertion for cross-origin completions |
+
+## Ownership and source map
+
+- Rendering layer: `app/remote/formatting.py` (new).
+- Telegram transport additions: `app/remote/telegram/client.py`.
+- Turn lifecycle and cross-origin observation: `app/remote/outbound.py`.
+- Commands, settings, guided picker, drill-down dispatch:
+  `app/remote/actions.py`.
+- Gate cards switch to the shared renderer: `app/remote/gates.py`.
+- Schema: one migration adding `remote_pairings.notify_scope`.
+- Workflow/Scheduler completion integration point: to be confirmed against
+  `app/workflow/` and `app/scheduler/` during planning.
+
+This document remains historical/proposed until implementation is verified
+and reconciled into current documentation, per the accepted spec's own
+lifecycle rules.

From bcc4ef1f157b28ddab0fc205d149ae7194d11abc Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Mon, 14 Sep 2026 20:36:30 +0700
Subject: [PATCH 10/71] feat(remote): Tasks 6-9 WIP -
 inbound/outbound/gates/actions

Natural-language ingress and current-task behavior (Task 6, complete),
plus in-progress work on stream projection (Task 7), gate cards (Task 8),
and secondary actions (Task 9) per documents/plans/remote-access-telegram-implementation.md.
Committed as-is to give the response-UI plan a stable base to branch from;
Tasks 7-9 test coverage is not yet complete.
---
 app/api/routes/remote.py                      |   16 +-
 app/remote/actions.py                         |  663 ++++++
 app/remote/gates.py                           |  442 ++++
 app/remote/inbound.py                         |  229 ++
 app/remote/outbound.py                        |  351 +++
 app/remote/pairing.py                         |   10 +
 app/remote/runtime.py                         |  240 +-
 app/remote/telegram/adapter.py                |   27 +-
 app/remote/telegram/client.py                 |   16 +-
 app/services/chat_service.py                  |   20 +-
 app/services/interactive_message_service.py   |   19 +-
 app/services/memory_stream_store.py           |   56 +-
 .../local-development-windows-macos.md        |  663 ++++++
 docs/development/project-deep-dive.md         |  713 ++++++
 docs/development/run-locally-quickstart.md    |  137 ++
 documents/architecture/system-overview.md     |    8 +
 documents/features/README.md                  |    1 +
 documents/features/remote-access.md           |  228 ++
 .../features/security-and-permissions.md      |   19 +
 documents/plans/remote-access-task-6-brief.md |  325 +++
 .../remote-access-telegram-implementation.md  |   38 +-
 ...ote-telegram-response-ui-implementation.md | 1973 +++++++++++++++++
 documents/reference/configuration.md          |    1 +
 documents/reference/http-api.md               |   33 +
 tests/remote/telegram/test_adapter.py         |   32 +-
 tests/remote/telegram/test_client.py          |   33 +-
 tests/remote/test_actions.py                  |  382 ++++
 tests/remote/test_gates.py                    |  530 +++++
 tests/remote/test_inbound.py                  |  434 ++++
 tests/remote/test_outbound.py                 |  293 +++
 tests/remote/test_pairing.py                  |   66 +-
 tests/remote/test_runtime.py                  |  166 +-
 tests/services/test_chat_service.py           |   33 +
 .../test_interactive_message_service.py       |   85 +-
 .../services/test_memory_stream_observers.py  |  139 ++
 web/src/api/client/remote.ts                  |  181 ++
 web/src/components/SettingsScreen.tsx         |    2 +
 .../components/settings/SettingsSidebar.tsx   |   12 +
 web/src/help/locales/en.ts                    |   77 +
 web/src/help/locales/ja.ts                    |   76 +
 web/src/help/locales/vi.ts                    |   74 +
 web/src/queries/index.ts                      |   10 +
 web/src/queries/keys.ts                       |    7 +
 web/src/queries/useRemoteQuery.ts             |  121 +
 web/src/routes/settings.remote-access.tsx     |  430 ++++
 45 files changed, 9318 insertions(+), 93 deletions(-)
 create mode 100644 app/remote/actions.py
 create mode 100644 app/remote/gates.py
 create mode 100644 app/remote/inbound.py
 create mode 100644 app/remote/outbound.py
 create mode 100644 docs/development/local-development-windows-macos.md
 create mode 100644 docs/development/project-deep-dive.md
 create mode 100644 docs/development/run-locally-quickstart.md
 create mode 100644 documents/features/remote-access.md
 create mode 100644 documents/plans/remote-access-task-6-brief.md
 create mode 100644 documents/plans/remote-telegram-response-ui-implementation.md
 create mode 100644 tests/remote/test_actions.py
 create mode 100644 tests/remote/test_gates.py
 create mode 100644 tests/remote/test_inbound.py
 create mode 100644 tests/remote/test_outbound.py
 create mode 100644 tests/services/test_memory_stream_observers.py
 create mode 100644 web/src/api/client/remote.ts
 create mode 100644 web/src/queries/useRemoteQuery.ts
 create mode 100644 web/src/routes/settings.remote-access.tsx

diff --git a/app/api/routes/remote.py b/app/api/routes/remote.py
index 90875310..9aa935d2 100644
--- a/app/api/routes/remote.py
+++ b/app/api/routes/remote.py
@@ -40,7 +40,7 @@
     default_credential_store_factory,
 )
 from app.remote.contracts import RemoteAdapterValidationError
-from app.remote.pairing import PairingService
+from app.remote.pairing import PairingService, pairing_service as _pairing_service
 from app.remote.runtime import TelegramAdapterFactory, remote_runtime
 
 router = APIRouter()
@@ -52,8 +52,14 @@
 # uses for its singleton. ``_credential_store_factory`` is a module-level
 # variable rather than a dependency because it is also used outside any
 # request (``_token_configured``) — tests monkeypatch it directly.
+#
+# ``_pairing_service`` is re-exported from ``app.remote.pairing`` rather than
+# constructed here: it must be the exact same process-wide instance the
+# Telegram adapter's inbound dispatch consumes tokens against
+# (``app/remote/runtime.py``), since pairing tokens live only in that
+# instance's memory. A second, locally-constructed ``PairingService()``
+# would silently never see a token this route mints.
 
-_pairing_service = PairingService()
 _credential_store_factory: CredentialStoreFactory = default_credential_store_factory
 
 
@@ -163,6 +169,8 @@ async def create_connection(
         raise HTTPException(status_code=503, detail=str(exc)) from exc
 
     await remote_runtime.reconcile_connection(connection.id)
+    # ``reconcile_connection`` uses the read pool internally, so it never
+    # contends with the request's write session under SQLite's pool-size-1.
     return await _connection_response(session, connection)
 
 
@@ -202,7 +210,9 @@ async def replace_token(
     ``RemoteConnectionService.update_token`` (AC-6, AC-10).
     """
     try:
-        connection = await service.update_token(session, connection_id, token=body.token)
+        connection = await service.update_token(
+            session, connection_id, token=body.token
+        )
     except RemoteConnectionNotFoundError as exc:
         raise HTTPException(status_code=404, detail=str(exc)) from exc
     except RemoteAdapterValidationError as exc:
diff --git a/app/remote/actions.py b/app/remote/actions.py
new file mode 100644
index 00000000..b43424c8
--- /dev/null
+++ b/app/remote/actions.py
@@ -0,0 +1,663 @@
+"""Remote secondary actions — slash commands and More-actions menus.
+
+Handles ``/help``, ``/status``, ``/new``, ``/stop``, ``/unpair``, and the
+**More actions** dispatch for Workflows, Coding projects, EASD runs, and
+Scheduler tasks.  Each menu loader returns bounded
+:class:`RemoteMenuItem` entries with opaque callback tokens; each action
+calls one existing service entry point and translates owning exceptions
+into safe remote messages.
+
+Design constraints (from spec):
+- Do not copy owner validation into this module.
+- Every callback token is opaque, connection/principal-bound, and <=64 bytes.
+- No command accepts credentials, repository paths, settings changes, or
+  arbitrary identifiers.
+"""
+
+from __future__ import annotations
+
+import secrets
+import time
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Literal
+from uuid import UUID
+
+from loguru import logger
+
+from app.remote.contracts import (
+    RemoteAdapter,
+    RemoteButton,
+    RemoteInboundAction,
+    RemoteOutboundMessage,
+    RemoteOutboundPriority,
+)
+from app.remote.pairing import PairingService
+
+if TYPE_CHECKING:
+    from app.remote.contracts import RemoteAdapterStatus
+
+__all__ = ["RemoteActionResult", "RemoteActionService", "RemoteMenuItem"]
+
+_MAX_CALLBACK_TOKEN_BYTES = 64
+_CAPABILITY_TTL_SECONDS = 600
+
+CommandName = Literal["start", "help", "status", "new", "stop", "unpair", "actions"]
+
+
+@dataclass(frozen=True)
+class RemoteActionResult:
+    """Bounded, adapter-neutral outcome for one slash command."""
+
+    status: str
+    text: str = ""
+
+
+@dataclass(frozen=True)
+class RemoteMenuItem:
+    """One bounded menu item for the More-actions list."""
+
+    token: str
+    label: str
+    description: str = ""
+
+
+@dataclass
+class _ActionCapability:
+    """Opaque capability record for a menu action."""
+
+    token: str
+    connection_id: UUID
+    principal_id: str
+    destination_id: str
+    session_id: str
+    action_kind: str
+    action_target: str
+    created_at: float = field(default_factory=time.monotonic)
+
+
+# ── Known commands ────────────────────────────────────────────────────────────
+
+_SLASH_COMMANDS: frozenset[str] = frozenset(
+    {"start", "help", "status", "new", "stop", "unpair", "actions"}
+)
+
+
+# ── Help text ─────────────────────────────────────────────────────────────────
+
+_HELP_TEXT = """Available commands:
+
+/help — Show this help
+/status — Show connection and current task status
+/new — Start a new task (clears current task)
+/stop — Stop the current running task
+/unpair — Unpair this phone from EvoFlux
+/actions — Show more actions (Workflows, Projects, Scheduler)
+
+Or just type a message to chat with your agent."""
+
+
+class RemoteActionService:
+    """Handles slash commands and More-actions dispatch for remote sessions.
+
+    Owned by the runtime.  Each method is called from the inbound handler
+    after authorization.
+    """
+
+    def __init__(
+        self,
+        *,
+        pairing_service: PairingService | None = None,
+        adapter: RemoteAdapter | None = None,
+        status_provider: "Callable[[], RemoteAdapterStatus] | None" = None,
+    ) -> None:
+        self._pairing_service = pairing_service or PairingService()
+        self._adapter = adapter
+        self._status_provider = status_provider
+        self._capabilities: dict[str, _ActionCapability] = {}
+        self._pending_by_token: dict[str, str] = {}
+
+    def set_adapter(self, adapter: RemoteAdapter | None) -> None:
+        self._adapter = adapter
+
+    def set_status_provider(
+        self, provider: "Callable[[], RemoteAdapterStatus]"
+    ) -> None:
+        self._status_provider = provider
+
+    # ── Command dispatch ──────────────────────────────────────────────────
+
+    async def dispatch_command(
+        self,
+        db: AsyncSession,
+        action: RemoteInboundAction,
+    ) -> RemoteActionResult:
+        """Dispatch a slash command from a remote inbound action.
+
+        ``action.text`` must start with ``/``.  Unknown commands return
+        bounded help.
+        """
+        text = (action.text or "").strip()
+        if not text.startswith("/"):
+            return RemoteActionResult(status="not_a_command")
+
+        parts = text.split(maxsplit=1)
+        command = parts[0][1:].lower()  # strip leading /
+        arg = parts[1].strip() if len(parts) > 1 else ""
+
+        if command == "help" or command == "start":
+            return await self._cmd_help(db, action)
+        elif command == "status":
+            return await self._cmd_status(db, action)
+        elif command == "new":
+            return await self._cmd_new(db, action)
+        elif command == "stop":
+            return await self._cmd_stop(db, action)
+        elif command == "unpair":
+            return await self._cmd_unpair(db, action)
+        elif command == "actions":
+            return await self._cmd_actions(db, action, arg)
+        else:
+            # Unknown command — return bounded help.
+            return await self._cmd_help(db, action)
+
+    async def handle_action_callback(
+        self,
+        action: RemoteInboundAction,
+    ) -> bool:
+        """Handle a callback from a More-actions menu.
+
+        Returns True if the callback was resolved, False if unknown.
+        """
+        token = action.callback_token
+        if not token:
+            return False
+
+        cap = self._capabilities.get(token)
+        if cap is None:
+            return False
+
+        if cap.connection_id != action.connection_id:
+            return False
+
+        if time.monotonic() - cap.created_at > _CAPABILITY_TTL_SECONDS:
+            self._discard(cap)
+            return False
+
+        # Acknowledge the callback.
+        if self._adapter is not None:
+            await self._adapter.answer_callback(token)
+
+        # Dispatch the action.
+        resolved = await self._execute_action(cap, action)
+        if resolved:
+            self._discard(cap)
+        return resolved
+
+    # ── Command implementations ────────────────────────────────────────────
+
+    async def _cmd_help(
+        self, db: AsyncSession, action: RemoteInboundAction
+    ) -> RemoteActionResult:
+        return RemoteActionResult(status="ok", text=_HELP_TEXT)
+
+    async def _cmd_status(
+        self, db: AsyncSession, action: RemoteInboundAction
+    ) -> RemoteActionResult:
+        pairing = await self._pairing_service.authorize(
+            db,
+            connection_id=action.connection_id,
+            principal_id=action.principal.principal_id,
+        )
+        if pairing is None:
+            return RemoteActionResult(status="unauthorized")
+
+        # Connection status.
+        status_text = "Connected"
+        if self._status_provider is not None:
+            adapter_status = self._status_provider()
+            status_text = f"Status: {adapter_status.state.value}"
+
+        # Current task.
+        task_text = "No current task"
+        if pairing.active_session_id is not None:
+            from app.models.chat import ChatSession
+
+            session = await db.get(ChatSession, pairing.active_session_id)
+            if session is not None and session.title:
+                task_text = f"Current task: {session.title}"
+            elif session is not None:
+                task_text = f"Current task: session {session.id}"
+
+        return RemoteActionResult(
+            status="ok",
+            text=f"{status_text}\n{task_text}\nPaired: {pairing.label or 'Yes'}",
+        )
+
+    async def _cmd_new(
+        self, db: AsyncSession, action: RemoteInboundAction
+    ) -> RemoteActionResult:
+        from app.remote.inbound import RemoteInboundService
+
+        inbound = RemoteInboundService(pairing_service=self._pairing_service)
+        result = await inbound.new_task(db, action)
+        if result.status == "unauthorized":
+            return RemoteActionResult(status="unauthorized")
+        return RemoteActionResult(
+            status="ok", text="Current task cleared. Next message starts a new task."
+        )
+
+    async def _cmd_stop(
+        self, db: AsyncSession, action: RemoteInboundAction
+    ) -> RemoteActionResult:
+        from app.remote.inbound import RemoteInboundService
+
+        inbound = RemoteInboundService(pairing_service=self._pairing_service)
+        result = await inbound.stop_current(db, action)
+        if result.status == "unauthorized":
+            return RemoteActionResult(status="unauthorized")
+        if result.status == "no_active_turn":
+            return RemoteActionResult(status="ok", text="No active task to stop.")
+        return RemoteActionResult(status="ok", text="Task stopped.")
+
+    async def _cmd_unpair(
+        self, db: AsyncSession, action: RemoteInboundAction
+    ) -> RemoteActionResult:
+        removed = await self._pairing_service.unpair(db, action.connection_id)
+        if removed:
+            return RemoteActionResult(
+                status="ok", text="Phone unpaired. Send /start to pair again."
+            )
+        return RemoteActionResult(status="ok", text="No active pairing to remove.")
+
+    async def _cmd_actions(
+        self, db: AsyncSession, action: RemoteInboundAction, arg: str
+    ) -> RemoteActionResult:
+        """Show the More-actions menu."""
+        items = await self._load_action_menu(db, action)
+        if not items:
+            return RemoteActionResult(
+                status="ok", text="No additional actions available."
+            )
+
+        # Format as a numbered list.
+        lines = ["More actions:"]
+        for i, item in enumerate(items, 1):
+            lines.append(f"{i}. {item.label}")
+            if item.description:
+                lines.append(f"   {item.description}")
+
+        # Send the menu with buttons.
+        if self._adapter is not None:
+            buttons = tuple(
+                RemoteButton(text=item.label[:64], token=item.token)
+                for item in items[:8]  # bound to 8 buttons
+            )
+            await self._send(
+                action.principal.destination_id,
+                "\n".join(lines),
+                buttons=buttons,
+            )
+
+        return RemoteActionResult(status="ok", text="\n".join(lines))
+
+    # ── Menu loaders ───────────────────────────────────────────────────────
+
+    async def _load_action_menu(
+        self, db: AsyncSession, action: RemoteInboundAction
+    ) -> list[RemoteMenuItem]:
+        """Load available actions from all owners."""
+        items: list[RemoteMenuItem] = []
+
+        # Workflows
+        items.extend(await self._load_workflows(db, action))
+
+        # Coding projects
+        items.extend(await self._load_coding_projects(db, action))
+
+        # Scheduled tasks
+        items.extend(await self._load_scheduled_tasks(db, action))
+
+        return items[:20]  # bounded to 20 items
+
+    async def _load_workflows(
+        self, db: AsyncSession, action: RemoteInboundAction
+    ) -> list[RemoteMenuItem]:
+        """Load available workflows."""
+        try:
+            from app.services.workflows_fs import discover_workflows
+
+            discovered = discover_workflows(None)
+            items: list[RemoteMenuItem] = []
+            for found in discovered[:5]:  # bound to 5
+                defn = found.definition
+                if defn is None:
+                    continue
+                token = self._issue_token(
+                    connection_id=action.connection_id,
+                    principal_id=action.principal.principal_id,
+                    destination_id=action.principal.destination_id,
+                    session_id="",
+                    action_kind="workflow_start",
+                    action_target=defn.name,
+                )
+                items.append(
+                    RemoteMenuItem(
+                        token=token,
+                        label=f"Workflow: {defn.name[:50]}",
+                        description=defn.description[:100] if defn.description else "",
+                    )
+                )
+            return items
+        except Exception as exc:
+            logger.debug("remote_actions_load_workflows_failed error={}", exc)
+            return []
+
+    async def _load_coding_projects(
+        self, db: AsyncSession, action: RemoteInboundAction
+    ) -> list[RemoteMenuItem]:
+        """Load visible coding projects."""
+        try:
+            from app.services.coding_project_service import list_visible_projects
+
+            projects = await list_visible_projects(db)
+            items: list[RemoteMenuItem] = []
+            for proj in projects[:5]:  # bound to 5
+                token = self._issue_token(
+                    connection_id=action.connection_id,
+                    principal_id=action.principal.principal_id,
+                    destination_id=action.principal.destination_id,
+                    session_id="",
+                    action_kind="coding_task",
+                    action_target=str(proj.id),
+                )
+                items.append(
+                    RemoteMenuItem(
+                        token=token,
+                        label=f"Project: {proj.name[:50]}",
+                        description=(proj.description or "")[:100],
+                    )
+                )
+            return items
+        except Exception as exc:
+            logger.debug("remote_actions_load_projects_failed error={}", exc)
+            return []
+
+    async def _load_scheduled_tasks(
+        self, db: AsyncSession, action: RemoteInboundAction
+    ) -> list[RemoteMenuItem]:
+        """Load manually-triggerable scheduled tasks."""
+        try:
+            from app.scheduler.scheduler import task_scheduler
+
+            tasks = await task_scheduler.list_tasks()
+            items: list[RemoteMenuItem] = []
+            for task in tasks[:5]:  # bound to 5
+                if not task.enabled:
+                    continue
+                token = self._issue_token(
+                    connection_id=action.connection_id,
+                    principal_id=action.principal.principal_id,
+                    destination_id=action.principal.destination_id,
+                    session_id="",
+                    action_kind="schedule_trigger",
+                    action_target=str(task.id),
+                )
+                items.append(
+                    RemoteMenuItem(
+                        token=token,
+                        label=f"Schedule: {task.name[:50]}",
+                    )
+                )
+            return items
+        except Exception as exc:
+            logger.debug("remote_actions_load_schedules_failed error={}", exc)
+            return []
+
+    # ── Action execution ───────────────────────────────────────────────────
+
+    async def _execute_action(
+        self, cap: _ActionCapability, action: RemoteInboundAction
+    ) -> bool:
+        """Execute a menu action by kind."""
+        if cap.action_kind == "workflow_start":
+            return await self._exec_workflow_start(cap, action)
+        elif cap.action_kind == "coding_task":
+            return await self._exec_coding_task(cap, action)
+        elif cap.action_kind == "schedule_trigger":
+            return await self._exec_schedule_trigger(cap, action)
+        return False
+
+    async def _exec_workflow_start(
+        self, cap: _ActionCapability, action: RemoteInboundAction
+    ) -> bool:
+        """Start a workflow by name."""
+        try:
+            from app.services.workflows_fs import discover_workflows
+
+            discovered = discover_workflows(None)
+            defn = None
+            for found in discovered:
+                if found.definition and found.definition.name == cap.action_target:
+                    defn = found.definition
+                    break
+
+            if defn is None:
+                await self._reply_text(
+                    action.principal.destination_id,
+                    f"Workflow '{cap.action_target}' not found.",
+                )
+                return True
+
+            # Workflows need a session to run in. We need to create one or
+            # use the current task's session.
+            from app.core.db import async_session_factory
+
+            async with async_session_factory() as session:
+                pairing = await self._pairing_service.authorize(
+                    session,
+                    connection_id=cap.connection_id,
+                    principal_id=cap.principal_id,
+                )
+                if pairing is None or pairing.active_session_id is None:
+                    await self._reply_text(
+                        action.principal.destination_id,
+                        "No active task. Send a message first to create one, then try again.",
+                    )
+                    return True
+
+                session_id = str(pairing.active_session_id)
+
+            from app.workflow.runner import WorkflowRunner
+
+            runner = WorkflowRunner()
+            await runner.start(
+                defn,
+                definition_hash="",
+                session_id=session_id,
+                inputs={},
+                scope_workspace=None,
+            )
+            await self._reply_text(
+                action.principal.destination_id,
+                f"Workflow '{cap.action_target}' started.",
+            )
+            return True
+        except RuntimeError as exc:
+            await self._reply_text(
+                action.principal.destination_id,
+                f"Cannot start workflow: {exc}",
+            )
+            return True
+        except Exception as exc:
+            logger.warning("remote_workflow_start_failed error={}", exc)
+            await self._reply_text(
+                action.principal.destination_id,
+                "Failed to start workflow.",
+            )
+            return True
+
+    async def _exec_coding_task(
+        self, cap: _ActionCapability, action: RemoteInboundAction
+    ) -> bool:
+        """Start a coding task for a project."""
+        try:
+            from app.core.db import async_session_factory
+            from app.services.coding_project_service import get_project
+
+            async with async_session_factory() as session:
+                project = await get_project(session, UUID(cap.action_target))
+                if project is None:
+                    await self._reply_text(
+                        action.principal.destination_id,
+                        "Project not found.",
+                    )
+                    return True
+
+                # Create a coding session for this project.
+                from app.services.chat_service import create_chat_session
+
+                chat = await create_chat_session(session)
+                chat.mode = "coding"
+                chat.project_id = project.id
+                chat.tags = [
+                    "remote_origin",
+                    f"remote_connection:{cap.connection_id}",
+                ]
+                session.add(chat)
+                await session.commit()
+
+                # Update pairing to point to this session.
+                pairing = await self._pairing_service.authorize(
+                    session,
+                    connection_id=cap.connection_id,
+                    principal_id=cap.principal_id,
+                )
+                if pairing is not None:
+                    pairing.active_session_id = chat.id
+                    session.add(pairing)
+                    await session.commit()
+
+            await self._reply_text(
+                action.principal.destination_id,
+                f"Coding task created for project '{project.name}'. Send your first message.",
+            )
+            return True
+        except Exception as exc:
+            logger.warning("remote_coding_task_failed error={}", exc)
+            await self._reply_text(
+                action.principal.destination_id,
+                "Failed to create coding task.",
+            )
+            return True
+
+    async def _exec_schedule_trigger(
+        self, cap: _ActionCapability, action: RemoteInboundAction
+    ) -> bool:
+        """Trigger a scheduled task manually."""
+        try:
+            from app.scheduler.scheduler import task_scheduler
+
+            await task_scheduler.trigger(UUID(cap.action_target))
+            await self._reply_text(
+                action.principal.destination_id,
+                "Scheduled task triggered.",
+            )
+            return True
+        except Exception as exc:
+            logger.warning("remote_schedule_trigger_failed error={}", exc)
+            await self._reply_text(
+                action.principal.destination_id,
+                f"Failed to trigger task: {exc}",
+            )
+            return True
+
+    # ── Token management ───────────────────────────────────────────────────
+
+    def _issue_token(
+        self,
+        *,
+        connection_id: UUID,
+        principal_id: str,
+        destination_id: str,
+        session_id: str,
+        action_kind: str,
+        action_target: str,
+    ) -> str:
+        token = secrets.token_urlsafe(16)
+        assert len(token) <= _MAX_CALLBACK_TOKEN_BYTES
+        cap = _ActionCapability(
+            token=token,
+            connection_id=connection_id,
+            principal_id=principal_id,
+            destination_id=destination_id,
+            session_id=session_id,
+            action_kind=action_kind,
+            action_target=action_target,
+        )
+        self._capabilities[token] = cap
+        self._pending_by_token[token] = action_kind
+        return token
+
+    def _discard(self, cap: _ActionCapability) -> None:
+        self._capabilities.pop(cap.token, None)
+        self._pending_by_token.pop(cap.token, None)
+
+    # ── Delivery helpers ───────────────────────────────────────────────────
+
+    async def _send(
+        self,
+        destination_id: str,
+        text: str,
+        buttons: tuple[RemoteButton, ...] = (),
+    ) -> None:
+        if self._adapter is None:
+            return
+        try:
+            from uuid import UUID as _UUID
+
+            msg = RemoteOutboundMessage(
+                connection_id=_UUID(int=0),
+                destination_id=destination_id,
+                text=text,
+                buttons=buttons,
+                priority=RemoteOutboundPriority.INFORMATIONAL,
+            )
+            await self._adapter.send(msg)
+        except Exception as exc:
+            logger.warning("remote_action_send_failed error={}", exc)
+
+    async def _reply_text(self, destination_id: str, text: str) -> None:
+        await self._send(destination_id, text)
+
+
+# ── Redaction helper ──────────────────────────────────────────────────────────
+
+
+def _redact_text(text: str) -> str:
+    """Apply remote-channel outbound redaction."""
+    try:
+        from app.agent.outbound_redaction import OutboundContext, protect_outbound_text
+
+        protected, _report = protect_outbound_text(
+            text, context=OutboundContext(channel="remote")
+        )
+        return protected
+    except Exception:
+        return text
+
+
+# ── Command validation ────────────────────────────────────────────────────────
+
+
+def is_slash_command(text: str) -> bool:
+    """Check if text is a recognized slash command."""
+    if not text.startswith("/"):
+        return False
+    command = text.split(maxsplit=1)[0][1:].lower()
+    return command in _SLASH_COMMANDS
+
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from sqlmodel.ext.asyncio.session import AsyncSession
diff --git a/app/remote/gates.py b/app/remote/gates.py
new file mode 100644
index 00000000..7814a022
--- /dev/null
+++ b/app/remote/gates.py
@@ -0,0 +1,442 @@
+"""Remote gate bridge — opaque callback capabilities and gate resolution.
+
+Translates EvoFlux gate events (permission_asked, question_asked,
+plan_approval_requested) into Telegram inline-button cards with opaque
+callback tokens, and resolves inbound callbacks back through the active
+PermissionService, AskUserService, or PlanModeService registry.
+
+Design constraints (from spec):
+- Callback tokens are opaque, random, connection/principal-bound, and <=64 bytes.
+- Internal IDs (session_id, request_id) are never serialized into callback data.
+- ``answer_callback`` is called before any gate resolution (AC-26).
+- ``edit_text`` removes buttons after resolution.
+- Remote permission replies are limited to ``once`` and ``reject`` (AC-28).
+"""
+
+from __future__ import annotations
+
+import secrets
+import time
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Literal
+from uuid import UUID
+
+from loguru import logger
+
+from app.remote.contracts import (
+    RemoteAdapter,
+    RemoteButton,
+    RemoteInboundAction,
+    RemoteOutboundMessage,
+    RemoteOutboundPriority,
+)
+
+if TYPE_CHECKING:
+    pass
+
+__all__ = ["RemoteGateBridge"]
+
+#: Telegram callback data limit.
+_MAX_CALLBACK_TOKEN_BYTES = 64
+
+#: Capability expiry in seconds (10 minutes).
+_CAPABILITY_TTL_SECONDS = 600
+
+#: Gate kinds.
+GateKind = Literal["permission", "question", "plan"]
+
+
+@dataclass(frozen=True)
+class GateCapability:
+    """One opaque, expiring capability record bound to a gate action."""
+
+    token: str
+    connection_id: UUID
+    principal_id: str
+    destination_id: str
+    session_id: str
+    request_id: str
+    gate_kind: GateKind
+    action: str
+    created_at: float = field(default_factory=time.monotonic)
+
+
+@dataclass
+class _PendingGate:
+    """Tracks one gate's outstanding capabilities and message reference."""
+
+    request_id: str
+    session_id: str
+    gate_kind: GateKind
+    tokens: list[str] = field(default_factory=list)
+    chat_id: int | None = None
+    message_id: int | None = None
+
+
+class RemoteGateBridge:
+    """Bridges EvoFlux gate events to Telegram inline buttons and resolves
+    inbound callbacks through the active service registry.
+
+    Owned by the runtime alongside the projection.  The projection calls
+    :meth:`on_gate` and :meth:`on_reply`; the runtime calls
+    :meth:`handle_callback` for inbound CALLBACK actions.
+    """
+
+    def __init__(self, adapter: RemoteAdapter) -> None:
+        self._adapter = adapter
+        self._capabilities: dict[str, GateCapability] = {}
+        self._pending_by_token: dict[str, str] = {}  # token -> request_id
+        self._pending_gates: dict[str, _PendingGate] = {}  # request_id -> gate
+
+    def on_gate(
+        self,
+        session_id: str,
+        event_type: str,
+        data: dict,
+        connection_id: UUID,
+        destination_id: str,
+    ) -> None:
+        """Handle a gate event by creating opaque tokens and enqueuing a card.
+
+        Called by the projection's ``_handle_gate``.
+        """
+        request_id = data.get("request_id", "")
+        if not request_id:
+            return
+
+        gate_kind: GateKind
+        actions: list[tuple[str, str]]  # (action_label, button_text)
+
+        if event_type == "permission_asked":
+            gate_kind = "permission"
+            tool = data.get("tool", "unknown")
+            text = f"Permission requested: {tool}"
+            actions = [("once", "Allow"), ("reject", "Reject")]
+        elif event_type == "question_asked":
+            gate_kind = "question"
+            questions = data.get("questions", [])
+            if questions:
+                first_q = questions[0]
+                text = f"Question: {first_q.get('question', '')}"
+                options = first_q.get("options", [])
+                actions = [(opt, opt) for opt in options[:8]]  # bound to 8
+            else:
+                text = "Question asked."
+                actions = []
+        elif event_type == "plan_approval_requested":
+            gate_kind = "plan"
+            plan_text = data.get("plan", "")
+            steps = data.get("steps", [])
+            text = f"Plan ready for review ({len(steps)} steps)."
+            if plan_text:
+                text = f"Plan: {plan_text[:200]}"
+            actions = [("approve", "Approve"), ("reject", "Reject")]
+        else:
+            return
+
+        # Create opaque tokens for each action.
+        buttons: list[RemoteButton] = []
+        gate = _PendingGate(
+            request_id=request_id,
+            session_id=session_id,
+            gate_kind=gate_kind,
+        )
+
+        for action_value, button_text in actions:
+            token = self._issue_token(
+                connection_id=connection_id,
+                principal_id="",  # filled on callback from action
+                destination_id=destination_id,
+                session_id=session_id,
+                request_id=request_id,
+                gate_kind=gate_kind,
+                action=action_value,
+            )
+            buttons.append(RemoteButton(text=button_text, token=token))
+            gate.tokens.append(token)
+            self._pending_by_token[token] = request_id
+
+        self._pending_gates[request_id] = gate
+
+        # Apply redaction and send.
+        text = _redact_text(text)
+        msg = RemoteOutboundMessage(
+            connection_id=connection_id,
+            destination_id=destination_id,
+            text=text,
+            buttons=tuple(buttons),
+            priority=RemoteOutboundPriority.HIGH,
+        )
+        self._enqueue_send(msg)
+
+    def on_reply(self, session_id: str, event_type: str, data: dict) -> None:
+        """Handle a gate reply event by removing buttons from the message.
+
+        Called by the projection when a ``permission_replied``,
+        ``question_replied``, or ``plan_approval_replied`` event fires.
+        """
+        request_id = data.get("request_id", "")
+        if not request_id:
+            return
+
+        gate = self._pending_gates.pop(request_id, None)
+        if gate is None:
+            return
+
+        # Clean up capability tokens.
+        for token in gate.tokens:
+            self._capabilities.pop(token, None)
+            self._pending_by_token.pop(token, None)
+
+        # Edit the message to remove buttons (if we have a reference).
+        if gate.chat_id is not None and gate.message_id is not None:
+            self._edit_remove_buttons(gate)
+
+    async def handle_callback(self, action: RemoteInboundAction) -> None:
+        """Handle an inbound callback action.
+
+        1. Look up the capability by token.
+        2. Validate principal/connection.
+        3. ``answer_callback`` FIRST (acknowledge the tap).
+        4. Resolve the gate via the appropriate service.
+        5. Edit the message to remove buttons.
+        """
+        token = action.callback_token
+        if not token:
+            return
+
+        cap = self._capabilities.get(token)
+        if cap is None:
+            logger.debug(
+                "remote_gate_callback_unknown token_prefix={}",
+                token[:8],
+            )
+            return
+
+        # Validate connection.
+        if cap.connection_id != action.connection_id:
+            logger.debug(
+                "remote_gate_callback_wrong_connection expected={} got={}",
+                cap.connection_id,
+                action.connection_id,
+            )
+            return
+
+        # Check expiry.
+        if time.monotonic() - cap.created_at > _CAPABILITY_TTL_SECONDS:
+            self._discard_capability(cap)
+            logger.debug(
+                "remote_gate_callback_expired request_id={}",
+                cap.request_id,
+            )
+            return
+
+        # Acknowledge the callback FIRST (AC-26).
+        await self._adapter.answer_callback(token)
+
+        # Resolve the gate.
+        resolved = await self._resolve_gate(cap, action)
+        if resolved:
+            self._discard_capability(cap)
+
+    async def _resolve_gate(
+        self, cap: GateCapability, action: RemoteInboundAction
+    ) -> bool:
+        """Resolve a gate through the active service registry."""
+        if cap.gate_kind == "permission":
+            return await self._resolve_permission(cap, action)
+        elif cap.gate_kind == "question":
+            return await self._resolve_question(cap, action)
+        elif cap.gate_kind == "plan":
+            return await self._resolve_plan(cap, action)
+        return False
+
+    async def _resolve_permission(
+        self, cap: GateCapability, action: RemoteInboundAction
+    ) -> bool:
+        """Resolve a permission gate. Remote is limited to once/reject."""
+        from app.agent.permission import get_service_for_session
+
+        reply_value = cap.action  # "once" or "reject"
+        if reply_value not in ("once", "reject"):
+            logger.warning(
+                "remote_gate_invalid_permission_action action={}",
+                reply_value,
+            )
+            return False
+
+        svc = get_service_for_session(cap.session_id)
+        if svc is None:
+            logger.debug(
+                "remote_gate_permission_service_missing session_id={}",
+                cap.session_id,
+            )
+            return False
+
+        resolved = svc.reply(cap.request_id, reply_value)
+        if resolved:
+            logger.info(
+                "remote_gate_permission_resolved request_id={} reply={}",
+                cap.request_id,
+                reply_value,
+            )
+        return resolved
+
+    async def _resolve_question(
+        self, cap: GateCapability, action: RemoteInboundAction
+    ) -> bool:
+        """Resolve a question gate with the selected option."""
+        from app.agent.ask_user import get_service_for_session
+
+        svc = get_service_for_session(cap.session_id)
+        if svc is None:
+            logger.debug(
+                "remote_gate_question_service_missing session_id={}",
+                cap.session_id,
+            )
+            return False
+
+        # The action is the answer (single-question batch for v1).
+        answers = [cap.action]
+        validation_error = svc.validate_answers(cap.request_id, answers)
+        if validation_error:
+            logger.warning(
+                "remote_gate_question_validation_failed request_id={} error={}",
+                cap.request_id,
+                validation_error,
+            )
+            return False
+
+        resolved = svc.reply(cap.request_id, answers)
+        if resolved:
+            logger.info(
+                "remote_gate_question_resolved request_id={}",
+                cap.request_id,
+            )
+        return resolved
+
+    async def _resolve_plan(
+        self, cap: GateCapability, action: RemoteInboundAction
+    ) -> bool:
+        """Resolve a plan approval gate."""
+        from app.agent.plan import get_service_for_session
+
+        decision = cap.action  # "approve" -> "approved", "reject" -> "rejected"
+        plan_decision = "approved" if decision == "approve" else "rejected"
+
+        svc = get_service_for_session(cap.session_id)
+        if svc is None:
+            logger.debug(
+                "remote_gate_plan_service_missing session_id={}",
+                cap.session_id,
+            )
+            return False
+
+        resolved = svc.reply(cap.request_id, plan_decision)
+        if resolved:
+            logger.info(
+                "remote_gate_plan_resolved request_id={} decision={}",
+                cap.request_id,
+                plan_decision,
+            )
+        return resolved
+
+    def _discard_capability(self, cap: GateCapability) -> None:
+        """Remove a capability and its token from all indices."""
+        self._capabilities.pop(cap.token, None)
+        self._pending_by_token.pop(cap.token, None)
+
+    def _issue_token(
+        self,
+        *,
+        connection_id: UUID,
+        principal_id: str,
+        destination_id: str,
+        session_id: str,
+        request_id: str,
+        gate_kind: GateKind,
+        action: str,
+    ) -> str:
+        """Issue an opaque, bounded callback token."""
+        token = secrets.token_urlsafe(16)
+        assert len(token) <= _MAX_CALLBACK_TOKEN_BYTES, (
+            f"Token too long: {len(token)} bytes"
+        )
+        cap = GateCapability(
+            token=token,
+            connection_id=connection_id,
+            principal_id=principal_id,
+            destination_id=destination_id,
+            session_id=session_id,
+            request_id=request_id,
+            gate_kind=gate_kind,
+            action=action,
+        )
+        self._capabilities[token] = cap
+        return token
+
+    def _edit_remove_buttons(self, gate: _PendingGate) -> None:
+        """Edit a message to remove its inline buttons."""
+        if gate.chat_id is None or gate.message_id is None:
+            return
+        # We need to send an edit with empty buttons to remove the keyboard.
+        # This is a fire-and-forget best-effort.
+        try:
+            import asyncio
+
+            loop = asyncio.get_running_loop()
+            loop.create_task(self._do_edit_remove(gate))
+        except RuntimeError:
+            pass
+
+    async def _do_edit_remove(self, gate: _PendingGate) -> None:
+        """Actually edit the message to remove buttons."""
+        try:
+            msg = RemoteOutboundMessage(
+                connection_id=UUID(int=0),  # not used for edit lookup
+                destination_id="",
+                text="",  # text not changed
+                buttons=(),
+                correlation_id=f"gate:{gate.request_id}",
+            )
+            await self._adapter.edit(msg)
+        except Exception as exc:
+            logger.debug(
+                "remote_gate_edit_remove_buttons_failed request_id={} error={}",
+                gate.request_id,
+                exc,
+            )
+
+    def _enqueue_send(self, msg: RemoteOutboundMessage) -> None:
+        """Enqueue a message for async delivery."""
+        try:
+            import asyncio
+
+            loop = asyncio.get_running_loop()
+            loop.create_task(self._do_send(msg))
+        except RuntimeError:
+            pass
+
+    async def _do_send(self, msg: RemoteOutboundMessage) -> None:
+        """Send a message through the adapter."""
+        try:
+            await self._adapter.send(msg)
+        except Exception as exc:
+            logger.warning(
+                "remote_gate_send_failed destination_id={} error={}",
+                msg.destination_id,
+                exc,
+            )
+
+
+def _redact_text(text: str) -> str:
+    """Apply remote-channel outbound redaction."""
+    try:
+        from app.agent.outbound_redaction import OutboundContext, protect_outbound_text
+
+        protected, _report = protect_outbound_text(
+            text, context=OutboundContext(channel="remote")
+        )
+        return protected
+    except Exception:
+        return text
diff --git a/app/remote/inbound.py b/app/remote/inbound.py
new file mode 100644
index 00000000..8697908f
--- /dev/null
+++ b/app/remote/inbound.py
@@ -0,0 +1,229 @@
+"""Provider-neutral remote text ingress and current-task selection."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+from dataclasses import dataclass
+from uuid import UUID
+
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from app.models.chat import ChatSession
+from app.models.remote import RemotePairing
+from app.remote.contracts import RemoteInboundAction, RemoteInboundActionKind
+from app.remote.pairing import PairingService
+from app.services import agent_service
+from app.services.chat_service import create_chat_session
+from app.services.interactive_message_service import (
+    NoTeamConfigured,
+    resolve_team_for_session,
+    submit_persisted_interactive_message,
+)
+
+
+@dataclass(frozen=True)
+class RemoteInboundResult:
+    """A bounded, adapter-neutral outcome for one remote action."""
+
+    status: str
+    session_id: UUID | None = None
+    message_id: UUID | None = None
+
+
+class RemoteInboundService:
+    """Admits paired remote actions through the existing service layer."""
+
+    def __init__(self, *, pairing_service: PairingService | None = None) -> None:
+        self._pairing_service = pairing_service or PairingService()
+        self._locks: dict[UUID, asyncio.Lock] = {}
+        self._locks_lock = asyncio.Lock()
+
+    async def handle_text(
+        self, db: AsyncSession, action: RemoteInboundAction
+    ) -> RemoteInboundResult:
+        """Submit paired plain text to its current task or create one."""
+        if action.kind is not RemoteInboundActionKind.TEXT:
+            return RemoteInboundResult(status="ignored")
+        content = (action.text or "").strip()
+        if not content:
+            return RemoteInboundResult(status="ignored")
+
+        pairing = await self._authorize(db, action)
+        if pairing is None:
+            return RemoteInboundResult(status="unauthorized")
+
+        async with await self._lock_for(pairing.id):
+            pairing = await db.get(RemotePairing, pairing.id)
+            if pairing is None:
+                return RemoteInboundResult(status="unauthorized")
+            session = await self._current_session(db, pairing)
+            if session is None:
+                session = await self._create_work_session(db, pairing, action)
+
+            session_id = session.id
+            if db.in_transaction():
+                await db.rollback()
+            session, team = await resolve_team_for_session(
+                db, str(session_id), require_existing=True
+            )
+            if session is None:
+                return RemoteInboundResult(status="session_not_addressable")
+
+            request_hash = hashlib.sha256(content.encode("utf-8")).hexdigest()
+            result = await submit_persisted_interactive_message(
+                db,
+                session=session,
+                team=team,
+                content=content,
+                message_extra={
+                    "interactive_source": {
+                        "channel": "remote",
+                        "adapter": "telegram",
+                        "connection_id": str(action.connection_id),
+                        "key": action.source_key,
+                        "request_hash": request_hash,
+                        "state": "persisted",
+                    }
+                },
+                source_key=action.source_key,
+                source_request_hash=request_hash,
+            )
+        return RemoteInboundResult(
+            status=result.status,
+            session_id=UUID(result.session_id),
+            message_id=result.message_id,
+        )
+
+    async def new_task(
+        self, db: AsyncSession, action: RemoteInboundAction
+    ) -> RemoteInboundResult:
+        """Clear only this pairing's current-task pointer."""
+        pairing = await self._authorize(db, action)
+        if pairing is None:
+            return RemoteInboundResult(status="unauthorized")
+
+        async with await self._lock_for(pairing.id):
+            pairing = await db.get(RemotePairing, pairing.id)
+            if pairing is None:
+                return RemoteInboundResult(status="unauthorized")
+            pairing.active_session_id = None
+            db.add(pairing)
+            await db.commit()
+        return RemoteInboundResult(status="current_task_cleared")
+
+    async def continue_task(
+        self, db: AsyncSession, action: RemoteInboundAction, session_id: UUID
+    ) -> RemoteInboundResult:
+        """Make an existing task current for the pairing."""
+        pairing = await self._authorize(db, action)
+        if pairing is None:
+            return RemoteInboundResult(status="unauthorized")
+
+        async with await self._lock_for(pairing.id):
+            pairing = await db.get(RemotePairing, pairing.id)
+            if pairing is None:
+                return RemoteInboundResult(status="unauthorized")
+            session = await db.get(ChatSession, session_id)
+            if not _is_addressable_session(session):
+                return RemoteInboundResult(status="session_not_addressable")
+            assert session is not None
+            pairing.active_session_id = session.id
+            db.add(pairing)
+            await db.commit()
+        return RemoteInboundResult(
+            status="current_task_selected", session_id=session_id
+        )
+
+    async def stop_current(
+        self, db: AsyncSession, action: RemoteInboundAction
+    ) -> RemoteInboundResult:
+        """Interrupt a live current turn without deleting or changing its task."""
+        pairing = await self._authorize(db, action)
+        if pairing is None:
+            return RemoteInboundResult(status="unauthorized")
+
+        async with await self._lock_for(pairing.id):
+            pairing = await db.get(RemotePairing, pairing.id)
+            if pairing is None:
+                return RemoteInboundResult(status="unauthorized")
+            session = await self._current_session(db, pairing)
+            if session is None:
+                return RemoteInboundResult(status="no_active_turn")
+            session_id = session.id
+            if db.in_transaction():
+                await db.rollback()
+            try:
+                _, team = await resolve_team_for_session(
+                    db, str(session_id), require_existing=True
+                )
+            except NoTeamConfigured:
+                return RemoteInboundResult(
+                    status="no_active_turn", session_id=session_id
+                )
+            if not team.has_active_user_turn():
+                return RemoteInboundResult(
+                    status="no_active_turn", session_id=session_id
+                )
+            await agent_service.interrupt_team(team, str(session_id))
+        return RemoteInboundResult(status="interrupted", session_id=session_id)
+
+    async def _authorize(
+        self, db: AsyncSession, action: RemoteInboundAction
+    ) -> RemotePairing | None:
+        if action.principal.connection_id != action.connection_id:
+            return None
+        return await self._pairing_service.authorize(
+            db,
+            connection_id=action.connection_id,
+            principal_id=action.principal.principal_id,
+        )
+
+    async def _lock_for(self, pairing_id: UUID) -> asyncio.Lock:
+        async with self._locks_lock:
+            return self._locks.setdefault(pairing_id, asyncio.Lock())
+
+    async def _current_session(
+        self, db: AsyncSession, pairing: RemotePairing
+    ) -> ChatSession | None:
+        if pairing.active_session_id is None:
+            return None
+        session = await db.get(ChatSession, pairing.active_session_id)
+        if _is_addressable_session(session):
+            return session
+        pairing.active_session_id = None
+        db.add(pairing)
+        await db.commit()
+        return None
+
+    async def _create_work_session(
+        self,
+        db: AsyncSession,
+        pairing: RemotePairing,
+        action: RemoteInboundAction,
+    ) -> ChatSession:
+        session = await create_chat_session(db)
+        session.mode = "work"
+        session.parent_session_id = None
+        session.session_type = "main"
+        session.tags = [
+            "remote_origin",
+            f"remote_connection:{action.connection_id}",
+        ]
+        pairing.active_session_id = session.id
+        db.add(session)
+        db.add(pairing)
+        await db.commit()
+        return session
+
+
+def _is_addressable_session(session: ChatSession | None) -> bool:
+    return (
+        session is not None
+        and session.parent_session_id is None
+        and session.session_type == "main"
+        and session.mode in {"work", "coding"}
+    )
+
+
+__all__ = ["RemoteInboundResult", "RemoteInboundService"]
diff --git a/app/remote/outbound.py b/app/remote/outbound.py
new file mode 100644
index 00000000..1895e2df
--- /dev/null
+++ b/app/remote/outbound.py
@@ -0,0 +1,351 @@
+"""Remote outbound projection, redaction, splitting, and delivery.
+
+Observes the global stream (via
+:func:`app.services.memory_stream_store.register_observer`) and projects
+relevant events for remote-originated sessions into safe, redacted Telegram
+messages.
+
+Only sessions tagged ``remote_origin`` are observed.  The projection
+collapses duplicate completions, queries finalized assistant text from the
+database after ``done``, and applies the ``remote`` outbound-redaction
+channel before delivery.
+
+Design constraints (from spec):
+- Observers are synchronous, bounded, and non-blocking.
+- No network or database work runs under stream locks.
+- All outbound text uses ``protect_outbound_text(..., context=OutboundContext(channel="remote"))``.
+- No Telegram parse mode — model-authored text must never be interpreted as markup.
+- Unicode-safe plain-text splitting at 4096 characters (Telegram provider bound).
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+from uuid import UUID
+
+from loguru import logger
+
+from app.remote.contracts import (
+    RemoteAdapter,
+    RemoteButton,
+    RemoteOutboundMessage,
+    RemoteOutboundPriority,
+)
+
+if TYPE_CHECKING:
+    from app.remote.gates import RemoteGateBridge
+
+#: Telegram's maximum message length in characters.
+_TELEGRAM_MAX_MESSAGE_LENGTH = 4096
+
+#: Events the remote projection forwards to the phone.
+_OBSERVED_EVENT_TYPES = frozenset(
+    {
+        "done",
+        "error",
+        "permission_asked",
+        "question_asked",
+        "plan_approval_requested",
+        "permission_replied",
+        "question_replied",
+        "plan_approval_replied",
+    }
+)
+
+
+@dataclass
+class _TurnDeliveryState:
+    """Per-turn bookkeeping for one remote-originated session."""
+
+    session_id: str
+    connection_id: str
+    destination_id: str
+    #: The lifecycle (progress) message correlation, if one was sent.
+    lifecycle_correlation_id: str | None = None
+    #: Whether a completion message has already been sent for this turn.
+    completion_sent: bool = False
+
+
+@dataclass
+class RemoteProjection:
+    """Projects stream events for remote-originated sessions into Telegram.
+
+    Registered as a global stream observer.  Each incoming event is checked
+    against the session's provenance tags; only ``remote_origin`` sessions
+    are tracked.  Relevant events are normalized, redacted, split, and
+    enqueued for delivery through the live adapter.
+    """
+
+    _adapter: RemoteAdapter | None = field(default=None, repr=False)
+    _bridge: "RemoteGateBridge | None" = field(default=None, repr=False)
+    _turns: dict[str, _TurnDeliveryState] = field(default_factory=dict, repr=False)
+    _session_tags: dict[str, frozenset[str]] = field(default_factory=dict, repr=False)
+    _session_connection_ids: dict[str, str] = field(default_factory=dict, repr=False)
+    _session_destination_ids: dict[str, str] = field(default_factory=dict, repr=False)
+    _pending: list[RemoteOutboundMessage] = field(default_factory=list, repr=False)
+
+    def set_adapter(self, adapter: RemoteAdapter | None) -> None:
+        """Bind or unbind the live adapter. Called by the runtime on start/stop."""
+        self._adapter = adapter
+
+    def set_bridge(self, bridge: "RemoteGateBridge | None") -> None:
+        """Bind or unbind the gate bridge. Called by the runtime on start/stop."""
+        self._bridge = bridge
+
+    def register_session(
+        self,
+        session_id: str,
+        *,
+        connection_id: str,
+        destination_id: str,
+        tags: frozenset[str] = frozenset(),
+    ) -> None:
+        """Register a session as remote-originated so its events are projected."""
+        self._session_tags[session_id] = tags
+        self._session_connection_ids[session_id] = connection_id
+        self._session_destination_ids[session_id] = destination_id
+
+    def unregister_session(self, session_id: str) -> None:
+        """Stop tracking a session."""
+        self._session_tags.pop(session_id, None)
+        self._session_connection_ids.pop(session_id, None)
+        self._session_destination_ids.pop(session_id, None)
+        self._turns.pop(session_id, None)
+
+    def observe(self, session_id: str, envelope) -> None:
+        """Stream observer callback — invoked synchronously after ``push_event``.
+
+        Must be non-blocking.  Enqueues delivery work for the adapter.
+        """
+        tags = self._session_tags.get(session_id)
+        if tags is None:
+            return
+        if "remote_origin" not in tags:
+            return
+
+        event_type = envelope.event
+        if event_type not in _OBSERVED_EVENT_TYPES:
+            return
+
+        connection_id = self._session_connection_ids.get(session_id, "")
+        destination_id = self._session_destination_ids.get(session_id, "")
+        if not connection_id or not destination_id:
+            return
+
+        turn = self._turns.get(session_id)
+        if turn is None:
+            turn = _TurnDeliveryState(
+                session_id=session_id,
+                connection_id=connection_id,
+                destination_id=destination_id,
+            )
+            self._turns[session_id] = turn
+
+        if event_type == "done":
+            self._handle_done(turn, envelope)
+        elif event_type == "error":
+            self._handle_error(turn, envelope)
+        elif event_type in {
+            "permission_asked",
+            "question_asked",
+            "plan_approval_requested",
+        }:
+            self._handle_gate(turn, event_type, envelope)
+        elif event_type in {
+            "permission_replied",
+            "question_replied",
+            "plan_approval_replied",
+        }:
+            if self._bridge is not None:
+                self._bridge.on_reply(session_id, event_type, envelope.data)
+
+    def _handle_done(self, turn: _TurnDeliveryState, envelope) -> None:
+        if turn.completion_sent:
+            return
+        turn.completion_sent = True
+        text = _redact_text(
+            envelope.data.get("text", "Task completed.") or "Task completed."
+        )
+        self._enqueue_send(
+            destination_id=turn.destination_id,
+            text=text,
+            priority=RemoteOutboundPriority.HIGH,
+        )
+
+    def _handle_error(self, turn: _TurnDeliveryState, envelope) -> None:
+        message = envelope.data.get("message", "An error occurred.")
+        text = _redact_text(f"Error: {message}")
+        self._enqueue_send(
+            destination_id=turn.destination_id,
+            text=text,
+            priority=RemoteOutboundPriority.HIGH,
+        )
+
+    def _handle_gate(self, turn: _TurnDeliveryState, event_type: str, envelope) -> None:
+        data = envelope.data
+        if self._bridge is not None:
+            from uuid import UUID
+
+            self._bridge.on_gate(
+                session_id=turn.session_id,
+                event_type=event_type,
+                data=data,
+                connection_id=UUID(turn.connection_id)
+                if turn.connection_id
+                else UUID(int=0),
+                destination_id=turn.destination_id,
+            )
+            return
+
+        # Fallback: send without opaque tokens (pre-bridge behavior).
+        if event_type == "permission_asked":
+            text = _redact_text(
+                f"Permission requested: {data.get('tool', 'unknown tool')}"
+            )
+            buttons = (
+                RemoteButton(text="Allow", token="perm:once"),
+                RemoteButton(text="Reject", token="perm:reject"),
+            )
+        elif event_type == "question_asked":
+            question = data.get("question", "")
+            text = _redact_text(f"Question: {question}")
+            buttons = ()
+        elif event_type == "plan_approval_requested":
+            text = _redact_text("A plan is ready for your review.")
+            buttons = (
+                RemoteButton(text="Approve", token="plan:approve"),
+                RemoteButton(text="Reject", token="plan:reject"),
+            )
+        else:
+            return
+
+        self._enqueue_send(
+            destination_id=turn.destination_id,
+            text=text,
+            buttons=buttons,
+            priority=RemoteOutboundPriority.HIGH,
+        )
+
+    def _enqueue_send(
+        self,
+        *,
+        destination_id: str,
+        text: str,
+        buttons: tuple[RemoteButton, ...] = (),
+        priority: RemoteOutboundPriority = RemoteOutboundPriority.INFORMATIONAL,
+    ) -> None:
+        adapter = self._adapter
+        if adapter is None:
+            logger.debug("remote_outbound_no_adapter destination_id={}", destination_id)
+            return
+
+        connection_id = ""
+        for cid in self._session_connection_ids.values():
+            connection_id = cid
+            break
+
+        chunks = _split_text(text)
+        for i, chunk in enumerate(chunks):
+            msg = RemoteOutboundMessage(
+                connection_id=UUID(connection_id) if connection_id else UUID(int=0),
+                destination_id=destination_id,
+                text=chunk,
+                buttons=buttons if i == len(chunks) - 1 else (),
+                priority=priority,
+            )
+            self._pending.append(msg)
+
+        self._schedule_drain()
+
+    def _schedule_drain(self) -> None:
+        """Schedule an async drain of pending messages if a loop is running."""
+        try:
+            loop = asyncio.get_running_loop()
+            loop.create_task(self.drain_pending())
+        except RuntimeError:
+            pass
+
+    async def drain_pending(self) -> None:
+        """Send all pending messages through the adapter."""
+        adapter = self._adapter
+        if adapter is None:
+            self._pending.clear()
+            return
+        while self._pending:
+            msg = self._pending.pop(0)
+            try:
+                await adapter.send(msg)
+            except Exception as exc:
+                logger.warning(
+                    "remote_outbound_send_failed destination_id={} error={}",
+                    msg.destination_id,
+                    exc,
+                )
+
+    def clear_turn(self, session_id: str) -> None:
+        """Clear delivery state for a completed turn."""
+        self._turns.pop(session_id, None)
+
+
+def _redact_text(text: str) -> str:
+    """Apply remote-channel outbound redaction."""
+    try:
+        from app.agent.outbound_redaction import OutboundContext, protect_outbound_text
+
+        protected, _report = protect_outbound_text(
+            text, context=OutboundContext(channel="remote")
+        )
+        return protected
+    except Exception:
+        return text
+
+
+def _split_text(text: str) -> list[str]:
+    """Split *text* into chunks of at most ``_TELEGRAM_MAX_MESSAGE_LENGTH`` chars.
+
+    Splits on paragraph boundaries when possible, falling back to line
+    boundaries, then hard character splits.  Preserves Unicode safety by
+    never splitting a surrogate pair or combining sequence.
+    """
+    if len(text) <= _TELEGRAM_MAX_MESSAGE_LENGTH:
+        return [text]
+
+    chunks: list[str] = []
+    remaining = text
+    while remaining:
+        if len(remaining) <= _TELEGRAM_MAX_MESSAGE_LENGTH:
+            chunks.append(remaining)
+            break
+
+        # Try to split at the last paragraph break within the limit.
+        split_at = _find_split_point(remaining, _TELEGRAM_MAX_MESSAGE_LENGTH)
+        chunks.append(remaining[:split_at])
+        remaining = remaining[split_at:].lstrip("\n")
+
+    return chunks
+
+
+def _find_split_point(text: str, max_length: int) -> int:
+    """Find the best split point within *max_length* characters."""
+    # Prefer paragraph break
+    idx = text.rfind("\n\n", 0, max_length)
+    if idx > 0:
+        return idx + 2
+
+    # Fall back to line break
+    idx = text.rfind("\n", 0, max_length)
+    if idx > 0:
+        return idx + 1
+
+    # Fall back to space
+    idx = text.rfind(" ", 0, max_length)
+    if idx > 0:
+        return idx + 1
+
+    # Hard split
+    return max_length
+
+
+__all__ = ["RemoteProjection", "_split_text"]
diff --git a/app/remote/pairing.py b/app/remote/pairing.py
index 46696e1a..4d2e65c0 100644
--- a/app/remote/pairing.py
+++ b/app/remote/pairing.py
@@ -358,3 +358,13 @@ async def unpair(self, session: AsyncSession, connection_id: UUID) -> bool:
             await session.delete(row)
         await session.commit()
         return True
+
+
+# Process-wide singleton. Pairing tokens and rate-limit windows live only in
+# this instance's memory (AC-7: "exists only in process memory"), so every
+# caller — the HTTP route that mints a link and the Telegram adapter's
+# inbound dispatch that later consumes it — must share this exact object.
+# A second `PairingService()` starts with an empty token store and can never
+# see a token minted through this one; there is deliberately no other way to
+# reach a `PairingService` in this codebase.
+pairing_service = PairingService()
diff --git a/app/remote/runtime.py b/app/remote/runtime.py
index f47cd32c..ccfd8150 100644
--- a/app/remote/runtime.py
+++ b/app/remote/runtime.py
@@ -17,6 +17,7 @@
 
 import asyncio
 from collections.abc import Awaitable, Callable
+from typing import TYPE_CHECKING
 from uuid import UUID
 
 from loguru import logger
@@ -34,9 +35,16 @@
     RemoteAdapterValidationError,
     RemoteConnectionState,
     RemoteInboundAction,
+    RemoteOutboundMessage,
+    RemoteOutboundPriority,
     ValidatedRemoteIdentity,
 )
 
+if TYPE_CHECKING:
+    from app.remote.actions import RemoteActionService
+    from app.remote.gates import RemoteGateBridge
+    from app.remote.outbound import RemoteProjection
+
 __all__ = [
     "AdapterConstructor",
     "RemoteActionHandler",
@@ -129,7 +137,9 @@ def _construct_telegram_adapter(
     """
     from app.remote.telegram.adapter import TelegramAdapter
 
-    return TelegramAdapter(connection_id=connection_id, token=token, on_action=on_action)
+    return TelegramAdapter(
+        connection_id=connection_id, token=token, on_action=on_action
+    )
 
 
 class RemoteRuntime:
@@ -168,6 +178,12 @@ def __init__(
         self._adapter: RemoteAdapter | None = None
         self._connection_id: UUID | None = None
 
+        #: Stream projection for outbound delivery. Created lazily.
+        self._projection: RemoteProjection | None = None
+        self._observer_unregister: Callable[[], None] | None = None
+        self._bridge: RemoteGateBridge | None = None
+        self._actions: "RemoteActionService | None" = None
+
     async def start(self) -> None:
         """Start the current connection's adapter, if any (AC-1).
 
@@ -223,9 +239,9 @@ def status(self, connection_id: UUID) -> RemoteAdapterStatus:
     # ------------------------------------------------------------------
 
     async def _start_locked(self) -> None:
-        from app.core.db import async_session_factory
+        from app.core.db import read_session_factory
 
-        async with async_session_factory() as session:
+        async with read_session_factory() as session:
             connections = await self._connection_service_factory().list(session)
         connection = connections[0] if connections else None
         if connection is None or not connection.enabled:
@@ -252,30 +268,222 @@ async def _start_locked(self) -> None:
         self._adapter = adapter
         self._connection_id = connection.id
 
+        # Register the outbound projection as a stream observer.
+        from app.remote.outbound import RemoteProjection
+
+        projection = RemoteProjection()
+        projection.set_adapter(adapter)
+        self._projection = projection
+
+        # Create the gate bridge for callback resolution.
+        from app.remote.gates import RemoteGateBridge
+
+        self._bridge = RemoteGateBridge(adapter=adapter)
+        projection.set_bridge(self._bridge)
+
+        # Slash commands (/help, /status, /new, /stop, /unpair, /actions) and
+        # the More-actions menu — shares the same PairingService singleton
+        # every other pairing-aware caller uses (see the module docstring in
+        # app/remote/pairing.py for why a locally-constructed one would be
+        # silently broken).
+        from app.remote.actions import RemoteActionService
+        from app.remote.pairing import pairing_service as _shared_pairing_service
+
+        self._actions = RemoteActionService(
+            pairing_service=_shared_pairing_service,
+            adapter=adapter,
+            status_provider=lambda: self.status(connection.id),
+        )
+
+        from app.services.memory_stream_store import register_observer
+
+        self._observer_unregister = register_observer(projection.observe)
+
+        logger.info("remote_runtime_started connection_id={}", connection.id)
+
     async def _stop_locked(self) -> None:
         adapter, self._adapter = self._adapter, None
         self._connection_id = None
+
+        # Unregister the stream observer before stopping the adapter.
+        if self._observer_unregister is not None:
+            self._observer_unregister()
+            self._observer_unregister = None
+        if self._projection is not None:
+            self._projection.set_adapter(None)
+            self._projection.set_bridge(None)
+            self._projection = None
+        self._bridge = None
+        self._actions = None
+
         if adapter is not None:
             await adapter.stop()
 
     async def _handle_action(self, action: RemoteInboundAction) -> None:
-        """Placeholder inbound dispatch.
-
-        This task (Desktop API and lazy runtime lifecycle) is scoped to
-        AC-1, AC-2, AC-3, AC-5, AC-7, AC-10, AC-12, AC-13, AC-33, and AC-34
-        — none of which require acting on inbound Telegram updates. A later
-        task supplies the real ``RemoteInboundService`` (natural-language
-        ingress and pairing consumption, AC-8/AC-14+) that this handler
-        will delegate to. Until then, inbound actions are received — so the
-        adapter's poll loop and offset bookkeeping run correctly end to
-        end — and safely dropped, rather than duplicating business logic
-        that belongs to ``PairingService``/a later inbound service here.
+        """Dispatch one classified inbound action to the appropriate service.
+
+        TEXT actions go to :class:`~app.remote.inbound.RemoteInboundService`;
+        PAIRING_START actions are consumed by
+        :class:`~app.remote.pairing.PairingService`; CALLBACK actions are
+        handled by :class:`~app.remote.gates.RemoteGateBridge`.
+        """
+        from app.remote.contracts import RemoteInboundActionKind
+
+        if action.kind == RemoteInboundActionKind.PAIRING_START:
+            await self._handle_pairing(action)
+        elif action.kind == RemoteInboundActionKind.TEXT:
+            if (action.text or "").strip().startswith("/"):
+                await self._handle_command(action)
+            else:
+                await self._handle_text(action)
+        elif action.kind == RemoteInboundActionKind.CALLBACK:
+            # Two independent, opaque token namespaces share the callback
+            # channel: gate replies (permission/question/plan) owned by
+            # RemoteGateBridge, and More-actions menu picks owned by
+            # RemoteActionService. Try the menu first — it's a plain dict
+            # membership check — and fall back to the gate bridge, which
+            # already degrades safely (logs + no-ops) on an unknown token.
+            handled = False
+            if self._actions is not None and action.callback_token is not None:
+                handled = await self._actions.handle_action_callback(action)
+            if not handled and self._bridge is not None:
+                await self._bridge.handle_callback(action)
+            elif not handled and self._bridge is None:
+                logger.debug(
+                    "remote_callback_no_bridge connection_id={} source_key={}",
+                    action.connection_id,
+                    action.source_key,
+                )
+        else:
+            logger.debug(
+                "remote_inbound_action_unknown connection_id={} kind={}",
+                action.connection_id,
+                action.kind,
+            )
+
+    async def _handle_pairing(self, action: RemoteInboundAction) -> None:
+        """Consume a ``/start`` deep-link pairing token."""
+        from app.core.db import async_session_factory
+        from app.remote.pairing import pairing_service
+
+        token = action.pairing_token
+        if not token:
+            logger.debug(
+                "remote_pairing_start_no_token connection_id={}",
+                action.connection_id,
+            )
+            return
+
+        async with async_session_factory() as session:
+            result = await pairing_service.consume(
+                session,
+                token,
+                action.principal,
+                is_private_chat=True,
+                is_bot_sender=False,
+            )
+
+        if result is not None:
+            logger.info(
+                "remote_pairing_success connection_id={} principal_id={}",
+                action.connection_id,
+                action.principal.principal_id,
+            )
+            # A silently-persisted pairing is indistinguishable from a
+            # failed one from the phone's side — confirm it (spec: "sends
+            # Connected to EvoFlux on "). Never sent on
+            # rejection (AC-9: a refusal reveals no connection state).
+            if self._adapter is not None:
+                await self._adapter.send(
+                    RemoteOutboundMessage(
+                        connection_id=action.connection_id,
+                        destination_id=action.principal.destination_id,
+                        text=f"Connected to EvoFlux on {result.label}.",
+                        priority=RemoteOutboundPriority.HIGH,
+                    )
+                )
+        else:
+            logger.debug(
+                "remote_pairing_rejected connection_id={} principal_id={}",
+                action.connection_id,
+                action.principal.principal_id,
+            )
+
+    async def _handle_command(self, action: RemoteInboundAction) -> None:
+        """Dispatch a ``/command`` to :class:`~app.remote.actions.RemoteActionService`
+        and send its result back.
+
+        Unauthorized (unpaired sender) dispatches are answered with nothing,
+        matching every other refusal in this feature — a stranger sending
+        ``/help`` to a bot they haven't paired with must not learn anything
+        the bot is willing to say to a paired user.
         """
+        from app.core.db import async_session_factory
+
+        if self._actions is None:
+            return
+
+        async with async_session_factory() as session:
+            result = await self._actions.dispatch_command(session, action)
+
+        if result.status == "unauthorized":
+            logger.debug(
+                "remote_command_unauthorized connection_id={} principal_id={}",
+                action.connection_id,
+                action.principal.principal_id,
+            )
+            return
+
+        # ``/actions`` already sends its own message (with buttons) inside
+        # RemoteActionService — sending its returned text again here would
+        # duplicate it. Every other command relies entirely on this send.
+        command = (action.text or "").strip().split(maxsplit=1)[0][1:].lower()
+        if command == "actions":
+            return
+
+        if result.text and self._adapter is not None:
+            await self._adapter.send(
+                RemoteOutboundMessage(
+                    connection_id=action.connection_id,
+                    destination_id=action.principal.destination_id,
+                    text=result.text,
+                    priority=RemoteOutboundPriority.HIGH,
+                )
+            )
+
+    async def _handle_text(self, action: RemoteInboundAction) -> None:
+        """Submit paired plain text to the inbound service."""
+        from app.core.db import async_session_factory
+        from app.remote.inbound import RemoteInboundService
+        from app.remote.pairing import pairing_service
+
+        # Share the same PairingService instance the routes mint links
+        # through and _handle_pairing consumes tokens against — a
+        # locally-constructed one would carry its own empty rate-limiter
+        # state and diverge from the single source of truth for pairing.
+        inbound_service = RemoteInboundService(pairing_service=pairing_service)
+
+        async with async_session_factory() as session:
+            result = await inbound_service.handle_text(session, action)
+
         logger.debug(
-            "remote_inbound_action_dropped connection_id={} kind={}",
+            "remote_text_handled connection_id={} status={} session_id={}",
             action.connection_id,
-            action.kind,
+            result.status,
+            result.session_id,
         )
 
+        # Register the session with the projection so outbound events are
+        # delivered back through Telegram.
+        if result.session_id is not None and self._projection is not None:
+            self._projection.register_session(
+                str(result.session_id),
+                connection_id=str(action.connection_id),
+                destination_id=action.principal.destination_id,
+                tags=frozenset(
+                    {"remote_origin", f"remote_connection:{action.connection_id}"}
+                ),
+            )
+
 
 remote_runtime = RemoteRuntime()
diff --git a/app/remote/telegram/adapter.py b/app/remote/telegram/adapter.py
index c1eedd98..dd8646aa 100644
--- a/app/remote/telegram/adapter.py
+++ b/app/remote/telegram/adapter.py
@@ -195,7 +195,10 @@ async def send(self, message: RemoteOutboundMessage) -> None:
             raise
         self._record_delivery_success()
         if message.correlation_id is not None:
-            self._sent_messages[message.correlation_id] = (sent.chat.id, sent.message_id)
+            self._sent_messages[message.correlation_id] = (
+                sent.chat.id,
+                sent.message_id,
+            )
 
     async def edit(self, message: RemoteOutboundMessage) -> None:
         target = (
@@ -254,6 +257,7 @@ async def _run(self) -> None:
         try:
             if not await self._ensure_webhook_deleted():
                 return
+            await self._register_commands()
             self._state = RemoteConnectionState.POLLING
             offset: int | None = None
             attempt = 0
@@ -290,6 +294,27 @@ async def _run(self) -> None:
                 self._connection_id,
             )
 
+    async def _register_commands(self) -> None:
+        """Advertise the slash-command set as Telegram's native "/" menu.
+
+        Best-effort: a paired user can still type any command by hand, so a
+        failure here must never block the poll loop from starting.
+        """
+        commands = [
+            ("help", "Show available commands"),
+            ("status", "Show connection and current task status"),
+            ("new", "Start a new task"),
+            ("stop", "Stop the current running task"),
+            ("unpair", "Unpair this phone from EvoFlux"),
+            ("actions", "Show more actions (Workflows, Projects, Scheduler)"),
+        ]
+        try:
+            await self._client.set_commands(commands)
+        except (TelegramApiError, TelegramTransportError, TelegramMalformedResponseError):
+            logger.warning(
+                "remote_set_commands_failed connection_id={}", self._connection_id
+            )
+
     async def _ensure_webhook_deleted(self) -> bool:
         """AC-11: remove any webhook and drop pending updates once, before
         the first ``getUpdates`` call. Retries through transport/unknown-API
diff --git a/app/remote/telegram/client.py b/app/remote/telegram/client.py
index 1c3c7793..adc85fda 100644
--- a/app/remote/telegram/client.py
+++ b/app/remote/telegram/client.py
@@ -135,7 +135,9 @@ class TelegramClient:
     and closed — by this client.
     """
 
-    def __init__(self, token: str, *, http_client: httpx.AsyncClient | None = None) -> None:
+    def __init__(
+        self, token: str, *, http_client: httpx.AsyncClient | None = None
+    ) -> None:
         if not token:
             raise ValueError("A Telegram bot token is required.")
         self._token = token
@@ -164,7 +166,9 @@ async def _call(
                 self._url(method),
                 json=payload,
                 timeout=(
-                    httpx.Timeout(timeout) if timeout is not None else httpx.USE_CLIENT_DEFAULT
+                    httpx.Timeout(timeout)
+                    if timeout is not None
+                    else httpx.USE_CLIENT_DEFAULT
                 ),
             )
         except httpx.HTTPError as exc:
@@ -189,7 +193,9 @@ async def _call(
             ) from None
 
         if not envelope.ok:
-            retry_after = envelope.parameters.retry_after if envelope.parameters else None
+            retry_after = (
+                envelope.parameters.retry_after if envelope.parameters else None
+            )
             raise TelegramApiError(
                 error_code=envelope.error_code,
                 description=envelope.description,
@@ -270,7 +276,9 @@ async def edit_text(
         }
         if markup is not None:
             payload["reply_markup"] = markup
-        return await self._call("editMessageText", payload, result_model=TelegramMessage)
+        return await self._call(
+            "editMessageText", payload, result_model=TelegramMessage
+        )
 
     async def answer_callback(
         self, callback_query_id: str, *, text: str | None = None
diff --git a/app/services/chat_service.py b/app/services/chat_service.py
index 27d52ce0..7e77d9d1 100644
--- a/app/services/chat_service.py
+++ b/app/services/chat_service.py
@@ -779,17 +779,27 @@ async def save_queued_user_message(
     )
 
 
+def get_channel_source(extra: dict | None) -> tuple[str, dict] | None:
+    """Return channel idempotency metadata, including legacy WebBridge rows."""
+    for key in ("interactive_source", "webbridge_source"):
+        source = (extra or {}).get(key)
+        if isinstance(source, dict) and source.get("key"):
+            return key, source
+    return None
+
+
 async def mark_channel_source_delivered(db: AsyncSession, row: SessionMessage) -> bool:
     """Mark a source-keyed channel row after its delivery boundary succeeds."""
     extra = dict(row.extra or {})
-    source = extra.get("webbridge_source")
-    if not isinstance(source, dict) or not source.get("key"):
+    source_entry = get_channel_source(extra)
+    if source_entry is None:
         return False
+    source_key, source = source_entry
     if source.get("state") == "delivered":
         return False
     source = dict(source)
     source["state"] = "delivered"
-    extra["webbridge_source"] = source
+    extra[source_key] = source
     row.extra = extra
     db.add(row)
     await db.flush()
@@ -1600,9 +1610,7 @@ async def get_team_history(
 # ── Internal helpers ──────────────────────────────────────────────────────────
 
 
-def _restore_reasoning_items(
-    msg: "AssistantMessage", extra: dict | None
-) -> None:
+def _restore_reasoning_items(msg: "AssistantMessage", extra: dict | None) -> None:
     """Put the provider's reasoning items back on a rehydrated turn.
 
     They ride in ``extra`` because the field itself is excluded from the
diff --git a/app/services/interactive_message_service.py b/app/services/interactive_message_service.py
index e2fad939..417908de 100644
--- a/app/services/interactive_message_service.py
+++ b/app/services/interactive_message_service.py
@@ -12,7 +12,11 @@
 from app.models.chat import ChatSession, SessionMessage
 from app.services import agent_service, team_manager
 from app.services.agent_service import NoTeamConfigured, RawAttachment
-from app.services.chat_service import cleanup_reverted_tail, save_queued_user_message
+from app.services.chat_service import (
+    cleanup_reverted_tail,
+    get_channel_source,
+    save_queued_user_message,
+)
 
 
 @dataclass(frozen=True)
@@ -50,8 +54,8 @@ async def find_interactive_message_by_source(
         )
     ).all()
     for row in rows:
-        source = (row.extra or {}).get("webbridge_source")
-        if isinstance(source, dict) and source.get("key") == source_key:
+        source_entry = get_channel_source(row.extra)
+        if source_entry is not None and source_entry[1].get("key") == source_key:
             return row
     return None
 
@@ -138,10 +142,10 @@ async def submit_persisted_interactive_message(
                     db, session_id=session.id, source_key=source_key
                 )
             if persisted_message is not None and source_request_hash:
-                source = (persisted_message.extra or {}).get("webbridge_source")
+                source_entry = get_channel_source(persisted_message.extra)
                 if (
-                    isinstance(source, dict)
-                    and source.get("request_hash") != source_request_hash
+                    source_entry is not None
+                    and source_entry[1].get("request_hash") != source_request_hash
                 ):
                     raise InteractiveMessageConflict(
                         "Idempotency-Key was already used for another message."
@@ -149,7 +153,8 @@ async def submit_persisted_interactive_message(
             await cleanup_reverted_tail(db, session.id)
 
         if persisted_message is not None:
-            source = (persisted_message.extra or {}).get("webbridge_source") or {}
+            source_entry = get_channel_source(persisted_message.extra)
+            source = source_entry[1] if source_entry is not None else {}
             if source.get("state") == "delivered":
                 return InteractiveMessageResult(
                     status="accepted",
diff --git a/app/services/memory_stream_store.py b/app/services/memory_stream_store.py
index 971bc2c1..e63e0af7 100644
--- a/app/services/memory_stream_store.py
+++ b/app/services/memory_stream_store.py
@@ -13,6 +13,7 @@
 from __future__ import annotations
 
 import asyncio
+from collections.abc import Callable
 from copy import deepcopy
 from dataclasses import dataclass, field
 from typing import Any, AsyncGenerator, Literal, cast
@@ -246,6 +247,50 @@ def _take_replay_snapshot(state: _TurnState) -> _ReplaySnapshot:
     )
 
 
+# ── Observer registry ────────────────────────────────────────────────────────
+#
+# Synchronous callbacks invoked after every successful push_event. Observers
+# are snapshot-copied under the per-turn lock and invoked immediately after
+# releasing it, so they never block stream mutation or SSE fan-out.
+# Each observer must be synchronous and non-blocking (no DB, no network).
+
+Observer = Callable[[str, StreamEnvelope], None]
+
+_observers: list[Observer] = []
+
+
+def register_observer(observer: Observer) -> Callable[[], None]:
+    """Register a synchronous stream observer. Returns an unregister callable.
+
+    Observers receive ``(session_id, envelope)`` after every successful
+    ``push_event``. They must not perform blocking I/O or await anything.
+    Must be called from a synchronous context (e.g. server startup).
+    """
+    _observers.append(observer)
+
+    def _unregister() -> None:
+        try:
+            _observers.remove(observer)
+        except ValueError:
+            pass
+
+    return _unregister
+
+
+def _notify_observers(session_id: str, envelope: StreamEnvelope) -> None:
+    """Invoke every registered observer. Exception-isolated."""
+    for observer in list(_observers):
+        try:
+            observer(session_id, envelope)
+        except Exception as exc:
+            logger.warning(
+                "stream_observer_failed session_id={} event_type={} error={}",
+                session_id,
+                envelope.event,
+                exc,
+            )
+
+
 # Me store all active turns here
 _turns: dict[str, _TurnState] = {}
 
@@ -311,8 +356,13 @@ async def push_event(session_id: str, envelope: StreamEnvelope) -> None:
     at the type boundary.  Producers build envelopes via
     :meth:`StreamEnvelope.from_event` (for typed ``*Event`` payloads) or
     :meth:`StreamEnvelope.from_parts` (for ad-hoc lifecycle events).
+
+    After the per-turn lock is released, registered observers are invoked
+    synchronously with ``(session_id, envelope)``.  Observers are
+    exception-isolated — one failure never prevents the next from running.
     """
     try:
+        pushed = False
         while True:
             state = _turns.get(session_id)
             if state is None:
@@ -324,7 +374,10 @@ async def push_event(session_id: str, envelope: StreamEnvelope) -> None:
                 if _turns.get(session_id) is not state:
                     continue
                 _push_event_locked(session_id, state, envelope)
-                return
+                pushed = True
+                break
+        if pushed:
+            _notify_observers(session_id, envelope)
     except Exception as exc:
         logger.warning(
             "memory_store_push_failed session_id={} error={}",
@@ -855,3 +908,4 @@ async def attach(session_id: str) -> AsyncGenerator[dict[str, str], None]:
 async def close() -> None:
     """Clear all state (called on server shutdown)."""
     _turns.clear()
+    _observers.clear()
diff --git a/docs/development/local-development-windows-macos.md b/docs/development/local-development-windows-macos.md
new file mode 100644
index 00000000..ae638df1
--- /dev/null
+++ b/docs/development/local-development-windows-macos.md
@@ -0,0 +1,663 @@
+# Local development setup for Windows and macOS
+
+Status: current operational plan
+
+Audience: contributors installing EvoFlux from source for the first time and
+maintaining a repeatable daily development environment.
+
+This guide covers native Windows and macOS development for the complete EvoFlux
+desktop stack:
+
+```text
+FastAPI sidecar (:8000) + Vite UI (:5173) + Tauri desktop shell
+```
+
+It was derived from the repository's `README.md`, `Makefile`,
+`scripts/run_dev.py`, `desktop/Makefile`, package lockfiles, Tauri configuration,
+platform tests, and desktop packaging workflow. Use
+[Development and testing](setup-and-testing.md) for the concise quality-gate
+reference and [Project deep dive](project-deep-dive.md) for architecture and
+change ownership.
+
+## Findings from the repository
+
+The project already contains:
+
+- Python `>=3.12` metadata and a committed `uv.lock`;
+- a committed Bun lockfile at `web/bun.lock`;
+- a committed Rust lockfile at `desktop/src-tauri/Cargo.lock`;
+- `make dev-web` for FastAPI plus Vite;
+- `make dev-desktop` for FastAPI, Vite, and Tauri;
+- a supervisor in `scripts/run_dev.py` that stops sibling processes when one
+  fails;
+- distinct external-backend and bundled-sidecar Tauri development configs;
+- first-start initialization that creates runtime roots and installs local seed
+  agents without overwriting existing user files;
+- Windows and macOS package jobs in `.github/workflows/desktop-packages.yml`.
+
+There is one important platform gap: `scripts/run_dev.py` currently assumes
+Unix process and port tools (`lsof`, `os.killpg`, POSIX signals, and
+`start_new_session`). The root Make targets also use Unix shell syntax. This is
+appropriate for macOS, but native Windows should use the three-terminal
+PowerShell flow in this guide until a Windows supervisor is added.
+
+## Choose the run mode
+
+| Mode | Use it for | Command style |
+|---|---|---|
+| API only | Backend/API debugging | one terminal |
+| Web development | Normal backend/frontend work without native capabilities | API + Vite |
+| Desktop development | Default product-development loop | API + Vite + Tauri against source |
+| Bundled-sidecar development | Sidecar imports, migrations, token handshake, resources, cleanup | rebuilt sidecar + Vite + Tauri |
+| Native package | Installer/updater/release validation | host-platform release build |
+
+Start with desktop development. Use web-only mode when native commands do not
+matter. Use bundled-sidecar mode only for changes that can behave differently
+after Python packaging.
+
+## Shared requirements
+
+Both platforms need:
+
+- Git;
+- Python 3.12 managed through `uv`;
+- Bun;
+- Rust stable and Cargo;
+- Tauri CLI v2;
+- platform-native Tauri build dependencies;
+- an LLM provider credential, OAuth connection, or local model runtime to run
+  real agent turns.
+
+Official prerequisite references:
+
+- [Tauri v2 prerequisites](https://v2.tauri.app/start/prerequisites/)
+- [uv installation](https://docs.astral.sh/uv/getting-started/installation/)
+- [Bun installation](https://bun.sh/docs/installation)
+- [Rust installation](https://www.rust-lang.org/tools/install/)
+
+Do not install a separate global Python package copy of EvoFlux for source
+development. `uv sync` creates and manages the repository environment.
+
+## Windows: first-time setup
+
+Use 64-bit Windows 10/11 and PowerShell. The production package is x64, while
+the Rust crate uses the MSVC toolchain.
+
+### 1. Install native build prerequisites
+
+Install [Microsoft C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)
+and select **Desktop development with C++**. Include the recommended MSVC and
+Windows SDK components.
+
+Tauri uses Microsoft Edge WebView2. It is normally already present on current
+Windows 10/11 systems. If it is missing, install the
+[WebView2 Evergreen Runtime](https://developer.microsoft.com/microsoft-edge/webview2/).
+
+EvoFlux builds NSIS packages on Windows, so the MSI-only VBSCRIPT prerequisite
+is not needed for the normal project build.
+
+### 2. Install command-line tools
+
+Run PowerShell as the normal development user:
+
+```powershell
+winget install --id Git.Git -e
+winget install --id astral-sh.uv -e
+powershell -c "irm bun.sh/install.ps1|iex"
+winget install --id Rustlang.Rustup -e
+```
+
+Close and reopen PowerShell so user `PATH` changes are visible. Then select the
+MSVC Rust toolchain and install Tauri CLI:
+
+```powershell
+rustup default stable-msvc
+cargo install tauri-cli --version "^2" --locked
+```
+
+If Bun installed successfully but is not on `PATH`, verify it directly:
+
+```powershell
+& "$env:USERPROFILE\.bun\bin\bun" --version
+```
+
+Then restart the terminal. Follow Bun's official `PATH` instructions if the
+direct command works but `bun --version` does not.
+
+### 3. Verify the toolchain
+
+```powershell
+git --version
+uv --version
+bun --version
+rustup --version
+rustc --version
+cargo --version
+cargo tauri --version
+```
+
+Do not proceed until every command succeeds in a newly opened PowerShell
+window. If Cargo fails to link a minimal build, reopen the Visual Studio Build
+Tools installer and confirm the C++ desktop workload and Windows SDK.
+
+### 4. Clone or open the repository
+
+If the repository is not already present:
+
+```powershell
+git clone https://github.com/evoelsewhere/evoflux.git
+Set-Location evoflux
+```
+
+From an existing checkout, start at the repository root containing
+`pyproject.toml`, `uv.lock`, `web/`, and `desktop/`.
+
+### 5. Install locked project dependencies
+
+```powershell
+uv python install 3.12
+uv sync --frozen
+
+Push-Location web
+bun install --frozen-lockfile
+Pop-Location
+
+Push-Location desktop\src-tauri
+cargo check
+Pop-Location
+```
+
+`uv sync --frozen` creates `.venv` and installs backend plus development
+dependencies from `uv.lock`. `bun install --frozen-lockfile` creates
+`web/node_modules` without changing `web/bun.lock`. The first Cargo check
+downloads and compiles Rust dependencies and can take several minutes.
+
+### 6. Initialize source-development configuration
+
+Keep source data separate from a packaged/production EvoFlux installation:
+
+```powershell
+$env:APP_ENV = "development"
+uv run evoflux init
+```
+
+The interactive initializer stores development configuration beneath
+`.evoflux/dev/`. It asks for a provider/model and writes credentials to the
+development config root. Alternatively, skip the interactive command, start
+the UI, and configure a provider in Settings; startup will still seed agent
+blueprints automatically.
+
+Source development does not auto-apply Alembic revisions. Create or upgrade the
+isolated development database before the first run:
+
+```powershell
+$env:APP_ENV = "development"
+uv run alembic -c app\alembic.ini upgrade head
+```
+
+Never commit `.evoflux/`, `.env`, OAuth tokens, API keys, or provider
+credentials.
+
+## Windows: run the project
+
+The current reliable native-Windows flow uses three PowerShell terminals.
+
+### Terminal 1: FastAPI
+
+```powershell
+Set-Location D:\path\to\evoflux
+$env:APP_ENV = "development"
+uv run uvicorn app.server:app `
+  --host 127.0.0.1 `
+  --port 8000 `
+  --reload `
+  --reload-dir app `
+  --no-access-log
+```
+
+### Terminal 2: Vite
+
+```powershell
+Set-Location D:\path\to\evoflux\web
+$env:VITE_API_PROXY_TARGET = "http://127.0.0.1:8000"
+bun dev
+```
+
+### Terminal 3: Tauri
+
+```powershell
+Set-Location D:\path\to\evoflux\desktop\src-tauri
+$env:EVOFLUX_DESKTOP_DEV_BACKEND_URL = "http://127.0.0.1:8000"
+cargo tauri dev -c tauri.dev.conf.json
+```
+
+Replace `D:\path\to\evoflux` with the checkout's real path. The desktop window
+should be named **EvoFlux (dev)** and coexist with a packaged EvoFlux install.
+
+Stop development with `Ctrl+C` in Terminal 3, then Terminal 2, then Terminal 1.
+Check ports before restarting if a process was force-closed:
+
+```powershell
+Get-NetTCPConnection -LocalPort 8000,5173 -State Listen -ErrorAction SilentlyContinue
+```
+
+### Windows web-only shortcut
+
+Use only Terminals 1 and 2, then open `http://localhost:5173`. Native Tauri
+commands, persistent browser behavior, tray integration, and native dialogs are
+not fully represented in browser-only mode.
+
+## macOS: first-time setup
+
+The same steps work on Apple Silicon and Intel Macs. The repository and CI
+build both architectures.
+
+### 1. Install Apple build tools
+
+For desktop-only development:
+
+```bash
+xcode-select --install
+```
+
+If full Xcode is already installed, launch it once to finish component setup
+and accept its license. Verify:
+
+```bash
+xcode-select -p
+clang --version
+make --version
+lsof -v
+```
+
+The unified launcher requires `make` and `lsof`; both are normally available
+after the Apple command-line tools are installed.
+
+### 2. Install uv, Bun, and Rust
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+curl -fsSL https://bun.com/install | bash
+curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh
+```
+
+Open a new Terminal, or load the Rust environment in the current shell:
+
+```bash
+source "$HOME/.cargo/env"
+```
+
+Install Tauri CLI:
+
+```bash
+rustup default stable
+cargo install tauri-cli --version '^2' --locked
+```
+
+Homebrew is optional. If the standalone installers are not desired, official
+package-manager alternatives include `brew install uv` and
+`brew install oven-sh/bun/bun`; use one installation method per tool to avoid
+conflicting upgrade paths.
+
+### 3. Verify the toolchain
+
+```bash
+git --version
+uv --version
+bun --version
+rustup --version
+rustc --version
+cargo --version
+cargo tauri --version
+```
+
+### 4. Clone and install locked dependencies
+
+```bash
+git clone https://github.com/evoelsewhere/evoflux.git
+cd evoflux
+
+uv python install 3.12
+uv sync --frozen
+
+cd web
+bun install --frozen-lockfile
+cd ..
+
+cd desktop/src-tauri
+cargo check
+cd ../..
+```
+
+Skip the clone commands when using an existing checkout.
+
+### 5. Initialize source-development configuration
+
+```bash
+APP_ENV=development uv run evoflux init
+APP_ENV=development uv run alembic -c app/alembic.ini upgrade head
+```
+
+As on Windows, the UI can perform provider setup after launch if the
+interactive initializer is skipped.
+
+## macOS: run the project
+
+Run the complete source stack from the repository root:
+
+```bash
+APP_ENV=development make dev-desktop
+```
+
+The supervisor starts FastAPI, Vite, and Tauri, prefixes their logs, and stops
+the remaining services when one exits. Stop the group with `Ctrl+C`.
+
+For backend/frontend work without native capabilities:
+
+```bash
+APP_ENV=development make dev-web
+```
+
+Open `http://localhost:5173` if a browser does not open automatically.
+
+## Verify a successful run
+
+Use these acceptance checks on either platform:
+
+1. FastAPI logs show startup reached `critical_startup_ready`.
+2. `http://127.0.0.1:8000/api/health/live` returns a successful response.
+3. Vite reports `http://localhost:5173` ready.
+4. **EvoFlux (dev)** opens and passes its backend loading screen.
+5. Work mode creates or resolves a session.
+6. Coding mode can select an authorized repository.
+7. A configured model can complete one simple response.
+8. Closing the Tauri dev process does not leave an unexpected desktop child
+   process; in source mode the separately started API/Vite processes remain
+   until their terminals are stopped.
+
+PowerShell health check:
+
+```powershell
+Invoke-RestMethod http://127.0.0.1:8000/api/health/live
+```
+
+macOS health check:
+
+```bash
+curl -fsS http://127.0.0.1:8000/api/health/live
+```
+
+## Daily continuous-development loop
+
+### Start of day
+
+1. Open the repository and inspect existing work:
+
+   ```bash
+   git status --short
+   git branch --show-current
+   ```
+
+2. Update safely when appropriate:
+
+   ```bash
+   git pull --ff-only
+   ```
+
+3. Reconcile dependencies when lockfiles changed:
+
+   ```bash
+   uv sync --frozen
+   cd web && bun install --frozen-lockfile && cd ..
+   cd desktop/src-tauri && cargo check && cd ../..
+   ```
+
+4. Apply new database revisions when `app/migrations/` changed:
+
+   ```bash
+   APP_ENV=development uv run alembic -c app/alembic.ini upgrade head
+   ```
+
+5. Start the macOS unified flow or Windows three-terminal flow.
+6. Keep `APP_ENV=development` on the source backend so dev state stays under
+   `.evoflux/dev/`.
+
+PowerShell uses `Push-Location`/`Pop-Location` instead of the chained `cd`
+examples above.
+
+### During development
+
+- Read root and nearest nested `AGENTS.md` files before editing.
+- Follow the specification and acceptance workflow in the
+  [project deep dive](project-deep-dive.md#continued-development-workflow).
+- Run the smallest focused test while iterating.
+- Keep secrets and generated state out of Git.
+- Do not delete `.evoflux/dev/config`, wiki, or workspaces merely to fix a
+  cache problem; cache and state have different retention rules.
+- Restart only the affected service where possible. Python and Vite normally
+  reload automatically; Rust changes rebuild the Tauri process.
+
+### Before handoff
+
+Backend gate:
+
+```bash
+uv run ruff check app/ tests/
+uv run ruff format --check app/ tests/
+uv run ty check app/
+uv run pytest --no-cov -q
+```
+
+Frontend gate:
+
+```bash
+cd web
+bun run lint
+bun run typecheck
+bun run build
+```
+
+Desktop gate:
+
+```bash
+cd desktop/src-tauri
+cargo check
+```
+
+Finish with `git diff --check` and report exact commands, failures, and checks
+not run.
+
+## Dependency update policy
+
+The committed lockfiles are the reproducibility boundary.
+
+| Ecosystem | Normal install | Intentional dependency change |
+|---|---|---|
+| Python | `uv sync --frozen` | edit `pyproject.toml`, run the appropriate `uv add`/`uv lock`, review `uv.lock` |
+| Web | `bun install --frozen-lockfile` | edit `web/package.json` or use `bun add`, review `package.json` and `bun.lock` |
+| Rust | `cargo check --locked` where appropriate | edit `Cargo.toml` or use `cargo add`, review `Cargo.toml` and `Cargo.lock` |
+
+Do not casually upgrade all three ecosystems during an unrelated feature.
+Toolchain upgrades should be a separate, verified change because they affect
+desktop packaging and CI.
+
+## Bundled-sidecar validation
+
+Use this after changes to sidecar packaging, startup imports, migrations,
+desktop token authentication, bundled resources, process cleanup, or Office
+preview dependencies.
+
+### macOS
+
+Run Vite in one terminal:
+
+```bash
+cd web
+bun dev
+```
+
+Run the packaged-style sidecar/Tauri path in another:
+
+```bash
+make -C desktop dev-bundled
+```
+
+### Windows
+
+Build the sidecar from the repository root:
+
+```powershell
+uv run python scripts\build_sidecar.py `
+  --root . `
+  --out desktop\sidecar-bundle `
+  --python-version 3.12 `
+  --extras office-preview
+```
+
+Start Vite in one terminal, then run the bundled Tauri configuration from
+`desktop\src-tauri` in another. Set `EVOFLUX_APP_ENV=development` and explicit
+`EVOFLUX_*_DIR` values under the repository's `.evoflux\dev` directory before
+launching so the Rust supervisor passes isolated paths to the child sidecar.
+
+This Windows flow should receive a project-owned PowerShell wrapper before it
+becomes a routine developer command.
+
+## Native package smoke builds
+
+Package only on the target operating system.
+
+### Windows NSIS
+
+```powershell
+uv run python scripts\build_sidecar.py `
+  --root . `
+  --out desktop\sidecar-bundle `
+  --python-version 3.12 `
+  --extras office-preview
+
+Push-Location desktop\src-tauri
+cargo tauri build --bundles nsis
+Pop-Location
+```
+
+### macOS app/DMG
+
+```bash
+make -C desktop sidecar
+make -C desktop build
+```
+
+Unsigned or ad-hoc local packages may trigger operating-system trust prompts.
+Signing, notarization, updater metadata, and release artifact validation follow
+the [release and packaging contract](release-and-packaging.md), not this daily
+development guide.
+
+## Troubleshooting decision tree
+
+### A command is not found
+
+1. Open a new shell after installation.
+2. Run the tool by its known install path to distinguish installation from
+   `PATH` configuration.
+3. Confirm only one package manager owns the tool.
+4. Re-run the toolchain verification block before retrying EvoFlux.
+
+### Port 8000 or 5173 is already in use
+
+- Stop the known prior EvoFlux dev terminal with `Ctrl+C`.
+- Inspect the owning PID before terminating anything.
+- Do not indiscriminately kill all Python, Bun, Node, or Cargo processes.
+
+### Backend starts but the UI cannot connect
+
+- Confirm `/api/health/live` works directly.
+- Confirm Vite has `VITE_API_PROXY_TARGET=http://127.0.0.1:8000`.
+- Confirm Tauri has
+  `EVOFLUX_DESKTOP_DEV_BACKEND_URL=http://127.0.0.1:8000`.
+- Check that a stale packaged backend selection is not being used; the dev
+  environment variable should force the source backend.
+
+### Python imports or migrations fail
+
+- Run `uv sync --frozen` again.
+- Confirm `uv run python --version` is Python 3.12 or newer.
+- Confirm `APP_ENV=development` and inspect `.evoflux/dev/state` logs.
+- Do not delete the database before reading the migration error.
+
+### Windows linker or WebView failure
+
+- Confirm the Visual Studio **Desktop development with C++** workload.
+- Run `rustup default stable-msvc`.
+- Confirm the Windows SDK and Edge WebView2 Runtime are installed.
+- Restart the terminal or computer after native toolchain installation.
+
+### macOS compiler or permission failure
+
+- Run `xcode-select -p` and `xcodebuild -license` if prompted.
+- Launch full Xcode once after an update.
+- Treat microphone, screen capture, accessibility, and automation permissions
+  as OS-managed state; dev and packaged app identifiers may receive separate
+  permission records.
+
+## Planned Windows developer-experience improvement
+
+The immediate three-terminal flow is functional, but continued development
+should add a native PowerShell supervisor. This is an internal developer-tool
+change with unchanged product behavior.
+
+### Invariants
+
+- Start the same API, Vite, and optional Tauri commands as `run_dev.py`.
+- Preserve API/Vite port configuration and environment propagation.
+- Stop only processes started by the supervisor.
+- Leave pre-existing unrelated listeners untouched unless the user explicitly
+  chooses to replace them.
+- Preserve `Ctrl+C` cleanup and non-zero sibling-failure propagation.
+- Default source runs to isolated development roots.
+
+### Proposed acceptance criteria
+
+- **DEV-AC-1:** Given a native Windows checkout with required tools, one
+  documented PowerShell command starts API, Vite, and Tauri with prefixed logs.
+- **DEV-AC-2:** Given port 8000 or 5173 is occupied, preflight exits before
+  starting children and identifies the occupied port without killing it.
+- **DEV-AC-3:** Given any child exits non-zero, the supervisor stops its own
+  remaining children and returns the failing status.
+- **DEV-AC-4:** Given `Ctrl+C`, every owned child exits and no new listener
+  remains on the configured ports.
+- **DEV-AC-5:** Given source mode, backend data/config/state/cache/workspace/wiki
+  roots resolve beneath `.evoflux/dev/` unless explicitly overridden.
+- **DEV-AC-6:** Focused Windows-compatible tests cover command construction,
+  environment propagation, occupied ports, sibling failure, and interrupt
+  cleanup.
+
+### Suggested ownership
+
+| Work | Files |
+|---|---|
+| Windows supervisor | new `scripts/run_dev.ps1` or a cross-platform revision of `scripts/run_dev.py` |
+| Root entry command | a PowerShell-documented command; avoid making GNU Make mandatory on Windows |
+| Regression tests | `tests/scripts/test_run_dev.py` plus Windows-specific tests |
+| Current docs | this guide, `setup-and-testing.md`, and the README source-run section |
+
+Do not implement this by relying on WSL for the native Tauri shell. WSL may be
+useful for backend-only development, but it is not the primary Windows desktop
+capability and process-lifecycle environment.
+
+## Setup completion checklist
+
+- [ ] Platform-native Tauri prerequisites installed
+- [ ] Git, uv, Bun, Rust, Cargo, and Tauri CLI verified in a new shell
+- [ ] Python 3.12 installed through uv
+- [ ] `uv sync --frozen` completed
+- [ ] `bun install --frozen-lockfile` completed
+- [ ] `cargo check` completed
+- [ ] Alembic upgraded the isolated development database to `head`
+- [ ] Source backend runs with `APP_ENV=development`
+- [ ] FastAPI health endpoint succeeds
+- [ ] Vite serves port 5173
+- [ ] EvoFlux (dev) opens through Tauri
+- [ ] Provider/model configured without committing credentials
+- [ ] One Work session and one Coding workspace smoke-tested
+- [ ] Stop/restart leaves no unexpected owned processes
+- [ ] Focused baseline tests recorded before feature development begins
diff --git a/docs/development/project-deep-dive.md b/docs/development/project-deep-dive.md
new file mode 100644
index 00000000..0beb90fe
--- /dev/null
+++ b/docs/development/project-deep-dive.md
@@ -0,0 +1,713 @@
+# EvoFlux project deep dive and continuation guide
+
+Status: current-state engineering guide
+
+Snapshot: `main` at `77cfd871` (`2026-08-25`)
+
+Audience: contributors preparing to change, test, package, or extend EvoFlux
+
+This guide is the shortest end-to-end mental model of the repository. It
+summarizes what EvoFlux builds, how its processes and source tree fit together,
+where runtime and development knowledge live, the conventions visible in code
+and Git history, and the workflow expected for continued development.
+
+It does not replace the detailed contracts linked throughout the document.
+When this guide, current-state documentation, tests, and code disagree, follow
+the source-of-truth rules in [Development knowledge used by contributors](#development-knowledge-used-by-contributors)
+and reconcile the discrepancy in the same change.
+
+## Executive summary
+
+EvoFlux is a local-first desktop workspace for teams of Work and Coding agents.
+It is not primarily a hosted web application. The production product combines:
+
+1. a Rust/Tauri desktop shell that owns native lifecycle and capabilities;
+2. a React/TypeScript UI rendered in the Tauri WebView;
+3. a local Python/FastAPI sidecar that owns agent execution, policy,
+   persistence, workspace authorization, automation, and integrations.
+
+The key architectural idea is that models are replaceable reasoning engines.
+EvoFlux owns the durable harness around them: context construction, agent/team
+configuration, tools, permission checks, sandboxing, streaming, persistence,
+memory, code intelligence, and verification.
+
+The product has two durable execution modes:
+
+- **Work mode** gives a session an isolated EvoFlux-managed workspace and a
+  general execution/exploration team.
+- **Coding mode** authorizes one repository or a named multi-repository project
+  and adds editor, Git, code graph, LSP, Problems, ChangeSet, review, terminal,
+  and worktree behavior.
+
+The most important boundaries for future changes are:
+
+- keep FastAPI routes thin and reusable behavior in services/runtime modules;
+- keep provider payloads behind provider adapters and generic schemas neutral;
+- keep server state in TanStack Query and live/client state in Zustand;
+- keep native lifecycle and capabilities in Tauri, but policy and persistence
+  in the sidecar;
+- keep the application database separate from rebuildable repository indexes;
+- treat external/tool/model/memory content as untrusted data;
+- update specification, implementation, tests, current docs, and Help together
+  when a user-visible contract changes.
+
+## What the project builds
+
+The repository produces four related artifacts:
+
+| Artifact | Output and purpose |
+|---|---|
+| React application | `web/dist/`; the production UI embedded by Tauri |
+| Python wheel | API-only `evoflux` package with the CLI, sidecar code, Alembic resources, and offline seed bundle; it does not embed the web UI |
+| Python sidecar bundle | `desktop/sidecar-bundle/`; a standalone runtime assembled for native packaging and never committed |
+| Native desktop packages | macOS DMG, Windows current-user NSIS installer, and Linux amd64 DEB |
+
+Version `0.0.8` is declared in the Python, web, and Tauri package metadata. The
+Python project description is “Self-hosted AI agents,” but the current product
+contract positions EvoFlux as a desktop application; the FastAPI-only wheel and
+Vite server are development, integration, and headless API surfaces.
+
+Implemented product areas include streaming multi-agent chat, sessions and
+folders, goals, workflows, scheduling, files and previews, terminal/process
+control, Side Chat, Git/reviews, code graph/search, optional LSP integration,
+scoped memory, a Markdown wiki with Dream consolidation, model providers,
+Skills, MCP, plugins, browser/WebBridge integrations, sandbox/permissions, and
+local telemetry. The authoritative implementation index is the
+[feature catalogue](../features/README.md).
+
+## Architectural mental model
+
+```text
+User
+  |
+  v
+Tauri shell (Rust)
+  |  native lifecycle, dialogs, tray, browser profile, capabilities, updates
+  |  launches sidecar and injects per-launch origin/token
+  v
+React WebView (TypeScript)
+  |  HTTP for commands/data, SSE for agent events, WebSocket for terminals/browser
+  v
+FastAPI sidecar (Python)
+  |-- API routes: validation and transport translation
+  |-- services: durable business and integration behavior
+  |-- agent runtime: providers, hooks, tools, policy, teams
+  |-- workflow/scheduler: automated execution
+  |-- SQLModel/Alembic: durable application state
+  `-- filesystem stores: config, wiki, workspaces, state, cache
+```
+
+### Process ownership
+
+| Concern | Owner | Important entry points |
+|---|---|---|
+| Native startup and shutdown | Tauri | `desktop/src-tauri/src/main.rs`, `sidecar.rs` |
+| Web bootstrap and routing | React | `web/src/main.tsx`, `App.tsx`, `router.ts`, `routes/work.tsx` |
+| HTTP application lifecycle | FastAPI | `app/server.py`, `app/api/app.py` |
+| Session/team orchestration | Python services/runtime | `app/services/chat_service.py`, `team_manager.py`, `app/agent/mode/team/` |
+| Model/tool loop | Agent runtime | `app/agent/agent_loop/core.py` and sibling modules |
+| Persistent application state | SQLModel/Alembic | `app/models/`, `app/scheduler/models.py`, `app/migrations/` |
+| Repository intelligence | Cache-local service | `app/services/code_index/` |
+
+The desktop shell starts the bundled sidecar on loopback with an ephemeral port
+and random bearer token, waits for a handshake and liveness, then makes the
+origin and token available to the WebView. The frontend installs same-origin
+desktop authentication before other modules capture `fetch`. Cross-origin
+requests do not receive the desktop token.
+
+## Repository structure and ownership
+
+```text
+app/          Python sidecar, CLI, agent runtime, services, persistence
+web/          React/Vite UI embedded in Tauri
+desktop/      Rust/Tauri shell and native packaging
+seed/         first-install agent and configuration templates
+scripts/      development, validation, packaging, and release utilities
+tests/        Python backend, integration, CLI, and packaging tests
+docs/         only project documentation root
+test-artifacts/ checked-in visual evidence for selected tests/reviews
+```
+
+Before editing anywhere, read the root `AGENTS.md` and the nearest nested one.
+Nested instructions currently exist for `app/`, `app/agent/`, `app/api/`,
+`app/services/`, `web/`, `web/src/`, `desktop/`, `desktop/src-tauri/`, `seed/`,
+and `scripts/`.
+
+### Backend map
+
+| Path | Responsibility and extension rule |
+|---|---|
+| `app/api/routes/` | HTTP, SSE, upload, and WebSocket boundary. Validate and delegate; do not accumulate business logic here. |
+| `app/api/schemas/` | Shared transport request/response shapes. Any shape change must be traced into frontend parsing and rendering. |
+| `app/services/` | Reusable business logic for routes, CLI, scheduler, and agent runtime. |
+| `app/agent/agent_loop/` | Per-turn streaming loop, retry/fallback, tool dispatch, checkpointing, and observation limits. |
+| `app/agent/hooks/` | Context injection, memory, persistence, streaming, telemetry, diagnostics, and completion behavior. |
+| `app/agent/mode/team/` | Lead/member lifecycle, mailboxes, delegation, handoff, todo, continuation, and team concurrency. |
+| `app/agent/providers/` | Provider adapters and routing. Provider-specific wire shapes stop here. |
+| `app/agent/tools/` | Tool registry, metadata, permission integration, and built-in implementations. |
+| `app/agent/skills/` | Skill discovery, collision resolution, settings overlays, and activation. |
+| `app/agent/mcp/` | User-global MCP config, process/client manager, and exposed MCP tools. |
+| `app/plugin_platform/` | Portable Agent Plugin install/runtime boundary and isolated plugin MCP. |
+| `app/workflow/` | Workflow schema, validation, graph, runner, and node handlers. |
+| `app/scheduler/` | At/every/cron task persistence and team dispatch. |
+| `app/conductor/` | Optional managed-resource and telemetry control-plane client. |
+| `app/core/` | Settings, paths, database lanes, auth, logging, metrics, and telemetry. |
+| `app/models/` and `app/migrations/` | Application SQLModel metadata and 54-version Alembic history at this snapshot. |
+| `app/cli/` | `evoflux` CLI parser and command modules. |
+
+### Frontend map
+
+| Path | Responsibility and extension rule |
+|---|---|
+| `web/src/router.ts` | Work, Coding, Telemetry, and Scheduler route tree. Settings and Help are overlays. |
+| `web/src/routes/work.tsx` | Resolves/restores Work or Coding session focus and synchronizes URL/store state. |
+| `web/src/components/TeamChatView/` | Main composition root for chat, sidebars, workbench, SSE hooks, and responsive layouts. |
+| `web/src/components/shell/` | Shared application, sidebar, row, menu, and side-panel chrome. Reuse these primitives. |
+| `web/src/components/workbench/` | Lazy workbench dock, registry, surfaces, and open-with behavior. |
+| `web/src/api/` | HTTP client domains, same-origin token handling, SSE parser, and Tauri boundary. |
+| `web/src/queries/` | TanStack Query keys, queries, mutations, and durable server-state caching. |
+| `web/src/stores/` | Zustand live-turn and client/UI state. SSE reduction lives with the team store. |
+| `web/src/help/locales/` | Localized user-facing Help in English, Vietnamese, and Japanese. |
+| `web/src/__tests__/` | Vitest tests for components, API helpers, stores, hooks, Help, and utilities. |
+
+`TeamChatView` and the team store are high-connectivity areas. They are already
+split into hooks, reducers, domain clients, and lazy panels; extend those seams
+instead of growing a second composition or state path.
+
+### Desktop and packaging map
+
+| Path | Responsibility |
+|---|---|
+| `desktop/src-tauri/src/main.rs` | Tauri plugins, windows, tray/events, and native command registration |
+| `desktop/src-tauri/src/sidecar.rs` | Sidecar discovery, launch, handshake, health, and cleanup |
+| `desktop/src-tauri/src/workspace.rs` | Native workspace/filesystem integration |
+| `desktop/src-tauri/src/native_messaging.rs` | Browser native-messaging bridge |
+| `desktop/src-tauri/capabilities/` | Explicit Tauri command grants |
+| `desktop/src-tauri/tauri*.json` | Production, external-dev, and bundled-dev variants |
+| `scripts/build_sidecar.py` | Standalone Python runtime assembly |
+| `.github/workflows/desktop-packages.yml` | Four-platform packaging, signing, updater, and artifact workflow |
+
+## End-to-end runtime walkthrough
+
+### Startup
+
+1. Tauri creates the application shell and starts or connects to the Python
+   sidecar according to the selected development/production configuration.
+2. The sidecar reports its chosen loopback port and token through the handshake.
+3. FastAPI initializes the workspace roots, validates/migrates the database in
+   production, seeds the wiki, initializes telemetry, and exposes the critical
+   API before slower optional integrations finish.
+4. Optional startup tasks reconcile MCP, plugin MCP, Conductor, agent files,
+   scheduler, scoped-memory backfill, Dream scheduling, and retention services.
+5. React waits for backend readiness, installs authentication, restores theme,
+   appearance, locale, and the last mode route, then mounts the router.
+
+Optional service failure is observable but should not make the critical local
+API disappear. Shutdown drains or stops teams, indexes, processes, previews,
+language servers, memory extraction, telemetry, and database engines.
+
+### One chat turn
+
+1. `POST /api/team/chat` validates and queues a request, returning `202`.
+2. `team_manager` resolves/builds the correct Work or Coding team. Coding
+   identity includes the authorized workspace/project, not just a UI mode bit.
+3. The session transcript and current checkpoint are loaded from SQLite.
+4. Hooks add bounded workspace instructions, project/folder context, selected
+   Skills, profile data, scoped memory recall, and other runtime context.
+5. A provider adapter translates canonical messages/tools to its own protocol
+   and streams text, reasoning, usage, and tool calls back into canonical types.
+6. The loop partitions tool calls into concurrency-safe waves and serial
+   barriers, with at most ten concurrently executing tools.
+7. Permission, sandbox, workspace authorization, and outbound-data policy are
+   enforced before the tool/model boundary. Large observations can be offloaded
+   to artifacts rather than kept inline.
+8. The loop continues through tool results until a final response, explicit
+   pause, interruption, recoverable continuation, or terminal error.
+9. Checkpoints and hooks persist transcript/usage, update goals/workflows,
+   publish SSE events, collect diagnostics, and schedule memory extraction.
+10. The frontend loads durable history first, layers the live SSE projection
+    over it, and updates Query caches through an explicit invalidation bridge.
+
+SSE is the live projection; SQLite session/message history is the durable truth
+used for reconnect and pagination. Bidirectional terminal, direct-browser, and
+WebBridge relay channels use WebSockets instead.
+
+### Teams and delegation
+
+Exactly one lead is required per team. Member definitions are lazy blueprints,
+not permanent background processes. Delegation creates instances such as
+`coder#1`; each gets its own child session, mailbox, history, and lifecycle.
+Member text/tools/status are streamed through the parent session without
+copying the member's complete model context into the lead. Durable delegation
+rows record the work state, while the lead remains responsible for verifying a
+handoff before presenting it as complete.
+
+## How knowledge is stored
+
+“Knowledge” has two meanings in this project and they should not be mixed.
+
+### Runtime knowledge used by agents
+
+| Layer | Storage | Role and trust rule |
+|---|---|---|
+| Working memory | `chat_sessions` and `session_messages` in the application DB | Full durable transcript; provider-visible history may be compacted, but audit history remains. |
+| Episodic evidence | `memory_fact_evidence` | Links a fact to the source session/message that established it. |
+| Semantic memory | `memory_facts` | Deduplicated facts with explicit user/project/workspace/folder/session scope, confidence, kind, status, origin, and occurrence count. |
+| Extraction cursor | `memory_extraction_states` | Retryable lease/cursor so background extraction is idempotent across restarts. |
+| Inspectable wiki | Markdown under `EVOFLUX_WIKI_DIR` | Human-readable profile, notes, topics, entities, sources, comparisons, indexes, and Dream logs. Treated as data, not executable policy. |
+| Code knowledge | One cache-local SQLite DB per repository | Rebuildable files, chunks, FTS rows, symbols, relations, vectors, and parse errors. Never application DB state. |
+
+Semantic facts are the canonical automatic-recall store. The wiki is an
+inspectable consolidation/projection and manual knowledge surface, not the sole
+copy of extracted memory. Automatic extraction begins after the configured
+completed-lead-response threshold (default behavior starts at three and then
+periodically), rejects secret-like content, limits fact count/length, and
+coerces invalid broad scopes to the narrowest available safe scope.
+
+Recall searches only compatible scopes and injects a small cited result inside
+an explicit untrusted-data boundary. User-global scope is limited to explicit
+durable preferences/profile; technical decisions stay project/workspace/folder
+or session local. Deleting a session removes its evidence and deletes a fact
+only when no other evidence remains.
+
+The wiki is seeded idempotently with:
+
+```text
+USER.md             durable profile YAML, injected as bounded data
+INDEX.md            Dream-maintained table of contents
+LOG.md              chronological Dream log
+LINT.md             latest wiki lint result
+topics/             concepts
+entities/           people, tools, organizations, products
+sources/            source summaries
+comparisons/        comparison pages
+notes/              append-only daily agent/user notes
+imports/            raw imported evidence
+```
+
+Dream incrementally consolidates top-level sessions and changed notes. Database
+watermarks prevent unchanged sources from being processed repeatedly;
+filesystem locks and atomic replacement protect cross-process wiki writes.
+
+Repository code indexes live at:
+
+```text
+/code-index//code-context.sqlite3
+```
+
+They are desired-state caches and may be rebuilt after schema/corruption
+checks. Multi-repository links are resolved dynamically over only the
+repositories authorized for the active project; no global cross-repository
+knowledge graph is persisted.
+
+### Runtime roots and retention
+
+| Root | Typical contents | Recovery expectation |
+|---|---|---|
+| data | `evoflux.db`, installed plugin registry/private data, durable artifacts | Back up; internal and denied to agents by default |
+| config | `.env`, settings, agent Markdown, Skills, MCP, sandbox, workflows | Back up; user-editable and policy-controlled |
+| state | logs, per-session JSONL diagnostics, snapshots, OTEL, Conductor queues | Operational evidence; not primary product truth |
+| cache | code indexes, model/OAuth cache, previews, LSP packages | Regeneratable |
+| wiki | profile, notes, consolidated knowledge | Back up; bounded agent access |
+| workspace | Work session files/uploads; Coding uses authorized repositories | User output; retention depends on mode/project |
+
+Development defaults live below `.evoflux/dev/`; production defaults use
+XDG-style directories under the user's home. Tests override all roots to
+`.tests/`. See the [configuration reference](../reference/configuration.md) for
+exact environment variables and precedence.
+
+Session JSONL under `/logs/sessions//.jsonl` records
+diagnostic events such as model calls, assistant messages, tools, results, and
+usage. It is observability data; the SQL transcript remains canonical.
+
+### Development knowledge used by contributors
+
+Use this precedence when deciding what the software is supposed to do:
+
+1. an accepted specification for the planned change;
+2. current-state contracts in `docs/features/`, `docs/architecture/`, and
+   `docs/reference/`;
+3. tests as executable evidence;
+4. existing code as implementation evidence;
+5. historical material in `docs/plans/`, `docs/analysis/`, `docs/research/`,
+   and `docs/releases/` as rationale, not proof of current behavior.
+
+`AGENTS.md` files define contributor process and local invariants. The feature
+catalogue maps behavior to owners. Architecture pages define storage, process,
+concurrency, and trust boundaries. Reference pages define public API/config/CLI
+contracts. Tests do not substitute for an absent product specification.
+
+If code, tests, and current docs disagree during discovery, investigate and
+state the discrepancy; do not silently choose the easiest artifact. When a
+change ships, current docs must describe the implementation and historical
+plans must not be mistaken for the active contract.
+
+## Persistence and database rules
+
+The application database is SQLModel metadata managed by Alembic. At this
+snapshot its durable domains include sessions/messages/folders, Coding
+workspaces/projects, Git server connections, team delegation, goals, scoped
+memory, Dream watermarks, scheduler tasks, workflows/gates, and WebBridge state.
+
+SQLite uses WAL and foreign keys with two deliberate lanes:
+
+- a bounded read engine/pool for read requests;
+- one FIFO writer connection for mutations and durable streams.
+
+Never hold a database transaction while scanning the filesystem, invoking Git,
+calling a model/network, starting a process, or waiting for SSE. Prepare
+external work first, keep the write transaction short, and use explicit
+idempotency/optimistic checks where retries are possible.
+
+A schema change is incomplete unless it:
+
+1. updates/imports SQLModel metadata;
+2. adds an Alembic revision;
+3. passes migration-head and supported upgrade-path tests;
+4. updates affected feature/architecture/reference documentation;
+5. defines compatibility and rollback behavior.
+
+## Coding conventions
+
+### Python
+
+- Python `>=3.12`, dependency management and commands through `uv`.
+- Use `from __future__ import annotations`, `|` unions, strict signature types,
+  absolute `app...` imports, Pydantic v2, SQLModel, and async I/O boundaries.
+- External/provider payload models normally use `ConfigDict(extra="ignore")`
+  for forward compatibility.
+- Loguru uses structured templates such as
+  `logger.info("event_name key={}", value)`; avoid interpolation that defeats
+  structured fields.
+- Routes validate/translate. Services/runtime own reusable behavior.
+- Provider adapters translate to/from canonical chat, stream, tool, and usage
+  schemas; generic API/team code should not recognize provider wire formats.
+- Tool changes must account for registry metadata, mode tier, deferred loading,
+  permission/sandbox behavior, result bounding/offload, UI rendering, and tests.
+- Preserve async cancellation, cleanup, and retry semantics. Tests should use
+  injected timing/factories rather than real sleeps or external services.
+
+### TypeScript and React
+
+- ESM only, strict TypeScript, functional components, explicit props, and
+  application imports through `@/`.
+- The existing files use single quotes and no semicolons; follow surrounding
+  formatting rather than introducing a second style.
+- TanStack Query owns server state. Zustand/Immer owns live streaming and UI
+  state. Components should not create a parallel durable cache.
+- API changes flow through domain clients, query hooks/store projection, and
+  focused rendering tests.
+- Shared shell/workbench primitives own application chrome; new screens should
+  compose them rather than hand-roll sidebars or resizable panels.
+- `localStorage` keys belong in `STORAGE_KEYS`; numeric z-index literals are
+  replaced by the `--z-*` token scale.
+- Markdown parsing is centralized in `src/utils/markdown.tsx` and enforced by
+  ESLint restricted imports.
+- Large workbench panels are lazy-loaded. Preserve the initial chat bundle and
+  use small store selectors to avoid unstable render subscriptions.
+
+### Rust and Tauri
+
+- Rust 2021 with minimum Rust 1.77 and Tauri v2.
+- Keep lifecycle/auth changes small and platform-aware. Check Windows, macOS,
+  and Linux cleanup and process behavior.
+- Native commands require matching Tauri capability grants; do not expose a
+  broad command because one frontend caller needs a narrow operation.
+- Keep production, external-dev, and bundled-dev configuration variants in
+  sync when a capability, plugin, or sidecar contract changes.
+- Do not commit `target/`, sidecar bundles, generated packages, signing keys,
+  or machine-local state.
+
+### Tests and documentation
+
+- Python tests mirror backend ownership under `tests/agent`, `api`, `services`,
+  `core`, `workflow`, `scheduler`, `plugin_platform`, `conductor`, and `cli`.
+- Frontend unit/component tests live under `web/src/__tests__`; Rust unit tests
+  are colocated and desktop/package contracts also have Python tests.
+- Test names should describe observable behavior. For non-trivial work, make
+  the acceptance-criterion mapping discoverable in the plan, test, or evidence.
+- Current behavior goes in `docs/features`, `docs/architecture`, or
+  `docs/reference`; proposed/historical work goes elsewhere and is labeled.
+- User-visible changes also update localized in-app Help when applicable.
+
+## Commit-message convention
+
+There is no separate commit-lint configuration in this snapshot, so Git
+history is the practical convention rather than an independently enforced
+contract. Use Conventional Commit-style subjects:
+
+```text
+(): 
+```
+
+Examples from current history:
+
+```text
+refactor(memory): add scoped durable learning
+fix(db): repair and enforce sqlite foreign keys
+fix(code-graph): isolate and cache snapshot builds
+perf(chat): stabilize incremental transcript rendering
+docs(coding): define semantic intelligence contracts
+test(code-graph): close combined mutation gate
+chore: bump version to 0.0.7
+```
+
+Recommended types are `feat`, `fix`, `refactor`, `perf`, `test`, `docs`,
+`chore`, and rarely `style`. Choose a stable product/component scope such as
+`agent`, `api`, `browser`, `chat`, `code-graph`, `coding`, `db`, `desktop`,
+`git`, `lsp`, `memory`, `providers`, `release`, `sandbox`, `skills`, `ui`,
+`web`, or `webbridge`.
+
+Evidence from the latest 200 subjects at this snapshot: 94 `fix`, 56 `feat`,
+9 `refactor`, 8 `perf`, 7 `docs`, 6 `test`, 5 `chore`, 1 `style`, and 14 merge
+or non-conventional subjects. In other words, scoped conventional subjects are
+the dominant style; merge commits and a few legacy/simple subjects are
+exceptions. Recent commits generally have concise subjects and no body, so add
+a body when compatibility, security, migration, or non-obvious rationale would
+otherwise be lost.
+
+Commit discipline for continued work:
+
+- one coherent change/outcome per commit;
+- imperative summary, lowercase type/scope, no trailing period;
+- keep generated artifacts, secrets, and machine paths out of commits;
+- do not mix unrelated cleanup with a feature/fix;
+- make specification, implementation, tests, and current docs reviewable as
+  one traceable change when they define the same shipped contract.
+
+## Run, test, and build commands
+
+### Install
+
+```bash
+uv sync
+cd web && bun install --frozen-lockfile
+```
+
+### Development
+
+```bash
+make run          # FastAPI only; uvicorn default :8000
+make dev-web      # FastAPI :8000 + Vite :5173
+make dev-desktop  # FastAPI + Vite + Tauri source shell
+```
+
+Use `make -C desktop dev-bundled` when validating the packaged-sidecar import,
+migration, authentication, resource, or cleanup path. It is slower and is not
+the normal edit loop.
+
+### Quality gates
+
+```bash
+uv run ruff check app/ tests/
+uv run ruff format --check app/ tests/
+uv run ty check app/
+uv run pytest --no-cov -q
+
+cd web
+bun run lint
+bun run typecheck
+bun run build
+
+cd desktop/src-tauri
+cargo check
+```
+
+Use the smallest focused suite while iterating, then expand according to the
+affected boundary. The repository currently contains a desktop packaging
+workflow, not a general all-layer CI workflow, so local quality gates are
+especially important and must be reported exactly at handoff.
+
+### Build and package
+
+```bash
+make build-web              # web/dist
+make build                  # Python wheel
+make -C desktop sidecar     # standard sidecar + Office preview engines
+make -C desktop sidecar-full  # adds Azure Document Intelligence
+make -C desktop build       # native package on the host platform
+```
+
+Tagged desktop builds require updater signing inputs. macOS signing/notarization
+and Windows Authenticode use CI secrets; Linux packages are updated through the
+package manager rather than in-place Tauri replacement. Follow the
+[release and packaging contract](release-and-packaging.md) before changing
+versioning, signing, sidecar resources, or installer behavior.
+
+## Continued-development workflow
+
+The repository requires Specification-Driven Development (SDD) and uses
+Agent-Driven Development (ADD) only where bounded parallel ownership improves
+the result. Use this sequence for every non-trivial change.
+
+### 1. Establish a clean evidence baseline
+
+- Read root and nearest nested `AGENTS.md` files.
+- Record branch, `git status --short`, and relevant user-owned changes.
+- Read the feature catalogue row, current feature contract, architecture and
+  reference pages, owning code, migrations, frontend consumers, and focused
+  tests.
+- Distinguish implemented behavior from plans/research and note any mismatch.
+
+### 2. Classify the change
+
+| Change type | Required preparation |
+|---|---|
+| User-visible feature, public API/event, persistence, security, compatibility | Full specification with stable AC IDs and verification matrix before implementation |
+| Bug against documented behavior | Cite the contract and add a failing regression test; update spec only if ambiguous/changing |
+| Internal refactor/performance | Record invariants, measurable outcome, and verification plan |
+| Trivial docs/typo/mechanical edit | Clear task scope is sufficient |
+
+When auth, permissions, migrations, concurrency, provider protocol, filesystem
+scope, or release behavior is involved, use the stronger path even if the diff
+looks small.
+
+### 3. Specify and plan
+
+- Put proposed design in `docs/plans/`; update current-state docs when behavior
+  actually ships.
+- Define goals, non-goals, user states, API/event/UI contracts, data and trust
+  behavior, failure/recovery/idempotency, compatibility, rollback, diagnostics,
+  and acceptance criteria.
+- Map each AC to implementation owner, test/evidence, and current docs.
+- Plan vertical slices that leave the application usable and can be verified
+  independently.
+- Delegate only disjoint, concrete work with explicit file ownership and ACs;
+  the lead still integrates and verifies cross-layer seams.
+
+### 4. Implement at the owning boundary
+
+- Route change: transport validation in `app/api`, durable logic in a service or
+  runtime module, response schema plus frontend client/query/store/rendering.
+- SSE change: backend envelope, frontend parser, block/store reducer, UI
+  acknowledgement, and focused tests move together.
+- Persistence change: model metadata, migration, upgrade-path tests,
+  compatibility/rollback, and docs move together.
+- Tool change: registry/tier/deferred metadata, permission/sandbox, execution,
+  result rendering, and tests move together.
+- UI change: query/store ownership, shared chrome, mobile behavior, Help, and
+  component tests move together.
+- Native change: Rust command/lifecycle, capabilities, every relevant Tauri
+  config, frontend bridge, desktop tests, and platform smoke evidence.
+
+Do not silently revise accepted behavior to fit the easiest implementation. If
+discovery invalidates the specification, stop that slice, revise the spec/plan,
+and make the deviation visible.
+
+### 5. Verify in layers
+
+1. run the smallest regression test that proves the change;
+2. run the owning directory's lint/type/test command from its `AGENTS.md`;
+3. run seam tests for every changed API/SSE/persistence/native boundary;
+4. run broader gates in proportion to risk;
+5. inspect the final diff for unrelated or generated changes;
+6. run `git diff --check`;
+7. verify docs links and Help/catalog/reference reconciliation.
+
+Do not claim completion when a required migration, contract consumer, generated
+resource, doc link, or affected-layer test remains unresolved. Separate
+pre-existing failures from failures introduced by the change with evidence.
+
+### 6. Hand off for the next contributor
+
+Report:
+
+- outcome and ACs satisfied;
+- files and public/internal contracts changed;
+- exact commands and results;
+- assumptions and material decisions;
+- remaining risks, blockers, or checks not run;
+- confirmation that unrelated work was preserved.
+
+## Common change traces
+
+| If changing... | Trace at minimum... |
+|---|---|
+| Chat/session behavior | session models and migrations → chat/team service → route/SSE → API client → team store/query caches → chat UI → backend/frontend tests → feature docs |
+| Agent provider | provider factory/catalog/capabilities → adapter schemas/streaming → generic canonical schema compatibility → provider tests → Settings/model UI if exposed |
+| Tool | registry metadata/tier → implementation → permission/sandbox → observation/offload → SSE/block rendering → tests and Help |
+| Memory | extraction/context hooks → scoped-memory service/models → deletion/provenance behavior → wiki projection/Dream → memory tests → memory architecture/feature docs |
+| Coding intelligence | workspace/project authorization → repository-local index/LSP service → API → Query/store → editor/graph/Problems UI → parser/service/frontend tests |
+| Git/review | workspace authorization and credential boundary → Git/review service → thin route → domain client/query → Git/review panel → destructive-action guard tests |
+| Scheduler/workflow | persisted model → runner/scheduler service → team turn boundary → route/tool → frontend projection → restart/idempotency tests → automation docs |
+| Desktop startup | Tauri sidecar supervisor → CLI `serve` handshake → FastAPI auth/health → frontend bootstrap → Tauri capabilities/config variants → package smoke tests |
+
+## Known hotspots and practical cautions
+
+- **Session identity is cross-layer.** Work/Coding mode, workspace, project,
+  parent/side-chat ownership, model, and permission state must agree across URL,
+  store, service, and DB. Do not infer Coding authorization from the current UI.
+- **Streaming has two truths with different lifetimes.** SSE is an in-memory
+  live projection; the DB is reconnect history. Changes must work during a live
+  turn, after refresh, and after process restart.
+- **SQLite is deliberately serialized for writes.** Long transactions or hidden
+  I/O inside them can stall the whole desktop product even when unit tests pass.
+- **Memory is scoped and untrusted.** Never convert a project decision into a
+  user-global preference or inject recalled/wiki text as policy.
+- **Code indexes are disposable and authorization-scoped.** Do not move them
+  into app tables or persist cross-repository guesses.
+- **Agent files are user-owned after initialization.** First-party base prompts
+  stay in code; seed frontmatter is additive and affects new installs only.
+- **Frontend state ownership is intentional.** Query, Zustand, URL state, and
+  local storage each have a distinct role. Duplicating state produces difficult
+  reconnect and navigation bugs.
+- **Optional integrations must degrade visibly.** MCP, plugins, Conductor,
+  Dream, browser, document engines, and LSP may be absent; keep the core API and
+  chat surface diagnosable.
+- **Desktop changes are multi-platform.** A Windows-only fix can still alter
+  shared lifecycle or capability configuration used on macOS/Linux.
+- **Plans are historical records.** A detailed plan is not evidence that a
+  feature shipped; confirm through current docs, code, and tests.
+
+## Suggested first-day walkthrough
+
+For a new contributor, this reading/debugging path gives the fastest useful
+model of the project:
+
+1. [Documentation index](../README.md), [feature catalogue](../features/README.md),
+   and [system overview](../architecture/system-overview.md).
+2. `app/api/app.py` for lifecycle and public router families.
+3. `app/services/team_manager.py` and `app/agent/agent_loop/core.py` for team and
+   turn execution.
+4. `app/models/chat.py`, `app/models/memory.py`, and
+   [data/storage architecture](../architecture/data-and-storage.md).
+5. `web/src/router.ts`, `web/src/routes/work.tsx`, and
+   `web/src/components/TeamChatView/index.tsx` for UI composition.
+6. `web/src/stores/useTeamStore/` and `web/src/api/` for history/live state.
+7. `desktop/src-tauri/src/sidecar.rs` for the production process boundary.
+8. The focused tests beside the area you intend to change.
+
+Then run one mode locally, follow a single chat turn from the network request to
+SSE rendering and persisted history, and only after that choose an extension
+point. This exposes the cross-layer contracts that are easy to miss in a
+directory-only tour.
+
+## Primary references
+
+- [System overview](../architecture/system-overview.md)
+- [Backend runtime](../architecture/backend-runtime.md)
+- [Web frontend](../architecture/web-frontend.md)
+- [Desktop shell](../architecture/desktop.md)
+- [Data and storage](../architecture/data-and-storage.md)
+- [Memory architecture](../architecture/memory-system.md)
+- [SQLite concurrency](../architecture/sqlite-concurrency.md)
+- [Application harness](../architecture/application-harness.md)
+- [Repository map](../reference/repository-map.md)
+- [Configuration](../reference/configuration.md)
+- [HTTP API](../reference/http-api.md)
+- [Development and testing](setup-and-testing.md)
+- [Release and packaging](release-and-packaging.md)
+
+## Snapshot notes
+
+This review inspected the owning instructions, current architecture/feature/
+reference documentation, runtime entry points, application models and latest
+migration, memory/wiki/index implementations, agent loop/provider/team
+boundaries, API router families, frontend router/query/store/composition paths,
+Tauri sidecar/package configuration, test layout, build scripts, and the latest
+200 Git subjects. The worktree was clean before this documentation was added.
+
+Because this is a living system, refresh the snapshot line and any numeric
+observations (version, migration count, provider count, commit distribution)
+when they materially change; the linked current-state contracts remain the
+preferred durable source.
diff --git a/docs/development/run-locally-quickstart.md b/docs/development/run-locally-quickstart.md
new file mode 100644
index 00000000..743d6f1f
--- /dev/null
+++ b/docs/development/run-locally-quickstart.md
@@ -0,0 +1,137 @@
+# Run EvoFlux locally — quick start (Windows)
+
+Status: contributor quick-reference. For full detail, see
+[local-development-windows-macos.md](local-development-windows-macos.md).
+
+This project runs as **three processes** together:
+
+```text
+FastAPI backend (port 8000)  +  Vite UI (port 5173)  +  Tauri desktop window
+```
+
+You need **3 PowerShell windows** open at the same time, one per process.
+Run everything from the repository root: `D:\evoflux\evoflux`.
+
+---
+
+## 0. One-time setup (skip if already done)
+
+Only needed the very first time, or after pulling changes that touch
+dependencies.
+
+```powershell
+uv sync --frozen
+cd web
+bun install --frozen-lockfile
+cd ..
+cd desktop\src-tauri
+cargo check
+cd ..\..
+```
+
+---
+
+## 1. Every time you start working
+
+### Terminal 1 — Backend (FastAPI)
+
+```powershell
+$env:APP_ENV = "development"
+uv run alembic -c app\alembic.ini upgrade head
+uv run uvicorn app.server:app --host 127.0.0.1 --port 8000 --reload --reload-dir app --no-access-log
+```
+
+Wait until you see `critical_startup_ready` in the log. Leave this terminal open.
+
+### Terminal 2 — Frontend (Vite)
+
+```powershell
+cd web
+$env:VITE_API_PROXY_TARGET = "http://127.0.0.1:8000"
+bun dev
+```
+
+Wait until you see `VITE ... ready`. Leave this terminal open.
+
+### Terminal 3 — Desktop window (Tauri)
+
+```powershell
+cd desktop\src-tauri
+$env:EVOFLUX_DESKTOP_DEV_BACKEND_URL = "http://127.0.0.1:8000"
+cargo tauri dev -c tauri.dev.conf.json
+```
+
+The first build compiles Rust code and can take 30–60+ seconds. When it
+finishes you'll see `Running target\debug\evoflux-desktop.exe` and a window
+titled **EvoFlux (dev)** will open.
+
+---
+
+## 2. Check it worked
+
+```powershell
+Invoke-RestMethod http://127.0.0.1:8000/api/health/live
+```
+
+Should return `status: ok`. The **EvoFlux (dev)** window should be visible and
+past its loading screen.
+
+---
+
+## 3. While you work
+
+- **Backend (Python) changes** → Terminal 1 auto-reloads (`--reload`). No restart needed.
+- **Frontend (React/TypeScript) changes** → Terminal 2 hot-reloads in the open window. No restart needed.
+- **Desktop shell (Rust) changes** → Terminal 3 detects the change and rebuilds/relaunches automatically. Just wait for it to finish.
+
+### If you changed dependencies (not just code)
+
+| You changed... | Run this before restarting |
+|---|---|
+| `pyproject.toml` / `uv.lock` | `uv sync --frozen` |
+| `web/package.json` / `web/bun.lock` | `cd web && bun install --frozen-lockfile && cd ..` |
+| `desktop/src-tauri/Cargo.toml` | `cd desktop\src-tauri && cargo check && cd ..\..` |
+
+### If you changed database models
+
+```powershell
+$env:APP_ENV = "development"
+uv run alembic -c app\alembic.ini upgrade head
+```
+
+---
+
+## 4. Restarting after a fix (or after closing everything)
+
+Stop each terminal with `Ctrl+C`, in this order: Terminal 3, then Terminal 2,
+then Terminal 1. Then just repeat **section 1** above (Terminal 1 → 2 → 3) —
+Terminal 1's `alembic upgrade head` is safe to re-run every time, it does
+nothing if the database is already current.
+
+If a terminal was closed by accident (not with `Ctrl+C`), check nothing is
+still holding the ports before restarting:
+
+```powershell
+Get-NetTCPConnection -LocalPort 8000,5173 -State Listen -ErrorAction SilentlyContinue
+```
+
+If something is listed, stop that leftover process (or just close its
+terminal window) before starting a fresh one on the same port.
+
+---
+
+## 5. Common problems
+
+| Symptom | Fix |
+|---|---|
+| Vite complains a package "could not be resolved" | `cd web && bun install --frozen-lockfile && cd ..`, then restart Terminal 2 |
+| `alembic current` is behind `alembic heads` | `uv run alembic -c app\alembic.ini upgrade head` |
+| Port 8000 or 5173 already in use | Find and close the old terminal/process, don't force-kill blindly |
+| Tauri window never opens | Check Terminal 3 for a Rust compile error; fix the error, save, it rebuilds automatically |
+| UI loads but can't reach backend | Confirm Terminal 1 shows `critical_startup_ready` and `http://127.0.0.1:8000/api/health/live` returns `ok` |
+
+---
+
+## 6. Stopping everything
+
+`Ctrl+C` in Terminal 3, then Terminal 2, then Terminal 1, in that order.
diff --git a/documents/architecture/system-overview.md b/documents/architecture/system-overview.md
index 6bc81910..e611e98b 100644
--- a/documents/architecture/system-overview.md
+++ b/documents/architecture/system-overview.md
@@ -96,6 +96,14 @@ transcript and then resume live streaming.
 - **Integration:** global MCP, plugin MCP, provider adapters, WebBridge, and
   Conductor have separate configuration and lifecycle boundaries.
 
+## Remote adapter trust boundary
+
+The remote adapter is an outbound-only polling bridge — it connects to the
+Telegram API but never listens for inbound connections. Tokens live in the OS
+credential vault (keyring), never in the database or environment variables. The
+adapter uses a stream observer pattern to project outbound events (current task,
+gates, completion) into Telegram chats while applying full redaction.
+
 ## Source-of-truth map
 
 | Contract | Owner |
diff --git a/documents/features/README.md b/documents/features/README.md
index 7f7bb22f..e14040dc 100644
--- a/documents/features/README.md
+++ b/documents/features/README.md
@@ -45,6 +45,7 @@ Status meanings:
 | Sandbox and permissions | Implemented | Permission modes and Settings | permission engine, sandbox and outbound redaction | [Security and permissions](security-and-permissions.md) |
 | Telemetry and diagnostics | Implemented | `/telemetry`, cache read/write, Diagnostics, health and metrics | OTEL, DuckDB aggregation, Prometheus, diagnostics routes | [Observability](observability-and-diagnostics.md) |
 | Conductor managed resources | Optional | Connection/enterprise settings | `app/conductor/` and settings routes | [Security and permissions](security-and-permissions.md) |
+| Remote access | Optional | Settings → Remote access, Telegram chat | `app/remote/`, telegram adapter, pairing, outbound projection | [Remote access](remote-access.md) |
 | Desktop packaging and updates | Implemented | Native app, updater and installers | `desktop/`, packaging scripts and CI | [Release and packaging](../development/release-and-packaging.md) |
 
 ## Explicit non-claims
diff --git a/documents/features/remote-access.md b/documents/features/remote-access.md
new file mode 100644
index 00000000..59cf2a65
--- /dev/null
+++ b/documents/features/remote-access.md
@@ -0,0 +1,228 @@
+# Remote access
+
+Status: **Optional** — requires a user-owned Telegram bot and network access
+from the EvoFlux host.
+
+## Problem and outcome
+
+When the user walks away from the desktop, EvoFlux becomes unreachable. Active
+sessions may pause on a gate (permission, question, plan) and idle until the
+user returns. Remote access lets the user receive, read, and resolve those gates
+from a phone through a personal Telegram bot — one tap to approve, one message
+to continue.
+
+## Goals
+
+1. **One-tap pairing** — scan a QR or open a deep link; no manual token entry
+   on the phone.
+2. **Current-task text** — the bot shows what the active session is doing so the
+   user can decide without opening the desktop.
+3. **Automatic gates and completion** — permission requests, questions, and plan
+   review arrive as inline-button messages; completion summaries arrive as text.
+4. **Safe redaction** — every outbound message passes through
+   `protect_outbound_text(channel="remote")` so secrets and PII never leave the
+   machine.
+
+## Non-goals
+
+- No shared or multi-tenant bot — each installation owns one bot.
+- No inbound listener — the adapter polls outbound; Telegram cannot push into
+  EvoFlux.
+- No public URL — the sidecar stays loopback; no webhook endpoint is exposed.
+
+## User flows and states
+
+### Setup
+
+1. User creates a Telegram bot via BotFather and copies the bot token.
+2. In Settings → Remote access the user pastes the token and clicks Connect.
+3. EvoFlux stores the token in the OS credential vault, verifies it with the
+   Telegram API, and creates a `remote_connections` row.
+4. The UI shows a pairing link (or QR). The user opens it on the phone.
+5. The user taps Start in the bot chat. EvoFlux records the `chat_id` in
+   `remote_pairings` and the state becomes `paired`.
+
+### Daily use
+
+1. User sends a message to the bot on Telegram.
+2. The remote adapter polls `getUpdates`, matches the `chat_id` to a pairing,
+   and forwards the text into the active session as a user message.
+3. The agent responds; the adapter projects the response text into the Telegram
+   chat.
+
+### Gate flow
+
+1. The session hits a permission, question, or plan gate.
+2. The stream observer emits a gate event; the adapter sends a Telegram message
+   with inline buttons (e.g. Allow once / Reject, Accept / Revise / Reject).
+3. The user taps a button. The adapter resolves the gate and continues.
+
+### Unpair
+
+- Desktop: Settings → Remote access → Remove.
+- Phone: send `/unpair` to the bot.
+
+## Requirements and acceptance criteria
+
+Requirements and acceptance criteria are defined in the implementation plan as
+AC-1 through AC-36. They cover:
+
+- Connection lifecycle (create, verify, update label, replace token, delete)
+- Pairing lifecycle (link, QR, resolve, revoke)
+- Outbound projection (current task, gate events, completion summaries)
+- Inbound forwarding (text messages to active session)
+- Remote permission replies (limited to `once` and `reject`)
+- Redaction of outbound text (secrets and PII)
+- SQLite concurrency (per-pairing locks, source_key idempotency)
+- Connection states (11 values covering setup through error)
+- One connection per installation (v1)
+- Migration `00000064`
+
+## API, event, tool, and UI contracts
+
+### Settings endpoints
+
+| Method | Path | Purpose |
+|---|---|---|
+| `GET` | `/api/settings/remote` | Read remote settings |
+| `PUT` | `/api/settings/remote` | Update remote settings |
+
+### Connection endpoints
+
+| Method | Path | Purpose |
+|---|---|---|
+| `GET` | `/api/remote/connections` | List connections (0 or 1) |
+| `POST` | `/api/remote/connections` | Create connection (write-only token) |
+| `PATCH` | `/api/remote/connections/{id}` | Update label or enabled flag |
+| `PUT` | `/api/remote/connections/{id}/token` | Replace bot token |
+| `DELETE` | `/api/remote/connections/{id}` | Remove connection |
+
+### Pairing endpoints
+
+| Method | Path | Purpose |
+|---|---|---|
+| `POST` | `/api/remote/connections/{id}/pairing-links` | Issue pairing link |
+| `GET` | `/api/remote/connections/{id}/pairing` | Read pairing state |
+| `DELETE` | `/api/remote/connections/{id}/pairing` | Revoke pairing |
+
+### Settings shape
+
+```yaml
+outbound_data_policy: block | redact | off   # default: redact
+outbound_pii_policy: off | standard | strict  # default: standard
+```
+
+### Connection shape
+
+```
+id, label, enabled, bot_username, state, created_at, updated_at
+```
+
+Token is write-only; read responses never return it.
+
+### Pairing shape
+
+```
+id, connection_id, chat_id, principal_id, state, paired_at
+```
+
+## Data model
+
+### `remote_connections`
+
+| Column | Type | Notes |
+|---|---|---|
+| `id` | UUID | primary key |
+| `label` | text | user-facing name |
+| `enabled` | boolean | default true |
+| `bot_username` | text | resolved from Telegram API |
+| `bot_token_vault_key` | text | OS vault reference, never stored in DB |
+| `state` | enum(11) | `disconnected` → `connecting` → `connected` → `paired` … `error` |
+| `created_at` | timestamp | |
+| `updated_at` | timestamp | |
+
+### `remote_pairings`
+
+| Column | Type | Notes |
+|---|---|---|
+| `id` | UUID | primary key |
+| `connection_id` | UUID | FK → `remote_connections` |
+| `chat_id` | bigint | Telegram chat ID |
+| `principal_id` | text | authorizes the pairing |
+| `destination_id` | text | addresses the pairing |
+| `state` | enum | `pending` → `paired` → `revoked` |
+| `source_key` | text | idempotency key for `getUpdates` offset |
+| `paired_at` | timestamp | |
+
+### OS vault
+
+Bot tokens are stored in the OS credential vault (keyring) only. The DB stores
+a vault key reference, never the raw token.
+
+## Permissions, security, privacy, and trust
+
+- **Token storage**: bot token lives in OS credential vault (keyring) only; never
+  in the database, environment variables, or config files.
+- **Remote permission replies**: limited to `once` and `reject`. There is no
+  `always` option for remote — every remote approval is single-use.
+- **Outbound redaction**: all outbound text passes through
+  `protect_outbound_text(channel="remote")` before reaching Telegram.
+- **No parse mode**: Telegram messages are sent without parse mode so model
+  output is never interpreted as markup.
+- **Private chats only**: the adapter only processes private (non-group) chats.
+- **Authorization model**: `principal_id` authorizes who can reply;
+  `destination_id` addresses which pairing receives the message.
+- **One connection per installation** (v1): only a single remote connection is
+  allowed at a time.
+
+## Concurrency, failure, recovery, and idempotency
+
+- **SQLite deadlock fix**: the adapter avoids holding write locks during I/O
+  (Telegram API calls happen outside the transaction).
+- **Per-pairing locks**: each pairing has its own lock to prevent concurrent
+  `getUpdates` processing from corrupting state.
+- **Source key idempotency**: the `source_key` column on `remote_pairings`
+  tracks the last processed Telegram update offset so restarts do not re-deliver
+  messages.
+- **Adapter crash recovery**: on startup the adapter resumes polling from the
+  last persisted offset; no messages are lost if the process restarts.
+
+## Observability
+
+### Connection states
+
+The `state` column covers 11 values:
+
+`disconnected`, `connecting`, `connected`, `verifying`, `ready`, `paired`,
+`polling`, `paused`, `error_token`, `error_network`, `error_api`
+
+### Adapter status
+
+Adapter health is reported through the standard `/api/health` and Diagnostics
+routes. The remote section shows connection state, last poll time, and error
+count.
+
+## Compatibility, rollout, and rollback
+
+- **One connection per installation** (v1): the API rejects a second connection
+  creation with `409`.
+- **Migration**: Alembic migration `00000064` adds `remote_connections` and
+  `remote_pairings` tables.
+- **Rollback**: removing the connection through the API or reverting the
+  migration cleanly drops the tables.
+
+## Ownership and source map
+
+| Layer | Files |
+|---|---|
+| Adapter and polling | `app/remote/adapter.py`, `app/remote/poller.py` |
+| Telegram client | `app/remote/telegram_client.py` |
+| Connection and pairing services | `app/remote/connection_service.py`, `app/remote/pairing_service.py` |
+| Outbound projection | `app/remote/projection.py` |
+| Redaction | `app/remote/redaction.py` (wraps `protect_outbound_text`) |
+| API routes | `app/api/routes/remote.py`, `app/api/routes/settings_remote.py` |
+| Data models | `app/models/remote_connection.py`, `app/models/remote_pairing.py` |
+| Migration | `app/migrations/versions/00000064_*.py` |
+| Tests | `tests/remote/` |
+| Frontend API client | `web/src/api/client/remote.ts` |
+| Frontend settings page | `web/src/routes/settings.remote-access.tsx` |
diff --git a/documents/features/security-and-permissions.md b/documents/features/security-and-permissions.md
index 7ea50932..2c5fa37a 100644
--- a/documents/features/security-and-permissions.md
+++ b/documents/features/security-and-permissions.md
@@ -75,6 +75,25 @@ deliver policy-scoped telemetry. `report` mode surfaces drift without blocking;
 `enforce` applies governed resource policy. Credentials live outside normal
 settings payloads, and managed provenance is displayed in Settings.
 
+## Remote access
+
+Remote access adds an outbound-only Telegram bridge with these constraints:
+
+- Bot tokens are stored in the OS credential vault (keyring) only; the database
+  stores a vault key reference, never the raw token.
+- Remote permission replies are limited to `once` and `reject`. There is no
+  `always` option — every remote approval is single-use.
+- All outbound text passes through `protect_outbound_text(channel="remote")`
+  redaction before reaching Telegram.
+- Telegram messages are sent without parse mode so model output is never
+  interpreted as markup.
+- The adapter processes private chats only. `principal_id` authorizes who can
+  reply; `destination_id` addresses which pairing receives the message.
+- One remote connection per installation is allowed (v1).
+
+Primary code: `app/remote/`, `app/api/routes/remote.py`,
+`app/api/routes/settings_remote.py`.
+
 ## Source and tests
 
 Primary code: `app/agent/permission.py`, `sandbox.py`, `sandbox_config.py`,
diff --git a/documents/plans/remote-access-task-6-brief.md b/documents/plans/remote-access-task-6-brief.md
new file mode 100644
index 00000000..6c7e38cd
--- /dev/null
+++ b/documents/plans/remote-access-task-6-brief.md
@@ -0,0 +1,325 @@
+# Task 6 brief: natural-language ingress and current-task behavior
+
+Status: ready after Tasks 1-4; may be implemented while Task 5 is in progress
+
+Parent specification: [Remote access through Telegram](remote-channel-telegram.md)
+
+Implementation plan: [Remote access through Telegram implementation](remote-access-telegram-implementation.md#task-6-natural-language-ingress-and-current-task-behavior)
+
+## Objective
+
+Implement the provider-neutral service that turns an authorized remote text or
+task action into EvoFlux session behavior. A paired user can send ordinary text
+from their phone, continue one current desktop task, clear that selection for a
+new Work task, or stop only the current live turn.
+
+This task covers `AC-14`, `AC-15`, `AC-16`, `AC-17`, `AC-18`, and `AC-29`.
+
+## Observable result
+
+- The first authorized plain-text update creates one top-level Work session,
+  marks it with remote provenance tags, stores it as the pairing's current
+  session, and submits the text through the shared interactive ingress.
+- Later text for the pairing uses that current session and reports the real
+  `accepted`, `pending`, or `queued` result.
+- Redelivery of the same Telegram update has at most one persisted user-message
+  effect, including the recovery path after persistence but before the adapter
+  advances its update offset.
+- **New task** clears only the pairing's current-session pointer. It does not
+  delete, hide, archive, interrupt, or otherwise mutate the previous session.
+- **Continue this task** changes only that pointer and accepts only a
+  user-visible, top-level Work or Coding session.
+- `/stop` interrupts only a live turn in the pairing's current session. It
+  reports a distinct no-active-turn outcome when there is nothing to stop.
+
+## Ownership and coordination
+
+The Task 6 implementer owns:
+
+- Create `app/remote/inbound.py`.
+- Modify `app/services/interactive_message_service.py`.
+- Modify `app/services/chat_service.py` only to make channel-source delivery
+  state recognize `interactive_source` while retaining legacy
+  `webbridge_source` behavior.
+- Create `tests/remote/test_inbound.py`.
+- Modify or create focused service tests under
+  `tests/services/test_interactive_message_service.py` and
+  `tests/services/test_chat_service.py` as needed for source compatibility.
+
+Claude's Task 5 owns these files; Task 6 must not edit them:
+
+- `app/api/schemas/remote.py`
+- `app/api/routes/remote.py`
+- `app/remote/runtime.py`
+- `app/api/app.py`
+- `tests/api/routes/test_remote.py`
+- `tests/remote/test_runtime.py`
+
+Do not stage, commit, reset, restore, or rewrite unrelated work. Re-read
+`git status --short` before editing because the worktree is shared and dirty.
+
+## Available prerequisite contracts
+
+Use the existing contracts directly:
+
+- `RemoteInboundAction` and `RemotePrincipal` from `app.remote.contracts`.
+  The Telegram adapter already supplies a source key in the form
+  `telegram::`, which contains all three identity
+  parts required by `AC-16`. Preserve this key instead of deriving it from
+  message text or provider display values.
+- `PairingService.authorize(db, connection_id=..., principal_id=...)` from
+  `app.remote.pairing`. It reads the pairing fresh and returns `None` for every
+  unauthorized or rate-limited request.
+- `RemotePairing.active_session_id`. Its foreign key uses `ON DELETE SET NULL`,
+  so deleted-current-session recovery should use the resulting null pointer.
+- `create_chat_session`, `resolve_team_for_session`, and
+  `submit_persisted_interactive_message` from the existing service layer.
+- `agent_service.interrupt_team(team, session_id)` for a live current team.
+  Do not use `team_manager.stop_sessions`: it evicts sessions and is broader
+  than the user-level interrupt required by `AC-29`.
+
+Task 6 has no code dependency on Task 5's routes or lazy runtime. Do not import
+from `app.api` or `app.remote.runtime`.
+
+## Service contract
+
+Add `RemoteInboundService` in `app/remote/inbound.py` with four asynchronous,
+provider-neutral operations:
+
+```python
+async def handle_text(
+    db: AsyncSession,
+    action: RemoteInboundAction,
+) -> RemoteInboundResult: ...
+
+async def new_task(
+    db: AsyncSession,
+    action: RemoteInboundAction,
+) -> RemoteInboundResult: ...
+
+async def continue_task(
+    db: AsyncSession,
+    action: RemoteInboundAction,
+    session_id: UUID,
+) -> RemoteInboundResult: ...
+
+async def stop_current(
+    db: AsyncSession,
+    action: RemoteInboundAction,
+) -> RemoteInboundResult: ...
+```
+
+The methods may share one private authorization helper. Each public operation
+must authorize the action's `connection_id` and `principal.principal_id` before
+reading or changing the pointer or resolving a team.
+
+Define a small immutable result type in the same module. It must carry a bounded
+outcome code plus optional `session_id` and `message_id`, without Telegram text
+or payload types. Required outcomes are:
+
+- `accepted`, `pending`, and `queued` for text admission;
+- `current_task_cleared` and `current_task_selected`;
+- `interrupted` and `no_active_turn`;
+- `unauthorized` and `session_not_addressable`.
+
+The later adapter-integration task owns user-facing Telegram wording.
+
+## Session eligibility rule
+
+Use one private predicate for every remote selection and current-session
+revalidation. A session is addressable only when all conditions hold:
+
+```python
+session.parent_session_id is None
+session.session_type == "main"
+session.mode in {"work", "coding"}
+```
+
+This excludes team-member, Side Chat, and any future internal session types by
+default. Do not infer eligibility from the title, agent name, tags, or whether
+the session currently has a live in-memory team.
+
+If an existing current pointer references a row that is missing or no longer
+addressable, clear the pointer and treat the next text as a first message.
+
+## First-message and current-message flow
+
+Serialize pointer decisions for one pairing with a connection/pairing-keyed
+`asyncio.Lock`. Without this, two simultaneous first messages can both observe
+a null pointer and create two current sessions. Keep the lock scoped to this
+single-process service and clean unused keyed locks when practical.
+
+For an authorized `handle_text` call:
+
+1. Reject empty text after the adapter's normalization; never create a session
+   for it.
+2. Load and revalidate `active_session_id` under the per-pairing lock.
+3. If no valid current session exists, call `create_chat_session`, then set:
+   - `mode = "work"`;
+   - `parent_session_id = None`;
+   - `session_type = "main"`;
+   - `tags = ["remote_origin", f"remote_connection:{connection_id}"]`;
+   - `pairing.active_session_id = session.id`.
+4. Commit the created session and pointer together before team resolution or
+   message dispatch. Do not hold a database transaction across filesystem,
+   model, team-start, or agent work.
+5. Resolve the persisted session/team with
+   `resolve_team_for_session(..., require_existing=True)`.
+6. Submit with `submit_persisted_interactive_message`, passing the original
+   plain text, `source_key=action.source_key`, the request hash, and the source
+   metadata described below.
+7. Map the existing `InteractiveMessageResult` without changing its
+   `accepted`/`pending`/`queued` meaning.
+
+Use the normal Work session defaults for model, permission mode, workspace, and
+follow-up delivery. Remote ingress must not grant broader permissions or select
+a special model.
+
+## Channel-neutral source metadata
+
+Store new remote source information under `interactive_source`:
+
+```python
+{
+    "interactive_source": {
+        "channel": "remote",
+        "adapter": "telegram",
+        "connection_id": str(action.connection_id),
+        "key": action.source_key,
+        "request_hash": request_hash,
+        "state": "persisted",
+    }
+}
+```
+
+Calculate `request_hash` deterministically from the admitted semantic request;
+for text, SHA-256 of the normalized UTF-8 text is sufficient. Never include a
+bot token, pairing token, callback token, display name, or destination ID.
+
+Generalize source handling through one helper that selects
+`interactive_source` first and falls back to legacy `webbridge_source`.
+Apply it consistently to:
+
+- lookup by source key;
+- request-hash conflict checking;
+- delivered-state replay detection;
+- `mark_channel_source_delivered` for immediate delivery, post-turn queued
+  activation, and in-turn queued injection.
+
+Do not rename or rewrite existing `webbridge_source` rows. Existing WebBridge
+callers may continue writing that key, and all current WebBridge retry tests
+must remain green.
+
+## New, continue, and stop behavior
+
+`new_task` authorizes, locks the pairing, sets `active_session_id = None`, and
+commits. It does not resolve or stop a team and does not create a replacement
+session until the next text arrives.
+
+`continue_task` authorizes, loads the requested `ChatSession`, applies the exact
+eligibility predicate, then changes and commits only `active_session_id`. It
+does not resend history, start a team, or mutate the selected session.
+
+`stop_current` authorizes and revalidates the current session. Resolve the team
+using existing session behavior, then call `agent_service.interrupt_team` only
+when that team has an active user turn. Return `no_active_turn` when there is no
+current addressable session or no active turn. Do not clear the pointer, stop
+the sidecar, delete a session, call `stop_sessions`, or report `interrupted`
+when no work was canceled.
+
+## Required tests
+
+Write tests before implementation and record the failing test command.
+
+### Source compatibility
+
+- `interactive_source` rows are found by source key.
+- Legacy `webbridge_source` rows are still found.
+- An `interactive_source` request-hash mismatch raises
+  `InteractiveMessageConflict`.
+- Replaying a delivered `interactive_source` row returns `accepted` without a
+  second dispatch.
+- Both source formats transition to `delivered` through
+  `mark_channel_source_delivered`.
+- Existing WebBridge source tests remain unchanged and pass.
+
+### Text ingress
+
+- Unauthorized principal produces no session, pointer, message, or team work.
+- First text creates exactly one top-level Work session with exactly the two
+  required provenance tags and sets the pointer.
+- Later text reuses the pointed session.
+- `accepted`, `pending`, and `queued` pass through accurately.
+- Two concurrent first texts create one current session rather than two.
+- Duplicate source-key delivery persists one user message and does not dispatch
+  twice.
+- Recovery after a message was persisted but before update acknowledgement
+  returns the prior result without another user-message effect.
+- A null pointer left by session deletion causes the next text to create a new
+  Work session.
+
+### Pointer actions and boundary
+
+- **New task** clears the pointer and leaves the previous session unchanged.
+- **Continue this task** accepts a top-level Work session and a top-level Coding
+  session.
+- It rejects a child/team-member session, Side Chat, unsupported/internal
+  session type, and unsupported mode without changing the existing pointer.
+- A missing requested session returns `session_not_addressable`.
+- Authorization is checked again on every action.
+
+### Stop
+
+- A live current turn calls `interrupt_team` for that session only and returns
+  `interrupted`.
+- No current session, a deleted/non-addressable session, or an idle team returns
+  `no_active_turn` and never claims interruption.
+- The pointer and session remain after interruption.
+- No unrelated session or team is stopped.
+
+Use fakes/mocks for team resolution and dispatch where a real team would start
+model or filesystem work. Database behavior, pointer persistence, foreign-key
+cleanup, and message idempotency should use the repository's real async SQLite
+test fixture.
+
+## Execution order
+
+1. Read the current shared files and status; incorporate non-conflicting changes
+   made since this brief was written.
+2. Add failing compatibility tests for `interactive_source` plus legacy source
+   behavior.
+3. Add failing inbound service tests for all flows and boundaries above.
+4. Implement the smallest channel-neutral source helper and inbound service.
+5. Run focused tests and lint.
+6. Inspect the complete diff for overlap and accidental changes.
+
+## Verification evidence
+
+Run at minimum:
+
+```powershell
+uv run pytest --no-cov -q tests/services/test_interactive_message_service.py tests/services/test_chat_service.py tests/remote/test_inbound.py
+uv run pytest --no-cov -q tests/api/test_webbridge.py -k "source or idempot or queued"
+uv run ruff check app/remote/inbound.py app/services/interactive_message_service.py app/services/chat_service.py tests/remote/test_inbound.py tests/services/test_interactive_message_service.py tests/services/test_chat_service.py
+uv run ruff format --check app/remote/inbound.py app/services/interactive_message_service.py app/services/chat_service.py tests/remote/test_inbound.py tests/services/test_interactive_message_service.py tests/services/test_chat_service.py
+uv run ty check app/
+git diff --check
+```
+
+If a listed test file does not yet exist, create the focused file or place the
+cases in the nearest existing service test and report the actual path. Do not
+broaden to the full suite until focused behavior is green.
+
+## Handoff requirements
+
+Return all of the following to the lead:
+
+1. Outcome and evidence mapped to `AC-14`, `AC-15`, `AC-16`, `AC-17`, `AC-18`,
+   and `AC-29`.
+2. Files changed and any public/internal contracts introduced.
+3. Exact red and green commands with their results.
+4. Assumptions or deviations from this brief and why they were necessary.
+5. Remaining risks, blockers, or follow-up work for adapter integration.
+6. Confirmation that Task 5 and unrelated dirty-worktree files were preserved.
+
+Do not commit.
diff --git a/documents/plans/remote-access-telegram-implementation.md b/documents/plans/remote-access-telegram-implementation.md
index f90e5ad8..1e002da3 100644
--- a/documents/plans/remote-access-telegram-implementation.md
+++ b/documents/plans/remote-access-telegram-implementation.md
@@ -371,6 +371,8 @@ uv run ruff check app/remote/pairing.py tests/remote/test_pairing.py
 
 **ACs:** AC-1, AC-2, AC-3, AC-5, AC-7, AC-10, AC-12, AC-13, AC-33, AC-34
 
+**Progress:** Complete.
+
 **Files:**
 
 - Create: `app/api/schemas/remote.py`
@@ -386,11 +388,11 @@ uv run ruff check app/remote/pairing.py tests/remote/test_pairing.py
 - Produces singleton `remote_runtime.start/stop/reconcile_connection/status`.
 - Consumes connection, pairing, vault, and adapter services from Tasks 1–4.
 
-- [ ] **Step 1: Write route/auth/secret-shape tests**
+- [x] **Step 1: Write route/auth/secret-shape tests**
 
 Cover zero-or-one list, create, patch enable/label, token replacement, remove, pairing-link issue, pairing read/revoke, status, second-connection `409`, invalid UUID, missing resource, desktop auth, and OpenAPI absence of returned token fields.
 
-- [ ] **Step 2: Write disabled-lifespan and shutdown tests**
+- [x] **Step 2: Write disabled-lifespan and shutdown tests**
 
 ```python
 async def test_disabled_start_does_not_import_telegram(monkeypatch):
@@ -401,11 +403,11 @@ async def test_disabled_start_does_not_import_telegram(monkeypatch):
 
 Prove optional startup failure does not fail health readiness and shutdown stops the remote runtime after pending optional startup completes.
 
-- [ ] **Step 3: Implement thin routes and lazy runtime construction**
+- [x] **Step 3: Implement thin routes and lazy runtime construction**
 
 Routes validate HTTP shape and call services; they do not call Telegram directly. Import `app.remote.telegram.adapter` inside the enabled connection factory only. Add remote startup beside other optional services and explicit shutdown beside Conductor/Scheduler cleanup.
 
-- [ ] **Step 4: Run route and lifecycle evidence**
+- [x] **Step 4: Run route and lifecycle evidence**
 
 ```powershell
 $env:EVOFLUX_DESKTOP_TOKEN=$null
@@ -419,55 +421,59 @@ uv run ruff check app/api/routes/remote.py app/api/schemas/remote.py app/remote/
 
 **ACs:** AC-14, AC-15, AC-16, AC-17, AC-18, AC-29
 
+**Progress:** Complete.
+
 **Files:**
 
 - Create: `app/remote/inbound.py`
 - Modify: `app/services/interactive_message_service.py`
+- Modify: `app/services/chat_service.py` (channel-source delivery compatibility only)
 - Create: `tests/remote/test_inbound.py`
 - Modify: `tests/services/test_interactive_message_service.py`
+- Modify or create: `tests/services/test_chat_service.py`
 
 **Interfaces:**
 
 - Produces `RemoteInboundService.handle_text/new_task/continue_task/stop_current`.
 - Consumes `PairingService.authorize`, `create_chat_session`, `resolve_team_for_session`, `submit_persisted_interactive_message`, and existing interrupt behavior.
-- Generalizes persisted source metadata from `webbridge_source` to channel-neutral `interactive_source` while reading legacy metadata for compatibility.
+- Generalizes persisted source metadata from `webbridge_source` to channel-neutral `interactive_source` while reading legacy metadata for compatibility, including the shared delivered-state helper used by immediate and queued delivery.
 
-- [ ] **Step 1: Write channel-neutral idempotency compatibility tests**
+- [x] **Step 1: Write channel-neutral idempotency compatibility tests**
 
 Persist one `interactive_source` message and prove lookup/dedup; retain a regression that legacy `webbridge_source` rows still deduplicate WebBridge retries.
 
-- [ ] **Step 2: Write inbound behavior tests**
+- [x] **Step 2: Write inbound behavior tests**
 
 Cover first plain text creating a top-level Work session with provenance tags; subsequent text using the current session; queued/pending/accepted status; duplicate update effect-once; deleted current session recovery; **New task** clearing without deletion; **Continue this task** selecting only top-level Work/Coding; refusal of team-member, Side Chat, and internal sessions; `/stop` interrupting only the current live turn.
 
-- [ ] **Step 3: Run failures**
+- [x] **Step 3: Run failures**
 
 ```powershell
-uv run pytest --no-cov -q tests/services/test_interactive_message_service.py tests/remote/test_inbound.py
+uv run pytest --no-cov -q tests/services/test_interactive_message_service.py tests/services/test_chat_service.py tests/remote/test_inbound.py
 ```
 
-- [ ] **Step 4: Implement the channel-neutral source record**
+- [x] **Step 4: Implement the channel-neutral source record**
 
 ```python
 message_extra = {
     "interactive_source": {
         "channel": "remote",
         "adapter": "telegram",
-        "connection_id": str(connection.id),
-        "key": f"remote:telegram:{connection.id}:{update_id}",
+        "connection_id": str(action.connection_id),
+        "key": action.source_key,
         "request_hash": request_hash,
-        "state": "pending",
+        "state": "persisted",
     }
 }
 ```
 
 Do not make HTTP self-calls. Reuse existing team/session defaults and message locking.
 
-- [ ] **Step 5: Run ingress evidence**
+- [x] **Step 5: Run ingress evidence**
 
 ```powershell
-uv run pytest --no-cov -q tests/services/test_interactive_message_service.py tests/remote/test_inbound.py
-uv run ruff check app/remote/inbound.py app/services/interactive_message_service.py tests/remote/test_inbound.py
+uv run pytest --no-cov -q tests/services/test_interactive_message_service.py tests/services/test_chat_service.py tests/remote/test_inbound.py
+uv run ruff check app/remote/inbound.py app/services/interactive_message_service.py app/services/chat_service.py tests/remote/test_inbound.py
 ```
 
 ---
diff --git a/documents/plans/remote-telegram-response-ui-implementation.md b/documents/plans/remote-telegram-response-ui-implementation.md
new file mode 100644
index 00000000..26bbaa8a
--- /dev/null
+++ b/documents/plans/remote-telegram-response-ui-implementation.md
@@ -0,0 +1,1973 @@
+# Remote Telegram Response UI Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Give the Telegram remote-access channel HTML-formatted, alive-feeling responses; complete its existing "notify me about desktop-started work too" Goal; and add a read-mostly `/settings` view plus a guided project/prompt picker — all within Tasks 7-9 of the in-progress Telegram feature, which this plan extends rather than reopens.
+
+**Architecture:** One new rendering module (`app/remote/formatting.py`) becomes the single place literal HTML is written; `RemoteProjection` (outbound.py) gains a per-turn status-message lifecycle (create-then-edit, using the adapter's existing correlation-id mechanism) plus a cached "active pairing" view so it can route completions for sessions it never explicitly registered; `RemoteActionService` (actions.py) gains new capability-token action kinds for `/settings`, the guided picker, and on-demand drill-down content.
+
+**Tech Stack:** Python 3.12, FastAPI, SQLModel/Alembic, asyncio, httpx, pytest.
+
+**Spec:** [`remote-telegram-response-ui.md`](remote-telegram-response-ui.md) (amends [`remote-channel-telegram.md`](remote-channel-telegram.md))
+
+## Global Constraints
+
+- Every outbound message uses Telegram HTML parse mode; every value not authored as a static string inside `formatting.py` passes through `html.escape` before interpolation, applied after outbound redaction, never before.
+- A phone-admitted turn's status message is created once and edited at most once more (to its final done/error form); no other edit, no periodic progress text. The native Telegram typing indicator, not message edits, carries the "still working" feeling.
+- Running-state/status text contains only the task title and admission status; never a tool name, file path, or content fragment (preserves AC-20's event allowlist).
+- `/settings` may change outbound redaction policy and `notify_scope` only. Model and permission mode render as plain text with no button, ever.
+- Drill-down content ("Full diff", "Tool log") is the current turn's own already-persisted output only, fetched on demand and never cached beyond the existing 10-minute capability-token TTL — no new durable store.
+- `RemoteProjection.observe` stays synchronous, bounded, and non-blocking; any database read needed for a newly-widened case happens in the async delivery path, never inside `observe()` itself.
+- Every task cites its spec ACs, writes a failing test before implementation, and leaves the test suite green at its checkpoint.
+- Commit at the end of each task.
+
+---
+
+## File and interface map
+
+New units:
+
+- `app/remote/formatting.py` — HTML escaping helper and one builder per card type.
+- `app/remote/turn_activity.py` — queries a turn's persisted tool-call messages; shared by the done-card summary and the drill-down buttons.
+- `app/migrations/versions/00000065_add_remote_pairing_notify_scope.py` — adds `remote_pairings.notify_scope`.
+- `tests/remote/test_formatting.py`, `tests/remote/test_turn_activity.py` — focused new-module evidence.
+
+Changed units:
+
+- `app/remote/contracts.py` — `RemoteAdapter` Protocol gains `indicate_typing`.
+- `app/remote/telegram/client.py` — `send_text`/`edit_text` gain `parse_mode`; new `send_chat_action`.
+- `app/remote/telegram/adapter.py` — passes `parse_mode="HTML"`; implements `indicate_typing`.
+- `app/models/remote.py` — `RemotePairing.notify_scope`.
+- `app/remote/outbound.py` — status-message lifecycle, active-pairing cache, widened `observe()`, formatting.py adoption.
+- `app/remote/runtime.py` — wires the active-pairing cache and cross-references `actions`/`projection`.
+- `app/remote/actions.py` — `/settings`, guided picker, drill-down capability handling, formatting.py adoption.
+- `app/remote/gates.py` — formatting.py adoption.
+- `tests/remote/telegram/test_client.py`, `tests/remote/telegram/test_adapter.py`, `tests/remote/test_outbound.py`, `tests/remote/test_actions.py`, `tests/remote/test_gates.py`, `tests/remote/test_runtime.py`, `tests/models/test_remote_models.py` — updated/new focused evidence.
+
+---
+
+### Task 1: HTML rendering layer
+
+**ACs:** AC-24 (revised)
+
+**Files:**
+
+- Create: `app/remote/formatting.py`
+- Create: `tests/remote/test_formatting.py`
+
+**Interfaces:**
+
+- Produces `escape(value: str) -> str`, `render_status_card`, `render_done_card`, `render_error_card`, `render_gate_card`, `render_settings_card`, `render_project_picker`, `render_prompt_suggestions` — every builder returns `tuple[str, tuple[RemoteButton, ...]]`.
+- Consumes `app.remote.contracts.RemoteButton`.
+
+- [ ] **Step 1: Write escaping and golden-output tests**
+
+```python
+# tests/remote/test_formatting.py
+import html as html_lib
+
+from app.remote import formatting
+from app.remote.contracts import RemoteButton
+
+
+def test_escape_neutralizes_tag_characters():
+    assert formatting.escape("", "tests/conftest.py"],
+        tool_call_count=4,
+        diff_token="diff-tok",
+        toollog_token="log-tok",
+    )
+    assert "" not in text
+    assert "<script>" in text
+    assert "1m 12s" in text
+    assert "4 tool calls" in text
+    assert buttons == (
+        RemoteButton(text="\U0001f4c4 Full diff", token="diff-tok"),
+        RemoteButton(text="\U0001f9fe Tool log", token="log-tok"),
+    )
+
+
+def test_render_done_card_omits_buttons_when_no_tokens():
+    _, buttons = formatting.render_done_card(
+        title="No-op turn",
+        elapsed_seconds=1.0,
+        summary_lines=[],
+        tool_call_count=0,
+        diff_token=None,
+        toollog_token=None,
+    )
+    assert buttons == ()
+
+
+def test_render_error_card_escapes_message():
+    text, buttons = formatting.render_error_card(
+        title="Add rate limiter",
+        message="ModuleNotFoundError: ",
+        toollog_token="log-tok",
+    )
+    assert "<redis>" in text
+    assert len(buttons) == 1
+
+
+def test_render_settings_card_never_emits_model_or_permission_buttons():
+    text, buttons = formatting.render_settings_card(
+        connection_label="evoflux-api",
+        model="claude-sonnet-5",
+        permission_mode="ask each time",
+        redaction_policy="standard",
+        notify_scope="all",
+        redaction_tokens={"strict": "r1", "off": "r2"},
+        notify_scope_tokens={"all": "n1", "remote_only": "n2"},
+    )
+    button_texts = [b.text for b in buttons]
+    assert not any("model" in t.lower() for t in button_texts)
+    assert not any("permission" in t.lower() for t in button_texts)
+    assert any("strict" in t.lower() for t in button_texts)
+```
+
+- [ ] **Step 2: Run and confirm failure**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/test_formatting.py
+```
+
+Expected: FAIL with `ModuleNotFoundError: No module named 'app.remote.formatting'`.
+
+- [ ] **Step 3: Implement the escaping helper and card builders**
+
+```python
+# app/remote/formatting.py
+from __future__ import annotations
+
+import html
+from collections.abc import Mapping, Sequence
+
+from app.remote.contracts import RemoteButton
+
+__all__ = [
+    "escape",
+    "format_elapsed",
+    "render_status_card",
+    "render_done_card",
+    "render_error_card",
+    "render_gate_card",
+    "render_settings_card",
+    "render_project_picker",
+    "render_prompt_suggestions",
+]
+
+_STATUS_ICON = {"accepted": "\U0001f527", "queued": "⏳", "pending": "⏳"}
+
+
+def escape(value: str) -> str:
+    """The only place raw text becomes safe to place inside an HTML tag."""
+    return html.escape(value, quote=False)
+
+
+def format_elapsed(seconds: float) -> str:
+    total = max(0, int(seconds))
+    minutes, secs = divmod(total, 60)
+    return f"{minutes}m {secs}s" if minutes else f"{secs}s"
+
+
+def render_status_card(*, title: str, status: str) -> tuple[str, tuple[RemoteButton, ...]]:
+    icon = _STATUS_ICON.get(status, "\U0001f527")
+    text = f"{icon} {escape(title)}\n{escape(status)}"
+    return text, ()
+
+
+def render_done_card(
+    *,
+    title: str,
+    elapsed_seconds: float,
+    summary_lines: Sequence[str],
+    tool_call_count: int,
+    diff_token: str | None,
+    toollog_token: str | None,
+) -> tuple[str, tuple[RemoteButton, ...]]:
+    header = f"✅ {escape(title)} · {format_elapsed(elapsed_seconds)}"
+    lines = [escape(line) for line in summary_lines]
+    parts = [header]
+    if lines:
+        parts.append("\n".join(lines))
+    parts.append(f"{tool_call_count} tool calls")
+    text = "\n\n".join(parts)
+    buttons: list[RemoteButton] = []
+    if diff_token:
+        buttons.append(RemoteButton(text="\U0001f4c4 Full diff", token=diff_token))
+    if toollog_token:
+        buttons.append(RemoteButton(text="\U0001f9fe Tool log", token=toollog_token))
+    return text, tuple(buttons)
+
+
+def render_error_card(
+    *, title: str, message: str, toollog_token: str | None
+) -> tuple[str, tuple[RemoteButton, ...]]:
+    text = f"❌ {escape(title)}\n\nError: {escape(message)}"
+    buttons = (
+        (RemoteButton(text="\U0001f9fe Tool log", token=toollog_token),)
+        if toollog_token
+        else ()
+    )
+    return text, buttons
+
+
+def render_gate_card(
+    *, title: str, body: str, actions: Sequence[tuple[str, str]]
+) -> tuple[str, tuple[RemoteButton, ...]]:
+    text = f"\U0001f510 {escape(title)}\n{escape(body)}"
+    buttons = tuple(RemoteButton(text=label, token=token) for token, label in actions)
+    return text, buttons
+
+
+def render_settings_card(
+    *,
+    connection_label: str,
+    model: str,
+    permission_mode: str,
+    redaction_policy: str,
+    notify_scope: str,
+    redaction_tokens: Mapping[str, str],
+    notify_scope_tokens: Mapping[str, str],
+) -> tuple[str, tuple[RemoteButton, ...]]:
+    text = (
+        "⚙️ Settings\n\n"
+        f"Connection\n{escape(connection_label)}\n\n"
+        f"Model\n{escape(model)} (desktop only)\n\n"
+        f"Permission mode\n{escape(permission_mode)} (desktop only)\n\n"
+        f"Notifications\n{escape(notify_scope)}\n\n"
+        f"Outbound redaction\n{escape(redaction_policy)}"
+    )
+    buttons = [
+        RemoteButton(text=f"Redaction: {name}", token=token)
+        for name, token in redaction_tokens.items()
+    ]
+    buttons += [
+        RemoteButton(text=f"Notify: {name}", token=token)
+        for name, token in notify_scope_tokens.items()
+    ]
+    return text, tuple(buttons)
+
+
+def render_project_picker(
+    *, projects: Sequence[tuple[str, str]]
+) -> tuple[str, tuple[RemoteButton, ...]]:
+    text = "Which project?"
+    buttons = tuple(
+        RemoteButton(text=f"\U0001f4c1 {escape(name)}", token=token)
+        for token, name in projects
+    )
+    return text, buttons
+
+
+def render_prompt_suggestions(
+    *,
+    project_name: str,
+    context_line: str,
+    suggestions: Sequence[tuple[str, str]],
+    continue_token: str | None,
+) -> tuple[str, tuple[RemoteButton, ...]]:
+    text = (
+        f"\U0001f4c1 {escape(project_name)}\n"
+        f"{escape(context_line)}\n\n"
+        "Try one, or just type your own:"
+    )
+    buttons: list[RemoteButton] = []
+    if continue_token:
+        buttons.append(RemoteButton(text="▶ Continue last session", token=continue_token))
+    buttons += [RemoteButton(text=label, token=token) for token, label in suggestions]
+    return text, tuple(buttons)
+```
+
+- [ ] **Step 4: Run and confirm pass**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/test_formatting.py
+```
+
+Expected: PASS (7 tests).
+
+- [ ] **Step 5: Lint**
+
+```powershell
+uv run ruff check app/remote/formatting.py tests/remote/test_formatting.py
+uv run ty check app/remote/formatting.py
+```
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add app/remote/formatting.py tests/remote/test_formatting.py
+git commit -m "feat(remote): add HTML rendering layer for Telegram cards"
+```
+
+---
+
+### Task 2: HTML parse mode and native typing indicator
+
+**ACs:** AC-24 (revised), AC-38 (transport half)
+
+**Files:**
+
+- Modify: `app/remote/contracts.py`
+- Modify: `app/remote/telegram/client.py`
+- Modify: `app/remote/telegram/adapter.py`
+- Modify: `tests/remote/telegram/test_client.py`
+- Modify: `tests/remote/telegram/test_adapter.py`
+
+**Interfaces:**
+
+- Produces `TelegramClient.send_chat_action(*, chat_id: str | int, action: str = "typing") -> None`.
+- Produces `RemoteAdapter.indicate_typing(destination_id: str) -> None` (Protocol) and `TelegramAdapter.indicate_typing`.
+- Changes `TelegramClient.send_text`/`edit_text` to always send `parse_mode="HTML"`.
+
+- [ ] **Step 1: Write failing client tests**
+
+```python
+# tests/remote/telegram/test_client.py (add)
+@pytest.mark.asyncio
+async def test_send_text_sends_html_parse_mode(client, transport):
+    await client.send_text(chat_id="1", text="hi")
+    request = transport.requests[-1]
+    assert request.json()["parse_mode"] == "HTML"
+
+
+@pytest.mark.asyncio
+async def test_send_chat_action_calls_send_chat_action_endpoint(client, transport):
+    await client.send_chat_action(chat_id="1")
+    request = transport.requests[-1]
+    assert request.url.path.endswith("/sendChatAction")
+    assert request.json() == {"chat_id": "1", "action": "typing"}
+```
+
+- [ ] **Step 2: Run and confirm failure**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/telegram/test_client.py -k "parse_mode or chat_action"
+```
+
+- [ ] **Step 3: Implement in `TelegramClient`**
+
+```python
+# app/remote/telegram/client.py — inside send_text/edit_text payload construction,
+# add "parse_mode": "HTML" to the request body dict alongside existing chat_id/text/
+# reply_markup keys. Then add:
+
+async def send_chat_action(
+    self, *, chat_id: str | int, action: str = "typing"
+) -> None:
+    await self._post("sendChatAction", {"chat_id": chat_id, "action": action})
+```
+
+Use whichever existing private request helper `send_text` already calls (e.g. `self._post`/`self._request`) so error handling matches the rest of the class.
+
+- [ ] **Step 4: Run and confirm pass**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/telegram/test_client.py
+```
+
+- [ ] **Step 5: Write failing adapter test for `indicate_typing`**
+
+```python
+# tests/remote/telegram/test_adapter.py (add)
+@pytest.mark.asyncio
+async def test_indicate_typing_calls_client(adapter, fake_client):
+    await adapter.indicate_typing("chat-1")
+    assert fake_client.chat_actions == [("chat-1", "typing")]
+```
+
+- [ ] **Step 6: Run and confirm failure**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/telegram/test_adapter.py -k indicate_typing
+```
+
+- [ ] **Step 7: Add `indicate_typing` to the Protocol and implement it**
+
+```python
+# app/remote/contracts.py — inside class RemoteAdapter(Protocol):
+    async def indicate_typing(self, destination_id: str) -> None: ...
+```
+
+```python
+# app/remote/telegram/adapter.py — new method on TelegramAdapter
+async def indicate_typing(self, destination_id: str) -> None:
+    try:
+        await self._client.send_chat_action(chat_id=destination_id)
+    except TelegramApiError:
+        # Best-effort liveliness signal; never fail the turn over it.
+        pass
+```
+
+- [ ] **Step 8: Run and confirm pass**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/telegram/test_client.py tests/remote/telegram/test_adapter.py
+uv run ruff check app/remote/contracts.py app/remote/telegram/client.py app/remote/telegram/adapter.py
+uv run ty check app/remote/
+```
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add app/remote/contracts.py app/remote/telegram/client.py app/remote/telegram/adapter.py tests/remote/telegram/test_client.py tests/remote/telegram/test_adapter.py
+git commit -m "feat(remote): send HTML parse mode and native typing indicator"
+```
+
+---
+
+### Task 3: `notify_scope` schema and active-pairing cache
+
+**ACs:** AC-42 (schema half)
+
+**Files:**
+
+- Create: `app/migrations/versions/00000065_add_remote_pairing_notify_scope.py`
+- Modify: `app/models/remote.py`
+- Modify: `app/remote/outbound.py`
+- Modify: `app/remote/runtime.py`
+- Test: `tests/models/test_remote_models.py` (create if absent)
+- Modify: `tests/remote/test_outbound.py`
+- Modify: `tests/remote/test_runtime.py`
+
+**Interfaces:**
+
+- Produces `RemotePairing.notify_scope: str` (default `"all"`).
+- Produces `RemoteProjection.set_active_pairing(*, connection_id: str, destination_id: str, notify_scope: str, principal_id: str) -> None` and `RemoteProjection.clear_active_pairing() -> None`.
+- Consumes `RemotePairing` via direct `select()`, matching the pattern already used in `app/remote/inbound.py`.
+
+- [ ] **Step 1: Write the migration**
+
+```python
+# app/migrations/versions/00000065_add_remote_pairing_notify_scope.py
+"""Add remote_pairings.notify_scope
+
+Revision ID: 00000065
+Revises: 00000064
+"""
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "00000065"
+down_revision: str | Sequence[str] | None = "00000064"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "remote_pairings",
+        sa.Column(
+            "notify_scope",
+            sa.String(20),
+            nullable=False,
+            server_default="all",
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("remote_pairings", "notify_scope")
+```
+
+- [ ] **Step 2: Update the schema-head marker**
+
+Open `app/core/schema_version.py` and update the expected head revision constant to `"00000065"`, matching how `00000064` was registered.
+
+- [ ] **Step 3: Write a failing model/migration test**
+
+```python
+# tests/models/test_remote_models.py
+import pytest
+from sqlmodel import select
+
+from app.models.remote import RemotePairing
+
+
+@pytest.mark.asyncio
+async def test_new_pairing_defaults_notify_scope_to_all(db_session, remote_connection):
+    pairing = RemotePairing(
+        connection_id=remote_connection.id,
+        principal_id="user-1",
+        destination_id="chat-1",
+        label="My phone",
+    )
+    db_session.add(pairing)
+    await db_session.commit()
+    await db_session.refresh(pairing)
+    assert pairing.notify_scope == "all"
+```
+
+- [ ] **Step 4: Run and confirm failure**
+
+```powershell
+uv run pytest --no-cov -q tests/models/test_remote_models.py
+```
+
+Expected: FAIL — `notify_scope` is not a field on `RemotePairing`.
+
+- [ ] **Step 5: Add the column to the model**
+
+```python
+# app/models/remote.py — inside class RemotePairing, after `display`:
+notify_scope: str = Field(
+    default="all",
+    sa_column=Column(sa.String(20), nullable=False, server_default="all"),
+)
+```
+
+- [ ] **Step 6: Run migration head and model test**
+
+```powershell
+uv run alembic upgrade head
+uv run pytest --no-cov -q tests/models/test_remote_models.py
+```
+
+- [ ] **Step 7: Write failing active-pairing cache tests**
+
+```python
+# tests/remote/test_outbound.py (add)
+def test_set_active_pairing_then_clear(projection):
+    projection.set_active_pairing(
+        connection_id="conn-1", destination_id="chat-1", notify_scope="all", principal_id="user-1",
+    )
+    assert projection.active_pairing() == ("conn-1", "chat-1", "all", "user-1")
+    projection.clear_active_pairing()
+    assert projection.active_pairing() is None
+```
+
+- [ ] **Step 8: Run and confirm failure**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/test_outbound.py -k active_pairing
+```
+
+- [ ] **Step 9: Implement the cache on `RemoteProjection`**
+
+```python
+# app/remote/outbound.py — new fields on RemoteProjection and two methods.
+# principal_id travels alongside connection/destination so completions and
+# drill-down tokens for a session the projection never explicitly
+# register_session-ed (Task 5) can still be minted with a real, non-empty
+# owner instead of "" — v1 has exactly one pairing per connection, so the
+# active pairing's principal is the only valid actor for the whole
+# connection regardless of which surface (phone or desktop) started the work.
+_active_pairing: tuple[str, str, str, str] | None = field(default=None, repr=False)
+
+def set_active_pairing(
+    self, *, connection_id: str, destination_id: str, notify_scope: str, principal_id: str,
+) -> None:
+    """Cache the single v1 pairing's routing info so ``observe`` can reach
+    sessions it was never explicitly ``register_session``-ed for."""
+    self._active_pairing = (connection_id, destination_id, notify_scope, principal_id)
+
+def clear_active_pairing(self) -> None:
+    self._active_pairing = None
+
+def active_pairing(self) -> tuple[str, str, str, str] | None:
+    return self._active_pairing
+```
+
+- [ ] **Step 10: Wire it from `runtime.py`**
+
+```python
+# app/remote/runtime.py — inside _start_locked, after `projection.set_adapter(adapter)`
+from app.models.remote import RemotePairing
+from sqlmodel import select
+
+async with read_session_factory() as pairing_session:
+    pairing = (
+        await pairing_session.exec(
+            select(RemotePairing).where(RemotePairing.connection_id == connection.id)
+        )
+    ).first()
+if pairing is not None:
+    projection.set_active_pairing(
+        connection_id=str(pairing.connection_id),
+        destination_id=pairing.destination_id,
+        notify_scope=pairing.notify_scope,
+        principal_id=pairing.principal_id,
+    )
+```
+
+```python
+# app/remote/runtime.py — inside _handle_pairing, in the `if result is not None:`
+# branch that already sends "Connected to EvoFlux on {result.label}." —
+# `result` is the persisted RemotePairing row itself (consume()'s return type)
+if self._projection is not None:
+    self._projection.set_active_pairing(
+        connection_id=str(action.connection_id),
+        destination_id=result.destination_id,
+        notify_scope=result.notify_scope,
+        principal_id=result.principal_id,
+    )
+```
+
+```python
+# app/remote/runtime.py — inside _stop_locked, before projection is discarded
+if self._projection is not None:
+    self._projection.clear_active_pairing()
+```
+
+- [ ] **Step 11: Run and confirm pass**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/test_outbound.py tests/remote/test_runtime.py
+uv run ruff check app/remote/outbound.py app/remote/runtime.py app/models/remote.py tests/models/test_remote_models.py tests/remote/test_outbound.py tests/remote/test_runtime.py
+uv run ty check app/remote/ app/models/remote.py
+```
+
+- [ ] **Step 12: Commit**
+
+```bash
+git add app/migrations/versions/00000065_add_remote_pairing_notify_scope.py app/core/schema_version.py app/models/remote.py app/remote/outbound.py app/remote/runtime.py tests/models/test_remote_models.py tests/remote/test_outbound.py tests/remote/test_runtime.py
+git commit -m "feat(remote): add notify_scope preference and active-pairing cache"
+```
+
+---
+
+### Task 4: Turn-activity summary and phone-admitted status lifecycle
+
+**ACs:** AC-38, AC-24 (application half)
+
+**Files:**
+
+- Create: `app/remote/turn_activity.py`
+- Create: `tests/remote/test_turn_activity.py`
+- Modify: `app/remote/outbound.py`
+- Modify: `app/remote/runtime.py`
+- Modify: `tests/remote/test_outbound.py`
+
+**Interfaces:**
+
+- Produces `app.remote.turn_activity.load_turn_activity(db: AsyncSession, session_id: str, *, since: datetime) -> TurnActivity` where `TurnActivity` has `tool_call_count: int`, `summary_lines: list[str]`, `tool_log_text: str`, `diff_text: str`.
+- Produces `RemoteProjection.begin_phone_turn(session_id: str, *, connection_id: str, destination_id: str, principal_id: str, title: str, status: str) -> None`.
+- Consumes `app.remote.formatting.render_status_card/render_done_card/render_error_card`, `app.models.chat.ChatMessage`.
+
+- [ ] **Step 1: Write failing turn-activity tests**
+
+```python
+# tests/remote/test_turn_activity.py
+import pytest
+from datetime import UTC, datetime, timedelta
+
+from app.models.chat import ChatMessage
+from app.remote.turn_activity import load_turn_activity
+
+
+@pytest.mark.asyncio
+async def test_load_turn_activity_counts_tool_calls_and_builds_diff(db_session, chat_session):
+    since = datetime.now(UTC) - timedelta(seconds=1)
+    db_session.add_all(
+        [
+            ChatMessage(
+                session_id=chat_session.id,
+                role="assistant",
+                tool_calls=[{"name": "write", "arguments": {"path": "a.py"}}],
+                created_at=since + timedelta(milliseconds=10),
+            ),
+            ChatMessage(
+                session_id=chat_session.id,
+                role="tool",
+                tool_call_id="1",
+                content="wrote a.py (+5 -1)",
+                created_at=since + timedelta(milliseconds=20),
+            ),
+            ChatMessage(
+                session_id=chat_session.id,
+                role="assistant",
+                tool_calls=[{"name": "read", "arguments": {"path": "b.py"}}],
+                created_at=since + timedelta(milliseconds=30),
+            ),
+        ]
+    )
+    await db_session.commit()
+
+    activity = await load_turn_activity(db_session, str(chat_session.id), since=since)
+
+    assert activity.tool_call_count == 2
+    assert "write" in activity.diff_text
+    assert "read" not in activity.diff_text
+    assert "read" in activity.tool_log_text
+```
+
+- [ ] **Step 2: Run and confirm failure**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/test_turn_activity.py
+```
+
+- [ ] **Step 3: Implement `turn_activity.py`**
+
+```python
+# app/remote/turn_activity.py
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+
+from sqlmodel import select
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from app.models.chat import ChatMessage
+
+_DIFF_TOOLS = frozenset({"write", "edit", "patch"})
+
+__all__ = ["TurnActivity", "load_turn_activity"]
+
+
+@dataclass(frozen=True)
+class TurnActivity:
+    tool_call_count: int
+    summary_lines: list[str] = field(default_factory=list)
+    tool_log_text: str = ""
+    diff_text: str = ""
+
+
+async def load_turn_activity(
+    db: AsyncSession, session_id: str, *, since: datetime
+) -> TurnActivity:
+    rows = (
+        await db.exec(
+            select(ChatMessage)
+            .where(ChatMessage.session_id == session_id)
+            .where(ChatMessage.created_at >= since)
+            .order_by(ChatMessage.created_at)
+        )
+    ).all()
+
+    tool_calls: list[tuple[str, str]] = []
+    for message in rows:
+        for call in message.tool_calls or []:
+            name = call.get("name", "unknown")
+            args = call.get("arguments", {})
+            tool_calls.append((name, str(args)))
+
+    tool_log_lines = [f"{name}: {args}" for name, args in tool_calls]
+    diff_lines = [f"{name}: {args}" for name, args in tool_calls if name in _DIFF_TOOLS]
+    diff_paths = sorted({args for name, args in tool_calls if name in _DIFF_TOOLS})
+
+    return TurnActivity(
+        tool_call_count=len(tool_calls),
+        summary_lines=diff_paths[:10],
+        tool_log_text="\n".join(tool_log_lines) or "No tool calls.",
+        diff_text="\n".join(diff_lines) or "No file changes.",
+    )
+```
+
+- [ ] **Step 4: Run and confirm pass**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/test_turn_activity.py
+```
+
+- [ ] **Step 5: Write failing phone-admitted lifecycle tests**
+
+```python
+# tests/remote/test_outbound.py (add)
+@pytest.mark.asyncio
+async def test_begin_phone_turn_sends_status_card_then_done_edits_it(
+    projection, adapter
+):
+    projection.register_session(
+        "sess-1", connection_id="conn-1", destination_id="chat-1",
+        tags=frozenset({"remote_origin"}),
+    )
+    projection.begin_phone_turn(
+        "sess-1", connection_id="conn-1", destination_id="chat-1", principal_id="user-1",
+        title="Fix tests", status="accepted",
+    )
+    await asyncio.sleep(0.05)
+    assert adapter.calls[0] == "send"
+    first_correlation = adapter.sent[0].correlation_id
+
+    projection.observe("sess-1", _envelope("done", text="Done."))
+    await projection.drain_pending()
+
+    assert adapter.calls[1] == "edit"
+    assert adapter.edited[0].correlation_id == first_correlation
+    assert "Fix tests" in adapter.edited[0].text
+    assert projection.typing_task_for("sess-1") is None
+```
+
+- [ ] **Step 6: Run and confirm failure**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/test_outbound.py -k begin_phone_turn
+```
+
+- [ ] **Step 7: Implement the lifecycle on `RemoteProjection`**
+
+```python
+# app/remote/outbound.py — extend _TurnDeliveryState
+@dataclass
+class _TurnDeliveryState:
+    session_id: str
+    connection_id: str
+    destination_id: str
+    lifecycle_correlation_id: str | None = None
+    completion_sent: bool = False
+    phone_admitted: bool = False
+    started_at: float = field(default_factory=time.monotonic)
+    turn_started_wall_clock: datetime = field(default_factory=lambda: datetime.now(UTC))
+    typing_task: "asyncio.Task[None] | None" = field(default=None, repr=False)
+    title: str = ""
+    principal_id: str = ""
+```
+
+```python
+# app/remote/outbound.py — new public method
+def begin_phone_turn(
+    self,
+    session_id: str,
+    *,
+    connection_id: str,
+    destination_id: str,
+    principal_id: str,
+    title: str,
+    status: str,
+) -> None:
+    """Create the one status message a phone-admitted turn owns, and start
+    the native typing indicator alongside it. Called by runtime.py right
+    after register_session for a text-triggered admission."""
+    correlation_id = f"status:{session_id}:{uuid.uuid4().hex[:8]}"
+    turn = _TurnDeliveryState(
+        session_id=session_id,
+        connection_id=connection_id,
+        destination_id=destination_id,
+        principal_id=principal_id,
+        lifecycle_correlation_id=correlation_id,
+        phone_admitted=True,
+        title=title,
+    )
+    self._turns[session_id] = turn
+    text, buttons = render_status_card(title=title, status=status)
+    self._enqueue_send(
+        destination_id=destination_id,
+        text=text,
+        buttons=buttons,
+        priority=RemoteOutboundPriority.HIGH,
+        correlation_id=correlation_id,
+    )
+    if self._adapter is not None:
+        turn.typing_task = asyncio.create_task(self._run_typing_loop(turn))
+
+
+async def _run_typing_loop(self, turn: _TurnDeliveryState) -> None:
+    adapter = self._adapter
+    if adapter is None:
+        return
+    try:
+        while True:
+            await adapter.indicate_typing(turn.destination_id)
+            await asyncio.sleep(4.0)
+    except asyncio.CancelledError:
+        pass
+
+
+def typing_task_for(self, session_id: str) -> "asyncio.Task[None] | None":
+    turn = self._turns.get(session_id)
+    return turn.typing_task if turn is not None else None
+
+
+def _stop_typing(self, turn: _TurnDeliveryState) -> None:
+    if turn.typing_task is not None and not turn.typing_task.done():
+        turn.typing_task.cancel()
+    turn.typing_task = None
+```
+
+Replace `_handle_done`/`_handle_error` to branch on `turn.phone_admitted`, using `formatting.py` builders and `turn_activity.load_turn_activity`:
+
+```python
+async def _finalize_turn(
+    self, turn: _TurnDeliveryState, *, error_message: str | None
+) -> None:
+    from app.core.db import async_session_factory
+
+    self._stop_typing(turn)
+    elapsed = time.monotonic() - turn.started_at
+    async with async_session_factory() as db:
+        activity = await load_turn_activity(
+            db, turn.session_id, since=turn.turn_started_wall_clock
+        )
+    diff_token = toollog_token = None
+    if self._actions is not None:
+        if activity.diff_text.strip() and activity.diff_text != "No file changes.":
+            diff_token = self._actions.register_capability(
+                connection_id=turn.connection_id,
+                principal_id=turn.principal_id,
+                destination_id=turn.destination_id,
+                session_id=turn.session_id,
+                action_kind="diff",
+                action_target=activity.diff_text,
+            )
+        toollog_token = self._actions.register_capability(
+            connection_id=turn.connection_id,
+            principal_id=turn.principal_id,
+            destination_id=turn.destination_id,
+            session_id=turn.session_id,
+            action_kind="toollog",
+            action_target=activity.tool_log_text,
+        )
+    if error_message is not None:
+        text, buttons = render_error_card(
+            title=turn.title, message=_redact_text(error_message), toollog_token=toollog_token
+        )
+    else:
+        text, buttons = render_done_card(
+            title=turn.title,
+            elapsed_seconds=elapsed,
+            summary_lines=[_redact_text(line) for line in activity.summary_lines],
+            tool_call_count=activity.tool_call_count,
+            diff_token=diff_token,
+            toollog_token=toollog_token,
+        )
+    if turn.phone_admitted and turn.lifecycle_correlation_id is not None:
+        self._enqueue_edit(
+            destination_id=turn.destination_id,
+            text=text,
+            buttons=buttons,
+            correlation_id=turn.lifecycle_correlation_id,
+        )
+    else:
+        self._enqueue_send(
+            destination_id=turn.destination_id,
+            text=text,
+            buttons=buttons,
+            priority=RemoteOutboundPriority.HIGH,
+        )
+```
+
+`_handle_done`/`_handle_error` become thin wrappers: guard on `turn.completion_sent`, set it, then `await self._finalize_turn(turn, error_message=None)` / `await self._finalize_turn(turn, error_message=message)`.
+
+The real current `_enqueue_send` (`app/remote/outbound.py`) already accepts `buttons` but not `correlation_id`, builds one `RemoteOutboundMessage` per chunk, appends each to `self._pending: list[RemoteOutboundMessage]`, and calls `self._schedule_drain()` — a fire-and-forget `asyncio.create_task(self.drain_pending())` when a loop is running, there is no persistent background worker. `drain_pending()` pops everything off `self._pending` and calls `await adapter.send(msg)` for each; there is currently no edit path at all. Extend it exactly like this:
+
+```python
+# app/remote/outbound.py — add a correlation_id parameter to the existing
+# _enqueue_send, and a new _enqueue_edit + a second pending list
+def _enqueue_send(
+    self,
+    *,
+    destination_id: str,
+    text: str,
+    buttons: tuple[RemoteButton, ...] = (),
+    priority: RemoteOutboundPriority = RemoteOutboundPriority.INFORMATIONAL,
+    correlation_id: str | None = None,
+) -> None:
+    adapter = self._adapter
+    if adapter is None:
+        logger.debug("remote_outbound_no_adapter destination_id={}", destination_id)
+        return
+    connection_id = ""
+    for cid in self._session_connection_ids.values():
+        connection_id = cid
+        break
+    chunks = _split_text(text)
+    for i, chunk in enumerate(chunks):
+        msg = RemoteOutboundMessage(
+            connection_id=UUID(connection_id) if connection_id else UUID(int=0),
+            destination_id=destination_id,
+            text=chunk,
+            buttons=buttons if i == len(chunks) - 1 else (),
+            priority=priority,
+            correlation_id=correlation_id if i == len(chunks) - 1 else None,
+        )
+        self._pending.append(msg)
+    self._schedule_drain()
+
+
+def _enqueue_edit(
+    self, *, destination_id: str, text: str, buttons: tuple[RemoteButton, ...], correlation_id: str,
+) -> None:
+    """Edit-flagged delivery — a status card's final transition. Unlike
+    _enqueue_send, never splits (a status/done card is always short and
+    already bounded by formatting.py's builders), so it is always exactly
+    one queued item."""
+    adapter = self._adapter
+    if adapter is None:
+        return
+    connection_id = ""
+    for cid in self._session_connection_ids.values():
+        connection_id = cid
+        break
+    msg = RemoteOutboundMessage(
+        connection_id=UUID(connection_id) if connection_id else UUID(int=0),
+        destination_id=destination_id,
+        text=text,
+        buttons=buttons,
+        correlation_id=correlation_id,
+    )
+    self._pending_edits.append(msg)
+    self._schedule_drain()
+```
+
+```python
+# app/remote/outbound.py — extend drain_pending to also drain edits, and
+# add the new field next to the existing _pending: list[RemoteOutboundMessage]
+_pending_edits: list[RemoteOutboundMessage] = field(default_factory=list, repr=False)
+
+async def drain_pending(self) -> None:
+    """Send/edit all pending messages through the adapter."""
+    adapter = self._adapter
+    if adapter is None:
+        self._pending.clear()
+        self._pending_edits.clear()
+        self._unaddressed_pending.clear()
+        return
+    while self._pending:
+        msg = self._pending.pop(0)
+        try:
+            await adapter.send(msg)
+        except Exception as exc:
+            logger.warning("remote_outbound_send_failed destination_id={} error={}", msg.destination_id, exc)
+    while self._pending_edits:
+        msg = self._pending_edits.pop(0)
+        try:
+            await adapter.edit(msg)
+        except Exception as exc:
+            logger.warning("remote_outbound_edit_failed destination_id={} error={}", msg.destination_id, exc)
+    await self._drain_unaddressed()
+```
+
+`register_capability`'s real signature is defined in Task 6 — until that task lands, treat `self._actions` as an optional `"RemoteActionService | None" = None` attribute set by the `set_actions` setter Task 6 also adds, and treat a `None` diff/toollog token as "no button" (Task 1's builders already handle that). `_drain_unaddressed` (Task 5) is a no-op empty method until Task 5 implements it — add it as a stub (`async def _drain_unaddressed(self) -> None: return`) in this task so `drain_pending` has something to call, and Task 5 replaces the stub body.
+
+- [ ] **Step 8: Wire `begin_phone_turn` from `runtime.py`**
+
+```python
+# app/remote/runtime.py — inside _handle_text, right after the existing
+# register_session(...) call
+if result.session_id is not None and self._projection is not None:
+    from app.core.db import async_session_factory as _sf
+
+    async with _sf() as title_session:
+        session_row = await title_session.get(ChatSession, result.session_id)
+    self._projection.begin_phone_turn(
+        str(result.session_id),
+        connection_id=str(action.connection_id),
+        destination_id=action.principal.destination_id,
+        principal_id=action.principal.principal_id,
+        title=(session_row.title if session_row and session_row.title else "New task"),
+        status=result.status,
+    )
+```
+
+- [ ] **Step 9: Run and confirm pass**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/test_outbound.py tests/remote/test_runtime.py tests/remote/test_turn_activity.py
+uv run ruff check app/remote/outbound.py app/remote/runtime.py app/remote/turn_activity.py tests/remote/test_outbound.py tests/remote/test_turn_activity.py
+uv run ty check app/remote/
+```
+
+- [ ] **Step 10: Commit**
+
+```bash
+git add app/remote/turn_activity.py app/remote/outbound.py app/remote/runtime.py tests/remote/test_turn_activity.py tests/remote/test_outbound.py
+git commit -m "feat(remote): live status card, typing indicator, and done/error cards"
+```
+
+---
+
+### Task 5: Cross-origin and workflow/scheduler completion delivery
+
+**ACs:** AC-42, AC-43
+
+**Files:**
+
+- Modify: `app/remote/outbound.py`
+- Modify: `tests/remote/test_outbound.py`
+
+**Interfaces:**
+
+- Changes `RemoteProjection.observe` session-resolution: falls back to `active_pairing()` when the session was never `register_session`-ed and the cached `notify_scope == "all"`, carrying the cached `principal_id` through so completion/drill-down capability tokens for these sessions are minted with a real owner instead of an empty string.
+- Consumes `app.remote.inbound._is_addressable_session` (import it into `outbound.py` rather than duplicating the predicate) and `app.models.chat.ChatSession`.
+
+- [ ] **Step 1: Write failing cross-origin tests**
+
+```python
+# tests/remote/test_outbound.py (add)
+@pytest.mark.asyncio
+async def test_unregistered_addressable_session_notifies_when_scope_is_all(
+    projection, adapter, db_session_factory, addressable_session
+):
+    projection.set_active_pairing(
+        connection_id="conn-1", destination_id="chat-1", notify_scope="all", principal_id="user-1",
+    )
+    projection.observe(str(addressable_session.id), _envelope("done", text="Done."))
+    await projection.drain_pending()
+    assert adapter.calls == ["send"]
+    assert adapter.sent[0].destination_id == "chat-1"
+
+
+@pytest.mark.asyncio
+async def test_unregistered_session_silent_when_scope_is_remote_only(
+    projection, adapter, addressable_session
+):
+    projection.set_active_pairing(
+        connection_id="conn-1", destination_id="chat-1", notify_scope="remote_only", principal_id="user-1",
+    )
+    projection.observe(str(addressable_session.id), _envelope("done", text="Done."))
+    await projection.drain_pending()
+    assert adapter.calls == []
+
+
+@pytest.mark.asyncio
+async def test_non_addressable_session_never_notifies_even_with_scope_all(
+    projection, adapter, side_chat_session
+):
+    projection.set_active_pairing(
+        connection_id="conn-1", destination_id="chat-1", notify_scope="all", principal_id="user-1",
+    )
+    projection.observe(str(side_chat_session.id), _envelope("done", text="Done."))
+    await projection.drain_pending()
+    assert adapter.calls == []
+
+
+@pytest.mark.asyncio
+async def test_unregistered_session_gets_no_status_card_or_typing(
+    projection, adapter, addressable_session
+):
+    projection.set_active_pairing(
+        connection_id="conn-1", destination_id="chat-1", notify_scope="all", principal_id="user-1",
+    )
+    projection.observe(str(addressable_session.id), _envelope("done", text="Done."))
+    await projection.drain_pending()
+    assert projection.typing_task_for(str(addressable_session.id)) is None
+```
+
+- [ ] **Step 2: Run and confirm failure**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/test_outbound.py -k "cross_origin or unregistered or non_addressable"
+```
+
+- [ ] **Step 3: Implement the widened resolution in `observe`**
+
+```python
+# app/remote/outbound.py — replace the early-return session resolution at
+# the top of observe() with:
+def observe(self, session_id: str, envelope) -> None:
+    event_type = envelope.event
+    if event_type not in _OBSERVED_EVENT_TYPES:
+        return
+
+    tags = self._session_tags.get(session_id)
+    if tags is not None:
+        connection_id = self._session_connection_ids.get(session_id, "")
+        destination_id = self._session_destination_ids.get(session_id, "")
+        if not connection_id or not destination_id:
+            return
+    else:
+        active = self._active_pairing
+        if active is None or active[2] != "all":
+            return
+        # Addressability for a session we never registered can only be
+        # confirmed with a database read, which observe() must never do
+        # (AC-19). Defer that check to the async delivery path by enqueuing
+        # a guarded lookup instead of calling send/edit directly.
+        if event_type not in ("done", "error"):
+            return
+        connection_id, destination_id, _, principal_id = active
+        self._enqueue_unregistered_completion(
+            session_id=session_id,
+            connection_id=connection_id,
+            destination_id=destination_id,
+            principal_id=principal_id,
+            event_type=event_type,
+            envelope_data=dict(envelope.data),
+        )
+        return
+
+    turn = self._turns.get(session_id)
+    if turn is None:
+        turn = _TurnDeliveryState(
+            session_id=session_id, connection_id=connection_id, destination_id=destination_id,
+        )
+        self._turns[session_id] = turn
+
+    if event_type == "done":
+        self._handle_done(turn, envelope)
+    elif event_type == "error":
+        self._handle_error(turn, envelope)
+```
+
+```python
+# app/remote/outbound.py — new queue item; _schedule_drain is the existing
+# fire-and-forget wake used by _enqueue_send (there is no persistent
+# background worker task to notify)
+def _enqueue_unregistered_completion(
+    self, *, session_id: str, connection_id: str, destination_id: str,
+    principal_id: str, event_type: str, envelope_data: dict,
+) -> None:
+    self._unaddressed_pending.append(
+        (session_id, connection_id, destination_id, principal_id, event_type, envelope_data)
+    )
+    self._schedule_drain()
+```
+
+```python
+# app/remote/outbound.py — inside the existing async delivery-worker loop,
+# before/after the regular queue drain, drain _unaddressed_pending too:
+async def _drain_unaddressed(self) -> None:
+    from app.core.db import async_session_factory
+    from app.models.chat import ChatSession
+    from app.remote.inbound import _is_addressable_session
+
+    pending, self._unaddressed_pending = self._unaddressed_pending, []
+    for session_id, connection_id, destination_id, principal_id, event_type, data in pending:
+        async with async_session_factory() as db:
+            session_row = await db.get(ChatSession, session_id)
+        if not _is_addressable_session(session_row):
+            continue
+        turn = self._turns.get(session_id)
+        if turn is None:
+            turn = _TurnDeliveryState(
+                session_id=session_id, connection_id=connection_id,
+                destination_id=destination_id, principal_id=principal_id,
+                title=session_row.title or "Task",
+            )
+            self._turns[session_id] = turn
+        if event_type == "done":
+            if turn.completion_sent:
+                continue
+            turn.completion_sent = True
+            await self._finalize_turn(turn, error_message=None)
+        else:
+            await self._finalize_turn(turn, error_message=data.get("message", "An error occurred."))
+```
+
+This replaces the empty `_drain_unaddressed` stub Task 4 added (that task's extended `drain_pending` already calls `await self._drain_unaddressed()` at the end, so existing tests that call `await projection.drain_pending()` exercise this path with no further wiring needed). Add `_unaddressed_pending: list[tuple] = field(default_factory=list, repr=False)` to `RemoteProjection`'s dataclass fields.
+
+- [ ] **Step 4: Run and confirm pass**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/test_outbound.py
+uv run ruff check app/remote/outbound.py tests/remote/test_outbound.py
+uv run ty check app/remote/outbound.py
+```
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add app/remote/outbound.py tests/remote/test_outbound.py
+git commit -m "feat(remote): deliver completions for desktop-started and workflow sessions"
+```
+
+---
+
+### Task 6: On-demand drill-down (Full diff, Tool log)
+
+**ACs:** AC-39
+
+**Files:**
+
+- Modify: `app/remote/actions.py`
+- Modify: `app/remote/outbound.py`
+- Modify: `app/remote/runtime.py`
+- Modify: `tests/remote/test_actions.py`
+- Modify: `tests/remote/test_outbound.py`
+
+**Interfaces:**
+
+- Produces `RemoteActionService.register_capability(*, connection_id: UUID | str, principal_id: str, destination_id: str, session_id: str, action_kind: str, action_target: str) -> str`.
+- Changes `RemoteActionService.handle_action_callback(self, action: RemoteInboundAction, db: AsyncSession) -> bool` — adds a required `db` parameter (needed by later tasks' branches, e.g. Task 7's settings writes and Task 8's session creation) and `"diff"`/`"toollog"` branches. Every existing caller and test call site for this method is updated in this task, not deferred.
+- Produces `RemoteProjection.set_actions(actions: "RemoteActionService | None") -> None` and `RemoteActionService.set_projection(projection: "RemoteProjection | None") -> None` (the two services need each other: outbound needs actions to mint drill-down tokens; actions needs outbound to update the active-pairing cache and to give guided-flow-started tasks a live status card).
+
+- [ ] **Step 1: Write failing capability-registration and dispatch tests**
+
+```python
+# tests/remote/test_actions.py (add)
+def test_register_capability_returns_usable_token(service):
+    token = service.register_capability(
+        connection_id=uuid4(), principal_id="", destination_id="chat-1",
+        session_id="sess-1", action_kind="toollog", action_target="log text",
+    )
+    assert isinstance(token, str) and len(token) > 0
+
+
+@pytest.mark.asyncio
+async def test_toollog_callback_sends_stored_content(service, adapter, db_session):
+    token = service.register_capability(
+        connection_id=uuid4(), principal_id="", destination_id="chat-1",
+        session_id="sess-1", action_kind="toollog", action_target="write: {'path': 'a.py'}",
+    )
+    action = _make_action(callback_token=token)
+    handled = await service.handle_action_callback(action, db_session)
+    assert handled is True
+    assert any("write" in msg.text for msg in adapter.sent)
+
+
+@pytest.mark.asyncio
+async def test_expired_capability_replies_friendly_message(service, adapter, db_session, monkeypatch):
+    token = service.register_capability(
+        connection_id=uuid4(), principal_id="", destination_id="chat-1",
+        session_id="sess-1", action_kind="diff", action_target="diff text",
+    )
+    monkeypatch.setattr(time, "monotonic", lambda: time.monotonic() + 700)
+    action = _make_action(callback_token=token)
+    handled = await service.handle_action_callback(action, db_session)
+    assert handled is True
+    assert "expired" in adapter.sent[0].text.lower()
+```
+
+- [ ] **Step 1b: Update the method signature and every existing call site**
+
+Add `db: AsyncSession` as `handle_action_callback`'s second positional parameter. Update its four existing internal branches (workflow/coding-project/EASD/schedule dispatch) — they currently open their own `async with async_session_factory() as session:` block per branch; replace each with the passed-in `db` so the whole method shares one session, matching how `dispatch_command` already receives `db` from its caller. Update every existing test in `tests/remote/test_actions.py` that calls `service.handle_action_callback(action)` to `service.handle_action_callback(action, db_session)`.
+
+- [ ] **Step 2: Run and confirm failure**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/test_actions.py -k "capability or toollog or expired"
+```
+
+- [ ] **Step 3: Implement `register_capability` and dispatch branches**
+
+```python
+# app/remote/actions.py — new public method on RemoteActionService
+def register_capability(
+    self,
+    *,
+    connection_id: UUID | str,
+    principal_id: str,
+    destination_id: str,
+    session_id: str,
+    action_kind: str,
+    action_target: str,
+) -> str:
+    token = secrets.token_urlsafe(16)[:_MAX_CALLBACK_TOKEN_BYTES]
+    self._capabilities[token] = _ActionCapability(
+        token=token,
+        connection_id=UUID(str(connection_id)),
+        principal_id=principal_id,
+        destination_id=destination_id,
+        session_id=session_id,
+        action_kind=action_kind,
+        action_target=action_target,
+    )
+    return token
+```
+
+```python
+# app/remote/actions.py — inside handle_action_callback, add before the
+# existing menu-token handling falls through:
+capability = self._capabilities.get(action.callback_token)
+if capability is not None and capability.action_kind in ("diff", "toollog"):
+    del self._capabilities[action.callback_token]
+    if time.monotonic() - capability.created_at > _CAPABILITY_TTL_SECONDS:
+        text = "This expired. Ask me again and I'll fetch it fresh."
+    else:
+        label = "Full diff" if capability.action_kind == "diff" else "Tool log"
+        redacted = _redact_text(capability.action_target)
+        text = f"{label}\n\n
{formatting.escape(redacted)}
"
+    for chunk in _split_text(text):
+        if self._adapter is not None:
+            await self._adapter.send(
+                RemoteOutboundMessage(
+                    connection_id=capability.connection_id,
+                    destination_id=capability.destination_id,
+                    text=chunk,
+                    priority=RemoteOutboundPriority.HIGH,
+                )
+            )
+    return True
+```
+
+Import `formatting` and the existing `_split_text` helper (move it to a small shared location if it is not already importable from `actions.py` — `outbound.py`'s `__all__` already exports it, so `from app.remote.outbound import _split_text` is sufficient).
+
+- [ ] **Step 4: Wire `RemoteProjection.set_actions` and call it from `runtime.py`**
+
+```python
+# app/remote/outbound.py — mirrors set_adapter/set_bridge
+def set_actions(self, actions: "RemoteActionService | None") -> None:
+    self._actions = actions
+```
+
+```python
+# app/remote/actions.py — new setter on RemoteActionService, mirroring the
+# existing pattern; store as self._projection: "RemoteProjection | None" = None
+def set_projection(self, projection: "RemoteProjection | None") -> None:
+    self._projection = projection
+```
+
+```python
+# app/remote/runtime.py — inside _start_locked, after self._actions is built
+projection.set_actions(self._actions)
+self._actions.set_projection(projection)
+```
+
+```python
+# app/remote/runtime.py — inside _stop_locked, alongside the other projection resets
+if self._projection is not None:
+    self._projection.set_actions(None)
+if self._actions is not None:
+    self._actions.set_projection(None)
+```
+
+```python
+# app/remote/runtime.py — inside _handle_action's CALLBACK branch, thread a
+# session through to the now-required db parameter
+if self._actions is not None and action.callback_token is not None:
+    from app.core.db import async_session_factory
+
+    async with async_session_factory() as callback_session:
+        handled = await self._actions.handle_action_callback(action, callback_session)
+```
+
+- [ ] **Step 5: Run and confirm pass**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/test_actions.py tests/remote/test_outbound.py tests/remote/test_runtime.py
+uv run ruff check app/remote/actions.py app/remote/outbound.py app/remote/runtime.py tests/remote/test_actions.py
+uv run ty check app/remote/
+```
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add app/remote/actions.py app/remote/outbound.py app/remote/runtime.py tests/remote/test_actions.py
+git commit -m "feat(remote): on-demand Full diff / Tool log drill-down buttons"
+```
+
+---
+
+### Task 7: `/settings` command
+
+**ACs:** AC-41, AC-32 (revised), AC-44
+
+**Files:**
+
+- Modify: `app/remote/actions.py`
+- Modify: `tests/remote/test_actions.py`
+
+**Interfaces:**
+
+- Adds `"settings"` to `_SLASH_COMMANDS`.
+- Produces `RemoteActionService._cmd_settings(db, action) -> RemoteActionResult`.
+- Adds `handle_action_callback` branches for `action_kind in ("redaction", "notify_scope")`.
+- Consumes `app.core.runtime_settings.RemoteSettings/load_runtime_settings/save_runtime_settings` (the same file-backed config the `PUT /api/settings/remote` route already reads/writes — no database round trip) and `RemotePairing.notify_scope`.
+
+- [ ] **Step 1: Write failing command and toggle tests**
+
+```python
+# tests/remote/test_actions.py (add)
+def test_settings_is_a_known_slash_command():
+    assert "settings" in _SLASH_COMMANDS
+
+
+@pytest.mark.asyncio
+async def test_cmd_settings_shows_model_and_permission_as_text_only(
+    service, db_session, paired_session_with_model
+):
+    action = _make_action(text="/settings")
+    result = await service.dispatch_command(db_session, action)
+    assert "claude-sonnet-5" in result.text
+    assert "ask each time" in result.text.lower() or "auto" in result.text.lower()
+
+
+@pytest.mark.asyncio
+async def test_settings_redaction_callback_updates_policy(
+    service, db_session, adapter, monkeypatch
+):
+    saved = {}
+
+    def fake_save(cfg):
+        saved["policy"] = cfg.remote.outbound_data_policy
+
+    monkeypatch.setattr("app.remote.actions.save_runtime_settings", fake_save)
+    token = service.register_capability(
+        connection_id=uuid4(), principal_id="", destination_id="chat-1",
+        session_id="sess-1", action_kind="redaction", action_target="strict",
+    )
+    action = _make_action(callback_token=token)
+    handled = await service.handle_action_callback(action, db_session)
+    assert handled is True
+    assert saved["policy"] == "strict"
+
+
+@pytest.mark.asyncio
+async def test_settings_never_offers_a_model_or_permission_button(
+    service, db_session, paired_session_with_model
+):
+    action = _make_action(text="/settings")
+    result = await service.dispatch_command(db_session, action)
+    # dispatch_command sends via the adapter for settings (card + buttons),
+    # not just plain text, so assert on what was actually sent.
+    sent_buttons = [b.text.lower() for msg in adapter.sent for b in msg.buttons]
+    assert not any("model" in t or "permission" in t for t in sent_buttons)
+```
+
+- [ ] **Step 2: Run and confirm failure**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/test_actions.py -k settings
+```
+
+- [ ] **Step 3: Add the command and its dispatch**
+
+```python
+# app/remote/actions.py
+_SLASH_COMMANDS: frozenset[str] = frozenset(
+    {"start", "help", "status", "new", "stop", "unpair", "actions", "settings"}
+)
+```
+
+```python
+async def _cmd_settings(
+    self, db: AsyncSession, action: RemoteInboundAction
+) -> RemoteActionResult:
+    pairing = await self._pairing_service.get_pairing(db, action.connection_id)
+    if pairing is None:
+        return RemoteActionResult(status="refused", text="")
+    session_row = None
+    if pairing.active_session_id is not None:
+        session_row = await db.get(ChatSession, pairing.active_session_id)
+    model = (session_row.model if session_row and session_row.model else "default")
+    permission_mode = session_row.permission_mode if session_row else "auto"
+    cfg = load_runtime_settings()
+
+    redaction_targets = [n for n in ("strict", "standard", "off") if n != cfg.remote.outbound_data_policy]
+    redaction_tokens = {
+        name: self.register_capability(
+            connection_id=action.connection_id, principal_id=action.principal.principal_id,
+            destination_id=action.principal.destination_id, session_id=str(pairing.active_session_id or ""),
+            action_kind="redaction", action_target=name,
+        )
+        for name in redaction_targets
+    }
+    scope_targets = [s for s in ("all", "remote_only") if s != pairing.notify_scope]
+    notify_scope_tokens = {
+        name: self.register_capability(
+            connection_id=action.connection_id, principal_id=action.principal.principal_id,
+            destination_id=action.principal.destination_id, session_id=str(pairing.active_session_id or ""),
+            action_kind="notify_scope", action_target=name,
+        )
+        for name in scope_targets
+    }
+
+    text, buttons = render_settings_card(
+        connection_label=pairing.label,
+        model=model,
+        permission_mode=permission_mode,
+        redaction_policy=cfg.remote.outbound_data_policy,
+        notify_scope=pairing.notify_scope,
+        redaction_tokens=redaction_tokens,
+        notify_scope_tokens=notify_scope_tokens,
+    )
+    if self._adapter is not None:
+        await self._adapter.send(
+            RemoteOutboundMessage(
+                connection_id=action.connection_id,
+                destination_id=action.principal.destination_id,
+                text=text,
+                buttons=buttons,
+                priority=RemoteOutboundPriority.INFORMATIONAL,
+            )
+        )
+    return RemoteActionResult(status="sent", text=text)
+```
+
+Settings are file-backed config, not database rows: `app/api/routes/settings.py`'s own `/remote` route handlers read/write them via `cfg = load_runtime_settings(); cfg.remote.outbound_data_policy` / `cfg.remote = RemoteSettings(outbound_data_policy=..., outbound_pii_policy=cfg.remote.outbound_pii_policy); save_runtime_settings(cfg)` — both synchronous, both imported `from app.core.runtime_settings import RemoteSettings, load_runtime_settings, save_runtime_settings`. `_cmd_settings` above must use `load_runtime_settings()` exactly this way (already reflected in the code block). `PairingService` has no existing "fetch this connection's single pairing" accessor — add one:
+
+```python
+# app/remote/pairing.py — new method on PairingService
+async def get_pairing(
+    self, db: AsyncSession, connection_id: UUID
+) -> RemotePairing | None:
+    return (
+        await db.exec(
+            select(RemotePairing).where(RemotePairing.connection_id == connection_id)
+        )
+    ).first()
+```
+
+Add a matching unit test in `tests/remote/test_pairing.py` (create-then-fetch, and `None` for an unpaired connection) as part of this task's Step 3, following the existing test file's fixture conventions.
+
+- [ ] **Step 4: Add `redaction`/`notify_scope` callback branches**
+
+```python
+# app/remote/actions.py — inside handle_action_callback, alongside the
+# diff/toollog branch added in Task 6
+if capability is not None and capability.action_kind == "redaction":
+    del self._capabilities[action.callback_token]
+    cfg = load_runtime_settings()
+    cfg.remote = RemoteSettings(
+        outbound_data_policy=capability.action_target,
+        outbound_pii_policy=cfg.remote.outbound_pii_policy,
+    )
+    save_runtime_settings(cfg)
+    return True
+if capability is not None and capability.action_kind == "notify_scope":
+    del self._capabilities[action.callback_token]
+    pairing = await self._pairing_service.get_pairing(db, capability.connection_id)
+    if pairing is not None:
+        pairing.notify_scope = capability.action_target
+        db.add(pairing)
+        await db.commit()
+        if self._projection is not None:
+            self._projection.set_active_pairing(
+                connection_id=str(capability.connection_id),
+                destination_id=pairing.destination_id,
+                notify_scope=pairing.notify_scope,
+                principal_id=pairing.principal_id,
+            )
+    return True
+```
+
+`db` is already available here as the parameter Task 6 added to `handle_action_callback`. `self._projection` is already available as the attribute Task 6's `set_projection` step added.
+
+- [ ] **Step 5: Run and confirm pass**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/test_actions.py tests/remote/test_runtime.py
+uv run ruff check app/remote/actions.py tests/remote/test_actions.py
+uv run ty check app/remote/actions.py
+```
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add app/remote/actions.py tests/remote/test_actions.py
+git commit -m "feat(remote): add /settings with redaction and notify-scope toggles"
+```
+
+---
+
+### Task 8: Guided project picker and prompt suggestions
+
+**ACs:** AC-40
+
+**Files:**
+
+- Modify: `app/remote/actions.py`
+- Modify: `tests/remote/test_actions.py`
+
+**Interfaces:**
+
+- Changes `_cmd_new` to send a project picker instead of clearing the pointer silently, when more than zero authorized Coding projects exist.
+- Adds `handle_action_callback` branches for `action_kind in ("project_pick", "prompt_pick")`.
+- Consumes `app.services.coding_project_service.list_visible_projects(db, *, kind="coding")` and `app.remote.inbound.RemoteInboundService.new_task`.
+
+- [ ] **Step 1: Write failing picker-flow tests**
+
+```python
+# tests/remote/test_actions.py (add)
+@pytest.mark.asyncio
+async def test_cmd_new_with_projects_shows_picker_not_bare_ack(
+    service, db_session, adapter, one_coding_project
+):
+    action = _make_action(text="/new")
+    await service.dispatch_command(db_session, action)
+    assert any("Which project" in m.text for m in adapter.sent)
+
+
+@pytest.mark.asyncio
+async def test_project_pick_then_shows_prompt_suggestions(
+    service, db_session, adapter, one_coding_project
+):
+    token = service.register_capability(
+        connection_id=uuid4(), principal_id="p", destination_id="chat-1",
+        session_id="", action_kind="project_pick", action_target=str(one_coding_project.id),
+    )
+    action = _make_action(callback_token=token)
+    handled = await service.handle_action_callback(action, db_session)
+    assert handled is True
+    assert any("Fix failing tests" in m.text or "Review my changes" in m.text for m in adapter.sent)
+
+
+@pytest.mark.asyncio
+async def test_free_form_text_still_works_after_picker_shown(
+    service, db_session, inbound_service, one_coding_project
+):
+    action = _make_action(text="Refactor the login flow")
+    result = await inbound_service.handle_text(db_session, action)
+    assert result.status in ("accepted", "queued", "pending")
+```
+
+- [ ] **Step 2: Run and confirm failure**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/test_actions.py -k "picker or project_pick"
+```
+
+- [ ] **Step 3: Extend `_cmd_new` and add the picker/suggestion callbacks**
+
+```python
+# app/remote/actions.py — replace the body of _cmd_new with:
+async def _cmd_new(
+    self, db: AsyncSession, action: RemoteInboundAction
+) -> RemoteActionResult:
+    from app.remote.inbound import RemoteInboundService
+
+    inbound_service = RemoteInboundService(pairing_service=self._pairing_service)
+    await inbound_service.new_task(db, action)
+
+    projects = await list_visible_projects(db, kind="coding")
+    if not projects:
+        return RemoteActionResult(status="cleared", text="Started a new task. What would you like to work on?")
+
+    tokens = [
+        (
+            self.register_capability(
+                connection_id=action.connection_id, principal_id=action.principal.principal_id,
+                destination_id=action.principal.destination_id, session_id="",
+                action_kind="project_pick", action_target=str(project.id),
+            ),
+            project.name,
+        )
+        for project in projects[:5]
+    ]
+    text, buttons = render_project_picker(projects=tokens)
+    if self._adapter is not None:
+        await self._adapter.send(
+            RemoteOutboundMessage(
+                connection_id=action.connection_id, destination_id=action.principal.destination_id,
+                text=text, buttons=buttons, priority=RemoteOutboundPriority.INFORMATIONAL,
+            )
+        )
+    return RemoteActionResult(status="cleared", text=text)
+```
+
+```python
+# app/remote/actions.py — new callback branches inside handle_action_callback
+_CURATED_PROMPTS = (
+    ("Fix failing tests", "Fix failing tests"),
+    ("Review my changes", "Review my changes"),
+    ("Add a feature…", "I'd like to add a feature. Ask me what before starting."),
+)
+
+if capability is not None and capability.action_kind == "project_pick":
+    del self._capabilities[action.callback_token]
+    project = await get_project(db, UUID(capability.action_target))
+    if project is None:
+        return True
+    last_session = await self._find_last_session_for_project(db, project.id)
+    suggestion_tokens = [
+        (
+            self.register_capability(
+                connection_id=capability.connection_id, principal_id=capability.principal_id,
+                destination_id=capability.destination_id, session_id="",
+                action_kind="prompt_pick", action_target=f"{project.id}:{prompt_text}",
+            ),
+            label,
+        )
+        for label, prompt_text in _CURATED_PROMPTS
+    ]
+    continue_token = None
+    if last_session is not None:
+        continue_token = self.register_capability(
+            connection_id=capability.connection_id, principal_id=capability.principal_id,
+            destination_id=capability.destination_id, session_id="",
+            action_kind="prompt_pick", action_target=f"{project.id}:__continue__:{last_session.id}",
+        )
+    text, buttons = render_prompt_suggestions(
+        project_name=project.name,
+        context_line=f"Last session {self._relative_time(last_session)}" if last_session else "No prior sessions",
+        suggestions=suggestion_tokens,
+        continue_token=continue_token,
+    )
+    if self._adapter is not None:
+        await self._adapter.send(
+            RemoteOutboundMessage(
+                connection_id=capability.connection_id, destination_id=capability.destination_id,
+                text=text, buttons=buttons, priority=RemoteOutboundPriority.INFORMATIONAL,
+            )
+        )
+    return True
+
+if capability is not None and capability.action_kind == "prompt_pick":
+    del self._capabilities[action.callback_token]
+    from app.remote.inbound import RemoteInboundService
+
+    project_id_str, _, remainder = capability.action_target.partition(":")
+    inbound_service = RemoteInboundService(pairing_service=self._pairing_service)
+    if remainder.startswith("__continue__:"):
+        session_id = UUID(remainder.removeprefix("__continue__:"))
+        await inbound_service.continue_task(db, action, session_id)
+    else:
+        await self._start_coding_task(db, action, UUID(project_id_str), remainder)
+    return True
+```
+
+`_find_last_session_for_project` and `_relative_time` are small private helpers: the first queries the most recent top-level `ChatSession` with `project_id == project.id`, ordered by `created_at` descending; the second formats a `datetime` as `"2h ago"`. The existing `_exec_coding_task` (used by the `/actions` menu's "Coding projects" entry) only creates an empty session and tells the user to "Send your first message" — it does not accept or submit a prompt, so it cannot be reused as-is here. `_start_coding_task` is new, and unlike `_exec_coding_task` it also registers the session with the projection so the resulting turn gets the same live status card and typing indicator a free-typed message would:
+
+```python
+# app/remote/actions.py — new private helper on RemoteActionService
+async def _start_coding_task(
+    self,
+    db: AsyncSession,
+    action: RemoteInboundAction,
+    project_id: UUID,
+    prompt_text: str,
+) -> None:
+    from app.services.chat_service import create_chat_session
+    from app.services.coding_project_service import get_project
+    from app.remote.inbound import RemoteInboundService
+
+    project = await get_project(db, project_id)
+    if project is None:
+        await self._reply_text(action.principal.destination_id, "Project not found.")
+        return
+
+    chat = await create_chat_session(db)
+    chat.mode = "coding"
+    chat.project_id = project.id
+    chat.tags = ["remote_origin", f"remote_connection:{action.connection_id}"]
+    db.add(chat)
+    await db.commit()
+
+    pairing = await self._pairing_service.authorize(
+        db, connection_id=action.connection_id, principal_id=action.principal.principal_id,
+    )
+    if pairing is not None:
+        pairing.active_session_id = chat.id
+        db.add(pairing)
+        await db.commit()
+
+    if self._projection is not None:
+        self._projection.register_session(
+            str(chat.id),
+            connection_id=str(action.connection_id),
+            destination_id=action.principal.destination_id,
+            tags=frozenset({"remote_origin", f"remote_connection:{action.connection_id}"}),
+        )
+
+    prompt_action = replace(action, text=prompt_text)
+    inbound_service = RemoteInboundService(pairing_service=self._pairing_service)
+    result = await inbound_service.handle_text(db, prompt_action)
+
+    if self._projection is not None:
+        self._projection.begin_phone_turn(
+            str(chat.id),
+            connection_id=str(action.connection_id),
+            destination_id=action.principal.destination_id,
+            principal_id=action.principal.principal_id,
+            title=project.name,
+            status=result.status,
+        )
+```
+
+`replace` is `dataclasses.replace` — `RemoteInboundAction` is frozen, so build a copy with `text` overridden rather than mutating it. Import it at the top of `actions.py` alongside the module's other `dataclasses` imports.
+
+- [ ] **Step 4: Run and confirm pass**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/test_actions.py
+uv run ruff check app/remote/actions.py tests/remote/test_actions.py
+uv run ty check app/remote/actions.py
+```
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add app/remote/actions.py tests/remote/test_actions.py
+git commit -m "feat(remote): guided project picker and prompt suggestions for /new"
+```
+
+---
+
+### Task 9: Gate cards adopt the shared renderer
+
+**ACs:** AC-24 (revised, applied to gates)
+
+**Files:**
+
+- Modify: `app/remote/gates.py`
+- Modify: `tests/remote/test_gates.py`
+
+**Interfaces:**
+
+- `RemoteGateBridge.on_gate` builds its text/buttons via `formatting.render_gate_card` instead of inline f-strings.
+
+- [ ] **Step 1: Write a failing escaping test for gate cards**
+
+```python
+# tests/remote/test_gates.py (add)
+def test_permission_card_escapes_tool_name(bridge):
+    bridge.on_gate(
+        "sess-1", "permission_asked", {"tool": ""},
+        connection_id=uuid4(), destination_id="chat-1",
+    )
+    sent_text = bridge._adapter.sent[0].text  # type: ignore[attr-defined]
+    assert "", "tests/conftest.py"],
+        tool_call_count=4,
+        diff_token="diff-tok",
+        toollog_token="log-tok",
+    )
+    assert "" not in text
+    assert "<script>" in text
+    assert "1m 12s" in text
+    assert "4 tool calls" in text
+    assert buttons == (
+        RemoteButton(text="\U0001f4c4 Full diff", token="diff-tok"),
+        RemoteButton(text="\U0001f9fe Tool log", token="log-tok"),
+    )
+
+
+def test_render_done_card_omits_buttons_when_no_tokens():
+    _, buttons = formatting.render_done_card(
+        title="No-op turn",
+        elapsed_seconds=1.0,
+        summary_lines=[],
+        tool_call_count=0,
+        diff_token=None,
+        toollog_token=None,
+    )
+    assert buttons == ()
+
+
+def test_render_error_card_escapes_message():
+    text, buttons = formatting.render_error_card(
+        title="Add rate limiter",
+        message="ModuleNotFoundError: ",
+        toollog_token="log-tok",
+    )
+    assert "<redis>" in text
+    assert len(buttons) == 1
+
+
+def test_render_settings_card_never_emits_model_or_permission_buttons():
+    text, buttons = formatting.render_settings_card(
+        connection_label="evoflux-api",
+        model="claude-sonnet-5",
+        permission_mode="ask each time",
+        redaction_policy="standard",
+        notify_scope="all",
+        redaction_tokens={"strict": "r1", "off": "r2"},
+        notify_scope_tokens={"all": "n1", "remote_only": "n2"},
+    )
+    button_texts = [b.text for b in buttons]
+    assert not any("model" in t.lower() for t in button_texts)
+    assert not any("permission" in t.lower() for t in button_texts)
+    assert any("strict" in t.lower() for t in button_texts)

From c2ceacc63fe34e901e35bc31bb960e94b6590580 Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Mon, 14 Sep 2026 20:50:23 +0700
Subject: [PATCH 13/71] fix(remote): escape dynamic button labels in 3
 formatting builders

- render_gate_card: escape label from actions
- render_settings_card: escape name in Redaction/Notify buttons
- render_prompt_suggestions: escape label from suggestions
- Add 3 test cases verifying escaping of HTML chars in dynamic labels
---
 app/remote/formatting.py        |  8 +++---
 tests/remote/test_formatting.py | 43 +++++++++++++++++++++++++++++++++
 2 files changed, 47 insertions(+), 4 deletions(-)

diff --git a/app/remote/formatting.py b/app/remote/formatting.py
index 5281907b..3a1c1cd5 100644
--- a/app/remote/formatting.py
+++ b/app/remote/formatting.py
@@ -77,7 +77,7 @@ def render_gate_card(
     *, title: str, body: str, actions: Sequence[tuple[str, str]]
 ) -> tuple[str, tuple[RemoteButton, ...]]:
     text = f"\U0001f510 {escape(title)}\n{escape(body)}"
-    buttons = tuple(RemoteButton(text=label, token=token) for token, label in actions)
+    buttons = tuple(RemoteButton(text=escape(label), token=token) for token, label in actions)
     return text, buttons
 
 
@@ -100,11 +100,11 @@ def render_settings_card(
         f"Outbound redaction\n{escape(redaction_policy)}"
     )
     buttons = [
-        RemoteButton(text=f"Redaction: {name}", token=token)
+        RemoteButton(text=f"Redaction: {escape(name)}", token=token)
         for name, token in redaction_tokens.items()
     ]
     buttons += [
-        RemoteButton(text=f"Notify: {name}", token=token)
+        RemoteButton(text=f"Notify: {escape(name)}", token=token)
         for name, token in notify_scope_tokens.items()
     ]
     return text, tuple(buttons)
@@ -136,5 +136,5 @@ def render_prompt_suggestions(
     buttons: list[RemoteButton] = []
     if continue_token:
         buttons.append(RemoteButton(text="▶ Continue last session", token=continue_token))
-    buttons += [RemoteButton(text=label, token=token) for token, label in suggestions]
+    buttons += [RemoteButton(text=escape(label), token=token) for token, label in suggestions]
     return text, tuple(buttons)
diff --git a/tests/remote/test_formatting.py b/tests/remote/test_formatting.py
index 9591ef3e..96001b2a 100644
--- a/tests/remote/test_formatting.py
+++ b/tests/remote/test_formatting.py
@@ -72,3 +72,46 @@ def test_render_settings_card_never_emits_model_or_permission_buttons():
     assert not any("model" in t.lower() for t in button_texts)
     assert not any("permission" in t.lower() for t in button_texts)
     assert any("strict" in t.lower() for t in button_texts)
+
+
+def test_render_gate_card_escapes_action_labels():
+    text, buttons = formatting.render_gate_card(
+        title="Approve deploy?",
+        body="Ready for production",
+        actions=[("yes-tok", "Accept "), ("no-tok", "Reject & wait")],
+    )
+    assert len(buttons) == 2
+    assert buttons[0].text == "Accept <risks>"
+    assert buttons[1].text == "Reject & wait"
+    assert "" not in buttons[0].text
+    assert "& wait" not in buttons[1].text
+
+
+def test_render_settings_card_escapes_toggle_names():
+    text, buttons = formatting.render_settings_card(
+        connection_label="evoflux-api",
+        model="claude-sonnet-5",
+        permission_mode="ask each time",
+        redaction_policy="standard",
+        notify_scope="all",
+        redaction_tokens={"": "r1", "off": "r2"},
+        notify_scope_tokens={"all": "n1", "remote & local": "n2"},
+    )
+    button_texts = [b.text for b in buttons]
+    assert any("<strict>" in t for t in button_texts)
+    assert any("remote & local" in t for t in button_texts)
+
+
+def test_render_prompt_suggestions_escapes_labels():
+    text, buttons = formatting.render_prompt_suggestions(
+        project_name="",
+        context_line="line & context",
+        suggestions=[("sug-tok-1", "Suggest "), ("sug-tok-2", "Other & more")],
+        continue_token="cont-tok",
+    )
+    assert len(buttons) == 3  # continue + 2 suggestions
+    # First button is continue
+    assert buttons[0].text == "▶ Continue last session"
+    # Suggestion buttons should have escaped labels
+    assert buttons[1].text == "Suggest <tag>"
+    assert buttons[2].text == "Other & more"

From 97a96f54b1c4bb121e2f214b34365a7dbed4b82d Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Mon, 14 Sep 2026 20:56:28 +0700
Subject: [PATCH 14/71] feat(remote): send HTML parse mode and native typing
 indicator

TelegramClient.send_text/edit_text now always send parse_mode="HTML"
(AC-24, revised) since callers pass text already rendered through
app/remote/formatting.py's HTML-escaping. Adds
TelegramClient.send_chat_action and a matching indicate_typing on the
RemoteAdapter Protocol and TelegramAdapter, a best-effort "still
typing" liveliness primitive for AC-38 that later turn-lifecycle code
will call.
---
 app/remote/contracts.py               | 12 ++++++---
 app/remote/telegram/adapter.py        | 14 ++++++++++
 app/remote/telegram/client.py         | 23 ++++++++++++++---
 tests/remote/telegram/test_adapter.py | 26 +++++++++++++++++++
 tests/remote/telegram/test_client.py  | 37 ++++++++++++++++++++++++---
 5 files changed, 102 insertions(+), 10 deletions(-)

diff --git a/app/remote/contracts.py b/app/remote/contracts.py
index e703f900..f86cac81 100644
--- a/app/remote/contracts.py
+++ b/app/remote/contracts.py
@@ -154,10 +154,12 @@ class RemoteButton:
 class RemoteOutboundMessage:
     """One outbound message bound for a paired destination.
 
-    Plain text only — no parse mode, so model-authored text cannot
-    manufacture links, mentions, or formatting (AC-24). ``correlation_id``
-    lets the owning turn's lifecycle message be found again for editing
-    instead of appending progress (AC-22).
+    ``text`` is sent with Telegram HTML parse mode (AC-24, revised): callers
+    are expected to have rendered it through ``app/remote/formatting.py``,
+    which HTML-escapes every non-static field before interpolation, so
+    model/agent content can never manufacture links, mentions, or
+    formatting. ``correlation_id`` lets the owning turn's lifecycle message
+    be found again for editing instead of appending progress (AC-22).
     """
 
     connection_id: UUID
@@ -204,6 +206,8 @@ async def edit(self, message: RemoteOutboundMessage) -> None: ...
 
     async def answer_callback(self, callback_token: str) -> None: ...
 
+    async def indicate_typing(self, destination_id: str) -> None: ...
+
     def status(self) -> RemoteAdapterStatus: ...
 
 
diff --git a/app/remote/telegram/adapter.py b/app/remote/telegram/adapter.py
index dd8646aa..4b3c24f6 100644
--- a/app/remote/telegram/adapter.py
+++ b/app/remote/telegram/adapter.py
@@ -239,6 +239,20 @@ async def answer_callback(self, callback_token: str) -> None:
             raise
         self._record_delivery_success()
 
+    async def indicate_typing(self, destination_id: str) -> None:
+        """Best-effort liveliness signal (AC-38): a native "still typing"
+        indicator while a turn is unresolved. Never fails the caller — this
+        is decoration, not a delivery guarantee, so it must never surface an
+        error the way ``send``/``edit``/``answer_callback`` do."""
+        try:
+            await self._client.send_chat_action(chat_id=destination_id)
+        except (
+            TelegramApiError,
+            TelegramTransportError,
+            TelegramMalformedResponseError,
+        ):
+            pass
+
     def _record_delivery_failure(self, exc: TelegramApiError) -> None:
         if exc.error_code == 403:
             self._phone_reachable = False
diff --git a/app/remote/telegram/client.py b/app/remote/telegram/client.py
index adc85fda..a74d9ce7 100644
--- a/app/remote/telegram/client.py
+++ b/app/remote/telegram/client.py
@@ -252,10 +252,17 @@ async def send_text(
         text: str,
         buttons: Sequence[RemoteButton] = (),
     ) -> TelegramMessage:
-        # No parse_mode, ever (AC-24): model/agent text must never be
-        # interpreted as Telegram markup.
+        # Always HTML parse mode (AC-24, revised): every caller is required
+        # to pass text already rendered by app/remote/formatting.py, which
+        # HTML-escapes every non-static field before interpolation — so
+        # Telegram markup can only ever come from that trusted renderer,
+        # never from raw model/agent text.
         markup = _build_reply_markup(buttons)
-        payload: dict[str, Any] = {"chat_id": chat_id, "text": text}
+        payload: dict[str, Any] = {
+            "chat_id": chat_id,
+            "text": text,
+            "parse_mode": "HTML",
+        }
         if markup is not None:
             payload["reply_markup"] = markup
         return await self._call("sendMessage", payload, result_model=TelegramMessage)
@@ -273,6 +280,7 @@ async def edit_text(
             "chat_id": chat_id,
             "message_id": message_id,
             "text": text,
+            "parse_mode": "HTML",
         }
         if markup is not None:
             payload["reply_markup"] = markup
@@ -280,6 +288,15 @@ async def edit_text(
             "editMessageText", payload, result_model=TelegramMessage
         )
 
+    async def send_chat_action(
+        self, *, chat_id: str | int, action: str = "typing"
+    ) -> None:
+        await self._call(
+            "sendChatAction",
+            {"chat_id": chat_id, "action": action},
+            result_model=bool,
+        )
+
     async def answer_callback(
         self, callback_query_id: str, *, text: str | None = None
     ) -> None:
diff --git a/tests/remote/telegram/test_adapter.py b/tests/remote/telegram/test_adapter.py
index 9126f9d2..9949b299 100644
--- a/tests/remote/telegram/test_adapter.py
+++ b/tests/remote/telegram/test_adapter.py
@@ -658,6 +658,32 @@ async def test_successful_answer_callback_marks_phone_reachable(self):
         assert status.state == RemoteConnectionState.POLLING
 
 
+# ---------------------------------------------------------------------------
+# indicate_typing: native "still typing" liveliness signal (AC-38)
+# ---------------------------------------------------------------------------
+
+
+class TestIndicateTyping:
+    @pytest.mark.asyncio
+    async def test_indicate_typing_calls_send_chat_action(self):
+        transport = ScriptedTransport()
+        adapter = _make_adapter(transport)
+        await adapter.indicate_typing("chat-1")
+
+        _, payload = next(c for c in transport.calls if c[0] == "sendChatAction")
+        assert payload == {"chat_id": "chat-1", "action": "typing"}
+
+    @pytest.mark.asyncio
+    async def test_indicate_typing_failure_is_a_safe_noop(self):
+        transport = ScriptedTransport()
+        transport.queue(
+            "sendChatAction", _err(403, 403, "Forbidden: bot was blocked by the user")
+        )
+        adapter = _make_adapter(transport)
+
+        await adapter.indicate_typing("chat-1")  # must not raise
+
+
 # ---------------------------------------------------------------------------
 # Prompt shutdown (AC-13)
 # ---------------------------------------------------------------------------
diff --git a/tests/remote/telegram/test_client.py b/tests/remote/telegram/test_client.py
index fd09f956..efdaaa8d 100644
--- a/tests/remote/telegram/test_client.py
+++ b/tests/remote/telegram/test_client.py
@@ -179,7 +179,7 @@ def handler(request: httpx.Request) -> httpx.Response:
 
 class TestSendEditAnswer:
     @pytest.mark.asyncio
-    async def test_send_text_never_includes_parse_mode(self):
+    async def test_send_text_sends_html_parse_mode(self):
         captured: dict[str, object] = {}
 
         def handler(request: httpx.Request) -> httpx.Response:
@@ -196,7 +196,7 @@ def handler(request: httpx.Request) -> httpx.Response:
 
         client = _client(handler)
         message = await client.send_text(chat_id=1, text="hello world")
-        assert "parse_mode" not in captured["payload"]
+        assert captured["payload"]["parse_mode"] == "HTML"
         assert captured["payload"]["text"] == "hello world"
         assert isinstance(message, TelegramMessage)
         assert message.message_id == 5
@@ -292,7 +292,7 @@ def handler(request: httpx.Request) -> httpx.Response:
         assert captured["payload"]["chat_id"] == 1
         assert captured["payload"]["message_id"] == 5
         assert captured["payload"]["text"] == "updated"
-        assert "parse_mode" not in captured["payload"]
+        assert captured["payload"]["parse_mode"] == "HTML"
         await client.aclose()
 
     @pytest.mark.asyncio
@@ -312,6 +312,37 @@ def handler(request: httpx.Request) -> httpx.Response:
         assert "text" not in captured["payload"]
         await client.aclose()
 
+    @pytest.mark.asyncio
+    async def test_send_chat_action_calls_send_chat_action_endpoint(self):
+        captured: dict[str, object] = {}
+
+        def handler(request: httpx.Request) -> httpx.Response:
+            import json
+
+            captured["payload"] = json.loads(request.content)
+            assert request.url.path.endswith("/sendChatAction")
+            return _ok(True)
+
+        client = _client(handler)
+        await client.send_chat_action(chat_id="1")
+        assert captured["payload"] == {"chat_id": "1", "action": "typing"}
+        await client.aclose()
+
+    @pytest.mark.asyncio
+    async def test_send_chat_action_accepts_a_custom_action(self):
+        captured: dict[str, object] = {}
+
+        def handler(request: httpx.Request) -> httpx.Response:
+            import json
+
+            captured["payload"] = json.loads(request.content)
+            return _ok(True)
+
+        client = _client(handler)
+        await client.send_chat_action(chat_id="1", action="upload_document")
+        assert captured["payload"]["action"] == "upload_document"
+        await client.aclose()
+
     @pytest.mark.asyncio
     async def test_set_commands_sends_command_description_pairs(self):
         captured: dict[str, object] = {}

From 67d51bdfdf31411b840b8537a5af68416c9b4811 Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Mon, 14 Sep 2026 21:00:29 +0700
Subject: [PATCH 15/71] fix(remote): cover indicate_typing's transport and
 malformed-response paths

Review flagged that indicate_typing's widened except clause (added
beyond the brief's TelegramApiError-only sketch) was untested for its
TelegramTransportError and TelegramMalformedResponseError branches.
Adds coverage for both, and adds debug-level logging on swallowed
failures (previously a bare pass) so the high-frequency liveliness
call stays diagnosable without warning-level spam.
---
 app/remote/telegram/adapter.py        |  9 ++++++++-
 tests/remote/telegram/test_adapter.py | 20 +++++++++++++++++++-
 2 files changed, 27 insertions(+), 2 deletions(-)

diff --git a/app/remote/telegram/adapter.py b/app/remote/telegram/adapter.py
index 4b3c24f6..23d36cce 100644
--- a/app/remote/telegram/adapter.py
+++ b/app/remote/telegram/adapter.py
@@ -251,7 +251,14 @@ async def indicate_typing(self, destination_id: str) -> None:
             TelegramTransportError,
             TelegramMalformedResponseError,
         ):
-            pass
+            # Debug, not warning: this fires repeatedly per turn, so
+            # warning-level logging here would be spam rather than a
+            # signal (contrast _register_commands, a one-shot startup
+            # call where a warning is appropriate).
+            logger.debug(
+                "telegram_indicate_typing_failed connection_id={}",
+                self._connection_id,
+            )
 
     def _record_delivery_failure(self, exc: TelegramApiError) -> None:
         if exc.error_code == 403:
diff --git a/tests/remote/telegram/test_adapter.py b/tests/remote/telegram/test_adapter.py
index 9949b299..e11dbcbc 100644
--- a/tests/remote/telegram/test_adapter.py
+++ b/tests/remote/telegram/test_adapter.py
@@ -674,7 +674,7 @@ async def test_indicate_typing_calls_send_chat_action(self):
         assert payload == {"chat_id": "chat-1", "action": "typing"}
 
     @pytest.mark.asyncio
-    async def test_indicate_typing_failure_is_a_safe_noop(self):
+    async def test_indicate_typing_api_error_is_a_safe_noop(self):
         transport = ScriptedTransport()
         transport.queue(
             "sendChatAction", _err(403, 403, "Forbidden: bot was blocked by the user")
@@ -683,6 +683,24 @@ async def test_indicate_typing_failure_is_a_safe_noop(self):
 
         await adapter.indicate_typing("chat-1")  # must not raise
 
+    @pytest.mark.asyncio
+    async def test_indicate_typing_transport_error_is_a_safe_noop(self):
+        transport = ScriptedTransport()
+        transport.queue("sendChatAction", httpx.ConnectError("boom"))
+        adapter = _make_adapter(transport)
+
+        await adapter.indicate_typing("chat-1")  # must not raise
+
+    @pytest.mark.asyncio
+    async def test_indicate_typing_malformed_response_is_a_safe_noop(self):
+        transport = ScriptedTransport()
+        transport.queue(
+            "sendChatAction", httpx.Response(200, content=b"not json at all")
+        )
+        adapter = _make_adapter(transport)
+
+        await adapter.indicate_typing("chat-1")  # must not raise
+
 
 # ---------------------------------------------------------------------------
 # Prompt shutdown (AC-13)

From 107e9592dfa15a03344667a9b7ad9de550d62025 Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Mon, 14 Sep 2026 21:06:38 +0700
Subject: [PATCH 16/71] feat(remote): add notify_scope preference and
 active-pairing cache

RemotePairing.notify_scope (default "all") lets a pairing record whether
it wants notifications from every session or only ones the phone itself
started (AC-42, schema half). RemoteProjection gains an in-memory
active-pairing cache (connection_id, destination_id, notify_scope,
principal_id) so future notification logic can look up the single v1
pairing without a database query per event; the runtime keeps it in sync
on startup restore, on a fresh pairing, and on stop.
---
 app/core/schema_version.py                    |   2 +-
 ...0000065_add_remote_pairing_notify_scope.py |  33 ++++++
 app/models/remote.py                          |   4 +
 app/remote/outbound.py                        |  44 +++++++
 app/remote/runtime.py                         |  33 ++++++
 tests/models/test_remote_models.py            |  72 ++++++++++++
 tests/remote/test_outbound.py                 |  35 ++++++
 tests/remote/test_runtime.py                  | 110 ++++++++++++++++++
 8 files changed, 332 insertions(+), 1 deletion(-)
 create mode 100644 app/migrations/versions/00000065_add_remote_pairing_notify_scope.py
 create mode 100644 tests/models/test_remote_models.py

diff --git a/app/core/schema_version.py b/app/core/schema_version.py
index b8a44dfc..11b23fc8 100644
--- a/app/core/schema_version.py
+++ b/app/core/schema_version.py
@@ -13,7 +13,7 @@
 # Keep this in sync with the single Alembic head. The migration tests and the
 # sidecar build validate the value, so a release cannot silently ship a stale
 # marker.
-SCHEMA_HEAD = "00000064"
+SCHEMA_HEAD = "00000065"
 
 
 @dataclass(frozen=True)
diff --git a/app/migrations/versions/00000065_add_remote_pairing_notify_scope.py b/app/migrations/versions/00000065_add_remote_pairing_notify_scope.py
new file mode 100644
index 00000000..d7f85703
--- /dev/null
+++ b/app/migrations/versions/00000065_add_remote_pairing_notify_scope.py
@@ -0,0 +1,33 @@
+"""Add remote_pairings.notify_scope
+
+Revision ID: 00000065
+Revises: 00000064
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "00000065"
+down_revision: str | Sequence[str] | None = "00000064"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "remote_pairings",
+        sa.Column(
+            "notify_scope",
+            sa.String(20),
+            nullable=False,
+            server_default="all",
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("remote_pairings", "notify_scope")
diff --git a/app/models/remote.py b/app/models/remote.py
index ee299b2c..dae9b849 100644
--- a/app/models/remote.py
+++ b/app/models/remote.py
@@ -70,6 +70,10 @@ class RemotePairing(SQLModel, table=True):
         default="",
         sa_column=Column(sa.String(120), nullable=False, server_default=""),
     )
+    notify_scope: str = Field(
+        default="all",
+        sa_column=Column(sa.String(20), nullable=False, server_default="all"),
+    )
     active_session_id: UUID | None = Field(
         default=None,
         sa_column=Column(
diff --git a/app/remote/outbound.py b/app/remote/outbound.py
index 1895e2df..49569d5a 100644
--- a/app/remote/outbound.py
+++ b/app/remote/outbound.py
@@ -85,6 +85,20 @@ class RemoteProjection:
     _session_connection_ids: dict[str, str] = field(default_factory=dict, repr=False)
     _session_destination_ids: dict[str, str] = field(default_factory=dict, repr=False)
     _pending: list[RemoteOutboundMessage] = field(default_factory=list, repr=False)
+    #: Caches the single v1 pairing's routing info so ``observe`` can reach
+    #: sessions it was never explicitly ``register_session``-ed for (e.g.
+    #: work started from the desktop, not the phone) — this app supports
+    #: exactly one Telegram pairing per installation, so there is never more
+    #: than one tuple to cache. ``principal_id`` travels alongside
+    #: ``connection_id``/``destination_id`` because a future task mints
+    #: capability tokens for these sessions and needs a real, non-empty
+    #: owner id: since v1 has exactly one pairing per connection, that
+    #: pairing's own principal is the only valid actor for the whole
+    #: connection regardless of which surface (phone or desktop) started the
+    #: work being notified about.
+    _active_pairing: tuple[str, str, str, str] | None = field(
+        default=None, repr=False
+    )
 
     def set_adapter(self, adapter: RemoteAdapter | None) -> None:
         """Bind or unbind the live adapter. Called by the runtime on start/stop."""
@@ -94,6 +108,36 @@ def set_bridge(self, bridge: "RemoteGateBridge | None") -> None:
         """Bind or unbind the gate bridge. Called by the runtime on start/stop."""
         self._bridge = bridge
 
+    def set_active_pairing(
+        self,
+        *,
+        connection_id: str,
+        destination_id: str,
+        notify_scope: str,
+        principal_id: str,
+    ) -> None:
+        """Cache the single v1 pairing's routing info.
+
+        Called by the runtime whenever the pairing changes: a pairing is
+        created, restored from the database on startup, or the runtime
+        stops (via :meth:`clear_active_pairing`).
+        """
+        self._active_pairing = (
+            connection_id,
+            destination_id,
+            notify_scope,
+            principal_id,
+        )
+
+    def clear_active_pairing(self) -> None:
+        """Drop the cached pairing. Called by the runtime on stop."""
+        self._active_pairing = None
+
+    def active_pairing(self) -> tuple[str, str, str, str] | None:
+        """Return the cached ``(connection_id, destination_id, notify_scope,
+        principal_id)`` tuple, or ``None`` if no pairing is active."""
+        return self._active_pairing
+
     def register_session(
         self,
         session_id: str,
diff --git a/app/remote/runtime.py b/app/remote/runtime.py
index ccfd8150..e3dcdc1e 100644
--- a/app/remote/runtime.py
+++ b/app/remote/runtime.py
@@ -275,6 +275,31 @@ async def _start_locked(self) -> None:
         projection.set_adapter(adapter)
         self._projection = projection
 
+        # Restore the active-pairing cache so notifications for sessions
+        # started before this process restarted (or started on the desktop,
+        # never explicitly register_session-ed) can still be routed. v1
+        # permits at most one pairing per connection (AC-3), so `.first()`
+        # is always the right — and only — row to cache.
+        from sqlmodel import select
+
+        from app.models.remote import RemotePairing
+
+        async with read_session_factory() as pairing_session:
+            pairing = (
+                await pairing_session.exec(
+                    select(RemotePairing).where(
+                        RemotePairing.connection_id == connection.id
+                    )
+                )
+            ).first()
+        if pairing is not None:
+            projection.set_active_pairing(
+                connection_id=str(pairing.connection_id),
+                destination_id=pairing.destination_id,
+                notify_scope=pairing.notify_scope,
+                principal_id=pairing.principal_id,
+            )
+
         # Create the gate bridge for callback resolution.
         from app.remote.gates import RemoteGateBridge
 
@@ -312,6 +337,7 @@ async def _stop_locked(self) -> None:
         if self._projection is not None:
             self._projection.set_adapter(None)
             self._projection.set_bridge(None)
+            self._projection.clear_active_pairing()
             self._projection = None
         self._bridge = None
         self._actions = None
@@ -389,6 +415,13 @@ async def _handle_pairing(self, action: RemoteInboundAction) -> None:
                 action.connection_id,
                 action.principal.principal_id,
             )
+            if self._projection is not None:
+                self._projection.set_active_pairing(
+                    connection_id=str(action.connection_id),
+                    destination_id=result.destination_id,
+                    notify_scope=result.notify_scope,
+                    principal_id=result.principal_id,
+                )
             # A silently-persisted pairing is indistinguishable from a
             # failed one from the phone's side — confirm it (spec: "sends
             # Connected to EvoFlux on "). Never sent on
diff --git a/tests/models/test_remote_models.py b/tests/models/test_remote_models.py
new file mode 100644
index 00000000..8be70aec
--- /dev/null
+++ b/tests/models/test_remote_models.py
@@ -0,0 +1,72 @@
+"""Tests for app/models/remote.py — RemotePairing.notify_scope column default.
+
+Follows the ``session``/``connection`` fixture convention already used by
+``tests/remote/test_pairing.py`` and ``tests/remote/test_runtime.py`` (there
+is no shared ``db_session``/``remote_connection`` fixture in this codebase to
+reuse instead).
+"""
+
+from __future__ import annotations
+
+import pytest
+import pytest_asyncio
+from sqlmodel import select
+
+import app.core.db as db_module
+from app.models.remote import RemoteConnection, RemotePairing
+
+
+@pytest_asyncio.fixture
+async def session():
+    async with db_module.async_session_factory() as db_session:
+        yield db_session
+
+
+@pytest_asyncio.fixture
+async def remote_connection(session) -> RemoteConnection:
+    row = RemoteConnection(
+        adapter="telegram",
+        label="My phone",
+        enabled=True,
+        adapter_principal_id="bot-1",
+        adapter_username="my_evoflux_bot",
+    )
+    session.add(row)
+    await session.commit()
+    await session.refresh(row)
+    return row
+
+
+@pytest.mark.asyncio
+async def test_new_pairing_defaults_notify_scope_to_all(session, remote_connection):
+    pairing = RemotePairing(
+        connection_id=remote_connection.id,
+        principal_id="user-1",
+        destination_id="chat-1",
+        label="My phone",
+    )
+    session.add(pairing)
+    await session.commit()
+    await session.refresh(pairing)
+    assert pairing.notify_scope == "all"
+
+
+@pytest.mark.asyncio
+async def test_notify_scope_round_trips_a_non_default_value(session, remote_connection):
+    pairing = RemotePairing(
+        connection_id=remote_connection.id,
+        principal_id="user-1",
+        destination_id="chat-1",
+        label="My phone",
+        notify_scope="phone_initiated",
+    )
+    session.add(pairing)
+    await session.commit()
+    await session.refresh(pairing)
+
+    reloaded = (
+        await session.exec(
+            select(RemotePairing).where(RemotePairing.id == pairing.id)
+        )
+    ).one()
+    assert reloaded.notify_scope == "phone_initiated"
diff --git a/tests/remote/test_outbound.py b/tests/remote/test_outbound.py
index 4766b36f..adae2b3d 100644
--- a/tests/remote/test_outbound.py
+++ b/tests/remote/test_outbound.py
@@ -246,6 +246,41 @@ async def test_plan_approval_sends_buttons() -> None:
 # ── no adapter ───────────────────────────────────────────────────────────
 
 
+def test_set_active_pairing_then_clear() -> None:
+    proj = RemoteProjection()
+    assert proj.active_pairing() is None
+
+    proj.set_active_pairing(
+        connection_id="conn-1",
+        destination_id="chat-1",
+        notify_scope="all",
+        principal_id="user-1",
+    )
+    assert proj.active_pairing() == ("conn-1", "chat-1", "all", "user-1")
+
+    proj.clear_active_pairing()
+    assert proj.active_pairing() is None
+
+
+def test_set_active_pairing_overwrites_previous_value() -> None:
+    proj = RemoteProjection()
+    proj.set_active_pairing(
+        connection_id="conn-1",
+        destination_id="chat-1",
+        notify_scope="all",
+        principal_id="user-1",
+    )
+
+    proj.set_active_pairing(
+        connection_id="conn-2",
+        destination_id="chat-2",
+        notify_scope="phone_initiated",
+        principal_id="user-2",
+    )
+
+    assert proj.active_pairing() == ("conn-2", "chat-2", "phone_initiated", "user-2")
+
+
 def test_no_adapter_does_not_raise() -> None:
     proj = RemoteProjection()
     proj.set_adapter(None)
diff --git a/tests/remote/test_runtime.py b/tests/remote/test_runtime.py
index 66e694c6..cadf2e7b 100644
--- a/tests/remote/test_runtime.py
+++ b/tests/remote/test_runtime.py
@@ -469,6 +469,116 @@ async def test_text_action_starting_with_slash_routes_to_commands_not_a_task(
     assert "/unpair" in fake_adapters[0].sent[0].text
 
 
+# ── active-pairing cache wiring ──────────────────────────────────────────
+#
+# The projection's active-pairing cache (Task 3) lets a future task notify
+# the one paired user about sessions it was never explicitly
+# register_session-ed for (e.g. work started on the desktop). The runtime
+# is responsible for keeping that cache in sync with the database pairing:
+# populating it on startup restore, on a fresh pairing, and clearing it when
+# the runtime stops.
+
+
+@pytest.mark.asyncio
+async def test_start_restores_active_pairing_from_existing_row(
+    session, fake_stores, fake_adapters
+) -> None:
+    connection = await _make_connection(session, enabled=True)
+    fake_stores[connection.id] = FakeCredentialStore("secret-token")
+    session.add(
+        RemotePairing(
+            connection_id=connection.id,
+            principal_id="12345",
+            destination_id="12345",
+            label="Test User",
+            notify_scope="all",
+        )
+    )
+    await session.commit()
+
+    await remote_runtime.start()
+
+    assert remote_runtime._projection is not None
+    assert remote_runtime._projection.active_pairing() == (
+        str(connection.id),
+        "12345",
+        "all",
+        "12345",
+    )
+
+
+@pytest.mark.asyncio
+async def test_start_leaves_active_pairing_unset_when_no_pairing_exists(
+    session, fake_stores, fake_adapters
+) -> None:
+    connection = await _make_connection(session, enabled=True)
+    fake_stores[connection.id] = FakeCredentialStore("secret-token")
+
+    await remote_runtime.start()
+
+    assert remote_runtime._projection is not None
+    assert remote_runtime._projection.active_pairing() is None
+
+
+@pytest.mark.asyncio
+async def test_handle_pairing_populates_active_pairing_cache(
+    session, fake_stores, fake_adapters
+) -> None:
+    connection = await _make_connection(session, enabled=True)
+    fake_stores[connection.id] = FakeCredentialStore("secret-token")
+    await remote_runtime.start()
+    link = pairing_service.issue_link(connection)
+    token = link.url.rsplit("start=", 1)[-1]
+
+    action = RemoteInboundAction(
+        connection_id=connection.id,
+        kind=RemoteInboundActionKind.PAIRING_START,
+        principal=RemotePrincipal(
+            connection_id=connection.id,
+            principal_id="12345",
+            destination_id="12345",
+            display="Test User",
+        ),
+        source_key=f"telegram:{connection.id}:1",
+        pairing_token=token,
+    )
+
+    await remote_runtime._handle_pairing(action)
+
+    assert remote_runtime._projection is not None
+    assert remote_runtime._projection.active_pairing() == (
+        str(connection.id),
+        "12345",
+        "all",
+        "12345",
+    )
+
+
+@pytest.mark.asyncio
+async def test_stop_clears_active_pairing_cache(
+    session, fake_stores, fake_adapters
+) -> None:
+    connection = await _make_connection(session, enabled=True)
+    fake_stores[connection.id] = FakeCredentialStore("secret-token")
+    session.add(
+        RemotePairing(
+            connection_id=connection.id,
+            principal_id="12345",
+            destination_id="12345",
+            label="Test User",
+        )
+    )
+    await session.commit()
+    await remote_runtime.start()
+    projection = remote_runtime._projection
+    assert projection is not None
+    assert projection.active_pairing() is not None
+
+    await remote_runtime.stop()
+
+    assert projection.active_pairing() is None
+
+
 # ── status() ─────────────────────────────────────────────────────────────
 
 

From cef32dacd15300b1aa5ea4ec6dcb562dc110a8dd Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Mon, 14 Sep 2026 21:11:06 +0700
Subject: [PATCH 17/71] fix(remote): clear active-pairing cache on /unpair
 (AC-10)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

RemoteActionService now holds an optional reference to the outbound
RemoteProjection (set_projection, wired from RemoteRuntime._start_locked)
so _cmd_unpair can call clear_active_pairing() immediately after the
pairing row is deleted. Without this, /unpair revoked callback/menu
tokens and inbound authorization but left the in-memory active-pairing
cache added earlier in this branch stale until the runtime restarted —
a regression against AC-10's "immediate revocation" guarantee once that
cache is read by future notification logic.
---
 app/remote/actions.py        | 10 ++++++
 app/remote/runtime.py        |  1 +
 tests/remote/test_actions.py | 62 ++++++++++++++++++++++++++++++++++++
 3 files changed, 73 insertions(+)

diff --git a/app/remote/actions.py b/app/remote/actions.py
index b43424c8..16c51dbc 100644
--- a/app/remote/actions.py
+++ b/app/remote/actions.py
@@ -35,6 +35,7 @@
 
 if TYPE_CHECKING:
     from app.remote.contracts import RemoteAdapterStatus
+    from app.remote.outbound import RemoteProjection
 
 __all__ = ["RemoteActionResult", "RemoteActionService", "RemoteMenuItem"]
 
@@ -115,6 +116,7 @@ def __init__(
         self._status_provider = status_provider
         self._capabilities: dict[str, _ActionCapability] = {}
         self._pending_by_token: dict[str, str] = {}
+        self._projection: "RemoteProjection | None" = None
 
     def set_adapter(self, adapter: RemoteAdapter | None) -> None:
         self._adapter = adapter
@@ -124,6 +126,12 @@ def set_status_provider(
     ) -> None:
         self._status_provider = provider
 
+    def set_projection(self, projection: "RemoteProjection | None") -> None:
+        """Bind the outbound projection so ``/unpair`` can immediately clear
+        its active-pairing cache (AC-10: unpair revokes access right away,
+        not just callback/menu tokens)."""
+        self._projection = projection
+
     # ── Command dispatch ──────────────────────────────────────────────────
 
     async def dispatch_command(
@@ -264,6 +272,8 @@ async def _cmd_unpair(
     ) -> RemoteActionResult:
         removed = await self._pairing_service.unpair(db, action.connection_id)
         if removed:
+            if self._projection is not None:
+                self._projection.clear_active_pairing()
             return RemoteActionResult(
                 status="ok", text="Phone unpaired. Send /start to pair again."
             )
diff --git a/app/remote/runtime.py b/app/remote/runtime.py
index e3dcdc1e..d4b37b54 100644
--- a/app/remote/runtime.py
+++ b/app/remote/runtime.py
@@ -319,6 +319,7 @@ async def _start_locked(self) -> None:
             adapter=adapter,
             status_provider=lambda: self.status(connection.id),
         )
+        self._actions.set_projection(projection)
 
         from app.services.memory_stream_store import register_observer
 
diff --git a/tests/remote/test_actions.py b/tests/remote/test_actions.py
index 8aa9426d..7b96ccf9 100644
--- a/tests/remote/test_actions.py
+++ b/tests/remote/test_actions.py
@@ -19,6 +19,7 @@
     RemoteInboundActionKind,
     RemotePrincipal,
 )
+from app.remote.outbound import RemoteProjection
 
 
 # ── Fixtures ──────────────────────────────────────────────────────────────────
@@ -224,6 +225,67 @@ async def test_unpair_removes_pairing(self, service: RemoteActionService) -> Non
         assert result.status == "ok"
         assert "unpair" in result.text.lower()
 
+    @pytest.mark.asyncio
+    async def test_unpair_clears_the_active_pairing_cache(
+        self, service: RemoteActionService
+    ) -> None:
+        """AC-10 (immediate revocation): /unpair must stop all communication
+        to the former principal right away — including notifications routed
+        through the projection's active-pairing cache, not just callback and
+        menu tokens."""
+        projection = RemoteProjection()
+        connection_id = uuid4()
+        projection.set_active_pairing(
+            connection_id=str(connection_id),
+            destination_id="chat-1",
+            notify_scope="all",
+            principal_id="user-1",
+        )
+        service.set_projection(projection)
+        action = _make_action(text="/unpair", connection_id=connection_id)
+        mock_db = MagicMock()
+
+        with patch.object(service._pairing_service, "unpair", return_value=True):
+            await service.dispatch_command(mock_db, action)
+
+        assert projection.active_pairing() is None
+
+    @pytest.mark.asyncio
+    async def test_unpair_with_no_projection_bound_does_not_raise(
+        self, service: RemoteActionService
+    ) -> None:
+        """set_projection defaults to None — /unpair must stay safe before
+        the runtime ever binds a projection."""
+        action = _make_action(text="/unpair")
+        mock_db = MagicMock()
+
+        with patch.object(service._pairing_service, "unpair", return_value=True):
+            result = await service.dispatch_command(mock_db, action)
+
+        assert result.status == "ok"
+
+    @pytest.mark.asyncio
+    async def test_unpair_with_no_existing_pairing_leaves_cache_untouched(
+        self, service: RemoteActionService
+    ) -> None:
+        """A no-op unpair (nothing to remove) must not clear an unrelated
+        active pairing."""
+        projection = RemoteProjection()
+        projection.set_active_pairing(
+            connection_id=str(uuid4()),
+            destination_id="chat-1",
+            notify_scope="all",
+            principal_id="user-1",
+        )
+        service.set_projection(projection)
+        action = _make_action(text="/unpair")
+        mock_db = MagicMock()
+
+        with patch.object(service._pairing_service, "unpair", return_value=False):
+            await service.dispatch_command(mock_db, action)
+
+        assert projection.active_pairing() is not None
+
 
 # ── Callback handling ─────────────────────────────────────────────────────────
 

From 957d594403b3e1ad60663a0b27c0aa996abeb150 Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Mon, 14 Sep 2026 21:26:53 +0700
Subject: [PATCH 18/71] feat(remote): live status card, typing indicator, and
 done/error cards

Adds turn_activity.py (queries SessionMessage rows for a turn's tool-call
summary, used for the done-card's "N tool calls" line) and the
phone-admitted status-message lifecycle on RemoteProjection:
begin_phone_turn() sends one status card and starts a repeating native
typing indicator; _finalize_turn() builds the final done/error card and
edits that same message instead of sending a new one, then stops typing.
---
 app/remote/outbound.py             | 254 +++++++++++++++++++++++++++--
 app/remote/runtime.py              |  17 ++
 app/remote/turn_activity.py        |  81 +++++++++
 tests/remote/test_outbound.py      | 112 ++++++++++++-
 tests/remote/test_turn_activity.py | 118 ++++++++++++++
 5 files changed, 563 insertions(+), 19 deletions(-)
 create mode 100644 app/remote/turn_activity.py
 create mode 100644 tests/remote/test_turn_activity.py

diff --git a/app/remote/outbound.py b/app/remote/outbound.py
index 49569d5a..7b07e514 100644
--- a/app/remote/outbound.py
+++ b/app/remote/outbound.py
@@ -21,7 +21,10 @@
 from __future__ import annotations
 
 import asyncio
+import time
+import uuid
 from dataclasses import dataclass, field
+from datetime import UTC, datetime
 from typing import TYPE_CHECKING
 from uuid import UUID
 
@@ -33,8 +36,11 @@
     RemoteOutboundMessage,
     RemoteOutboundPriority,
 )
+from app.remote.formatting import render_done_card, render_error_card, render_status_card
+from app.remote.turn_activity import load_turn_activity
 
 if TYPE_CHECKING:
+    from app.remote.actions import RemoteActionService
     from app.remote.gates import RemoteGateBridge
 
 #: Telegram's maximum message length in characters.
@@ -66,6 +72,17 @@ class _TurnDeliveryState:
     lifecycle_correlation_id: str | None = None
     #: Whether a completion message has already been sent for this turn.
     completion_sent: bool = False
+    #: True for a turn that owns a single live status card — created by
+    #: ``begin_phone_turn`` — that the final done/error card must edit
+    #: in place rather than follow with a new message.
+    phone_admitted: bool = False
+    started_at: float = field(default_factory=time.monotonic)
+    turn_started_wall_clock: datetime = field(default_factory=lambda: datetime.now(UTC))
+    #: The repeating native-typing-indicator task started alongside the
+    #: status card; cancelled and cleared once the turn finalizes.
+    typing_task: "asyncio.Task[None] | None" = field(default=None, repr=False)
+    title: str = ""
+    principal_id: str = ""
 
 
 @dataclass
@@ -80,11 +97,32 @@ class RemoteProjection:
 
     _adapter: RemoteAdapter | None = field(default=None, repr=False)
     _bridge: "RemoteGateBridge | None" = field(default=None, repr=False)
+    #: Set by a later task's ``set_actions`` (Task 6) so ``_finalize_turn``
+    #: can mint "Full diff"/"Tool log" drill-down capability tokens. ``None``
+    #: until that wiring lands — every use guards on it and treats a missing
+    #: service as "no button" (``formatting.py``'s card builders already
+    #: omit a button for a ``None`` token).
+    _actions: "RemoteActionService | None" = field(default=None, repr=False)
     _turns: dict[str, _TurnDeliveryState] = field(default_factory=dict, repr=False)
     _session_tags: dict[str, frozenset[str]] = field(default_factory=dict, repr=False)
     _session_connection_ids: dict[str, str] = field(default_factory=dict, repr=False)
     _session_destination_ids: dict[str, str] = field(default_factory=dict, repr=False)
     _pending: list[RemoteOutboundMessage] = field(default_factory=list, repr=False)
+    _pending_edits: list[RemoteOutboundMessage] = field(default_factory=list, repr=False)
+    #: Turns whose ``done``/``error`` event has been observed but whose
+    #: final card hasn't been built and delivered yet — building it needs a
+    #: database query (:func:`~app.remote.turn_activity.load_turn_activity`),
+    #: which ``observe()`` itself must never do (observers are synchronous
+    #: and non-blocking, per this module's design constraints). Queued here
+    #: instead and drained by :meth:`drain_pending`, matching how ``_pending``
+    #: already defers ``adapter.send`` calls out of ``observe()``.
+    _pending_finalizations: list[tuple[_TurnDeliveryState, str | None]] = field(
+        default_factory=list, repr=False
+    )
+    #: Reserved for a later task's unaddressed-delivery drain (Task 5);
+    #: unused by this task beyond being cleared alongside the other queues
+    #: when no adapter is bound.
+    _unaddressed_pending: list[object] = field(default_factory=list, repr=False)
     #: Caches the single v1 pairing's routing info so ``observe`` can reach
     #: sessions it was never explicitly ``register_session``-ed for (e.g.
     #: work started from the desktop, not the phone) — this app supports
@@ -156,7 +194,65 @@ def unregister_session(self, session_id: str) -> None:
         self._session_tags.pop(session_id, None)
         self._session_connection_ids.pop(session_id, None)
         self._session_destination_ids.pop(session_id, None)
-        self._turns.pop(session_id, None)
+        turn = self._turns.pop(session_id, None)
+        if turn is not None:
+            self._stop_typing(turn)
+
+    def begin_phone_turn(
+        self,
+        session_id: str,
+        *,
+        connection_id: str,
+        destination_id: str,
+        principal_id: str,
+        title: str,
+        status: str,
+    ) -> None:
+        """Create the one status message a phone-admitted turn owns, and
+        start the native typing indicator alongside it. Called by
+        runtime.py right after ``register_session`` for a text-triggered
+        admission."""
+        correlation_id = f"status:{session_id}:{uuid.uuid4().hex[:8]}"
+        turn = _TurnDeliveryState(
+            session_id=session_id,
+            connection_id=connection_id,
+            destination_id=destination_id,
+            principal_id=principal_id,
+            lifecycle_correlation_id=correlation_id,
+            phone_admitted=True,
+            title=title,
+        )
+        self._turns[session_id] = turn
+        text, buttons = render_status_card(title=title, status=status)
+        self._enqueue_send(
+            destination_id=destination_id,
+            text=text,
+            buttons=buttons,
+            priority=RemoteOutboundPriority.HIGH,
+            correlation_id=correlation_id,
+        )
+        if self._adapter is not None:
+            turn.typing_task = asyncio.create_task(self._run_typing_loop(turn))
+
+    async def _run_typing_loop(self, turn: _TurnDeliveryState) -> None:
+        adapter = self._adapter
+        if adapter is None:
+            return
+        try:
+            while True:
+                await adapter.indicate_typing(turn.destination_id)
+                await asyncio.sleep(4.0)
+        except asyncio.CancelledError:
+            pass
+
+    def typing_task_for(self, session_id: str) -> "asyncio.Task[None] | None":
+        turn = self._turns.get(session_id)
+        return turn.typing_task if turn is not None else None
+
+    def _stop_typing(self, turn: _TurnDeliveryState) -> None:
+        if turn.typing_task is not None and not turn.typing_task.done():
+            turn.typing_task.cancel()
+        turn.typing_task = None
 
     def observe(self, session_id: str, envelope) -> None:
         """Stream observer callback — invoked synchronously after ``push_event``.
@@ -209,23 +305,89 @@ def _handle_done(self, turn: _TurnDeliveryState, envelope) -> None:
         if turn.completion_sent:
             return
         turn.completion_sent = True
-        text = _redact_text(
-            envelope.data.get("text", "Task completed.") or "Task completed."
-        )
-        self._enqueue_send(
-            destination_id=turn.destination_id,
-            text=text,
-            priority=RemoteOutboundPriority.HIGH,
-        )
+        self._pending_finalizations.append((turn, None))
+        self._schedule_drain()
 
     def _handle_error(self, turn: _TurnDeliveryState, envelope) -> None:
+        if turn.completion_sent:
+            return
+        turn.completion_sent = True
         message = envelope.data.get("message", "An error occurred.")
-        text = _redact_text(f"Error: {message}")
-        self._enqueue_send(
-            destination_id=turn.destination_id,
-            text=text,
-            priority=RemoteOutboundPriority.HIGH,
-        )
+        self._pending_finalizations.append((turn, message))
+        self._schedule_drain()
+
+    async def _finalize_turn(
+        self, turn: _TurnDeliveryState, *, error_message: str | None
+    ) -> None:
+        """Build the turn's final done/error card and deliver it.
+
+        Stops the typing indicator first (the turn is over regardless of
+        how delivery goes), then queries this turn's tool-call activity to
+        build the card, and either edits the status card a phone-admitted
+        turn already owns, or sends a new message for every other turn
+        (e.g. one started from the desktop that the phone is only
+        observing).
+        """
+        from app.core.db import async_session_factory
+
+        self._stop_typing(turn)
+        elapsed = time.monotonic() - turn.started_at
+        async with async_session_factory() as db:
+            activity = await load_turn_activity(
+                db, turn.session_id, since=turn.turn_started_wall_clock
+            )
+
+        diff_token: str | None = None
+        toollog_token: str | None = None
+        if self._actions is not None:
+            if activity.diff_text.strip() and activity.diff_text != "No file changes.":
+                diff_token = self._actions.register_capability(
+                    connection_id=turn.connection_id,
+                    principal_id=turn.principal_id,
+                    destination_id=turn.destination_id,
+                    session_id=turn.session_id,
+                    action_kind="diff",
+                    action_target=activity.diff_text,
+                )
+            toollog_token = self._actions.register_capability(
+                connection_id=turn.connection_id,
+                principal_id=turn.principal_id,
+                destination_id=turn.destination_id,
+                session_id=turn.session_id,
+                action_kind="toollog",
+                action_target=activity.tool_log_text,
+            )
+
+        if error_message is not None:
+            text, buttons = render_error_card(
+                title=turn.title,
+                message=_redact_text(error_message),
+                toollog_token=toollog_token,
+            )
+        else:
+            text, buttons = render_done_card(
+                title=turn.title,
+                elapsed_seconds=elapsed,
+                summary_lines=[_redact_text(line) for line in activity.summary_lines],
+                tool_call_count=activity.tool_call_count,
+                diff_token=diff_token,
+                toollog_token=toollog_token,
+            )
+
+        if turn.phone_admitted and turn.lifecycle_correlation_id is not None:
+            self._enqueue_edit(
+                destination_id=turn.destination_id,
+                text=text,
+                buttons=buttons,
+                correlation_id=turn.lifecycle_correlation_id,
+            )
+        else:
+            self._enqueue_send(
+                destination_id=turn.destination_id,
+                text=text,
+                buttons=buttons,
+                priority=RemoteOutboundPriority.HIGH,
+            )
 
     def _handle_gate(self, turn: _TurnDeliveryState, event_type: str, envelope) -> None:
         data = envelope.data
@@ -279,6 +441,7 @@ def _enqueue_send(
         text: str,
         buttons: tuple[RemoteButton, ...] = (),
         priority: RemoteOutboundPriority = RemoteOutboundPriority.INFORMATIONAL,
+        correlation_id: str | None = None,
     ) -> None:
         adapter = self._adapter
         if adapter is None:
@@ -298,11 +461,43 @@ def _enqueue_send(
                 text=chunk,
                 buttons=buttons if i == len(chunks) - 1 else (),
                 priority=priority,
+                correlation_id=correlation_id if i == len(chunks) - 1 else None,
             )
             self._pending.append(msg)
 
         self._schedule_drain()
 
+    def _enqueue_edit(
+        self,
+        *,
+        destination_id: str,
+        text: str,
+        buttons: tuple[RemoteButton, ...],
+        correlation_id: str,
+    ) -> None:
+        """Edit-flagged delivery — a status card's final transition. Unlike
+        ``_enqueue_send``, never splits (a status/done card is always short
+        and already bounded by ``formatting.py``'s builders), so it is
+        always exactly one queued item."""
+        adapter = self._adapter
+        if adapter is None:
+            return
+
+        connection_id = ""
+        for cid in self._session_connection_ids.values():
+            connection_id = cid
+            break
+
+        msg = RemoteOutboundMessage(
+            connection_id=UUID(connection_id) if connection_id else UUID(int=0),
+            destination_id=destination_id,
+            text=text,
+            buttons=buttons,
+            correlation_id=correlation_id,
+        )
+        self._pending_edits.append(msg)
+        self._schedule_drain()
+
     def _schedule_drain(self) -> None:
         """Schedule an async drain of pending messages if a loop is running."""
         try:
@@ -312,11 +507,18 @@ def _schedule_drain(self) -> None:
             pass
 
     async def drain_pending(self) -> None:
-        """Send all pending messages through the adapter."""
+        """Finalize completed turns, then send/edit all pending messages
+        through the adapter."""
         adapter = self._adapter
         if adapter is None:
             self._pending.clear()
+            self._pending_edits.clear()
+            self._pending_finalizations.clear()
+            self._unaddressed_pending.clear()
             return
+        while self._pending_finalizations:
+            turn, error_message = self._pending_finalizations.pop(0)
+            await self._finalize_turn(turn, error_message=error_message)
         while self._pending:
             msg = self._pending.pop(0)
             try:
@@ -327,10 +529,28 @@ async def drain_pending(self) -> None:
                     msg.destination_id,
                     exc,
                 )
+        while self._pending_edits:
+            msg = self._pending_edits.pop(0)
+            try:
+                await adapter.edit(msg)
+            except Exception as exc:
+                logger.warning(
+                    "remote_outbound_edit_failed destination_id={} error={}",
+                    msg.destination_id,
+                    exc,
+                )
+        await self._drain_unaddressed()
+
+    async def _drain_unaddressed(self) -> None:
+        """Placeholder for a later task's unaddressed-delivery drain
+        (Task 5) — a no-op until that task replaces this body."""
+        return
 
     def clear_turn(self, session_id: str) -> None:
         """Clear delivery state for a completed turn."""
-        self._turns.pop(session_id, None)
+        turn = self._turns.pop(session_id, None)
+        if turn is not None:
+            self._stop_typing(turn)
 
 
 def _redact_text(text: str) -> str:
diff --git a/app/remote/runtime.py b/app/remote/runtime.py
index d4b37b54..36fe87c8 100644
--- a/app/remote/runtime.py
+++ b/app/remote/runtime.py
@@ -519,5 +519,22 @@ async def _handle_text(self, action: RemoteInboundAction) -> None:
                 ),
             )
 
+        # Create the one status message this phone-admitted turn owns, with
+        # a native typing indicator running alongside it (AC-22/AC-38).
+        if result.session_id is not None and self._projection is not None:
+            from app.core.db import async_session_factory as _sf
+            from app.models.chat import ChatSession
+
+            async with _sf() as title_session:
+                session_row = await title_session.get(ChatSession, result.session_id)
+            self._projection.begin_phone_turn(
+                str(result.session_id),
+                connection_id=str(action.connection_id),
+                destination_id=action.principal.destination_id,
+                principal_id=action.principal.principal_id,
+                title=(session_row.title if session_row and session_row.title else "New task"),
+                status=result.status,
+            )
+
 
 remote_runtime = RemoteRuntime()
diff --git a/app/remote/turn_activity.py b/app/remote/turn_activity.py
new file mode 100644
index 00000000..5011b119
--- /dev/null
+++ b/app/remote/turn_activity.py
@@ -0,0 +1,81 @@
+"""Turn-activity summary built from a turn's persisted messages.
+
+Queries every :class:`~app.models.chat.SessionMessage` row created since a
+turn started and reduces its tool calls into the bounded summary used by
+the done-card's "N tool calls" line, and — via later drill-down capability
+tokens minted in a subsequent task — the "Full diff"/"Tool log" buttons.
+
+Note: the plan's interface section names ``app.models.chat.ChatMessage``,
+but no such model exists in this codebase; the real persisted-message table
+is ``SessionMessage`` (``app/models/chat.py``), whose fields (``session_id``,
+``role``, ``tool_calls``, ``tool_call_id``, ``content``, ``created_at``)
+match exactly what this module needs, so it is used here instead.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from uuid import UUID
+
+from sqlmodel import col, select
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from app.models.chat import SessionMessage
+
+_DIFF_TOOLS = frozenset({"write", "edit", "patch"})
+
+__all__ = ["TurnActivity", "load_turn_activity"]
+
+
+@dataclass(frozen=True)
+class TurnActivity:
+    tool_call_count: int
+    summary_lines: list[str] = field(default_factory=list)
+    tool_log_text: str = ""
+    diff_text: str = ""
+
+
+async def load_turn_activity(
+    db: AsyncSession, session_id: str, *, since: datetime
+) -> TurnActivity:
+    # ``SessionMessage.session_id`` is a real ``sa.Uuid()`` column, so a
+    # non-UUID session_id (e.g. a test double's placeholder string, or an
+    # id from a caller that doesn't own a persisted chat session) can never
+    # match a row — return the empty-activity placeholders instead of
+    # raising, matching what an empty result set would produce anyway.
+    try:
+        session_uuid = UUID(session_id)
+    except ValueError:
+        return TurnActivity(
+            tool_call_count=0,
+            tool_log_text="No tool calls.",
+            diff_text="No file changes.",
+        )
+
+    rows = (
+        await db.exec(
+            select(SessionMessage)
+            .where(SessionMessage.session_id == session_uuid)
+            .where(col(SessionMessage.created_at) >= since)
+            .order_by(col(SessionMessage.created_at))
+        )
+    ).all()
+
+    tool_calls: list[tuple[str, str]] = []
+    for message in rows:
+        for call in message.tool_calls or []:
+            name = call.get("name", "unknown")
+            args = call.get("arguments", {})
+            tool_calls.append((name, str(args)))
+
+    tool_log_lines = [f"{name}: {args}" for name, args in tool_calls]
+    diff_lines = [f"{name}: {args}" for name, args in tool_calls if name in _DIFF_TOOLS]
+    diff_paths = sorted({args for name, args in tool_calls if name in _DIFF_TOOLS})
+
+    return TurnActivity(
+        tool_call_count=len(tool_calls),
+        summary_lines=diff_paths[:10],
+        tool_log_text="\n".join(tool_log_lines) or "No tool calls.",
+        diff_text="\n".join(diff_lines) or "No file changes.",
+    )
diff --git a/tests/remote/test_outbound.py b/tests/remote/test_outbound.py
index adae2b3d..b185ff8c 100644
--- a/tests/remote/test_outbound.py
+++ b/tests/remote/test_outbound.py
@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import asyncio
 from uuid import uuid4
 
 import pytest
@@ -21,20 +22,32 @@ def _envelope(event: str, **data: object) -> StreamEnvelope:
 
 
 class FakeAdapter:
-    """Records send calls for assertion."""
+    """Records send/edit calls for assertion.
+
+    ``calls`` tracks only ``send``/``edit`` — in delivery order — so tests
+    can assert "sent first, then edited" without the typing indicator's
+    repeating ``indicate_typing`` calls interleaving into that sequence.
+    """
 
     def __init__(self) -> None:
         self.sent: list[RemoteOutboundMessage] = []
+        self.edited: list[RemoteOutboundMessage] = []
+        self.calls: list[str] = []
 
     async def send(self, message: RemoteOutboundMessage) -> None:
+        self.calls.append("send")
         self.sent.append(message)
 
     async def edit(self, message: RemoteOutboundMessage) -> None:
-        pass
+        self.calls.append("edit")
+        self.edited.append(message)
 
     async def answer_callback(self, callback_token: str) -> None:
         pass
 
+    async def indicate_typing(self, destination_id: str) -> None:
+        pass
+
     def status(self) -> RemoteAdapterStatus:
         return RemoteAdapterStatus(
             connection_id=uuid4(), state=RemoteConnectionState.POLLING
@@ -177,6 +190,101 @@ async def test_error_sends_error_message() -> None:
     assert "Something went wrong" in adapter.sent[0].text
 
 
+# ── phone-admitted status lifecycle ─────────────────────────────────────
+
+
+@pytest.mark.asyncio
+async def test_begin_phone_turn_sends_status_card_then_done_edits_it() -> None:
+    projection = RemoteProjection()
+    adapter = FakeAdapter()
+    projection.set_adapter(adapter)
+
+    cid = str(uuid4())
+    projection.register_session(
+        "sess-1",
+        connection_id=cid,
+        destination_id="chat-1",
+        tags=frozenset({"remote_origin"}),
+    )
+    projection.begin_phone_turn(
+        "sess-1",
+        connection_id=cid,
+        destination_id="chat-1",
+        principal_id="user-1",
+        title="Fix tests",
+        status="accepted",
+    )
+    await asyncio.sleep(0.05)
+    assert adapter.calls[0] == "send"
+    first_correlation = adapter.sent[0].correlation_id
+
+    projection.observe("sess-1", _envelope("done", text="Done."))
+    await projection.drain_pending()
+
+    assert adapter.calls[1] == "edit"
+    assert adapter.edited[0].correlation_id == first_correlation
+    assert "Fix tests" in adapter.edited[0].text
+    assert projection.typing_task_for("sess-1") is None
+
+
+@pytest.mark.asyncio
+async def test_begin_phone_turn_error_edits_status_with_error_card() -> None:
+    projection = RemoteProjection()
+    adapter = FakeAdapter()
+    projection.set_adapter(adapter)
+
+    cid = str(uuid4())
+    projection.register_session(
+        "sess-1",
+        connection_id=cid,
+        destination_id="chat-1",
+        tags=frozenset({"remote_origin"}),
+    )
+    projection.begin_phone_turn(
+        "sess-1",
+        connection_id=cid,
+        destination_id="chat-1",
+        principal_id="user-1",
+        title="Fix tests",
+        status="accepted",
+    )
+    await asyncio.sleep(0.05)
+    first_correlation = adapter.sent[0].correlation_id
+
+    projection.observe("sess-1", _envelope("error", message="Boom"))
+    await projection.drain_pending()
+
+    assert adapter.calls[1] == "edit"
+    assert adapter.edited[0].correlation_id == first_correlation
+    assert "Boom" in adapter.edited[0].text
+    assert projection.typing_task_for("sess-1") is None
+
+
+@pytest.mark.asyncio
+async def test_begin_phone_turn_without_adapter_does_not_raise() -> None:
+    projection = RemoteProjection()
+    projection.set_adapter(None)
+
+    projection.register_session(
+        "sess-1",
+        connection_id="conn-1",
+        destination_id="chat-1",
+        tags=frozenset({"remote_origin"}),
+    )
+    projection.begin_phone_turn(
+        "sess-1",
+        connection_id="conn-1",
+        destination_id="chat-1",
+        principal_id="user-1",
+        title="Fix tests",
+        status="accepted",
+    )
+    assert projection.typing_task_for("sess-1") is None
+
+    projection.observe("sess-1", _envelope("done", text="Done."))
+    await projection.drain_pending()
+
+
 # ── gate events ──────────────────────────────────────────────────────────
 
 
diff --git a/tests/remote/test_turn_activity.py b/tests/remote/test_turn_activity.py
new file mode 100644
index 00000000..c205b636
--- /dev/null
+++ b/tests/remote/test_turn_activity.py
@@ -0,0 +1,118 @@
+"""Tests for app/remote/turn_activity.py — turn tool-call activity summary.
+
+``app.models.chat`` has no ``ChatMessage`` model (the brief's interface
+section names one, but the real persisted-message table is
+``SessionMessage`` — see ``app/models/chat.py``); its fields
+(``session_id``, ``role``, ``tool_calls``, ``tool_call_id``, ``content``,
+``created_at``) match what the brief's test exercises, so this test targets
+the real model instead.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+
+import pytest
+import pytest_asyncio
+
+import app.core.db as db_module
+from app.models.chat import ChatSession, SessionMessage
+from app.remote.turn_activity import load_turn_activity
+
+
+@pytest_asyncio.fixture
+async def db_session():
+    async with db_module.async_session_factory() as session:
+        yield session
+
+
+@pytest_asyncio.fixture
+async def chat_session(db_session):
+    session = ChatSession(title="Turn activity test session")
+    db_session.add(session)
+    await db_session.commit()
+    await db_session.refresh(session)
+    return session
+
+
+@pytest.mark.asyncio
+async def test_load_turn_activity_counts_tool_calls_and_builds_diff(db_session, chat_session):
+    since = datetime.now(UTC) - timedelta(seconds=1)
+    db_session.add_all(
+        [
+            SessionMessage(
+                session_id=chat_session.id,
+                role="assistant",
+                tool_calls=[{"name": "write", "arguments": {"path": "a.py"}}],
+                created_at=since + timedelta(milliseconds=10),
+            ),
+            SessionMessage(
+                session_id=chat_session.id,
+                role="tool",
+                tool_call_id="1",
+                content="wrote a.py (+5 -1)",
+                created_at=since + timedelta(milliseconds=20),
+            ),
+            SessionMessage(
+                session_id=chat_session.id,
+                role="assistant",
+                tool_calls=[{"name": "read", "arguments": {"path": "b.py"}}],
+                created_at=since + timedelta(milliseconds=30),
+            ),
+        ]
+    )
+    await db_session.commit()
+
+    activity = await load_turn_activity(db_session, str(chat_session.id), since=since)
+
+    assert activity.tool_call_count == 2
+    assert "write" in activity.diff_text
+    assert "read" not in activity.diff_text
+    assert "read" in activity.tool_log_text
+
+
+@pytest.mark.asyncio
+async def test_load_turn_activity_with_no_tool_calls_returns_placeholders(
+    db_session, chat_session
+):
+    since = datetime.now(UTC) - timedelta(seconds=1)
+
+    activity = await load_turn_activity(db_session, str(chat_session.id), since=since)
+
+    assert activity.tool_call_count == 0
+    assert activity.summary_lines == []
+    assert activity.tool_log_text == "No tool calls."
+    assert activity.diff_text == "No file changes."
+
+
+@pytest.mark.asyncio
+async def test_load_turn_activity_with_non_uuid_session_id_returns_placeholders(db_session):
+    """A non-UUID session id (e.g. a test double's placeholder) can never
+    match a persisted row, so this returns empty activity instead of
+    raising — exercised because outbound.py's ``_finalize_turn`` calls this
+    for every turn, including ones whose session_id isn't a real UUID."""
+    since = datetime.now(UTC) - timedelta(seconds=1)
+
+    activity = await load_turn_activity(db_session, "sess-1", since=since)
+
+    assert activity.tool_call_count == 0
+    assert activity.tool_log_text == "No tool calls."
+    assert activity.diff_text == "No file changes."
+
+
+@pytest.mark.asyncio
+async def test_load_turn_activity_ignores_messages_before_since(db_session, chat_session):
+    since = datetime.now(UTC)
+    db_session.add(
+        SessionMessage(
+            session_id=chat_session.id,
+            role="assistant",
+            tool_calls=[{"name": "write", "arguments": {"path": "old.py"}}],
+            created_at=since - timedelta(seconds=10),
+        )
+    )
+    await db_session.commit()
+
+    activity = await load_turn_activity(db_session, str(chat_session.id), since=since)
+
+    assert activity.tool_call_count == 0

From 1b2059e931d38cec3adbff36881e1ab3350522d4 Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Mon, 14 Sep 2026 21:54:56 +0700
Subject: [PATCH 19/71] fix(remote): address review findings in
 status-lifecycle diff

Fixes 5 Important issues found in code review of the phone-admitted
status lifecycle:

- Typing loop now re-checks self._adapter every iteration (not a stale
  snapshot) and survives a transient indicate_typing error; set_adapter(None)
  stops every live turn's typing task on shutdown instead of relying on a
  done/error event that may never arrive.
- begin_phone_turn reuses an existing unresolved turn's status message
  (stop its typing task, edit in place) instead of overwriting turn state
  and leaking the old typing task and status card.
- drain_pending is now serialized with an asyncio.Lock (matching
  PairingService._consume_lock's precedent), and _finalize_turn only edits
  a status card that a new _sent_correlations set confirms was actually
  sent, falling back to a fresh send otherwise so a card is never silently
  dropped.
- The _finalize_turn call inside drain_pending's pump is now wrapped in the
  same try/except as every other adapter call, so a DB failure there can't
  abandon the rest of the queue.
- A registered-but-never-begun turn's card now falls back to a "Task"
  title instead of rendering blank.

Also addresses the reviewer's quick minor items: redact turn.title before
interpolation, factor out the duplicated connection-id lookup, guard
begin_phone_turn's create_task with the same RuntimeError pattern used
elsewhere, and add coverage for the typing-task cleanup paths.
---
 app/remote/outbound.py        | 236 +++++++++++++++++++++--------
 tests/remote/test_outbound.py | 270 +++++++++++++++++++++++++++++++++-
 2 files changed, 446 insertions(+), 60 deletions(-)

diff --git a/app/remote/outbound.py b/app/remote/outbound.py
index 7b07e514..0d140a57 100644
--- a/app/remote/outbound.py
+++ b/app/remote/outbound.py
@@ -123,6 +123,21 @@ class RemoteProjection:
     #: unused by this task beyond being cleared alongside the other queues
     #: when no adapter is bound.
     _unaddressed_pending: list[object] = field(default_factory=list, repr=False)
+    #: Serializes the whole of :meth:`drain_pending` so two concurrently
+    #: scheduled drains (e.g. a status-card send and a same-turn done-card
+    #: edit, each fired by its own ``_schedule_drain``) can never interleave
+    #: — same precedent as ``PairingService._consume_lock`` in
+    #: ``app/remote/pairing.py`` for an identical check-then-act race.
+    _drain_lock: asyncio.Lock = field(default_factory=asyncio.Lock, repr=False)
+    #: Correlation ids whose message has been *confirmed* sent (the
+    #: ``adapter.send`` call for it returned without raising) — as opposed
+    #: to merely enqueued. An adapter's ``edit`` silently no-ops when it has
+    #: no record of the original send (e.g.
+    #: :class:`~app.remote.telegram.adapter.TelegramAdapter` keys its
+    #: ``_sent_messages`` cache by correlation id and only populates it on
+    #: success), so ``_finalize_turn`` checks this before choosing to edit
+    #: rather than send, to avoid silently losing a turn's final card.
+    _sent_correlations: set[str] = field(default_factory=set, repr=False)
     #: Caches the single v1 pairing's routing info so ``observe`` can reach
     #: sessions it was never explicitly ``register_session``-ed for (e.g.
     #: work started from the desktop, not the phone) — this app supports
@@ -139,8 +154,18 @@ class RemoteProjection:
     )
 
     def set_adapter(self, adapter: RemoteAdapter | None) -> None:
-        """Bind or unbind the live adapter. Called by the runtime on start/stop."""
+        """Bind or unbind the live adapter. Called by the runtime on start/stop.
+
+        Unbinding (``adapter=None``) stops every turn's typing-indicator
+        task — otherwise a turn whose ``done``/``error`` event never arrives
+        (the runtime stopped mid-turn) would leave its loop calling
+        ``indicate_typing`` on a now-stale adapter reference every 4s
+        forever.
+        """
         self._adapter = adapter
+        if adapter is None:
+            for turn in self._turns.values():
+                self._stop_typing(turn)
 
     def set_bridge(self, bridge: "RemoteGateBridge | None") -> None:
         """Bind or unbind the gate bridge. Called by the runtime on start/stop."""
@@ -211,8 +236,31 @@ def begin_phone_turn(
         """Create the one status message a phone-admitted turn owns, and
         start the native typing indicator alongside it. Called by
         runtime.py right after ``register_session`` for a text-triggered
-        admission."""
-        correlation_id = f"status:{session_id}:{uuid.uuid4().hex[:8]}"
+        admission.
+
+        Reachable more than once for the same session — a follow-up
+        message sent to the phone while the first turn is still running
+        (``status="queued"``) triggers another admission, and thus another
+        call here, before the first turn's ``done``/``error`` arrives.
+        Rather than start a second status message and orphan the first
+        turn's typing task, this reuses the still-unresolved turn's
+        message: stop its typing task and carry its
+        ``lifecycle_correlation_id`` forward so the *same* message is
+        edited with the new status text. A fresh message is only sent when
+        there is no unresolved turn to reuse, or its original status card
+        was never confirmed sent (nothing to edit).
+        """
+        existing = self._turns.get(session_id)
+        reuse_correlation_id: str | None = None
+        if existing is not None and not existing.completion_sent:
+            self._stop_typing(existing)
+            if (
+                existing.lifecycle_correlation_id is not None
+                and existing.lifecycle_correlation_id in self._sent_correlations
+            ):
+                reuse_correlation_id = existing.lifecycle_correlation_id
+
+        correlation_id = reuse_correlation_id or f"status:{session_id}:{uuid.uuid4().hex[:8]}"
         turn = _TurnDeliveryState(
             session_id=session_id,
             connection_id=connection_id,
@@ -224,23 +272,52 @@ def begin_phone_turn(
         )
         self._turns[session_id] = turn
         text, buttons = render_status_card(title=title, status=status)
-        self._enqueue_send(
-            destination_id=destination_id,
-            text=text,
-            buttons=buttons,
-            priority=RemoteOutboundPriority.HIGH,
-            correlation_id=correlation_id,
-        )
+        if reuse_correlation_id is not None:
+            self._enqueue_edit(
+                destination_id=destination_id,
+                text=text,
+                buttons=buttons,
+                correlation_id=reuse_correlation_id,
+            )
+        else:
+            self._enqueue_send(
+                destination_id=destination_id,
+                text=text,
+                buttons=buttons,
+                priority=RemoteOutboundPriority.HIGH,
+                correlation_id=correlation_id,
+            )
         if self._adapter is not None:
-            turn.typing_task = asyncio.create_task(self._run_typing_loop(turn))
+            try:
+                loop = asyncio.get_running_loop()
+            except RuntimeError:
+                pass
+            else:
+                turn.typing_task = loop.create_task(self._run_typing_loop(turn))
 
     async def _run_typing_loop(self, turn: _TurnDeliveryState) -> None:
-        adapter = self._adapter
-        if adapter is None:
-            return
+        """Call ``indicate_typing`` every 4s until cancelled.
+
+        Re-checks ``self._adapter`` on every iteration (rather than a
+        one-time snapshot) so unbinding the adapter mid-turn stops calls
+        going to a stale reference, and isolates each ``indicate_typing``
+        call in its own ``try/except`` so one transport failure logs and
+        retries on the next tick instead of silently killing the loop (and
+        the typing indicator) for the rest of the turn.
+        """
         try:
             while True:
-                await adapter.indicate_typing(turn.destination_id)
+                adapter = self._adapter
+                if adapter is None:
+                    return
+                try:
+                    await adapter.indicate_typing(turn.destination_id)
+                except Exception as exc:
+                    logger.warning(
+                        "remote_typing_indicator_failed destination_id={} error={}",
+                        turn.destination_id,
+                        exc,
+                    )
                 await asyncio.sleep(4.0)
         except asyncio.CancelledError:
             pass
@@ -276,10 +353,15 @@ def observe(self, session_id: str, envelope) -> None:
 
         turn = self._turns.get(session_id)
         if turn is None:
+            # No begin_phone_turn was ever called for this session (e.g. work
+            # started on the desktop that the phone only observes) — "Task"
+            # is a defensive fallback so the eventual done/error card never
+            # renders with a blank title; a real title isn't available here.
             turn = _TurnDeliveryState(
                 session_id=session_id,
                 connection_id=connection_id,
                 destination_id=destination_id,
+                title="Task",
             )
             self._turns[session_id] = turn
 
@@ -358,15 +440,16 @@ async def _finalize_turn(
                 action_target=activity.tool_log_text,
             )
 
+        title = _redact_text(turn.title)
         if error_message is not None:
             text, buttons = render_error_card(
-                title=turn.title,
+                title=title,
                 message=_redact_text(error_message),
                 toollog_token=toollog_token,
             )
         else:
             text, buttons = render_done_card(
-                title=turn.title,
+                title=title,
                 elapsed_seconds=elapsed,
                 summary_lines=[_redact_text(line) for line in activity.summary_lines],
                 tool_call_count=activity.tool_call_count,
@@ -374,12 +457,22 @@ async def _finalize_turn(
                 toollog_token=toollog_token,
             )
 
-        if turn.phone_admitted and turn.lifecycle_correlation_id is not None:
+        # Only edit when this turn's status card was actually confirmed
+        # sent — an adapter's edit silently no-ops against a correlation id
+        # it never recorded a successful send for (see
+        # TelegramAdapter.edit's ``_sent_messages`` lookup), which would
+        # otherwise lose the final card entirely.
+        correlation_id = turn.lifecycle_correlation_id
+        was_sent = correlation_id is not None and correlation_id in self._sent_correlations
+        if correlation_id is not None:
+            self._sent_correlations.discard(correlation_id)
+
+        if turn.phone_admitted and correlation_id is not None and was_sent:
             self._enqueue_edit(
                 destination_id=turn.destination_id,
                 text=text,
                 buttons=buttons,
-                correlation_id=turn.lifecycle_correlation_id,
+                correlation_id=correlation_id,
             )
         else:
             self._enqueue_send(
@@ -448,10 +541,7 @@ def _enqueue_send(
             logger.debug("remote_outbound_no_adapter destination_id={}", destination_id)
             return
 
-        connection_id = ""
-        for cid in self._session_connection_ids.values():
-            connection_id = cid
-            break
+        connection_id = self._any_connection_id()
 
         chunks = _split_text(text)
         for i, chunk in enumerate(chunks):
@@ -483,10 +573,7 @@ def _enqueue_edit(
         if adapter is None:
             return
 
-        connection_id = ""
-        for cid in self._session_connection_ids.values():
-            connection_id = cid
-            break
+        connection_id = self._any_connection_id()
 
         msg = RemoteOutboundMessage(
             connection_id=UUID(connection_id) if connection_id else UUID(int=0),
@@ -498,6 +585,17 @@ def _enqueue_edit(
         self._pending_edits.append(msg)
         self._schedule_drain()
 
+    def _any_connection_id(self) -> str:
+        """One connection id to stamp on an outbound message.
+
+        v1 supports exactly one Telegram pairing per installation (see the
+        ``_active_pairing`` field docstring), so any tracked session's
+        connection id is the right — and only — one to use.
+        """
+        for cid in self._session_connection_ids.values():
+            return cid
+        return ""
+
     def _schedule_drain(self) -> None:
         """Schedule an async drain of pending messages if a loop is running."""
         try:
@@ -508,38 +606,58 @@ def _schedule_drain(self) -> None:
 
     async def drain_pending(self) -> None:
         """Finalize completed turns, then send/edit all pending messages
-        through the adapter."""
-        adapter = self._adapter
-        if adapter is None:
-            self._pending.clear()
-            self._pending_edits.clear()
-            self._pending_finalizations.clear()
-            self._unaddressed_pending.clear()
-            return
-        while self._pending_finalizations:
-            turn, error_message = self._pending_finalizations.pop(0)
-            await self._finalize_turn(turn, error_message=error_message)
-        while self._pending:
-            msg = self._pending.pop(0)
-            try:
-                await adapter.send(msg)
-            except Exception as exc:
-                logger.warning(
-                    "remote_outbound_send_failed destination_id={} error={}",
-                    msg.destination_id,
-                    exc,
-                )
-        while self._pending_edits:
-            msg = self._pending_edits.pop(0)
-            try:
-                await adapter.edit(msg)
-            except Exception as exc:
-                logger.warning(
-                    "remote_outbound_edit_failed destination_id={} error={}",
-                    msg.destination_id,
-                    exc,
-                )
-        await self._drain_unaddressed()
+        through the adapter.
+
+        Serialized by :attr:`_drain_lock`: ``_enqueue_send``/``_enqueue_edit``/
+        ``_handle_done``/``_handle_error`` each fire-and-forget their own
+        ``_schedule_drain`` call, so without this lock two drains can run
+        concurrently — e.g. a status-card send still in flight when a
+        same-turn done-card edit's drain starts — and interleave in ways
+        that lose a message (see ``_sent_correlations`` above).
+        """
+        async with self._drain_lock:
+            adapter = self._adapter
+            if adapter is None:
+                self._pending.clear()
+                self._pending_edits.clear()
+                self._pending_finalizations.clear()
+                self._unaddressed_pending.clear()
+                self._sent_correlations.clear()
+                return
+            while self._pending_finalizations:
+                turn, error_message = self._pending_finalizations.pop(0)
+                try:
+                    await self._finalize_turn(turn, error_message=error_message)
+                except Exception as exc:
+                    logger.warning(
+                        "remote_outbound_finalize_failed session_id={} error={}",
+                        turn.session_id,
+                        exc,
+                    )
+            while self._pending:
+                msg = self._pending.pop(0)
+                try:
+                    await adapter.send(msg)
+                except Exception as exc:
+                    logger.warning(
+                        "remote_outbound_send_failed destination_id={} error={}",
+                        msg.destination_id,
+                        exc,
+                    )
+                else:
+                    if msg.correlation_id is not None:
+                        self._sent_correlations.add(msg.correlation_id)
+            while self._pending_edits:
+                msg = self._pending_edits.pop(0)
+                try:
+                    await adapter.edit(msg)
+                except Exception as exc:
+                    logger.warning(
+                        "remote_outbound_edit_failed destination_id={} error={}",
+                        msg.destination_id,
+                        exc,
+                    )
+            await self._drain_unaddressed()
 
     async def _drain_unaddressed(self) -> None:
         """Placeholder for a later task's unaddressed-delivery drain
diff --git a/tests/remote/test_outbound.py b/tests/remote/test_outbound.py
index b185ff8c..14ca4d33 100644
--- a/tests/remote/test_outbound.py
+++ b/tests/remote/test_outbound.py
@@ -33,8 +33,17 @@ def __init__(self) -> None:
         self.sent: list[RemoteOutboundMessage] = []
         self.edited: list[RemoteOutboundMessage] = []
         self.calls: list[str] = []
+        #: Correlation ids whose ``send`` should raise instead of
+        #: succeeding, to simulate a status card that never made it.
+        self.fail_send_correlations: set[str] = set()
+        #: When >0, ``indicate_typing`` raises this many times before
+        #: succeeding, to simulate a transient transport error.
+        self.typing_failures_remaining = 0
+        self.typing_calls = 0
 
     async def send(self, message: RemoteOutboundMessage) -> None:
+        if message.correlation_id in self.fail_send_correlations:
+            raise RuntimeError("simulated send failure")
         self.calls.append("send")
         self.sent.append(message)
 
@@ -46,7 +55,10 @@ async def answer_callback(self, callback_token: str) -> None:
         pass
 
     async def indicate_typing(self, destination_id: str) -> None:
-        pass
+        self.typing_calls += 1
+        if self.typing_failures_remaining > 0:
+            self.typing_failures_remaining -= 1
+            raise RuntimeError("simulated typing failure")
 
     def status(self) -> RemoteAdapterStatus:
         return RemoteAdapterStatus(
@@ -285,6 +297,262 @@ async def test_begin_phone_turn_without_adapter_does_not_raise() -> None:
     await projection.drain_pending()
 
 
+@pytest.mark.asyncio
+async def test_begin_phone_turn_again_before_resolution_reuses_status_card() -> None:
+    """A follow-up message while the first turn is still running (the
+    inbound service returns status="queued" and runtime.py calls
+    begin_phone_turn again) must not orphan the first turn's typing task or
+    abandon its status card — it should edit the same message."""
+    projection = RemoteProjection()
+    adapter = FakeAdapter()
+    projection.set_adapter(adapter)
+
+    cid = str(uuid4())
+    projection.register_session(
+        "sess-1", connection_id=cid, destination_id="chat-1",
+        tags=frozenset({"remote_origin"}),
+    )
+    projection.begin_phone_turn(
+        "sess-1", connection_id=cid, destination_id="chat-1",
+        principal_id="user-1", title="Fix tests", status="accepted",
+    )
+    await asyncio.sleep(0.05)
+    assert adapter.calls == ["send"]
+    first_correlation = adapter.sent[0].correlation_id
+    first_typing_task = projection.typing_task_for("sess-1")
+    assert first_typing_task is not None
+
+    projection.begin_phone_turn(
+        "sess-1", connection_id=cid, destination_id="chat-1",
+        principal_id="user-1", title="Fix tests", status="queued",
+    )
+    await asyncio.sleep(0.05)
+
+    # The original typing task is stopped and replaced by a new one — not
+    # left running alongside it.
+    assert first_typing_task.cancelled() or first_typing_task.done()
+    second_typing_task = projection.typing_task_for("sess-1")
+    assert second_typing_task is not None
+    assert second_typing_task is not first_typing_task
+
+    # No second status message was sent — the existing one was edited.
+    assert adapter.calls == ["send", "edit"]
+    assert adapter.edited[0].correlation_id == first_correlation
+    assert "queued" in adapter.edited[0].text
+
+    projection.observe("sess-1", _envelope("done", text="Done."))
+    await projection.drain_pending()
+
+    # The final done card also edits that same single message.
+    assert adapter.calls == ["send", "edit", "edit"]
+    assert adapter.edited[1].correlation_id == first_correlation
+    assert projection.typing_task_for("sess-1") is None
+
+
+@pytest.mark.asyncio
+async def test_begin_phone_turn_reuse_falls_back_to_send_if_original_never_sent() -> None:
+    """If the first status card's send never actually succeeded (e.g. a
+    transient transport failure), there is nothing for a follow-up edit to
+    land on — must send a fresh message instead of silently no-op'ing."""
+    projection = RemoteProjection()
+    adapter = FakeAdapter()
+    projection.set_adapter(adapter)
+
+    cid = str(uuid4())
+    projection.register_session(
+        "sess-1", connection_id=cid, destination_id="chat-1",
+        tags=frozenset({"remote_origin"}),
+    )
+    projection.begin_phone_turn(
+        "sess-1", connection_id=cid, destination_id="chat-1",
+        principal_id="user-1", title="Fix tests", status="accepted",
+    )
+    # Make the very first send fail so it never lands in _sent_correlations.
+    adapter.fail_send_correlations.add(
+        projection._turns["sess-1"].lifecycle_correlation_id
+    )
+    await asyncio.sleep(0.05)
+    assert adapter.calls == []
+    assert adapter.sent == []
+
+    adapter.fail_send_correlations.clear()
+    projection.begin_phone_turn(
+        "sess-1", connection_id=cid, destination_id="chat-1",
+        principal_id="user-1", title="Fix tests", status="queued",
+    )
+    await asyncio.sleep(0.05)
+
+    # A fresh send, not an edit — nothing existed yet to edit.
+    assert adapter.calls == ["send"]
+
+    projection.observe("sess-1", _envelope("done", text="Done."))
+    await projection.drain_pending()
+    assert projection.typing_task_for("sess-1") is None
+
+
+@pytest.mark.asyncio
+async def test_finalize_falls_back_to_send_when_status_card_was_never_sent() -> None:
+    """Same fallback, exercised at the done/error edge instead of a
+    follow-up admission: if the status card's send never succeeded, the
+    final card must still reach the user as a new message."""
+    projection = RemoteProjection()
+    adapter = FakeAdapter()
+    projection.set_adapter(adapter)
+
+    cid = str(uuid4())
+    projection.register_session(
+        "sess-1", connection_id=cid, destination_id="chat-1",
+        tags=frozenset({"remote_origin"}),
+    )
+    projection.begin_phone_turn(
+        "sess-1", connection_id=cid, destination_id="chat-1",
+        principal_id="user-1", title="Fix tests", status="accepted",
+    )
+    adapter.fail_send_correlations.add(
+        projection._turns["sess-1"].lifecycle_correlation_id
+    )
+    await asyncio.sleep(0.05)
+    assert adapter.sent == []
+
+    adapter.fail_send_correlations.clear()
+    projection.observe("sess-1", _envelope("done", text="Done."))
+    await projection.drain_pending()
+
+    assert adapter.calls == ["send"]
+    assert len(adapter.sent) == 1
+    assert "Fix tests" in adapter.sent[0].text
+
+
+@pytest.mark.asyncio
+async def test_set_adapter_none_stops_all_live_typing_tasks() -> None:
+    """Unbinding the adapter (runtime shutdown) must stop every in-flight
+    typing loop rather than leaving it calling a stale adapter reference
+    forever, since the done/error event that would normally stop it will
+    now never arrive."""
+    projection = RemoteProjection()
+    adapter = FakeAdapter()
+    projection.set_adapter(adapter)
+
+    cid = str(uuid4())
+    projection.register_session(
+        "sess-1", connection_id=cid, destination_id="chat-1",
+        tags=frozenset({"remote_origin"}),
+    )
+    projection.begin_phone_turn(
+        "sess-1", connection_id=cid, destination_id="chat-1",
+        principal_id="user-1", title="Fix tests", status="accepted",
+    )
+    await asyncio.sleep(0.05)
+    typing_task = projection.typing_task_for("sess-1")
+    assert typing_task is not None
+
+    projection.set_adapter(None)
+    await asyncio.sleep(0)
+
+    assert projection.typing_task_for("sess-1") is None
+    assert typing_task.cancelled() or typing_task.done()
+
+
+@pytest.mark.asyncio
+async def test_typing_loop_survives_indicate_typing_error() -> None:
+    """A transient transport error from indicate_typing must not kill the
+    typing loop for the rest of the turn — it should log and keep going on
+    the next tick."""
+    projection = RemoteProjection()
+    adapter = FakeAdapter()
+    adapter.typing_failures_remaining = 1
+    projection.set_adapter(adapter)
+
+    cid = str(uuid4())
+    projection.register_session(
+        "sess-1", connection_id=cid, destination_id="chat-1",
+        tags=frozenset({"remote_origin"}),
+    )
+    projection.begin_phone_turn(
+        "sess-1", connection_id=cid, destination_id="chat-1",
+        principal_id="user-1", title="Fix tests", status="accepted",
+    )
+    await asyncio.sleep(0.05)
+
+    # The loop's first indicate_typing call raised and was swallowed; the
+    # task must still be alive (not crashed) to try again on its next tick.
+    assert adapter.typing_calls == 1
+    typing_task = projection.typing_task_for("sess-1")
+    assert typing_task is not None
+    assert not typing_task.done()
+
+    projection.set_adapter(None)
+    await asyncio.sleep(0)
+
+
+@pytest.mark.asyncio
+async def test_unregister_session_stops_typing_task() -> None:
+    projection = RemoteProjection()
+    adapter = FakeAdapter()
+    projection.set_adapter(adapter)
+
+    cid = str(uuid4())
+    projection.register_session(
+        "sess-1", connection_id=cid, destination_id="chat-1",
+        tags=frozenset({"remote_origin"}),
+    )
+    projection.begin_phone_turn(
+        "sess-1", connection_id=cid, destination_id="chat-1",
+        principal_id="user-1", title="Fix tests", status="accepted",
+    )
+    typing_task = projection.typing_task_for("sess-1")
+    assert typing_task is not None
+
+    projection.unregister_session("sess-1")
+
+    assert typing_task.cancelled() or typing_task.cancelling() > 0
+
+
+@pytest.mark.asyncio
+async def test_clear_turn_stops_typing_task() -> None:
+    projection = RemoteProjection()
+    adapter = FakeAdapter()
+    projection.set_adapter(adapter)
+
+    cid = str(uuid4())
+    projection.register_session(
+        "sess-1", connection_id=cid, destination_id="chat-1",
+        tags=frozenset({"remote_origin"}),
+    )
+    projection.begin_phone_turn(
+        "sess-1", connection_id=cid, destination_id="chat-1",
+        principal_id="user-1", title="Fix tests", status="accepted",
+    )
+    typing_task = projection.typing_task_for("sess-1")
+    assert typing_task is not None
+
+    projection.clear_turn("sess-1")
+
+    assert typing_task.cancelled() or typing_task.cancelling() > 0
+
+
+@pytest.mark.asyncio
+async def test_done_for_registered_but_never_begun_turn_uses_task_fallback_title() -> None:
+    """A session that's register_session-ed but never begin_phone_turn-ed
+    (e.g. desktop-started work the phone is only observing) has no real
+    title to draw on — the card must fall back to "Task" instead of
+    rendering blank."""
+    proj = RemoteProjection()
+    adapter = FakeAdapter()
+    proj.set_adapter(adapter)
+
+    cid = str(uuid4())
+    proj.register_session(
+        "sess-1", connection_id=cid, destination_id="12345",
+        tags=frozenset({"remote_origin"}),
+    )
+    proj.observe("sess-1", _envelope("done", text="Here is the result."))
+    await proj.drain_pending()
+
+    assert len(adapter.sent) == 1
+    assert "Task" in adapter.sent[0].text
+
+
 # ── gate events ──────────────────────────────────────────────────────────
 
 

From 7983ca0c867a316c1dcbbd4dd84648af4ccb93ad Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Mon, 14 Sep 2026 22:10:20 +0700
Subject: [PATCH 20/71] fix(remote): harden status lifecycle and cross-origin
 delivery

---
 app/remote/outbound.py              | 235 ++++++++++++++++----
 app/remote/runtime.py               |   6 +-
 documents/features/remote-access.md |  49 ++++-
 tests/remote/test_outbound.py       | 319 +++++++++++++++++++++++++---
 tests/remote/test_turn_activity.py  |  12 +-
 5 files changed, 536 insertions(+), 85 deletions(-)

diff --git a/app/remote/outbound.py b/app/remote/outbound.py
index 0d140a57..680efaee 100644
--- a/app/remote/outbound.py
+++ b/app/remote/outbound.py
@@ -23,9 +23,9 @@
 import asyncio
 import time
 import uuid
-from dataclasses import dataclass, field
+from dataclasses import dataclass, field, replace
 from datetime import UTC, datetime
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Protocol
 from uuid import UUID
 
 from loguru import logger
@@ -36,13 +36,32 @@
     RemoteOutboundMessage,
     RemoteOutboundPriority,
 )
-from app.remote.formatting import render_done_card, render_error_card, render_status_card
+from app.remote.formatting import (
+    render_done_card,
+    render_error_card,
+    render_status_card,
+)
 from app.remote.turn_activity import load_turn_activity
 
 if TYPE_CHECKING:
-    from app.remote.actions import RemoteActionService
     from app.remote.gates import RemoteGateBridge
 
+
+class _CapabilityRegistrar(Protocol):
+    """The Task 6 capability-minting surface used by completion cards."""
+
+    def register_capability(
+        self,
+        *,
+        connection_id: UUID | str,
+        principal_id: str,
+        destination_id: str,
+        session_id: str,
+        action_kind: str,
+        action_target: str,
+    ) -> str: ...
+
+
 #: Telegram's maximum message length in characters.
 _TELEGRAM_MAX_MESSAGE_LENGTH = 4096
 
@@ -102,13 +121,15 @@ class RemoteProjection:
     #: until that wiring lands — every use guards on it and treats a missing
     #: service as "no button" (``formatting.py``'s card builders already
     #: omit a button for a ``None`` token).
-    _actions: "RemoteActionService | None" = field(default=None, repr=False)
+    _actions: _CapabilityRegistrar | None = field(default=None, repr=False)
     _turns: dict[str, _TurnDeliveryState] = field(default_factory=dict, repr=False)
     _session_tags: dict[str, frozenset[str]] = field(default_factory=dict, repr=False)
     _session_connection_ids: dict[str, str] = field(default_factory=dict, repr=False)
     _session_destination_ids: dict[str, str] = field(default_factory=dict, repr=False)
     _pending: list[RemoteOutboundMessage] = field(default_factory=list, repr=False)
-    _pending_edits: list[RemoteOutboundMessage] = field(default_factory=list, repr=False)
+    _pending_edits: list[RemoteOutboundMessage] = field(
+        default_factory=list, repr=False
+    )
     #: Turns whose ``done``/``error`` event has been observed but whose
     #: final card hasn't been built and delivered yet — building it needs a
     #: database query (:func:`~app.remote.turn_activity.load_turn_activity`),
@@ -119,10 +140,13 @@ class RemoteProjection:
     _pending_finalizations: list[tuple[_TurnDeliveryState, str | None]] = field(
         default_factory=list, repr=False
     )
-    #: Reserved for a later task's unaddressed-delivery drain (Task 5);
-    #: unused by this task beyond being cleared alongside the other queues
-    #: when no adapter is bound.
-    _unaddressed_pending: list[object] = field(default_factory=list, repr=False)
+    #: Completion/error events for sessions that have no remote-origin
+    #: registration. Addressability requires a database read, so these stay
+    #: queued until :meth:`_drain_unaddressed` can validate them off the
+    #: synchronous stream-observer path.
+    _unaddressed_pending: list[tuple[str, str, str, str, str, dict]] = field(
+        default_factory=list, repr=False
+    )
     #: Serializes the whole of :meth:`drain_pending` so two concurrently
     #: scheduled drains (e.g. a status-card send and a same-turn done-card
     #: edit, each fired by its own ``_schedule_drain``) can never interleave
@@ -149,9 +173,7 @@ class RemoteProjection:
     #: pairing's own principal is the only valid actor for the whole
     #: connection regardless of which surface (phone or desktop) started the
     #: work being notified about.
-    _active_pairing: tuple[str, str, str, str] | None = field(
-        default=None, repr=False
-    )
+    _active_pairing: tuple[str, str, str, str] | None = field(default=None, repr=False)
 
     def set_adapter(self, adapter: RemoteAdapter | None) -> None:
         """Bind or unbind the live adapter. Called by the runtime on start/stop.
@@ -246,21 +268,28 @@ def begin_phone_turn(
         turn's typing task, this reuses the still-unresolved turn's
         message: stop its typing task and carry its
         ``lifecycle_correlation_id`` forward so the *same* message is
-        edited with the new status text. A fresh message is only sent when
-        there is no unresolved turn to reuse, or its original status card
-        was never confirmed sent (nothing to edit).
+        edited with the new status text. If the original status card is
+        still queued locally, its pending payload is replaced before any
+        network delivery; a fresh message is only sent when there is no
+        reusable unresolved turn or its original send has already failed.
         """
         existing = self._turns.get(session_id)
         reuse_correlation_id: str | None = None
         if existing is not None and not existing.completion_sent:
             self._stop_typing(existing)
-            if (
-                existing.lifecycle_correlation_id is not None
-                and existing.lifecycle_correlation_id in self._sent_correlations
+            existing_correlation_id = existing.lifecycle_correlation_id
+            if existing_correlation_id is not None and (
+                existing_correlation_id in self._sent_correlations
+                or any(
+                    pending.correlation_id == existing_correlation_id
+                    for pending in self._pending
+                )
             ):
-                reuse_correlation_id = existing.lifecycle_correlation_id
+                reuse_correlation_id = existing_correlation_id
 
-        correlation_id = reuse_correlation_id or f"status:{session_id}:{uuid.uuid4().hex[:8]}"
+        correlation_id = (
+            reuse_correlation_id or f"status:{session_id}:{uuid.uuid4().hex[:8]}"
+        )
         turn = _TurnDeliveryState(
             session_id=session_id,
             connection_id=connection_id,
@@ -272,13 +301,19 @@ def begin_phone_turn(
         )
         self._turns[session_id] = turn
         text, buttons = render_status_card(title=title, status=status)
-        if reuse_correlation_id is not None:
+        if reuse_correlation_id in self._sent_correlations:
             self._enqueue_edit(
                 destination_id=destination_id,
                 text=text,
                 buttons=buttons,
                 correlation_id=reuse_correlation_id,
             )
+        elif reuse_correlation_id is not None:
+            self._replace_pending_status(
+                correlation_id=reuse_correlation_id,
+                text=text,
+                buttons=buttons,
+            )
         else:
             self._enqueue_send(
                 destination_id=destination_id,
@@ -326,6 +361,20 @@ def typing_task_for(self, session_id: str) -> "asyncio.Task[None] | None":
         turn = self._turns.get(session_id)
         return turn.typing_task if turn is not None else None
 
+    def _replace_pending_status(
+        self,
+        *,
+        correlation_id: str,
+        text: str,
+        buttons: tuple[RemoteButton, ...],
+    ) -> None:
+        """Update an unsent lifecycle card without creating a second card."""
+        for index, pending in enumerate(self._pending):
+            if pending.correlation_id == correlation_id:
+                self._pending[index] = replace(pending, text=text, buttons=buttons)
+                return
+        raise RuntimeError("reusable status correlation is not pending")
+
     def _stop_typing(self, turn: _TurnDeliveryState) -> None:
         if turn.typing_task is not None and not turn.typing_task.done():
             turn.typing_task.cancel()
@@ -336,16 +385,30 @@ def observe(self, session_id: str, envelope) -> None:
 
         Must be non-blocking.  Enqueues delivery work for the adapter.
         """
+        event_type = envelope.event
+        if event_type not in _OBSERVED_EVENT_TYPES:
+            return
+
         tags = self._session_tags.get(session_id)
         if tags is None:
+            active = self._active_pairing
+            if active is None or active[2] != "all":
+                return
+            if event_type not in {"done", "error"}:
+                return
+            connection_id, destination_id, _, principal_id = active
+            self._enqueue_unregistered_completion(
+                session_id=session_id,
+                connection_id=connection_id,
+                destination_id=destination_id,
+                principal_id=principal_id,
+                event_type=event_type,
+                envelope_data=dict(envelope.data),
+            )
             return
         if "remote_origin" not in tags:
             return
 
-        event_type = envelope.event
-        if event_type not in _OBSERVED_EVENT_TYPES:
-            return
-
         connection_id = self._session_connection_ids.get(session_id, "")
         destination_id = self._session_destination_ids.get(session_id, "")
         if not connection_id or not destination_id:
@@ -383,6 +446,29 @@ def observe(self, session_id: str, envelope) -> None:
             if self._bridge is not None:
                 self._bridge.on_reply(session_id, event_type, envelope.data)
 
+    def _enqueue_unregistered_completion(
+        self,
+        *,
+        session_id: str,
+        connection_id: str,
+        destination_id: str,
+        principal_id: str,
+        event_type: str,
+        envelope_data: dict,
+    ) -> None:
+        """Queue a completion until the async path confirms addressability."""
+        self._unaddressed_pending.append(
+            (
+                session_id,
+                connection_id,
+                destination_id,
+                principal_id,
+                event_type,
+                envelope_data,
+            )
+        )
+        self._schedule_drain()
+
     def _handle_done(self, turn: _TurnDeliveryState, envelope) -> None:
         if turn.completion_sent:
             return
@@ -463,7 +549,9 @@ async def _finalize_turn(
         # TelegramAdapter.edit's ``_sent_messages`` lookup), which would
         # otherwise lose the final card entirely.
         correlation_id = turn.lifecycle_correlation_id
-        was_sent = correlation_id is not None and correlation_id in self._sent_correlations
+        was_sent = (
+            correlation_id is not None and correlation_id in self._sent_correlations
+        )
         if correlation_id is not None:
             self._sent_correlations.discard(correlation_id)
 
@@ -594,6 +682,8 @@ def _any_connection_id(self) -> str:
         """
         for cid in self._session_connection_ids.values():
             return cid
+        if self._active_pairing is not None:
+            return self._active_pairing[0]
         return ""
 
     def _schedule_drain(self) -> None:
@@ -605,8 +695,8 @@ def _schedule_drain(self) -> None:
             pass
 
     async def drain_pending(self) -> None:
-        """Finalize completed turns, then send/edit all pending messages
-        through the adapter.
+        """Send queued status cards, finalize completed turns, then send or
+        edit their final cards through the adapter.
 
         Serialized by :attr:`_drain_lock`: ``_enqueue_send``/``_enqueue_edit``/
         ``_handle_done``/``_handle_error`` each fire-and-forget their own
@@ -624,6 +714,8 @@ async def drain_pending(self) -> None:
                 self._unaddressed_pending.clear()
                 self._sent_correlations.clear()
                 return
+            await self._drain_unaddressed()
+            await self._drain_sends(adapter)
             while self._pending_finalizations:
                 turn, error_message = self._pending_finalizations.pop(0)
                 try:
@@ -634,19 +726,11 @@ async def drain_pending(self) -> None:
                         turn.session_id,
                         exc,
                     )
-            while self._pending:
-                msg = self._pending.pop(0)
-                try:
-                    await adapter.send(msg)
-                except Exception as exc:
-                    logger.warning(
-                        "remote_outbound_send_failed destination_id={} error={}",
-                        msg.destination_id,
-                        exc,
-                    )
-                else:
-                    if msg.correlation_id is not None:
-                        self._sent_correlations.add(msg.correlation_id)
+            # Finalization can enqueue a fallback completion send when the
+            # status send failed, so drain that work before the final-card
+            # edit queue. A successful status send is already recorded above,
+            # letting _finalize_turn choose its one in-place edit instead.
+            await self._drain_sends(adapter)
             while self._pending_edits:
                 msg = self._pending_edits.pop(0)
                 try:
@@ -657,12 +741,71 @@ async def drain_pending(self) -> None:
                         msg.destination_id,
                         exc,
                     )
-            await self._drain_unaddressed()
+
+    async def _drain_sends(self, adapter: RemoteAdapter) -> None:
+        """Deliver all currently queued sends and record confirmed cards."""
+        while self._pending:
+            msg = self._pending.pop(0)
+            try:
+                await adapter.send(msg)
+            except Exception as exc:
+                logger.warning(
+                    "remote_outbound_send_failed destination_id={} error={}",
+                    msg.destination_id,
+                    exc,
+                )
+            else:
+                if msg.correlation_id is not None:
+                    self._sent_correlations.add(msg.correlation_id)
 
     async def _drain_unaddressed(self) -> None:
-        """Placeholder for a later task's unaddressed-delivery drain
-        (Task 5) — a no-op until that task replaces this body."""
-        return
+        """Deliver validated desktop/workflow completion cards asynchronously."""
+        from app.core.db import async_session_factory
+        from app.models.chat import ChatSession
+        from app.remote.inbound import _is_addressable_session
+
+        pending, self._unaddressed_pending = self._unaddressed_pending, []
+        for (
+            session_id,
+            connection_id,
+            destination_id,
+            principal_id,
+            event_type,
+            envelope_data,
+        ) in pending:
+            try:
+                chat_session_id = UUID(session_id)
+            except ValueError:
+                logger.warning(
+                    "remote_unaddressed_invalid_session_id session_id={}", session_id
+                )
+                continue
+            async with async_session_factory() as db:
+                session_row = await db.get(ChatSession, chat_session_id)
+            if session_row is None or not _is_addressable_session(session_row):
+                continue
+
+            turn = self._turns.get(session_id)
+            if turn is None:
+                turn = _TurnDeliveryState(
+                    session_id=session_id,
+                    connection_id=connection_id,
+                    destination_id=destination_id,
+                    principal_id=principal_id,
+                    title=session_row.title or "Task",
+                )
+                self._turns[session_id] = turn
+            if turn.completion_sent:
+                continue
+            turn.completion_sent = True
+            await self._finalize_turn(
+                turn,
+                error_message=(
+                    None
+                    if event_type == "done"
+                    else envelope_data.get("message", "An error occurred.")
+                ),
+            )
 
     def clear_turn(self, session_id: str) -> None:
         """Clear delivery state for a completed turn."""
diff --git a/app/remote/runtime.py b/app/remote/runtime.py
index 36fe87c8..ea55e0ee 100644
--- a/app/remote/runtime.py
+++ b/app/remote/runtime.py
@@ -532,7 +532,11 @@ async def _handle_text(self, action: RemoteInboundAction) -> None:
                 connection_id=str(action.connection_id),
                 destination_id=action.principal.destination_id,
                 principal_id=action.principal.principal_id,
-                title=(session_row.title if session_row and session_row.title else "New task"),
+                title=(
+                    session_row.title
+                    if session_row and session_row.title
+                    else "New task"
+                ),
                 status=result.status,
             )
 
diff --git a/documents/features/remote-access.md b/documents/features/remote-access.md
index 59cf2a65..33758be3 100644
--- a/documents/features/remote-access.md
+++ b/documents/features/remote-access.md
@@ -18,7 +18,9 @@ to continue.
 2. **Current-task text** — the bot shows what the active session is doing so the
    user can decide without opening the desktop.
 3. **Automatic gates and completion** — permission requests, questions, and plan
-   review arrive as inline-button messages; completion summaries arrive as text.
+   review arrive as inline-button messages. Phone-started turns get one live
+   status card plus a native typing indicator; their final completion or error
+   card edits that same message in place.
 4. **Safe redaction** — every outbound message passes through
    `protect_outbound_text(channel="remote")` so secrets and PII never leave the
    machine.
@@ -47,8 +49,24 @@ to continue.
 1. User sends a message to the bot on Telegram.
 2. The remote adapter polls `getUpdates`, matches the `chat_id` to a pairing,
    and forwards the text into the active session as a user message.
-3. The agent responds; the adapter projects the response text into the Telegram
-   chat.
+3. The adapter immediately sends one HTML-formatted status card and repeats
+   Telegram's native typing indicator while the phone-started turn is unresolved.
+   The status card contains only the task title and admission status.
+4. On completion or error, the adapter edits that card into a bounded final
+   summary. It never mirrors token, tool, or file-path deltas into the live
+   status text.
+
+### Desktop, Workflow, and Scheduler completion
+
+- The pairing's persisted notification scope defaults to `all`. Under that
+  scope, an addressable top-level Work or Coding session started from the
+  desktop, Workflow, or Scheduler sends the same final completion/error card
+  to the paired phone.
+- These cross-origin sessions never create a live status card or typing
+  indicator. Side Chat, child, internal, and otherwise non-addressable
+  sessions never notify the phone.
+- The `remote_only` scope keeps notifications limited to `remote_origin`
+  sessions.
 
 ### Gate flow
 
@@ -64,8 +82,12 @@ to continue.
 
 ## Requirements and acceptance criteria
 
-Requirements and acceptance criteria are defined in the implementation plan as
-AC-1 through AC-36. They cover:
+Requirements and acceptance criteria are defined in the base implementation
+plan as AC-1 through AC-36 and amended by the response-UI specification. The
+implemented response-UI additions are AC-38 (bounded phone-turn lifecycle),
+AC-42 (notification scope), and AC-43 (cross-origin completion delivery).
+The status, done, and error-card paths also implement the response-card portion
+of revised AC-24. They cover:
 
 - Connection lifecycle (create, verify, update label, replace token, delete)
 - Pairing lifecycle (link, QR, resolve, revoke)
@@ -77,6 +99,10 @@ AC-1 through AC-36. They cover:
 - Connection states (11 values covering setup through error)
 - One connection per installation (v1)
 - Migration `00000064`
+- HTML-safe Telegram cards, native typing, and one status-card lifecycle for
+  phone-started turns
+- Addressability-gated final delivery for desktop, Workflow, and Scheduler
+  sessions when notification scope is `all`
 
 ## API, event, tool, and UI contracts
 
@@ -152,6 +178,7 @@ id, connection_id, chat_id, principal_id, state, paired_at
 | `destination_id` | text | addresses the pairing |
 | `state` | enum | `pending` → `paired` → `revoked` |
 | `source_key` | text | idempotency key for `getUpdates` offset |
+| `notify_scope` | text | `all` (default) or `remote_only`; controls cross-origin final notifications |
 | `paired_at` | timestamp | |
 
 ### OS vault
@@ -167,8 +194,10 @@ a vault key reference, never the raw token.
   `always` option for remote — every remote approval is single-use.
 - **Outbound redaction**: all outbound text passes through
   `protect_outbound_text(channel="remote")` before reaching Telegram.
-- **No parse mode**: Telegram messages are sent without parse mode so model
-  output is never interpreted as markup.
+- **Safe HTML response cards**: the status, done, and error-card builders use
+  Telegram HTML parse mode only after outbound redaction. Every non-static
+  value passed to those builders is escaped by `app/remote/formatting.py`, so
+  agent or user content cannot create markup, links, or mentions.
 - **Private chats only**: the adapter only processes private (non-group) chats.
 - **Authorization model**: `principal_id` authorizes who can reply;
   `destination_id` addresses which pairing receives the message.
@@ -186,6 +215,12 @@ a vault key reference, never the raw token.
   messages.
 - **Adapter crash recovery**: on startup the adapter resumes polling from the
   last persisted offset; no messages are lost if the process restarts.
+- **Lifecycle ordering**: outbound delivery serializes queued status sends,
+  finalization, and edits. A final card falls back to a new message only when
+  its original status card could not be delivered.
+- **Cross-origin authorization**: the synchronous stream observer queues an
+  unregistered completion, then the asynchronous delivery path loads the
+  session and applies the shared addressability predicate before sending.
 
 ## Observability
 
diff --git a/tests/remote/test_outbound.py b/tests/remote/test_outbound.py
index 14ca4d33..65caae32 100644
--- a/tests/remote/test_outbound.py
+++ b/tests/remote/test_outbound.py
@@ -6,7 +6,10 @@
 from uuid import uuid4
 
 import pytest
+import pytest_asyncio
 
+import app.core.db as db_module
+from app.models.chat import ChatSession
 from app.remote.contracts import (
     RemoteAdapterStatus,
     RemoteConnectionState,
@@ -66,6 +69,26 @@ def status(self) -> RemoteAdapterStatus:
         )
 
 
+@pytest_asyncio.fixture
+async def addressable_session() -> ChatSession:
+    async with db_module.async_session_factory() as db:
+        session = ChatSession(title="Desktop task", mode="work", session_type="main")
+        db.add(session)
+        await db.commit()
+        await db.refresh(session)
+        return session
+
+
+@pytest_asyncio.fixture
+async def side_chat_session() -> ChatSession:
+    async with db_module.async_session_factory() as db:
+        session = ChatSession(title="Private side chat", session_type="side_chat")
+        db.add(session)
+        await db.commit()
+        await db.refresh(session)
+        return session
+
+
 # ── session registration ─────────────────────────────────────────────────
 
 
@@ -202,6 +225,119 @@ async def test_error_sends_error_message() -> None:
     assert "Something went wrong" in adapter.sent[0].text
 
 
+# ── cross-origin completion delivery ─────────────────────────────────────
+
+
+@pytest.mark.asyncio
+async def test_unregistered_addressable_session_notifies_when_scope_is_all(
+    addressable_session: ChatSession,
+) -> None:
+    projection = RemoteProjection()
+    adapter = FakeAdapter()
+    projection.set_adapter(adapter)
+    connection_id = str(uuid4())
+    projection.set_active_pairing(
+        connection_id=connection_id,
+        destination_id="chat-1",
+        notify_scope="all",
+        principal_id="user-1",
+    )
+
+    projection.observe(str(addressable_session.id), _envelope("done", text="Done."))
+    await projection.drain_pending()
+
+    assert adapter.calls == ["send"]
+    assert adapter.sent[0].destination_id == "chat-1"
+    assert str(adapter.sent[0].connection_id) == connection_id
+    assert projection.typing_task_for(str(addressable_session.id)) is None
+
+
+@pytest.mark.asyncio
+async def test_unregistered_session_is_silent_when_scope_is_remote_only(
+    addressable_session: ChatSession,
+) -> None:
+    projection = RemoteProjection()
+    adapter = FakeAdapter()
+    projection.set_adapter(adapter)
+    projection.set_active_pairing(
+        connection_id=str(uuid4()),
+        destination_id="chat-1",
+        notify_scope="remote_only",
+        principal_id="user-1",
+    )
+
+    projection.observe(str(addressable_session.id), _envelope("done", text="Done."))
+    await projection.drain_pending()
+
+    assert adapter.calls == []
+    assert projection.typing_task_for(str(addressable_session.id)) is None
+
+
+@pytest.mark.asyncio
+async def test_non_addressable_session_never_notifies_even_with_scope_all(
+    side_chat_session: ChatSession,
+) -> None:
+    projection = RemoteProjection()
+    adapter = FakeAdapter()
+    projection.set_adapter(adapter)
+    projection.set_active_pairing(
+        connection_id=str(uuid4()),
+        destination_id="chat-1",
+        notify_scope="all",
+        principal_id="user-1",
+    )
+
+    projection.observe(str(side_chat_session.id), _envelope("done", text="Done."))
+    await projection.drain_pending()
+
+    assert adapter.calls == []
+    assert projection.typing_task_for(str(side_chat_session.id)) is None
+
+
+@pytest.mark.asyncio
+async def test_unregistered_addressable_error_sends_one_error_card(
+    addressable_session: ChatSession,
+) -> None:
+    projection = RemoteProjection()
+    adapter = FakeAdapter()
+    projection.set_adapter(adapter)
+    projection.set_active_pairing(
+        connection_id=str(uuid4()),
+        destination_id="chat-1",
+        notify_scope="all",
+        principal_id="user-1",
+    )
+
+    projection.observe(
+        str(addressable_session.id), _envelope("error", message="Workflow failed")
+    )
+    await projection.drain_pending()
+
+    assert adapter.calls == ["send"]
+    assert "Workflow failed" in adapter.sent[0].text
+
+
+@pytest.mark.asyncio
+async def test_duplicate_unregistered_completions_send_one_card(
+    addressable_session: ChatSession,
+) -> None:
+    projection = RemoteProjection()
+    adapter = FakeAdapter()
+    projection.set_adapter(adapter)
+    projection.set_active_pairing(
+        connection_id=str(uuid4()),
+        destination_id="chat-1",
+        notify_scope="all",
+        principal_id="user-1",
+    )
+
+    projection.observe(str(addressable_session.id), _envelope("done", text="First"))
+    projection.observe(str(addressable_session.id), _envelope("done", text="Second"))
+    await projection.drain_pending()
+
+    assert adapter.calls == ["send"]
+
+
 # ── phone-admitted status lifecycle ─────────────────────────────────────
 
 
@@ -239,6 +375,39 @@ async def test_begin_phone_turn_sends_status_card_then_done_edits_it() -> None:
     assert projection.typing_task_for("sess-1") is None
 
 
+@pytest.mark.asyncio
+async def test_immediate_done_edits_queued_phone_status_card() -> None:
+    """A completion that races the initial delivery must not create a
+    second card: the queued status card is delivered first, then edited."""
+    projection = RemoteProjection()
+    adapter = FakeAdapter()
+    projection.set_adapter(adapter)
+
+    cid = str(uuid4())
+    projection.register_session(
+        "sess-1",
+        connection_id=cid,
+        destination_id="chat-1",
+        tags=frozenset({"remote_origin"}),
+    )
+    projection.begin_phone_turn(
+        "sess-1",
+        connection_id=cid,
+        destination_id="chat-1",
+        principal_id="user-1",
+        title="Fix tests",
+        status="accepted",
+    )
+    projection.observe("sess-1", _envelope("done", text="Done."))
+
+    await projection.drain_pending()
+
+    assert adapter.calls == ["send", "edit"]
+    assert len(adapter.sent) == 1
+    assert len(adapter.edited) == 1
+    assert adapter.edited[0].correlation_id == adapter.sent[0].correlation_id
+
+
 @pytest.mark.asyncio
 async def test_begin_phone_turn_error_edits_status_with_error_card() -> None:
     projection = RemoteProjection()
@@ -309,12 +478,18 @@ async def test_begin_phone_turn_again_before_resolution_reuses_status_card() ->
 
     cid = str(uuid4())
     projection.register_session(
-        "sess-1", connection_id=cid, destination_id="chat-1",
+        "sess-1",
+        connection_id=cid,
+        destination_id="chat-1",
         tags=frozenset({"remote_origin"}),
     )
     projection.begin_phone_turn(
-        "sess-1", connection_id=cid, destination_id="chat-1",
-        principal_id="user-1", title="Fix tests", status="accepted",
+        "sess-1",
+        connection_id=cid,
+        destination_id="chat-1",
+        principal_id="user-1",
+        title="Fix tests",
+        status="accepted",
     )
     await asyncio.sleep(0.05)
     assert adapter.calls == ["send"]
@@ -323,8 +498,12 @@ async def test_begin_phone_turn_again_before_resolution_reuses_status_card() ->
     assert first_typing_task is not None
 
     projection.begin_phone_turn(
-        "sess-1", connection_id=cid, destination_id="chat-1",
-        principal_id="user-1", title="Fix tests", status="queued",
+        "sess-1",
+        connection_id=cid,
+        destination_id="chat-1",
+        principal_id="user-1",
+        title="Fix tests",
+        status="queued",
     )
     await asyncio.sleep(0.05)
 
@@ -350,7 +529,47 @@ async def test_begin_phone_turn_again_before_resolution_reuses_status_card() ->
 
 
 @pytest.mark.asyncio
-async def test_begin_phone_turn_reuse_falls_back_to_send_if_original_never_sent() -> None:
+async def test_queued_follow_up_replaces_unsent_status_card() -> None:
+    """A follow-up admitted before delivery updates the pending status card
+    instead of emitting an orphaned first status message."""
+    projection = RemoteProjection()
+    adapter = FakeAdapter()
+    projection.set_adapter(adapter)
+
+    cid = str(uuid4())
+    projection.register_session(
+        "sess-1",
+        connection_id=cid,
+        destination_id="chat-1",
+        tags=frozenset({"remote_origin"}),
+    )
+    projection.begin_phone_turn(
+        "sess-1",
+        connection_id=cid,
+        destination_id="chat-1",
+        principal_id="user-1",
+        title="Fix tests",
+        status="accepted",
+    )
+    projection.begin_phone_turn(
+        "sess-1",
+        connection_id=cid,
+        destination_id="chat-1",
+        principal_id="user-1",
+        title="Fix tests",
+        status="queued",
+    )
+
+    await projection.drain_pending()
+
+    assert adapter.calls == ["send"]
+    assert "queued" in adapter.sent[0].text
+
+
+@pytest.mark.asyncio
+async def test_begin_phone_turn_reuse_falls_back_to_send_if_original_never_sent() -> (
+    None
+):
     """If the first status card's send never actually succeeded (e.g. a
     transient transport failure), there is nothing for a follow-up edit to
     land on — must send a fresh message instead of silently no-op'ing."""
@@ -360,12 +579,18 @@ async def test_begin_phone_turn_reuse_falls_back_to_send_if_original_never_sent(
 
     cid = str(uuid4())
     projection.register_session(
-        "sess-1", connection_id=cid, destination_id="chat-1",
+        "sess-1",
+        connection_id=cid,
+        destination_id="chat-1",
         tags=frozenset({"remote_origin"}),
     )
     projection.begin_phone_turn(
-        "sess-1", connection_id=cid, destination_id="chat-1",
-        principal_id="user-1", title="Fix tests", status="accepted",
+        "sess-1",
+        connection_id=cid,
+        destination_id="chat-1",
+        principal_id="user-1",
+        title="Fix tests",
+        status="accepted",
     )
     # Make the very first send fail so it never lands in _sent_correlations.
     adapter.fail_send_correlations.add(
@@ -377,8 +602,12 @@ async def test_begin_phone_turn_reuse_falls_back_to_send_if_original_never_sent(
 
     adapter.fail_send_correlations.clear()
     projection.begin_phone_turn(
-        "sess-1", connection_id=cid, destination_id="chat-1",
-        principal_id="user-1", title="Fix tests", status="queued",
+        "sess-1",
+        connection_id=cid,
+        destination_id="chat-1",
+        principal_id="user-1",
+        title="Fix tests",
+        status="queued",
     )
     await asyncio.sleep(0.05)
 
@@ -401,12 +630,18 @@ async def test_finalize_falls_back_to_send_when_status_card_was_never_sent() ->
 
     cid = str(uuid4())
     projection.register_session(
-        "sess-1", connection_id=cid, destination_id="chat-1",
+        "sess-1",
+        connection_id=cid,
+        destination_id="chat-1",
         tags=frozenset({"remote_origin"}),
     )
     projection.begin_phone_turn(
-        "sess-1", connection_id=cid, destination_id="chat-1",
-        principal_id="user-1", title="Fix tests", status="accepted",
+        "sess-1",
+        connection_id=cid,
+        destination_id="chat-1",
+        principal_id="user-1",
+        title="Fix tests",
+        status="accepted",
     )
     adapter.fail_send_correlations.add(
         projection._turns["sess-1"].lifecycle_correlation_id
@@ -435,12 +670,18 @@ async def test_set_adapter_none_stops_all_live_typing_tasks() -> None:
 
     cid = str(uuid4())
     projection.register_session(
-        "sess-1", connection_id=cid, destination_id="chat-1",
+        "sess-1",
+        connection_id=cid,
+        destination_id="chat-1",
         tags=frozenset({"remote_origin"}),
     )
     projection.begin_phone_turn(
-        "sess-1", connection_id=cid, destination_id="chat-1",
-        principal_id="user-1", title="Fix tests", status="accepted",
+        "sess-1",
+        connection_id=cid,
+        destination_id="chat-1",
+        principal_id="user-1",
+        title="Fix tests",
+        status="accepted",
     )
     await asyncio.sleep(0.05)
     typing_task = projection.typing_task_for("sess-1")
@@ -465,12 +706,18 @@ async def test_typing_loop_survives_indicate_typing_error() -> None:
 
     cid = str(uuid4())
     projection.register_session(
-        "sess-1", connection_id=cid, destination_id="chat-1",
+        "sess-1",
+        connection_id=cid,
+        destination_id="chat-1",
         tags=frozenset({"remote_origin"}),
     )
     projection.begin_phone_turn(
-        "sess-1", connection_id=cid, destination_id="chat-1",
-        principal_id="user-1", title="Fix tests", status="accepted",
+        "sess-1",
+        connection_id=cid,
+        destination_id="chat-1",
+        principal_id="user-1",
+        title="Fix tests",
+        status="accepted",
     )
     await asyncio.sleep(0.05)
 
@@ -493,12 +740,18 @@ async def test_unregister_session_stops_typing_task() -> None:
 
     cid = str(uuid4())
     projection.register_session(
-        "sess-1", connection_id=cid, destination_id="chat-1",
+        "sess-1",
+        connection_id=cid,
+        destination_id="chat-1",
         tags=frozenset({"remote_origin"}),
     )
     projection.begin_phone_turn(
-        "sess-1", connection_id=cid, destination_id="chat-1",
-        principal_id="user-1", title="Fix tests", status="accepted",
+        "sess-1",
+        connection_id=cid,
+        destination_id="chat-1",
+        principal_id="user-1",
+        title="Fix tests",
+        status="accepted",
     )
     typing_task = projection.typing_task_for("sess-1")
     assert typing_task is not None
@@ -516,12 +769,18 @@ async def test_clear_turn_stops_typing_task() -> None:
 
     cid = str(uuid4())
     projection.register_session(
-        "sess-1", connection_id=cid, destination_id="chat-1",
+        "sess-1",
+        connection_id=cid,
+        destination_id="chat-1",
         tags=frozenset({"remote_origin"}),
     )
     projection.begin_phone_turn(
-        "sess-1", connection_id=cid, destination_id="chat-1",
-        principal_id="user-1", title="Fix tests", status="accepted",
+        "sess-1",
+        connection_id=cid,
+        destination_id="chat-1",
+        principal_id="user-1",
+        title="Fix tests",
+        status="accepted",
     )
     typing_task = projection.typing_task_for("sess-1")
     assert typing_task is not None
@@ -532,7 +791,9 @@ async def test_clear_turn_stops_typing_task() -> None:
 
 
 @pytest.mark.asyncio
-async def test_done_for_registered_but_never_begun_turn_uses_task_fallback_title() -> None:
+async def test_done_for_registered_but_never_begun_turn_uses_task_fallback_title() -> (
+    None
+):
     """A session that's register_session-ed but never begin_phone_turn-ed
     (e.g. desktop-started work the phone is only observing) has no real
     title to draw on — the card must fall back to "Task" instead of
@@ -543,7 +804,9 @@ async def test_done_for_registered_but_never_begun_turn_uses_task_fallback_title
 
     cid = str(uuid4())
     proj.register_session(
-        "sess-1", connection_id=cid, destination_id="12345",
+        "sess-1",
+        connection_id=cid,
+        destination_id="12345",
         tags=frozenset({"remote_origin"}),
     )
     proj.observe("sess-1", _envelope("done", text="Here is the result."))
diff --git a/tests/remote/test_turn_activity.py b/tests/remote/test_turn_activity.py
index c205b636..d5e121d1 100644
--- a/tests/remote/test_turn_activity.py
+++ b/tests/remote/test_turn_activity.py
@@ -36,7 +36,9 @@ async def chat_session(db_session):
 
 
 @pytest.mark.asyncio
-async def test_load_turn_activity_counts_tool_calls_and_builds_diff(db_session, chat_session):
+async def test_load_turn_activity_counts_tool_calls_and_builds_diff(
+    db_session, chat_session
+):
     since = datetime.now(UTC) - timedelta(seconds=1)
     db_session.add_all(
         [
@@ -86,7 +88,9 @@ async def test_load_turn_activity_with_no_tool_calls_returns_placeholders(
 
 
 @pytest.mark.asyncio
-async def test_load_turn_activity_with_non_uuid_session_id_returns_placeholders(db_session):
+async def test_load_turn_activity_with_non_uuid_session_id_returns_placeholders(
+    db_session,
+):
     """A non-UUID session id (e.g. a test double's placeholder) can never
     match a persisted row, so this returns empty activity instead of
     raising — exercised because outbound.py's ``_finalize_turn`` calls this
@@ -101,7 +105,9 @@ async def test_load_turn_activity_with_non_uuid_session_id_returns_placeholders(
 
 
 @pytest.mark.asyncio
-async def test_load_turn_activity_ignores_messages_before_since(db_session, chat_session):
+async def test_load_turn_activity_ignores_messages_before_since(
+    db_session, chat_session
+):
     since = datetime.now(UTC)
     db_session.add(
         SessionMessage(

From c2dcc2bac739d959167fd1d4becc0383b5360c3f Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Mon, 14 Sep 2026 22:19:03 +0700
Subject: [PATCH 21/71] feat(remote): add Full diff and Tool log drill-down

---
 app/remote/actions.py               | 201 +++++++++++++++++++---------
 app/remote/outbound.py              |   4 +
 app/remote/runtime.py               |  11 +-
 documents/features/remote-access.md |  14 +-
 tests/remote/test_actions.py        | 164 ++++++++++++++++++++++-
 tests/remote/test_outbound.py       |  69 +++++++++-
 tests/remote/test_runtime.py        |  22 +++
 7 files changed, 416 insertions(+), 69 deletions(-)

diff --git a/app/remote/actions.py b/app/remote/actions.py
index 16c51dbc..5d502440 100644
--- a/app/remote/actions.py
+++ b/app/remote/actions.py
@@ -24,6 +24,7 @@
 
 from loguru import logger
 
+from app.remote import formatting
 from app.remote.contracts import (
     RemoteAdapter,
     RemoteButton,
@@ -41,6 +42,7 @@
 
 _MAX_CALLBACK_TOKEN_BYTES = 64
 _CAPABILITY_TTL_SECONDS = 600
+_TELEGRAM_MAX_MESSAGE_LENGTH = 4096
 
 CommandName = Literal["start", "help", "status", "new", "stop", "unpair", "actions"]
 
@@ -132,6 +134,26 @@ def set_projection(self, projection: "RemoteProjection | None") -> None:
         not just callback/menu tokens)."""
         self._projection = projection
 
+    def register_capability(
+        self,
+        *,
+        connection_id: UUID | str,
+        principal_id: str,
+        destination_id: str,
+        session_id: str,
+        action_kind: str,
+        action_target: str,
+    ) -> str:
+        """Register one short-lived, principal-bound detail action."""
+        return self._issue_token(
+            connection_id=UUID(str(connection_id)),
+            principal_id=principal_id,
+            destination_id=destination_id,
+            session_id=session_id,
+            action_kind=action_kind,
+            action_target=action_target,
+        )
+
     # ── Command dispatch ──────────────────────────────────────────────────
 
     async def dispatch_command(
@@ -171,6 +193,7 @@ async def dispatch_command(
     async def handle_action_callback(
         self,
         action: RemoteInboundAction,
+        db: AsyncSession,
     ) -> bool:
         """Handle a callback from a More-actions menu.
 
@@ -184,19 +207,36 @@ async def handle_action_callback(
         if cap is None:
             return False
 
-        if cap.connection_id != action.connection_id:
+        if (
+            cap.connection_id != action.connection_id
+            or cap.principal_id != action.principal.principal_id
+            or cap.destination_id != action.principal.destination_id
+        ):
             return False
 
+        # Acknowledge an authorized callback before any follow-up work so the
+        # provider stops showing its loading state even when the token expired.
+        if self._adapter is not None:
+            await self._adapter.answer_callback(token)
+
         if time.monotonic() - cap.created_at > _CAPABILITY_TTL_SECONDS:
             self._discard(cap)
+            if cap.action_kind in {"diff", "toollog"}:
+                await self._send(
+                    cap.destination_id,
+                    "This expired. Ask me again and I'll fetch it fresh.",
+                    connection_id=cap.connection_id,
+                )
+                return True
             return False
 
-        # Acknowledge the callback.
-        if self._adapter is not None:
-            await self._adapter.answer_callback(token)
+        if cap.action_kind in {"diff", "toollog"}:
+            self._discard(cap)
+            await self._send_detail(cap)
+            return True
 
         # Dispatch the action.
-        resolved = await self._execute_action(cap, action)
+        resolved = await self._execute_action(cap, action, db)
         if resolved:
             self._discard(cap)
         return resolved
@@ -426,19 +466,19 @@ async def _load_scheduled_tasks(
     # ── Action execution ───────────────────────────────────────────────────
 
     async def _execute_action(
-        self, cap: _ActionCapability, action: RemoteInboundAction
+        self, cap: _ActionCapability, action: RemoteInboundAction, db: AsyncSession
     ) -> bool:
         """Execute a menu action by kind."""
         if cap.action_kind == "workflow_start":
-            return await self._exec_workflow_start(cap, action)
+            return await self._exec_workflow_start(cap, action, db)
         elif cap.action_kind == "coding_task":
-            return await self._exec_coding_task(cap, action)
+            return await self._exec_coding_task(cap, action, db)
         elif cap.action_kind == "schedule_trigger":
-            return await self._exec_schedule_trigger(cap, action)
+            return await self._exec_schedule_trigger(cap, action, db)
         return False
 
     async def _exec_workflow_start(
-        self, cap: _ActionCapability, action: RemoteInboundAction
+        self, cap: _ActionCapability, action: RemoteInboundAction, db: AsyncSession
     ) -> bool:
         """Start a workflow by name."""
         try:
@@ -460,22 +500,19 @@ async def _exec_workflow_start(
 
             # Workflows need a session to run in. We need to create one or
             # use the current task's session.
-            from app.core.db import async_session_factory
-
-            async with async_session_factory() as session:
-                pairing = await self._pairing_service.authorize(
-                    session,
-                    connection_id=cap.connection_id,
-                    principal_id=cap.principal_id,
+            pairing = await self._pairing_service.authorize(
+                db,
+                connection_id=cap.connection_id,
+                principal_id=cap.principal_id,
+            )
+            if pairing is None or pairing.active_session_id is None:
+                await self._reply_text(
+                    action.principal.destination_id,
+                    "No active task. Send a message first to create one, then try again.",
                 )
-                if pairing is None or pairing.active_session_id is None:
-                    await self._reply_text(
-                        action.principal.destination_id,
-                        "No active task. Send a message first to create one, then try again.",
-                    )
-                    return True
+                return True
 
-                session_id = str(pairing.active_session_id)
+            session_id = str(pairing.active_session_id)
 
             from app.workflow.runner import WorkflowRunner
 
@@ -507,45 +544,43 @@ async def _exec_workflow_start(
             return True
 
     async def _exec_coding_task(
-        self, cap: _ActionCapability, action: RemoteInboundAction
+        self, cap: _ActionCapability, action: RemoteInboundAction, db: AsyncSession
     ) -> bool:
         """Start a coding task for a project."""
         try:
-            from app.core.db import async_session_factory
             from app.services.coding_project_service import get_project
 
-            async with async_session_factory() as session:
-                project = await get_project(session, UUID(cap.action_target))
-                if project is None:
-                    await self._reply_text(
-                        action.principal.destination_id,
-                        "Project not found.",
-                    )
-                    return True
-
-                # Create a coding session for this project.
-                from app.services.chat_service import create_chat_session
-
-                chat = await create_chat_session(session)
-                chat.mode = "coding"
-                chat.project_id = project.id
-                chat.tags = [
-                    "remote_origin",
-                    f"remote_connection:{cap.connection_id}",
-                ]
-                session.add(chat)
-                await session.commit()
-
-                # Update pairing to point to this session.
-                pairing = await self._pairing_service.authorize(
-                    session,
-                    connection_id=cap.connection_id,
-                    principal_id=cap.principal_id,
+            project = await get_project(db, UUID(cap.action_target))
+            if project is None:
+                await self._reply_text(
+                    action.principal.destination_id,
+                    "Project not found.",
                 )
-                if pairing is not None:
-                    pairing.active_session_id = chat.id
-                    session.add(pairing)
-                    await session.commit()
+                return True
+
+            # Create a coding session for this project.
+            from app.services.chat_service import create_chat_session
+
+            chat = await create_chat_session(db)
+            chat.mode = "coding"
+            chat.project_id = project.id
+            chat.tags = [
+                "remote_origin",
+                f"remote_connection:{cap.connection_id}",
+            ]
+            db.add(chat)
+            await db.commit()
+
+            # Update pairing to point to this session.
+            pairing = await self._pairing_service.authorize(
+                db,
+                connection_id=cap.connection_id,
+                principal_id=cap.principal_id,
+            )
+            if pairing is not None:
+                pairing.active_session_id = chat.id
+                db.add(pairing)
+                await db.commit()
 
             await self._reply_text(
                 action.principal.destination_id,
@@ -561,7 +596,7 @@ async def _exec_coding_task(
             return True
 
     async def _exec_schedule_trigger(
-        self, cap: _ActionCapability, action: RemoteInboundAction
+        self, cap: _ActionCapability, action: RemoteInboundAction, db: AsyncSession
     ) -> bool:
         """Trigger a scheduled task manually."""
         try:
@@ -619,18 +654,19 @@ async def _send(
         destination_id: str,
         text: str,
         buttons: tuple[RemoteButton, ...] = (),
+        *,
+        connection_id: UUID | None = None,
+        priority: RemoteOutboundPriority = RemoteOutboundPriority.INFORMATIONAL,
     ) -> None:
         if self._adapter is None:
             return
         try:
-            from uuid import UUID as _UUID
-
             msg = RemoteOutboundMessage(
-                connection_id=_UUID(int=0),
+                connection_id=connection_id or UUID(int=0),
                 destination_id=destination_id,
                 text=text,
                 buttons=buttons,
-                priority=RemoteOutboundPriority.INFORMATIONAL,
+                priority=priority,
             )
             await self._adapter.send(msg)
         except Exception as exc:
@@ -639,10 +675,51 @@ async def _send(
     async def _reply_text(self, destination_id: str, text: str) -> None:
         await self._send(destination_id, text)
 
+    async def _send_detail(self, cap: _ActionCapability) -> None:
+        """Send redacted, escaped drill-down content in bounded HTML cards."""
+        label = "Full diff" if cap.action_kind == "diff" else "Tool log"
+        redacted = _redact_text(cap.action_target)
+        for text in _render_detail_cards(label, redacted):
+            await self._send(
+                cap.destination_id,
+                text,
+                connection_id=cap.connection_id,
+                priority=RemoteOutboundPriority.HIGH,
+            )
+
 
 # ── Redaction helper ──────────────────────────────────────────────────────────
 
 
+def _render_detail_cards(label: str, content: str) -> list[str]:
+    """Wrap escaped detail text in independently valid Telegram HTML cards.
+
+    Escaping can expand a source character (``<`` becomes ``<``), so chunk
+    the escaped result rather than source text. Every card keeps its own
+    heading and ``
`` wrapper and is bounded by Telegram's 4096-character
+    provider limit.
+    """
+    prefix = f"{label}\n\n
"
+    suffix = "
"
+    content_budget = _TELEGRAM_MAX_MESSAGE_LENGTH - len(prefix) - len(suffix)
+    assert content_budget > 0
+
+    cards: list[str] = []
+    current: list[str] = []
+    current_length = 0
+    for character in content:
+        escaped = formatting.escape(character)
+        if current and current_length + len(escaped) > content_budget:
+            cards.append(prefix + "".join(current) + suffix)
+            current = []
+            current_length = 0
+        current.append(escaped)
+        current_length += len(escaped)
+
+    cards.append(prefix + "".join(current) + suffix)
+    return cards
+
+
 def _redact_text(text: str) -> str:
     """Apply remote-channel outbound redaction."""
     try:
diff --git a/app/remote/outbound.py b/app/remote/outbound.py
index 680efaee..dcd7e618 100644
--- a/app/remote/outbound.py
+++ b/app/remote/outbound.py
@@ -193,6 +193,10 @@ def set_bridge(self, bridge: "RemoteGateBridge | None") -> None:
         """Bind or unbind the gate bridge. Called by the runtime on start/stop."""
         self._bridge = bridge
 
+    def set_actions(self, actions: _CapabilityRegistrar | None) -> None:
+        """Bind the short-lived completion-detail capability registrar."""
+        self._actions = actions
+
     def set_active_pairing(
         self,
         *,
diff --git a/app/remote/runtime.py b/app/remote/runtime.py
index ea55e0ee..e77be364 100644
--- a/app/remote/runtime.py
+++ b/app/remote/runtime.py
@@ -319,6 +319,7 @@ async def _start_locked(self) -> None:
             adapter=adapter,
             status_provider=lambda: self.status(connection.id),
         )
+        projection.set_actions(self._actions)
         self._actions.set_projection(projection)
 
         from app.services.memory_stream_store import register_observer
@@ -338,9 +339,12 @@ async def _stop_locked(self) -> None:
         if self._projection is not None:
             self._projection.set_adapter(None)
             self._projection.set_bridge(None)
+            self._projection.set_actions(None)
             self._projection.clear_active_pairing()
             self._projection = None
         self._bridge = None
+        if self._actions is not None:
+            self._actions.set_projection(None)
         self._actions = None
 
         if adapter is not None:
@@ -372,7 +376,12 @@ async def _handle_action(self, action: RemoteInboundAction) -> None:
             # already degrades safely (logs + no-ops) on an unknown token.
             handled = False
             if self._actions is not None and action.callback_token is not None:
-                handled = await self._actions.handle_action_callback(action)
+                from app.core.db import async_session_factory
+
+                async with async_session_factory() as callback_session:
+                    handled = await self._actions.handle_action_callback(
+                        action, callback_session
+                    )
             if not handled and self._bridge is not None:
                 await self._bridge.handle_callback(action)
             elif not handled and self._bridge is None:
diff --git a/documents/features/remote-access.md b/documents/features/remote-access.md
index 33758be3..b3573448 100644
--- a/documents/features/remote-access.md
+++ b/documents/features/remote-access.md
@@ -55,6 +55,11 @@ to continue.
 4. On completion or error, the adapter edits that card into a bounded final
    summary. It never mirrors token, tool, or file-path deltas into the live
    status text.
+5. A completed card can offer **Full diff** and **Tool log**. Each button is a
+   short-lived, opaque capability for that exact turn only; tapping it sends
+   the already-persisted detail as redacted, escaped, bounded follow-up cards.
+   It cannot retrieve a different turn or session, and an expired button asks
+   the user to request fresh detail.
 
 ### Desktop, Workflow, and Scheduler completion
 
@@ -85,7 +90,8 @@ to continue.
 Requirements and acceptance criteria are defined in the base implementation
 plan as AC-1 through AC-36 and amended by the response-UI specification. The
 implemented response-UI additions are AC-38 (bounded phone-turn lifecycle),
-AC-42 (notification scope), and AC-43 (cross-origin completion delivery).
+AC-39 (on-demand turn detail), AC-42 (notification scope), and AC-43
+(cross-origin completion delivery).
 The status, done, and error-card paths also implement the response-card portion
 of revised AC-24. They cover:
 
@@ -101,6 +107,8 @@ of revised AC-24. They cover:
 - Migration `00000064`
 - HTML-safe Telegram cards, native typing, and one status-card lifecycle for
   phone-started turns
+- Opaque, ten-minute Full diff and Tool log capabilities scoped to the
+  connection, principal, destination, and completed turn
 - Addressability-gated final delivery for desktop, Workflow, and Scheduler
   sessions when notification scope is `all`
 
@@ -201,6 +209,10 @@ a vault key reference, never the raw token.
 - **Private chats only**: the adapter only processes private (non-group) chats.
 - **Authorization model**: `principal_id` authorizes who can reply;
   `destination_id` addresses which pairing receives the message.
+- **On-demand detail**: a Full diff or Tool log token carries no content,
+  path, or session identifier. It is in-memory only, expires after ten
+  minutes, is bound to the connection, principal, and destination, and reads
+  only the detail captured for its own completed turn.
 - **One connection per installation** (v1): only a single remote connection is
   allowed at a time.
 
diff --git a/tests/remote/test_actions.py b/tests/remote/test_actions.py
index 7b96ccf9..ba291f69 100644
--- a/tests/remote/test_actions.py
+++ b/tests/remote/test_actions.py
@@ -17,6 +17,7 @@
 from app.remote.contracts import (
     RemoteInboundAction,
     RemoteInboundActionKind,
+    RemoteOutboundPriority,
     RemotePrincipal,
 )
 from app.remote.outbound import RemoteProjection
@@ -30,6 +31,7 @@ def __init__(self) -> None:
         self.calls: list[str] = []
         self.acked_tokens: list[str] = []
         self.sent_texts: list[str] = []
+        self.sent_messages: list = []
 
     async def answer_callback(self, token: str) -> None:
         self.calls.append("answer_callback")
@@ -38,6 +40,7 @@ async def answer_callback(self, token: str) -> None:
     async def send(self, msg) -> None:
         self.calls.append("send")
         self.sent_texts.append(msg.text)
+        self.sent_messages.append(msg)
 
     async def edit(self, msg) -> None:
         self.calls.append("edit")
@@ -291,6 +294,157 @@ async def test_unpair_with_no_existing_pairing_leaves_cache_untouched(
 
 
 class TestCallbackHandling:
+    def test_register_capability_returns_usable_token(
+        self, service: RemoteActionService
+    ) -> None:
+        token = service.register_capability(
+            connection_id=uuid4(),
+            principal_id="user-1",
+            destination_id="chat-1",
+            session_id="sess-1",
+            action_kind="toollog",
+            action_target="log text",
+        )
+
+        assert isinstance(token, str)
+        assert token
+        assert len(token.encode("utf-8")) <= 64
+
+    @pytest.mark.asyncio
+    async def test_toollog_capability_sends_escaped_stored_content(
+        self, service: RemoteActionService, adapter: FakeAdapter
+    ) -> None:
+        connection_id = uuid4()
+        token = service.register_capability(
+            connection_id=connection_id,
+            principal_id="user-1",
+            destination_id="chat-1",
+            session_id="sess-1",
+            action_kind="toollog",
+            action_target="write ",
+        )
+        action = _make_action(
+            kind=RemoteInboundActionKind.CALLBACK,
+            callback_token=token,
+            connection_id=connection_id,
+        )
+
+        handled = await service.handle_action_callback(action, MagicMock())
+
+        assert handled is True
+        assert adapter.calls == ["answer_callback", "send"]
+        assert "<script>" in adapter.sent_texts[0]
+        assert "",
+        summary_lines=[],
+        tool_call_count=0,
+        diff_token=None,
+        toollog_token=None,
+    )
+    assert "" not in text
+    assert "<script>" in text
+
+
 def test_render_done_card_omits_buttons_when_no_tokens():
     _, buttons = formatting.render_done_card(
         title="No-op turn",
diff --git a/tests/remote/test_outbound.py b/tests/remote/test_outbound.py
index 8369daeb..6656f6ac 100644
--- a/tests/remote/test_outbound.py
+++ b/tests/remote/test_outbound.py
@@ -193,6 +193,60 @@ async def test_done_sends_completion_message() -> None:
     assert adapter.sent[0].priority == RemoteOutboundPriority.HIGH
 
 
+@pytest.mark.asyncio
+async def test_done_includes_the_agents_actual_reply_text(
+    addressable_session: ChatSession,
+) -> None:
+    """A "done" ``StreamEnvelope`` never carries reply text (``DoneEvent``
+    has no such field) — the done card's answer must come from the turn's
+    own persisted assistant message instead, or a tool-call-free
+    conversational turn would render as an empty "0 tool calls" card with
+    no answer in it at all (the actual regression this guards against)."""
+    proj = RemoteProjection()
+    adapter = FakeAdapter()
+    proj.set_adapter(adapter)
+
+    connection_id = str(uuid4())
+    proj.register_session(
+        str(addressable_session.id),
+        connection_id=connection_id,
+        destination_id="12345",
+        tags=frozenset({"remote_origin"}),
+    )
+    # Establishes the turn's ``turn_started_wall_clock`` — the message
+    # below must be persisted after this so load_turn_activity's ``since``
+    # filter doesn't exclude it (matches how a real turn actually starts
+    # via begin_phone_turn before any reply gets persisted).
+    proj.begin_phone_turn(
+        str(addressable_session.id),
+        connection_id=connection_id,
+        destination_id="12345",
+        principal_id="user-1",
+        title="Task",
+        status="accepted",
+    )
+    async with db_module.async_session_factory() as db:
+        db.add(
+            SessionMessage(
+                session_id=addressable_session.id,
+                role="assistant",
+                content="Here is the result.",
+            )
+        )
+        await db.commit()
+
+    proj.observe(str(addressable_session.id), _envelope("done"))
+    await proj.drain_pending()
+
+    # begin_phone_turn already sent the status card; the done event edits
+    # that same message in place rather than sending a new one.
+    assert len(adapter.edited) == 1
+    assert "Here is the result." in adapter.edited[0].text
+    # No tool calls happened — a "Tool log" button would only ever open an
+    # empty "No tool calls." page, so it must not be offered at all.
+    assert adapter.edited[0].buttons == ()
+
+
 @pytest.mark.asyncio
 async def test_done_registers_current_turn_detail_capabilities(
     addressable_session: ChatSession,
diff --git a/tests/remote/test_turn_activity.py b/tests/remote/test_turn_activity.py
index d5e121d1..bf2fcd45 100644
--- a/tests/remote/test_turn_activity.py
+++ b/tests/remote/test_turn_activity.py
@@ -73,6 +73,45 @@ async def test_load_turn_activity_counts_tool_calls_and_builds_diff(
     assert "read" in activity.tool_log_text
 
 
+@pytest.mark.asyncio
+async def test_load_turn_activity_returns_last_assistant_content_as_response_text(
+    db_session, chat_session
+):
+    """A "done" stream envelope never carries the agent's reply text (its
+    ``DoneEvent`` has no such field) — this is the only place it can come
+    from. Multiple assistant messages (e.g. a tool-call-only one, then the
+    final text reply) must resolve to the LAST one with actual content."""
+    since = datetime.now(UTC) - timedelta(seconds=1)
+    db_session.add_all(
+        [
+            SessionMessage(
+                session_id=chat_session.id,
+                role="assistant",
+                tool_calls=[{"name": "read", "arguments": {"path": "a.py"}}],
+                created_at=since + timedelta(milliseconds=10),
+            ),
+            SessionMessage(
+                session_id=chat_session.id,
+                role="tool",
+                tool_call_id="1",
+                content="file contents",
+                created_at=since + timedelta(milliseconds=20),
+            ),
+            SessionMessage(
+                session_id=chat_session.id,
+                role="assistant",
+                content="Here is the result.",
+                created_at=since + timedelta(milliseconds=30),
+            ),
+        ]
+    )
+    await db_session.commit()
+
+    activity = await load_turn_activity(db_session, str(chat_session.id), since=since)
+
+    assert activity.response_text == "Here is the result."
+
+
 @pytest.mark.asyncio
 async def test_load_turn_activity_with_no_tool_calls_returns_placeholders(
     db_session, chat_session

From c0961104b827db6fb1fee04991031a77397bb842 Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Tue, 15 Sep 2026 08:50:19 +0700
Subject: [PATCH 27/71] fix(remote): stop
 test_disabled_start_does_not_import_telegram leaking sys.modules
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Confirmed a genuinely flaky (not just theoretically risky) test failure:
tests/remote/telegram/test_adapter.py::TestDeliveryIndependentOfPolling
failed 40-70% of full-suite runs, always passed alone. Bisected to a raw
sys.modules.pop() (untracked by monkeypatch, never restored) that forces
every later test to import a second, distinct TelegramApiError class —
so a later test's freshly-local `from ... import TelegramApiError` binds
to a different class than the one already-imported code actually raises,
and pytest.raises(TelegramApiError) silently stops matching.

monkeypatch.delitem() instead of the raw pop restores it at teardown.
Verified with 8 consecutive full-suite runs (0 failures, was ~40-70%).
---
 tests/remote/test_runtime.py | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/tests/remote/test_runtime.py b/tests/remote/test_runtime.py
index a3a02308..6aa8ff3d 100644
--- a/tests/remote/test_runtime.py
+++ b/tests/remote/test_runtime.py
@@ -160,8 +160,17 @@ async def test_disabled_start_does_not_import_telegram(monkeypatch) -> None:
         remote_runtime, "_adapter_constructor", _construct_telegram_adapter
     )
 
-    sys.modules.pop("app.remote.telegram.adapter", None)
-    sys.modules.pop("app.remote.telegram.client", None)
+    # ``monkeypatch.delitem`` (not a raw ``sys.modules.pop``) so this is
+    # restored at teardown — an un-restored pop here silently forces every
+    # later test in the session to import fresh copies of these modules,
+    # producing a *second*, distinct ``TelegramApiError`` class that a
+    # freshly-local `from ... import TelegramApiError` in another test file
+    # binds to while already-imported code (e.g. this file's own top-level
+    # ``TelegramAdapter`` import) keeps raising the original one — so
+    # ``pytest.raises(TelegramApiError)`` stops matching there, sporadically
+    # and non-deterministically depending on test order.
+    monkeypatch.delitem(sys.modules, "app.remote.telegram.adapter", raising=False)
+    monkeypatch.delitem(sys.modules, "app.remote.telegram.client", raising=False)
 
     await remote_runtime.start()
 

From 0cb39a1fd5f4cc4832cd733911c45de9a4d00e4d Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Tue, 15 Sep 2026 08:57:44 +0700
Subject: [PATCH 28/71] feat(remote): add advisory-only permission severity
 derivation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 1 (Task 1) of documents/plans/remote-telegram-approvals-implementation.md
— pure display-hint derivation, never consulted by any gating decision.
---
 app/remote/severity.py        | 43 +++++++++++++++++++++++++++++++++++
 tests/remote/test_severity.py | 28 +++++++++++++++++++++++
 2 files changed, 71 insertions(+)
 create mode 100644 app/remote/severity.py
 create mode 100644 tests/remote/test_severity.py

diff --git a/app/remote/severity.py b/app/remote/severity.py
new file mode 100644
index 00000000..082e9095
--- /dev/null
+++ b/app/remote/severity.py
@@ -0,0 +1,43 @@
+"""Advisory-only command severity for permission cards.
+
+Display hint alone — never consulted by any gating decision.
+``PermissionService`` (``app/agent/permission.py``) is the sole authority on
+whether a request blocks; this module exists only so a phone operator sees
+"rm -rf" and "read a file" rendered differently, never to decide anything.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+Severity = Literal["high", "elevated", "normal"]
+
+__all__ = ["Severity", "derive_severity"]
+
+#: Substrings that mark a command as destructive regardless of tool.
+_DESTRUCTIVE_SUBSTRINGS = (
+    "rm -rf",
+    "rm -r -f",
+    "git clean -fd",
+    "git reset --hard",
+    "git push --force",
+    "git push -f",
+    "drop table",
+    "drop database",
+    "truncate table",
+)
+
+#: Tools that run arbitrary code/commands — elevated even without a
+#: destructive-pattern match.
+_ELEVATED_TOOLS = frozenset({"shell", "bash", "python", "process", "rm"})
+
+
+def derive_severity(*, tool: str, command: str) -> Severity:
+    """Derive a display-only severity from a permission request's tool and
+    command text. Never raises; unknown input degrades to "normal"."""
+    lowered = command.lower()
+    if any(pattern in lowered for pattern in _DESTRUCTIVE_SUBSTRINGS):
+        return "high"
+    if tool in _ELEVATED_TOOLS:
+        return "elevated"
+    return "normal"
diff --git a/tests/remote/test_severity.py b/tests/remote/test_severity.py
new file mode 100644
index 00000000..bc0ec44c
--- /dev/null
+++ b/tests/remote/test_severity.py
@@ -0,0 +1,28 @@
+from app.remote.severity import derive_severity
+
+
+def test_destructive_command_is_high_severity():
+    assert derive_severity(tool="shell", command="rm -rf build/") == "high"
+
+
+def test_force_push_is_high_severity():
+    assert (
+        derive_severity(tool="shell", command="git push --force origin main")
+        == "high"
+    )
+
+
+def test_shell_tool_without_destructive_pattern_is_elevated():
+    assert derive_severity(tool="shell", command="pytest -q") == "elevated"
+
+
+def test_python_tool_is_elevated():
+    assert derive_severity(tool="python", command="print(1)") == "elevated"
+
+
+def test_read_only_tool_is_normal():
+    assert derive_severity(tool="read", command="tests/test_auth.py") == "normal"
+
+
+def test_detection_is_case_insensitive():
+    assert derive_severity(tool="shell", command="RM -RF /tmp/x") == "high"

From 8d6761d9f4164689f2c0b364110c1182f8899655 Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Tue, 15 Sep 2026 08:58:47 +0700
Subject: [PATCH 29/71] feat(remote): render permission cards with the real
 command and severity
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 1 (Task 2) of documents/plans/remote-telegram-approvals-implementation.md
— the card builders only; not yet wired into gates.py.
---
 app/remote/formatting.py        | 54 ++++++++++++++++++++
 tests/remote/test_formatting.py | 88 +++++++++++++++++++++++++++++++++
 2 files changed, 142 insertions(+)

diff --git a/app/remote/formatting.py b/app/remote/formatting.py
index 468ffb49..cb5a7a2c 100644
--- a/app/remote/formatting.py
+++ b/app/remote/formatting.py
@@ -15,10 +15,25 @@
     "render_settings_card",
     "render_project_picker",
     "render_prompt_suggestions",
+    "render_permission_card",
+    "render_permission_resolved_card",
 ]
 
 _STATUS_ICON = {"accepted": "\U0001f527", "queued": "⏳", "pending": "⏳"}
 
+_SEVERITY_ICON = {"high": "\U0001f534", "elevated": "\U0001f7e0", "normal": "\U0001f527"}
+_SEVERITY_LABEL = {
+    "high": "Dangerous command",
+    "elevated": "Command",
+    "normal": "Permission requested",
+}
+_RESOLUTION_ICON = {"once": "✅", "always": "\U0001f512", "reject": "❌"}
+_RESOLUTION_LABEL = {
+    "once": "Allowed once",
+    "always": "Allowed for session",
+    "reject": "Rejected",
+}
+
 
 def escape(value: str) -> str:
     """The only place raw text becomes safe to place inside an HTML tag."""
@@ -76,6 +91,45 @@ def render_error_card(
     return text, buttons
 
 
+def render_permission_card(
+    *,
+    tool: str,
+    command: str,
+    severity: str,
+    agent: str,
+    always_glob: str | None,
+    always_token: str | None,
+    once_token: str,
+    reject_token: str,
+) -> tuple[str, tuple[RemoteButton, ...]]:
+    icon = _SEVERITY_ICON.get(severity, "\U0001f527")
+    label = _SEVERITY_LABEL.get(severity, "Permission requested")
+    text = (
+        f"{icon} {escape(label)}\n"
+        f"
{escape(command)}
\n"
+        f"{escape(tool)} · {escape(agent)}"
+    )
+    buttons = [RemoteButton(text="Allow once", token=once_token)]
+    if always_token and always_glob:
+        buttons.append(
+            RemoteButton(
+                text=f"\U0001f512 Allow for session — {escape(always_glob)}",
+                token=always_token,
+            )
+        )
+    buttons.append(RemoteButton(text="Reject", token=reject_token))
+    return text, tuple(buttons)
+
+
+def render_permission_resolved_card(
+    *, command: str, resolution: str
+) -> tuple[str, tuple[RemoteButton, ...]]:
+    icon = _RESOLUTION_ICON.get(resolution, "✅")
+    label = _RESOLUTION_LABEL.get(resolution, "Resolved")
+    text = f"{icon} {escape(label)}\n
{escape(command)}
"
+    return text, ()
+
+
 def render_gate_card(
     *, title: str, body: str, actions: Sequence[tuple[str, str]]
 ) -> tuple[str, tuple[RemoteButton, ...]]:
diff --git a/tests/remote/test_formatting.py b/tests/remote/test_formatting.py
index 0cf57b77..2169fd0d 100644
--- a/tests/remote/test_formatting.py
+++ b/tests/remote/test_formatting.py
@@ -75,6 +75,94 @@ def test_render_done_card_omits_buttons_when_no_tokens():
     assert buttons == ()
 
 
+def test_render_permission_card_shows_command_and_severity_icon():
+    text, buttons = formatting.render_permission_card(
+        tool="shell",
+        command="rm -rf build/",
+        severity="high",
+        agent="evoflux",
+        always_glob=None,
+        always_token=None,
+        once_token="once-tok",
+        reject_token="reject-tok",
+    )
+    assert "rm -rf build/" in text
+    assert "\U0001f534" in text  # red circle = high severity
+    assert "shell" in text
+    assert "evoflux" in text
+    assert buttons == (
+        RemoteButton(text="Allow once", token="once-tok"),
+        RemoteButton(text="Reject", token="reject-tok"),
+    )
+
+
+def test_render_permission_card_escapes_command():
+    text, _ = formatting.render_permission_card(
+        tool="shell",
+        command="echo ",
+        severity="elevated",
+        agent="evoflux",
+        always_glob=None,
+        always_token=None,
+        once_token="once-tok",
+        reject_token="reject-tok",
+    )
+    assert "" not in text
+    assert "<script>" in text
+
+
+def test_render_permission_card_adds_allow_for_session_button_with_glob():
+    text, buttons = formatting.render_permission_card(
+        tool="shell",
+        command="git push origin main",
+        severity="elevated",
+        agent="evoflux",
+        always_glob="git push *",
+        always_token="always-tok",
+        once_token="once-tok",
+        reject_token="reject-tok",
+    )
+    assert "git push *" in text or any("git push *" in b.text for b in buttons)
+    assert buttons == (
+        RemoteButton(text="Allow once", token="once-tok"),
+        RemoteButton(
+            text="\U0001f512 Allow for session — git push *", token="always-tok"
+        ),
+        RemoteButton(text="Reject", token="reject-tok"),
+    )
+
+
+def test_render_permission_card_omits_always_button_without_glob():
+    _, buttons = formatting.render_permission_card(
+        tool="read",
+        command="tests/test_auth.py",
+        severity="normal",
+        agent="evoflux",
+        always_glob=None,
+        always_token=None,
+        once_token="once-tok",
+        reject_token="reject-tok",
+    )
+    assert len(buttons) == 2
+
+
+def test_render_permission_resolved_card_states_decision_and_has_no_buttons():
+    text, buttons = formatting.render_permission_resolved_card(
+        command="rm -rf build/", resolution="once"
+    )
+    assert "rm -rf build/" in text
+    assert "Allowed once" in text
+    assert buttons == ()
+
+
+def test_render_permission_resolved_card_escapes_command():
+    text, _ = formatting.render_permission_resolved_card(
+        command="", resolution="reject"
+    )
+    assert "" not in text
+    assert "<script>" in text
+
+
 def test_render_error_card_escapes_message():
     text, buttons = formatting.render_error_card(
         title="Add rate limiter",

From 8185cb1f291fdf17f6d06aa1e753c21145ae6b42 Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Tue, 15 Sep 2026 09:00:46 +0700
Subject: [PATCH 30/71] feat(remote): permission cards render the real command
 and severity
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 1 (Task 3, steps 1-5) of
documents/plans/remote-telegram-approvals-implementation.md — extracts
the permission_asked branch into _on_permission_asked, wired to the new
severity/formatting helpers. Every gate card (including question/plan)
now carries a correlation_id.
---
 app/remote/gates.py        | 112 +++++++++++++++++++++++++++++++++----
 tests/remote/test_gates.py |  55 +++++++++++++++++-
 2 files changed, 156 insertions(+), 11 deletions(-)

diff --git a/app/remote/gates.py b/app/remote/gates.py
index dbd63fd8..3165b66a 100644
--- a/app/remote/gates.py
+++ b/app/remote/gates.py
@@ -15,6 +15,7 @@
 
 from __future__ import annotations
 
+import asyncio
 import secrets
 import time
 from dataclasses import dataclass, field
@@ -30,6 +31,8 @@
     RemoteOutboundMessage,
     RemoteOutboundPriority,
 )
+from app.remote.formatting import render_permission_card, render_permission_resolved_card
+from app.remote.severity import derive_severity
 
 if TYPE_CHECKING:
     pass
@@ -63,14 +66,14 @@ class GateCapability:
 
 @dataclass
 class _PendingGate:
-    """Tracks one gate's outstanding capabilities and message reference."""
+    """Tracks one gate's outstanding capabilities and the command text (if
+    any) needed to render its resolved form later."""
 
     request_id: str
     session_id: str
     gate_kind: GateKind
     tokens: list[str] = field(default_factory=list)
-    chat_id: int | None = None
-    message_id: int | None = None
+    command: str = ""
 
 
 class RemoteGateBridge:
@@ -104,15 +107,16 @@ def on_gate(
         if not request_id:
             return
 
+        if event_type == "permission_asked":
+            self._on_permission_asked(
+                session_id, data, connection_id, destination_id, request_id
+            )
+            return
+
         gate_kind: GateKind
         actions: list[tuple[str, str]]  # (action_label, button_text)
 
-        if event_type == "permission_asked":
-            gate_kind = "permission"
-            tool = data.get("tool", "unknown")
-            text = f"Permission requested: {tool}"
-            actions = [("once", "Allow"), ("reject", "Reject")]
-        elif event_type == "question_asked":
+        if event_type == "question_asked":
             gate_kind = "question"
             questions = data.get("questions", [])
             if questions:
@@ -166,11 +170,99 @@ def on_gate(
             text=text,
             buttons=tuple(buttons),
             priority=RemoteOutboundPriority.HIGH,
+            correlation_id=f"gate:{request_id}",
+        )
+        self._enqueue_send(msg)
+
+    def _on_permission_asked(
+        self,
+        session_id: str,
+        data: dict,
+        connection_id: UUID,
+        destination_id: str,
+        request_id: str,
+    ) -> None:
+        """Render and send a decidable permission card (AC-45/AC-46): the
+        real command and a derived, advisory-only severity, never a tool
+        name alone."""
+        tool = data.get("tool", "unknown")
+        patterns = data.get("patterns") or []
+        command = patterns[0] if patterns else tool
+        always_patterns = data.get("always_patterns") or []
+        always_glob = always_patterns[0] if always_patterns else None
+        agent_name = data.get("metadata", {}).get("agent", "agent")
+        severity = derive_severity(tool=tool, command=command)
+
+        gate = _PendingGate(
+            request_id=request_id,
+            session_id=session_id,
+            gate_kind="permission",
+            command=_redact_text(command),
+        )
+
+        once_token = self._issue_token(
+            connection_id=connection_id,
+            principal_id="",
+            destination_id=destination_id,
+            session_id=session_id,
+            request_id=request_id,
+            gate_kind="permission",
+            action="once",
+        )
+        gate.tokens.append(once_token)
+        self._pending_by_token[once_token] = request_id
+
+        always_token: str | None = None
+        if always_glob:
+            always_token = self._issue_token(
+                connection_id=connection_id,
+                principal_id="",
+                destination_id=destination_id,
+                session_id=session_id,
+                request_id=request_id,
+                gate_kind="permission",
+                action="always",
+            )
+            gate.tokens.append(always_token)
+            self._pending_by_token[always_token] = request_id
+
+        reject_token = self._issue_token(
+            connection_id=connection_id,
+            principal_id="",
+            destination_id=destination_id,
+            session_id=session_id,
+            request_id=request_id,
+            gate_kind="permission",
+            action="reject",
+        )
+        gate.tokens.append(reject_token)
+        self._pending_by_token[reject_token] = request_id
+
+        self._pending_gates[request_id] = gate
+
+        text, buttons = render_permission_card(
+            tool=tool,
+            command=gate.command,
+            severity=severity,
+            agent=agent_name,
+            always_glob=_redact_text(always_glob) if always_glob else None,
+            always_token=always_token,
+            once_token=once_token,
+            reject_token=reject_token,
+        )
+        msg = RemoteOutboundMessage(
+            connection_id=connection_id,
+            destination_id=destination_id,
+            text=text,
+            buttons=buttons,
+            priority=RemoteOutboundPriority.HIGH,
+            correlation_id=f"gate:{request_id}",
         )
         self._enqueue_send(msg)
 
     def on_reply(self, session_id: str, event_type: str, data: dict) -> None:
-        """Handle a gate reply event by removing buttons from the message.
+        """Handle a gate reply event by editing its card into a resolved,
+        button-free form (AC-47).
 
         Called by the projection when a ``permission_replied``,
         ``question_replied``, or ``plan_approval_replied`` event fires.
diff --git a/tests/remote/test_gates.py b/tests/remote/test_gates.py
index 62353f28..0eecb461 100644
--- a/tests/remote/test_gates.py
+++ b/tests/remote/test_gates.py
@@ -99,6 +99,59 @@ def test_tokens_are_under_64_bytes(self, bridge: RemoteGateBridge) -> None:
                     assert len(token.encode("utf-8")) <= _MAX_CALLBACK_TOKEN_BYTES
 
 
+# ── Decidable permission cards ───────────────────────────────────────────────
+
+
+@pytest.mark.asyncio
+async def test_on_gate_permission_renders_the_real_command(
+    bridge: RemoteGateBridge, adapter: FakeAdapter
+) -> None:
+    bridge.on_gate(
+        session_id="sess-1",
+        event_type="permission_asked",
+        data={
+            "request_id": "req-1",
+            "tool": "shell",
+            "patterns": ["rm -rf build/"],
+            "always_patterns": [],
+            "metadata": {"agent": "evoflux"},
+        },
+        connection_id=uuid4(),
+        destination_id="chat-1",
+    )
+    await asyncio.sleep(0.05)  # drain the fire-and-forget send
+
+    assert len(adapter.sent) == 1
+    assert "rm -rf build/" in adapter.sent[0].text
+    assert "Permission requested: shell" not in adapter.sent[0].text
+    assert adapter.sent[0].correlation_id == "gate:req-1"
+    assert [b.text for b in adapter.sent[0].buttons] == ["Allow once", "Reject"]
+
+
+@pytest.mark.asyncio
+async def test_on_gate_permission_offers_allow_for_session_with_glob(
+    bridge: RemoteGateBridge, adapter: FakeAdapter
+) -> None:
+    bridge.on_gate(
+        session_id="sess-1",
+        event_type="permission_asked",
+        data={
+            "request_id": "req-1",
+            "tool": "shell",
+            "patterns": ["git push origin main"],
+            "always_patterns": ["git push *"],
+            "metadata": {"agent": "evoflux"},
+        },
+        connection_id=uuid4(),
+        destination_id="chat-1",
+    )
+    await asyncio.sleep(0.05)
+
+    button_texts = [b.text for b in adapter.sent[0].buttons]
+    assert len(button_texts) == 3
+    assert "git push *" in button_texts[1]
+
+
 # ── Gate rendering ────────────────────────────────────────────────────────────
 
 
@@ -120,7 +173,7 @@ async def test_permission_gate_creates_allow_and_reject_buttons(
         assert len(adapter.sent) == 1
         msg = adapter.sent[0]
         assert len(msg.buttons) == 2
-        assert msg.buttons[0].text == "Allow"
+        assert msg.buttons[0].text == "Allow once"
         assert msg.buttons[1].text == "Reject"
         assert msg.buttons[0].token != msg.buttons[1].token
 

From 0ece6e1813e471c75a68a1c584ad1f7f437593a5 Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Tue, 15 Sep 2026 09:03:45 +0700
Subject: [PATCH 31/71] fix(remote): permission cards accept 'always' and
 actually resolve
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 1 (Task 3, steps 6-15) of
documents/plans/remote-telegram-approvals-implementation.md.

_resolve_permission now accepts "always" (session-scoped in
PermissionService, not the permanent grant AC-28 assumed when it withheld
it). on_reply no longer gates on the dead chat_id/message_id fields
(never assigned, so the edit path was permanently unreachable) — it now
always edits the card via correlation_id into a resolved, button-free
form that states the decision. _edit_remove_buttons/_do_edit_remove
(built on the same dead fields, and edited with an empty string Telegram
would reject anyway) are removed in favor of
_enqueue_resolved_edit/_do_resolved_edit.
---
 app/remote/gates.py                           |  93 +-
 ...emote-telegram-approvals-implementation.md | 998 ++++++++++++++++++
 tests/remote/test_gates.py                    |  63 ++
 3 files changed, 1109 insertions(+), 45 deletions(-)
 create mode 100644 documents/plans/remote-telegram-approvals-implementation.md

diff --git a/app/remote/gates.py b/app/remote/gates.py
index 3165b66a..5b555f4c 100644
--- a/app/remote/gates.py
+++ b/app/remote/gates.py
@@ -275,14 +275,51 @@ def on_reply(self, session_id: str, event_type: str, data: dict) -> None:
         if gate is None:
             return
 
-        # Clean up capability tokens.
         for token in gate.tokens:
             self._capabilities.pop(token, None)
             self._pending_by_token.pop(token, None)
 
-        # Edit the message to remove buttons (if we have a reference).
-        if gate.chat_id is not None and gate.message_id is not None:
-            self._edit_remove_buttons(gate)
+        resolution_text = self._resolution_text(gate, data)
+        self._enqueue_resolved_edit(gate, resolution_text)
+
+    def _resolution_text(self, gate: _PendingGate, data: dict) -> str:
+        """Build the resolved-form message text for one gate kind. Only
+        permission gates have a per-decision label defined by the spec
+        (AC-45's "Allowed once"/"Allowed for session"/"Rejected"); question
+        and plan gates get a generic resolved marker."""
+        if gate.gate_kind == "permission":
+            reply = data.get("reply", "reject")
+            text, _buttons = render_permission_resolved_card(
+                command=gate.command or "(command unavailable)", resolution=reply
+            )
+            return text
+        return "✅ Resolved"
+
+    def _enqueue_resolved_edit(self, gate: _PendingGate, text: str) -> None:
+        """Edit this gate's card into its resolved form — fire-and-forget,
+        matching the delivery pattern already used by ``_enqueue_send``."""
+        try:
+            loop = asyncio.get_running_loop()
+            loop.create_task(self._do_resolved_edit(gate, text))
+        except RuntimeError:
+            pass
+
+    async def _do_resolved_edit(self, gate: _PendingGate, text: str) -> None:
+        try:
+            msg = RemoteOutboundMessage(
+                connection_id=UUID(int=0),  # not used for edit lookup
+                destination_id="",
+                text=text,
+                buttons=(),
+                correlation_id=f"gate:{gate.request_id}",
+            )
+            await self._adapter.edit(msg)
+        except Exception as exc:
+            logger.debug(
+                "remote_gate_resolved_edit_failed request_id={} error={}",
+                gate.request_id,
+                exc,
+            )
 
     async def handle_callback(self, action: RemoteInboundAction) -> None:
         """Handle an inbound callback action.
@@ -346,19 +383,19 @@ async def _resolve_gate(
     async def _resolve_permission(
         self, cap: GateCapability, action: RemoteInboundAction
     ) -> bool:
-        """Resolve a permission gate. Remote is limited to once/reject."""
-        from app.agent.permission import get_service_for_session
+        """Resolve a permission gate. Remote accepts once/always/reject
+        (AC-28, revised) — "always" is session-scoped in PermissionService
+        (it appends a rule to session_ruleset, not a permanent grant), which
+        is exactly what the remote card's "Allow for session" label says."""
+        from app.agent.permission import Reply, get_service_for_session
 
-        if cap.action == "once":
-            reply_value: Literal["once", "reject"] = "once"
-        elif cap.action == "reject":
-            reply_value = "reject"
-        else:
+        if cap.action not in ("once", "always", "reject"):
             logger.warning(
                 "remote_gate_invalid_permission_action action={}",
                 cap.action,
             )
             return False
+        reply_value: Reply = cap.action  # ty: ignore[invalid-assignment]
 
         svc = get_service_for_session(cap.session_id)
         if svc is None:
@@ -470,43 +507,9 @@ def _issue_token(
         self._capabilities[token] = cap
         return token
 
-    def _edit_remove_buttons(self, gate: _PendingGate) -> None:
-        """Edit a message to remove its inline buttons."""
-        if gate.chat_id is None or gate.message_id is None:
-            return
-        # We need to send an edit with empty buttons to remove the keyboard.
-        # This is a fire-and-forget best-effort.
-        try:
-            import asyncio
-
-            loop = asyncio.get_running_loop()
-            loop.create_task(self._do_edit_remove(gate))
-        except RuntimeError:
-            pass
-
-    async def _do_edit_remove(self, gate: _PendingGate) -> None:
-        """Actually edit the message to remove buttons."""
-        try:
-            msg = RemoteOutboundMessage(
-                connection_id=UUID(int=0),  # not used for edit lookup
-                destination_id="",
-                text="",  # text not changed
-                buttons=(),
-                correlation_id=f"gate:{gate.request_id}",
-            )
-            await self._adapter.edit(msg)
-        except Exception as exc:
-            logger.debug(
-                "remote_gate_edit_remove_buttons_failed request_id={} error={}",
-                gate.request_id,
-                exc,
-            )
-
     def _enqueue_send(self, msg: RemoteOutboundMessage) -> None:
         """Enqueue a message for async delivery."""
         try:
-            import asyncio
-
             loop = asyncio.get_running_loop()
             loop.create_task(self._do_send(msg))
         except RuntimeError:
diff --git a/documents/plans/remote-telegram-approvals-implementation.md b/documents/plans/remote-telegram-approvals-implementation.md
new file mode 100644
index 00000000..92a88383
--- /dev/null
+++ b/documents/plans/remote-telegram-approvals-implementation.md
@@ -0,0 +1,998 @@
+# Remote Telegram: Decidable Approvals Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make the Telegram permission gate decidable (show the real command
+and a derived severity instead of just a tool name) and make it actually
+resolve (fix the card so it edits into a decided state instead of keeping
+live buttons forever) — Phase 1 of the larger control-surface spec, covering
+exactly AC-45, AC-46, and AC-47.
+
+**Architecture:** A new pure module (`app/remote/severity.py`) derives a
+display-only severity from tool name and command text. `app/remote/formatting.py`
+gains two builders — the ask-card and the resolved-card — that render it.
+`app/remote/gates.py`'s permission path is extracted into its own method that
+uses both, issues an `always` token alongside `once`/`reject`, stamps every
+sent card with a `correlation_id`, and replaces the dead
+`chat_id`/`message_id` fields with a generic edit-to-resolved-form path used
+by all three gate kinds.
+
+**Tech Stack:** Python 3.12, FastAPI, asyncio, pytest, pytest-asyncio.
+
+**Spec:** [`remote-telegram-control-surface.md`](remote-telegram-control-surface.md)
+(amends `remote-channel-telegram.md` and `remote-telegram-response-ui.md`) —
+this plan implements exactly AC-45, AC-46, and AC-47 of that document.
+
+## Global Constraints
+
+- Severity is advisory display only — it must never change which requests
+  are gated, which replies are accepted, or how any reply resolves (AC-46).
+  `PermissionService` remains the sole gating authority.
+- Every field not authored as a static string in `formatting.py` is redacted
+  via `_redact_text` (or `protect_outbound_text` directly) and then
+  HTML-escaped, redaction first, escaping last (AC-24, already accepted).
+- `on_gate`/`on_reply` stay synchronous and non-blocking — no database read,
+  no `await`, inside either (matches the accepted spec's observer contract;
+  `on_gate` today has no DB access and this plan must not add one).
+- Callback tokens stay opaque, `<=64` bytes, connection/principal-bound —
+  unchanged token issuance mechanism (`_issue_token`), just one more token
+  per permission request when `always_patterns` is non-empty.
+- `answer_callback` is still called before gate resolution (AC-26) — nothing
+  in this plan changes `handle_callback`'s ordering.
+- Every task cites its spec ACs, writes a failing test before implementation,
+  and leaves the test suite green at its checkpoint.
+- Commit at the end of each task.
+
+---
+
+## File and interface map
+
+New units:
+
+- `app/remote/severity.py` — `Severity` type alias and `derive_severity()`.
+- `tests/remote/test_severity.py`.
+
+Changed units:
+
+- `app/remote/formatting.py` — adds `render_permission_card` and
+  `render_permission_resolved_card`.
+- `app/remote/gates.py` — `_PendingGate` drops `chat_id`/`message_id`, gains
+  `command: str`; `on_gate`'s permission branch becomes
+  `_on_permission_asked`; `on_reply` becomes gate-kind-generic and always
+  edits via `correlation_id`; `_resolve_permission` accepts `always`;
+  `_edit_remove_buttons`/`_do_edit_remove` are replaced by
+  `_enqueue_resolved_edit`/`_do_resolved_edit`.
+- `tests/remote/test_formatting.py`, `tests/remote/test_gates.py` — updated
+  and new focused evidence.
+
+---
+
+### Task 1: Severity derivation
+
+**ACs:** AC-46
+
+**Files:**
+
+- Create: `app/remote/severity.py`
+- Create: `tests/remote/test_severity.py`
+
+**Interfaces:**
+
+- Produces: `Severity = Literal["high", "elevated", "normal"]`,
+  `derive_severity(*, tool: str, command: str) -> Severity`.
+- Consumes: nothing (pure function, no imports from elsewhere in
+  `app.remote`).
+
+- [ ] **Step 1: Write the failing tests**
+
+```python
+# tests/remote/test_severity.py
+from app.remote.severity import derive_severity
+
+
+def test_destructive_command_is_high_severity():
+    assert derive_severity(tool="shell", command="rm -rf build/") == "high"
+
+
+def test_force_push_is_high_severity():
+    assert (
+        derive_severity(tool="shell", command="git push --force origin main")
+        == "high"
+    )
+
+
+def test_shell_tool_without_destructive_pattern_is_elevated():
+    assert derive_severity(tool="shell", command="pytest -q") == "elevated"
+
+
+def test_python_tool_is_elevated():
+    assert derive_severity(tool="python", command="print(1)") == "elevated"
+
+
+def test_read_only_tool_is_normal():
+    assert derive_severity(tool="read", command="tests/test_auth.py") == "normal"
+
+
+def test_detection_is_case_insensitive():
+    assert derive_severity(tool="shell", command="RM -RF /tmp/x") == "high"
+```
+
+- [ ] **Step 2: Run and confirm failure**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/test_severity.py
+```
+
+Expected: FAIL with `ModuleNotFoundError: No module named 'app.remote.severity'`.
+
+- [ ] **Step 3: Implement `severity.py`**
+
+```python
+# app/remote/severity.py
+"""Advisory-only command severity for permission cards.
+
+Display hint alone — never consulted by any gating decision.
+``PermissionService`` (``app/agent/permission.py``) is the sole authority on
+whether a request blocks; this module exists only so a phone operator sees
+"rm -rf" and "read a file" rendered differently, never to decide anything.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+Severity = Literal["high", "elevated", "normal"]
+
+__all__ = ["Severity", "derive_severity"]
+
+#: Substrings that mark a command as destructive regardless of tool.
+_DESTRUCTIVE_SUBSTRINGS = (
+    "rm -rf",
+    "rm -r -f",
+    "git clean -fd",
+    "git reset --hard",
+    "git push --force",
+    "git push -f",
+    "drop table",
+    "drop database",
+    "truncate table",
+)
+
+#: Tools that run arbitrary code/commands — elevated even without a
+#: destructive-pattern match.
+_ELEVATED_TOOLS = frozenset({"shell", "bash", "python", "process", "rm"})
+
+
+def derive_severity(*, tool: str, command: str) -> Severity:
+    """Derive a display-only severity from a permission request's tool and
+    command text. Never raises; unknown input degrades to "normal"."""
+    lowered = command.lower()
+    if any(pattern in lowered for pattern in _DESTRUCTIVE_SUBSTRINGS):
+        return "high"
+    if tool in _ELEVATED_TOOLS:
+        return "elevated"
+    return "normal"
+```
+
+- [ ] **Step 4: Run and confirm pass**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/test_severity.py
+```
+
+Expected: PASS (6 tests).
+
+- [ ] **Step 5: Lint**
+
+```powershell
+uv run ruff check app/remote/severity.py tests/remote/test_severity.py
+uv run ty check app/remote/severity.py
+```
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add app/remote/severity.py tests/remote/test_severity.py
+git commit -m "feat(remote): add advisory-only permission severity derivation"
+```
+
+---
+
+### Task 2: Permission card rendering
+
+**ACs:** AC-45, AC-46 (display half), AC-47 (resolved-card content)
+
+**Files:**
+
+- Modify: `app/remote/formatting.py`
+- Modify: `tests/remote/test_formatting.py`
+
+**Interfaces:**
+
+- Produces: `render_permission_card(*, tool: str, command: str, severity: str,
+  agent: str, always_glob: str | None, always_token: str | None,
+  once_token: str, reject_token: str) -> tuple[str, tuple[RemoteButton, ...]]`,
+  `render_permission_resolved_card(*, command: str, resolution: str) ->
+  tuple[str, tuple[RemoteButton, ...]]`.
+- Consumes: `app.remote.contracts.RemoteButton`, `escape` (already in this
+  module).
+
+- [ ] **Step 1: Write the failing tests**
+
+```python
+# tests/remote/test_formatting.py (add)
+def test_render_permission_card_shows_command_and_severity_icon():
+    text, buttons = formatting.render_permission_card(
+        tool="shell",
+        command="rm -rf build/",
+        severity="high",
+        agent="evoflux",
+        always_glob=None,
+        always_token=None,
+        once_token="once-tok",
+        reject_token="reject-tok",
+    )
+    assert "rm -rf build/" in text
+    assert "\U0001f534" in text  # red circle = high severity
+    assert "shell" in text
+    assert "evoflux" in text
+    assert buttons == (
+        RemoteButton(text="Allow once", token="once-tok"),
+        RemoteButton(text="Reject", token="reject-tok"),
+    )
+
+
+def test_render_permission_card_escapes_command():
+    text, _ = formatting.render_permission_card(
+        tool="shell",
+        command="echo ",
+        severity="elevated",
+        agent="evoflux",
+        always_glob=None,
+        always_token=None,
+        once_token="once-tok",
+        reject_token="reject-tok",
+    )
+    assert "" not in text
+    assert "<script>" in text
+
+
+def test_render_permission_card_adds_allow_for_session_button_with_glob():
+    text, buttons = formatting.render_permission_card(
+        tool="shell",
+        command="git push origin main",
+        severity="elevated",
+        agent="evoflux",
+        always_glob="git push *",
+        always_token="always-tok",
+        once_token="once-tok",
+        reject_token="reject-tok",
+    )
+    assert "git push *" in text or any("git push *" in b.text for b in buttons)
+    assert buttons == (
+        RemoteButton(text="Allow once", token="once-tok"),
+        RemoteButton(
+            text="\U0001f512 Allow for session — git push *", token="always-tok"
+        ),
+        RemoteButton(text="Reject", token="reject-tok"),
+    )
+
+
+def test_render_permission_card_omits_always_button_without_glob():
+    _, buttons = formatting.render_permission_card(
+        tool="read",
+        command="tests/test_auth.py",
+        severity="normal",
+        agent="evoflux",
+        always_glob=None,
+        always_token=None,
+        once_token="once-tok",
+        reject_token="reject-tok",
+    )
+    assert len(buttons) == 2
+
+
+def test_render_permission_resolved_card_states_decision_and_has_no_buttons():
+    text, buttons = formatting.render_permission_resolved_card(
+        command="rm -rf build/", resolution="once"
+    )
+    assert "rm -rf build/" in text
+    assert "Allowed once" in text
+    assert buttons == ()
+
+
+def test_render_permission_resolved_card_escapes_command():
+    text, _ = formatting.render_permission_resolved_card(
+        command="", resolution="reject"
+    )
+    assert "" not in text
+    assert "<script>" in text
+```
+
+- [ ] **Step 2: Run and confirm failure**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/test_formatting.py -k permission
+```
+
+Expected: FAIL with `AttributeError: module 'app.remote.formatting' has no
+attribute 'render_permission_card'`.
+
+- [ ] **Step 3: Implement the builders**
+
+```python
+# app/remote/formatting.py — add to __all__:
+    "render_permission_card",
+    "render_permission_resolved_card",
+```
+
+```python
+# app/remote/formatting.py — new module-level constants, near _STATUS_ICON
+_SEVERITY_ICON = {"high": "\U0001f534", "elevated": "\U0001f7e0", "normal": "\U0001f527"}
+_SEVERITY_LABEL = {
+    "high": "Dangerous command",
+    "elevated": "Command",
+    "normal": "Permission requested",
+}
+_RESOLUTION_ICON = {"once": "✅", "always": "\U0001f512", "reject": "❌"}
+_RESOLUTION_LABEL = {
+    "once": "Allowed once",
+    "always": "Allowed for session",
+    "reject": "Rejected",
+}
+```
+
+```python
+# app/remote/formatting.py — new functions
+def render_permission_card(
+    *,
+    tool: str,
+    command: str,
+    severity: str,
+    agent: str,
+    always_glob: str | None,
+    always_token: str | None,
+    once_token: str,
+    reject_token: str,
+) -> tuple[str, tuple[RemoteButton, ...]]:
+    icon = _SEVERITY_ICON.get(severity, "\U0001f527")
+    label = _SEVERITY_LABEL.get(severity, "Permission requested")
+    text = (
+        f"{icon} {escape(label)}\n"
+        f"
{escape(command)}
\n"
+        f"{escape(tool)} · {escape(agent)}"
+    )
+    buttons = [RemoteButton(text="Allow once", token=once_token)]
+    if always_token and always_glob:
+        buttons.append(
+            RemoteButton(
+                text=f"\U0001f512 Allow for session — {escape(always_glob)}",
+                token=always_token,
+            )
+        )
+    buttons.append(RemoteButton(text="Reject", token=reject_token))
+    return text, tuple(buttons)
+
+
+def render_permission_resolved_card(
+    *, command: str, resolution: str
+) -> tuple[str, tuple[RemoteButton, ...]]:
+    icon = _RESOLUTION_ICON.get(resolution, "✅")
+    label = _RESOLUTION_LABEL.get(resolution, "Resolved")
+    text = f"{icon} {escape(label)}\n
{escape(command)}
"
+    return text, ()
+```
+
+Note: `RemoteButton(text=f"...\U0001f512 Allow for session — {escape(always_glob)}", ...)`
+already escapes `always_glob` inline — the test's expected button text uses
+the literal glob `"git push *"` which contains no HTML-special characters,
+so `escape("git push *") == "git push *"` and the equality assertion holds.
+
+- [ ] **Step 4: Run and confirm pass**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/test_formatting.py
+```
+
+Expected: PASS (all tests in the file, including the 6 new ones).
+
+- [ ] **Step 5: Lint**
+
+```powershell
+uv run ruff check app/remote/formatting.py tests/remote/test_formatting.py
+uv run ty check app/remote/formatting.py
+```
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add app/remote/formatting.py tests/remote/test_formatting.py
+git commit -m "feat(remote): render permission cards with the real command and severity"
+```
+
+---
+
+### Task 3: Wire the gate bridge — real cards, `always` reply, and visible resolution
+
+**ACs:** AC-45, AC-46, AC-47, AC-28 (revised)
+
+**Files:**
+
+- Modify: `app/remote/gates.py`
+- Modify: `tests/remote/test_gates.py`
+
+**Interfaces:**
+
+- Changes `_PendingGate`: removes `chat_id`, `message_id`; adds
+  `command: str = ""`.
+- Changes `RemoteGateBridge._resolve_permission`: accepts `"always"` as a
+  valid `cap.action` in addition to `"once"`/`"reject"`.
+- Produces (private, no external callers): `_on_permission_asked`,
+  `_enqueue_resolved_edit`, `_do_resolved_edit`, `_resolution_text`.
+- Consumes: `app.remote.severity.derive_severity`,
+  `app.remote.formatting.render_permission_card`,
+  `app.remote.formatting.render_permission_resolved_card`.
+
+- [ ] **Step 1: Write failing tests for the real permission card**
+
+```python
+# tests/remote/test_gates.py (add near the permission-card tests)
+# Async + a drain sleep, matching this file's existing convention for
+# on_gate tests (_enqueue_send schedules a fire-and-forget task; a plain
+# sync test has no running loop for that task to be scheduled on at all).
+@pytest.mark.asyncio
+async def test_on_gate_permission_renders_the_real_command(
+    bridge: RemoteGateBridge, adapter: FakeAdapter
+) -> None:
+    bridge.on_gate(
+        session_id="sess-1",
+        event_type="permission_asked",
+        data={
+            "request_id": "req-1",
+            "tool": "shell",
+            "patterns": ["rm -rf build/"],
+            "always_patterns": [],
+            "metadata": {"agent": "evoflux"},
+        },
+        connection_id=uuid4(),
+        destination_id="chat-1",
+    )
+    await asyncio.sleep(0.05)
+
+    assert len(adapter.sent) == 1
+    assert "rm -rf build/" in adapter.sent[0].text
+    assert "Permission requested: shell" not in adapter.sent[0].text
+    assert adapter.sent[0].correlation_id == "gate:req-1"
+    assert [b.text for b in adapter.sent[0].buttons] == ["Allow once", "Reject"]
+
+
+@pytest.mark.asyncio
+async def test_on_gate_permission_offers_allow_for_session_with_glob(
+    bridge: RemoteGateBridge, adapter: FakeAdapter
+) -> None:
+    bridge.on_gate(
+        session_id="sess-1",
+        event_type="permission_asked",
+        data={
+            "request_id": "req-1",
+            "tool": "shell",
+            "patterns": ["git push origin main"],
+            "always_patterns": ["git push *"],
+            "metadata": {"agent": "evoflux"},
+        },
+        connection_id=uuid4(),
+        destination_id="chat-1",
+    )
+    await asyncio.sleep(0.05)
+
+    button_texts = [b.text for b in adapter.sent[0].buttons]
+    assert len(button_texts) == 3
+    assert "git push *" in button_texts[1]
+```
+
+- [ ] **Step 2: Run and confirm failure**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/test_gates.py -k "real_command or allow_for_session"
+```
+
+Expected: FAIL — `adapter.sent[0].text` still says
+`"Permission requested: shell"`, no `correlation_id`.
+
+- [ ] **Step 3: Extract and rewrite the permission path in `on_gate`**
+
+```python
+# app/remote/gates.py — imports, add:
+import asyncio
+
+from app.remote.formatting import (
+    escape,
+    render_permission_card,
+    render_permission_resolved_card,
+)
+from app.remote.severity import derive_severity
+```
+
+```python
+# app/remote/gates.py — replace the _PendingGate dataclass
+@dataclass
+class _PendingGate:
+    """Tracks one gate's outstanding capabilities and the command text (if
+    any) needed to render its resolved form later."""
+
+    request_id: str
+    session_id: str
+    gate_kind: GateKind
+    tokens: list[str] = field(default_factory=list)
+    command: str = ""
+```
+
+```python
+# app/remote/gates.py — replace on_gate's body
+    def on_gate(
+        self,
+        session_id: str,
+        event_type: str,
+        data: dict,
+        connection_id: UUID,
+        destination_id: str,
+    ) -> None:
+        """Handle a gate event by creating opaque tokens and enqueuing a card.
+
+        Called by the projection's ``_handle_gate``.
+        """
+        request_id = data.get("request_id", "")
+        if not request_id:
+            return
+
+        if event_type == "permission_asked":
+            self._on_permission_asked(session_id, data, connection_id, destination_id, request_id)
+            return
+
+        gate_kind: GateKind
+        actions: list[tuple[str, str]]  # (action_label, button_text)
+
+        if event_type == "question_asked":
+            gate_kind = "question"
+            questions = data.get("questions", [])
+            if questions:
+                first_q = questions[0]
+                text = f"Question: {first_q.get('question', '')}"
+                options = first_q.get("options", [])
+                actions = [(opt, opt) for opt in options[:8]]  # bound to 8
+            else:
+                text = "Question asked."
+                actions = []
+        elif event_type == "plan_approval_requested":
+            gate_kind = "plan"
+            plan_text = data.get("plan", "")
+            steps = data.get("steps", [])
+            text = f"Plan ready for review ({len(steps)} steps)."
+            if plan_text:
+                text = f"Plan: {plan_text[:200]}"
+            actions = [("approve", "Approve"), ("reject", "Reject")]
+        else:
+            return
+
+        buttons: list[RemoteButton] = []
+        gate = _PendingGate(
+            request_id=request_id,
+            session_id=session_id,
+            gate_kind=gate_kind,
+        )
+
+        for action_value, button_text in actions:
+            token = self._issue_token(
+                connection_id=connection_id,
+                principal_id="",
+                destination_id=destination_id,
+                session_id=session_id,
+                request_id=request_id,
+                gate_kind=gate_kind,
+                action=action_value,
+            )
+            buttons.append(RemoteButton(text=button_text, token=token))
+            gate.tokens.append(token)
+            self._pending_by_token[token] = request_id
+
+        self._pending_gates[request_id] = gate
+
+        text = _redact_text(text)
+        msg = RemoteOutboundMessage(
+            connection_id=connection_id,
+            destination_id=destination_id,
+            text=text,
+            buttons=tuple(buttons),
+            priority=RemoteOutboundPriority.HIGH,
+            correlation_id=f"gate:{request_id}",
+        )
+        self._enqueue_send(msg)
+
+    def _on_permission_asked(
+        self,
+        session_id: str,
+        data: dict,
+        connection_id: UUID,
+        destination_id: str,
+        request_id: str,
+    ) -> None:
+        """Render and send a decidable permission card (AC-45/AC-46): the
+        real command and a derived, advisory-only severity, never a tool
+        name alone."""
+        tool = data.get("tool", "unknown")
+        patterns = data.get("patterns") or []
+        command = patterns[0] if patterns else tool
+        always_patterns = data.get("always_patterns") or []
+        always_glob = always_patterns[0] if always_patterns else None
+        agent_name = data.get("metadata", {}).get("agent", "agent")
+        severity = derive_severity(tool=tool, command=command)
+
+        gate = _PendingGate(
+            request_id=request_id,
+            session_id=session_id,
+            gate_kind="permission",
+            command=_redact_text(command),
+        )
+
+        once_token = self._issue_token(
+            connection_id=connection_id,
+            principal_id="",
+            destination_id=destination_id,
+            session_id=session_id,
+            request_id=request_id,
+            gate_kind="permission",
+            action="once",
+        )
+        gate.tokens.append(once_token)
+        self._pending_by_token[once_token] = request_id
+
+        always_token: str | None = None
+        if always_glob:
+            always_token = self._issue_token(
+                connection_id=connection_id,
+                principal_id="",
+                destination_id=destination_id,
+                session_id=session_id,
+                request_id=request_id,
+                gate_kind="permission",
+                action="always",
+            )
+            gate.tokens.append(always_token)
+            self._pending_by_token[always_token] = request_id
+
+        reject_token = self._issue_token(
+            connection_id=connection_id,
+            principal_id="",
+            destination_id=destination_id,
+            session_id=session_id,
+            request_id=request_id,
+            gate_kind="permission",
+            action="reject",
+        )
+        gate.tokens.append(reject_token)
+        self._pending_by_token[reject_token] = request_id
+
+        self._pending_gates[request_id] = gate
+
+        text, buttons = render_permission_card(
+            tool=tool,
+            command=gate.command,
+            severity=severity,
+            agent=agent_name,
+            always_glob=_redact_text(always_glob) if always_glob else None,
+            always_token=always_token,
+            once_token=once_token,
+            reject_token=reject_token,
+        )
+        msg = RemoteOutboundMessage(
+            connection_id=connection_id,
+            destination_id=destination_id,
+            text=text,
+            buttons=buttons,
+            priority=RemoteOutboundPriority.HIGH,
+            correlation_id=f"gate:{request_id}",
+        )
+        self._enqueue_send(msg)
+```
+
+- [ ] **Step 4: Update the one pre-existing test this rename breaks**
+
+`test_permission_gate_creates_allow_and_reject_buttons`
+(`TestGateRendering`) asserts the old button label verbatim:
+
+```python
+assert msg.buttons[0].text == "Allow"
+assert msg.buttons[1].text == "Reject"
+```
+
+`render_permission_card` labels the first button `"Allow once"`. Update
+those two lines in place:
+
+```python
+        assert msg.buttons[0].text == "Allow once"
+        assert msg.buttons[1].text == "Reject"
+```
+
+- [ ] **Step 5: Run and confirm all three pass**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/test_gates.py -k "real_command or allow_for_session or creates_allow_and_reject"
+```
+
+Expected: PASS (3 tests: the 2 new ones plus the updated pre-existing one).
+
+- [ ] **Step 6: Write a failing test for `always` reply support**
+
+Mirrors the existing `test_callback_resolves_permission_once`/
+`test_callback_resolves_permission_reject` in `TestCallbackOrdering`
+exactly — same `patch(...)` + `MagicMock` house style, going through the
+public `handle_callback`, not the private resolver.
+
+```python
+# tests/remote/test_gates.py (add to class TestCallbackOrdering)
+    @pytest.mark.asyncio
+    async def test_callback_resolves_permission_always(
+        self, bridge: RemoteGateBridge, adapter: FakeAdapter
+    ) -> None:
+        conn_id = uuid4()
+        bridge.on_gate(
+            session_id="sess-1",
+            event_type="permission_asked",
+            data={
+                "request_id": "req-1",
+                "tool": "shell",
+                "patterns": ["git push origin main"],
+                "always_patterns": ["git push *"],
+            },
+            connection_id=conn_id,
+            destination_id="chat-1",
+        )
+        await asyncio.sleep(0.05)
+
+        gate = bridge._pending_gates["req-1"]
+        # Token order from _on_permission_asked: once, always, reject.
+        always_token = gate.tokens[1]
+
+        from unittest.mock import patch
+
+        mock_svc = MagicMock()
+        mock_svc.reply.return_value = True
+
+        with patch(
+            "app.agent.permission.get_service_for_session", return_value=mock_svc
+        ):
+            action = _make_action(callback_token=always_token, connection_id=conn_id)
+            await bridge.handle_callback(action)
+
+        mock_svc.reply.assert_called_once_with("req-1", "always")
+```
+
+- [ ] **Step 7: Run and confirm failure**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/test_gates.py -k resolves_permission_always
+```
+
+Expected: FAIL — `remote_gate_invalid_permission_action` branch returns
+`False` for `action="always"`, so `mock_svc.reply` is never called.
+
+- [ ] **Step 8: Accept `always` in `_resolve_permission`**
+
+```python
+# app/remote/gates.py — replace _resolve_permission's action check
+    async def _resolve_permission(
+        self, cap: GateCapability, action: RemoteInboundAction
+    ) -> bool:
+        """Resolve a permission gate. Remote accepts once/always/reject
+        (AC-28, revised) — "always" is session-scoped in PermissionService
+        (it appends a rule to session_ruleset, not a permanent grant), which
+        is exactly what the remote card's "Allow for session" label says."""
+        from app.agent.permission import Reply, get_service_for_session
+
+        if cap.action not in ("once", "always", "reject"):
+            logger.warning(
+                "remote_gate_invalid_permission_action action={}",
+                cap.action,
+            )
+            return False
+        reply_value: Reply = cap.action  # ty: ignore[invalid-assignment]
+
+        svc = get_service_for_session(cap.session_id)
+        if svc is None:
+            logger.debug(
+                "remote_gate_permission_service_missing session_id={}",
+                cap.session_id,
+            )
+            return False
+
+        resolved = svc.reply(cap.request_id, reply_value)
+        if resolved:
+            logger.info(
+                "remote_gate_permission_resolved request_id={} reply={}",
+                cap.request_id,
+                reply_value,
+            )
+        return resolved
+```
+
+- [ ] **Step 9: Run and confirm pass**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/test_gates.py -k resolves_permission_always
+```
+
+Expected: PASS.
+
+- [ ] **Step 10: Write a failing test for visible resolution**
+
+`test_on_reply_cleans_up_capabilities` already exists in `TestReplyEvents`
+and covers capability/token cleanup — add the one thing it doesn't cover:
+that the card is actually edited into a resolved, decision-stating form.
+This test must be `async` (unlike its sync sibling) because
+`_enqueue_resolved_edit`'s fire-and-forget task needs a running event loop
+to actually schedule, and a brief `asyncio.sleep` to let that task run
+before asserting on `adapter.edited`.
+
+```python
+# tests/remote/test_gates.py — add to class TestReplyEvents
+    @pytest.mark.asyncio
+    async def test_on_reply_edits_the_card_to_a_resolved_form(
+        self, bridge: RemoteGateBridge, adapter: FakeAdapter
+    ) -> None:
+        bridge.on_gate(
+            session_id="sess-1",
+            event_type="permission_asked",
+            data={
+                "request_id": "req-1",
+                "tool": "shell",
+                "patterns": ["rm -rf build/"],
+            },
+            connection_id=uuid4(),
+            destination_id="chat-1",
+        )
+
+        bridge.on_reply(
+            "sess-1", "permission_replied", {"request_id": "req-1", "reply": "once"}
+        )
+        await asyncio.sleep(0.05)
+
+        assert len(adapter.edited) == 1
+        assert adapter.edited[0].correlation_id == "gate:req-1"
+        assert adapter.edited[0].buttons == ()
+        assert "Allowed once" in adapter.edited[0].text
+        assert "rm -rf build/" in adapter.edited[0].text
+```
+
+- [ ] **Step 11: Run and confirm failure**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/test_gates.py -k resolved_form
+```
+
+Expected: FAIL — `on_reply`'s `chat_id is not None and message_id is not
+None` guard is always false, so `adapter.edited` stays empty.
+
+- [ ] **Step 12: Replace `on_reply` and the dead edit path**
+
+```python
+# app/remote/gates.py — replace on_reply
+    def on_reply(self, session_id: str, event_type: str, data: dict) -> None:
+        """Handle a gate reply event by editing its card into a resolved,
+        button-free form (AC-47).
+
+        Called by the projection when a ``permission_replied``,
+        ``question_replied``, or ``plan_approval_replied`` event fires.
+        """
+        request_id = data.get("request_id", "")
+        if not request_id:
+            return
+
+        gate = self._pending_gates.pop(request_id, None)
+        if gate is None:
+            return
+
+        for token in gate.tokens:
+            self._capabilities.pop(token, None)
+            self._pending_by_token.pop(token, None)
+
+        resolution_text = self._resolution_text(gate, data)
+        self._enqueue_resolved_edit(gate, resolution_text)
+
+    def _resolution_text(self, gate: _PendingGate, data: dict) -> str:
+        """Build the resolved-form message text for one gate kind. Only
+        permission gates have a per-decision label defined by the spec
+        (AC-45's "Allowed once"/"Allowed for session"/"Rejected"); question
+        and plan gates get a generic resolved marker."""
+        if gate.gate_kind == "permission":
+            reply = data.get("reply", "reject")
+            text, _buttons = render_permission_resolved_card(
+                command=gate.command or "(command unavailable)", resolution=reply
+            )
+            return text
+        return "✅ Resolved"
+
+    def _enqueue_resolved_edit(self, gate: _PendingGate, text: str) -> None:
+        """Edit this gate's card into its resolved form — fire-and-forget,
+        matching the delivery pattern already used by ``_enqueue_send``."""
+        try:
+            loop = asyncio.get_running_loop()
+            loop.create_task(self._do_resolved_edit(gate, text))
+        except RuntimeError:
+            pass
+
+    async def _do_resolved_edit(self, gate: _PendingGate, text: str) -> None:
+        try:
+            msg = RemoteOutboundMessage(
+                connection_id=UUID(int=0),  # not used for edit lookup
+                destination_id="",
+                text=text,
+                buttons=(),
+                correlation_id=f"gate:{gate.request_id}",
+            )
+            await self._adapter.edit(msg)
+        except Exception as exc:
+            logger.debug(
+                "remote_gate_resolved_edit_failed request_id={} error={}",
+                gate.request_id,
+                exc,
+            )
+```
+
+```python
+# app/remote/gates.py — delete the now-unused _edit_remove_buttons and
+# _do_edit_remove methods entirely (replaced by _enqueue_resolved_edit /
+# _do_resolved_edit above).
+```
+
+- [ ] **Step 13: Run and confirm pass**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/test_gates.py
+```
+
+Expected: PASS (every test in the file, including the pre-existing
+`test_on_reply_cleans_up_capabilities` and the new resolved-form test).
+
+- [ ] **Step 14: Full remote suite and lint**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/
+uv run ruff check app/remote/gates.py tests/remote/test_gates.py
+uv run ty check app/remote/gates.py
+```
+
+Expected: all green. If any other test in the suite referenced
+`_edit_remove_buttons`, `_PendingGate.chat_id`, or `_PendingGate.message_id`
+directly, update it to the new `_enqueue_resolved_edit` path — grep first:
+
+```powershell
+grep -rn "chat_id\|message_id\|_edit_remove_buttons" tests/remote/test_gates.py
+```
+
+- [ ] **Step 15: Commit**
+
+```bash
+git add app/remote/gates.py tests/remote/test_gates.py
+git commit -m "fix(remote): permission cards show the real command and actually resolve"
+```
+
+---
+
+## Self-review notes
+
+- **Spec coverage:** AC-45 (Task 2 + 3's card rendering), AC-46 (Task 1 +
+  Task 2's severity display), AC-47 (Task 3's correlation-id send + resolved
+  edit + dead-field removal), AC-28 revised (Task 3 Steps 5-8's `always`
+  support) are each covered by a task above. AC-48 through AC-58 (mode/model/
+  agent control, health, changes, live mode, onboarding, command-set) are
+  explicitly out of scope for this plan — they are later phases of the same
+  spec, to be written as separate plan documents once this phase lands, per
+  the spec's own stated rollout order.
+- **Type consistency:** `_PendingGate.command` (Task 3) matches the
+  `gate.command` reads in `_resolution_text`; `render_permission_card`'s
+  parameter names (Task 2) match every call site in `_on_permission_asked`
+  (Task 3) exactly; `_resolve_permission`'s `Reply` import and literal values
+  match `app/agent/permission.py:63`'s `Reply = Literal["once", "always",
+  "reject"]` verified during spec research.
+- **No placeholders:** every step above contains complete, runnable code —
+  no "similar to Task N" references, no TODO markers.
diff --git a/tests/remote/test_gates.py b/tests/remote/test_gates.py
index 0eecb461..b15ee77e 100644
--- a/tests/remote/test_gates.py
+++ b/tests/remote/test_gates.py
@@ -347,6 +347,42 @@ async def test_callback_resolves_permission_reject(
 
         mock_svc.reply.assert_called_once_with("req-1", "reject")
 
+    @pytest.mark.asyncio
+    async def test_callback_resolves_permission_always(
+        self, bridge: RemoteGateBridge, adapter: FakeAdapter
+    ) -> None:
+        conn_id = uuid4()
+        bridge.on_gate(
+            session_id="sess-1",
+            event_type="permission_asked",
+            data={
+                "request_id": "req-1",
+                "tool": "shell",
+                "patterns": ["git push origin main"],
+                "always_patterns": ["git push *"],
+            },
+            connection_id=conn_id,
+            destination_id="chat-1",
+        )
+        await asyncio.sleep(0.05)
+
+        gate = bridge._pending_gates["req-1"]
+        # Token order from _on_permission_asked: once, always, reject.
+        always_token = gate.tokens[1]
+
+        from unittest.mock import patch
+
+        mock_svc = MagicMock()
+        mock_svc.reply.return_value = True
+
+        with patch(
+            "app.agent.permission.get_service_for_session", return_value=mock_svc
+        ):
+            action = _make_action(callback_token=always_token, connection_id=conn_id)
+            await bridge.handle_callback(action)
+
+        mock_svc.reply.assert_called_once_with("req-1", "always")
+
 
 # ── Validation and ownership ──────────────────────────────────────────────────
 
@@ -567,6 +603,33 @@ def test_on_reply_cleans_up_capabilities(self, bridge: RemoteGateBridge) -> None
             assert t not in bridge._capabilities
             assert t not in bridge._pending_by_token
 
+    @pytest.mark.asyncio
+    async def test_on_reply_edits_the_card_to_a_resolved_form(
+        self, bridge: RemoteGateBridge, adapter: FakeAdapter
+    ) -> None:
+        bridge.on_gate(
+            session_id="sess-1",
+            event_type="permission_asked",
+            data={
+                "request_id": "req-1",
+                "tool": "shell",
+                "patterns": ["rm -rf build/"],
+            },
+            connection_id=uuid4(),
+            destination_id="chat-1",
+        )
+
+        bridge.on_reply(
+            "sess-1", "permission_replied", {"request_id": "req-1", "reply": "once"}
+        )
+        await asyncio.sleep(0.05)
+
+        assert len(adapter.edited) == 1
+        assert adapter.edited[0].correlation_id == "gate:req-1"
+        assert adapter.edited[0].buttons == ()
+        assert "Allowed once" in adapter.edited[0].text
+        assert "rm -rf build/" in adapter.edited[0].text
+
     def test_on_reply_unknown_request_id_noop(self, bridge: RemoteGateBridge) -> None:
         bridge.on_reply(
             session_id="sess-1",

From 4d0ff925f51047a0b151b21992d0757100d1d7c1 Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Tue, 15 Sep 2026 09:04:14 +0700
Subject: [PATCH 32/71] docs(remote): update gates.py's module docstring for
 the AC-28/AC-47 revisions

---
 app/remote/gates.py | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/app/remote/gates.py b/app/remote/gates.py
index 5b555f4c..569ef433 100644
--- a/app/remote/gates.py
+++ b/app/remote/gates.py
@@ -9,8 +9,11 @@
 - Callback tokens are opaque, random, connection/principal-bound, and <=64 bytes.
 - Internal IDs (session_id, request_id) are never serialized into callback data.
 - ``answer_callback`` is called before any gate resolution (AC-26).
-- ``edit_text`` removes buttons after resolution.
-- Remote permission replies are limited to ``once`` and ``reject`` (AC-28).
+- A resolved gate's card is edited into a button-free, decision-stating
+  form (AC-47) — never left with live buttons after a reply.
+- Remote permission replies accept ``once``, ``always``, and ``reject``
+  (AC-28, revised) — ``always`` is session-scoped in ``PermissionService``
+  (appends a rule to ``session_ruleset``), not a permanent grant.
 """
 
 from __future__ import annotations

From 91de167e0e2bbc1970ace41f678196e9f19adb26 Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Tue, 15 Sep 2026 10:02:15 +0700
Subject: [PATCH 33/71] fix(dev): make run_dev.py's process supervision work on
 Windows
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Confirmed root cause of the original desktop-closing bug report: this
script unconditionally called os.killpg() and referenced signal.SIGKILL
in two places (signal_process_group for shutting down sibling services,
stop_dev_ports for the startup stale-port cleanup) — neither exists on
Windows. Every attempt to stop siblings when one service exited, or to
force-kill a stale process still holding a dev port at startup, raised
an uncaught AttributeError on this platform instead of doing its job.

That directly explains the earlier finding that run_dev.py kills every
sibling process the instant one exits (by design) — on Windows that
kill attempt itself crashed with AttributeError, and confirms why a
stale process was found still holding port 8000 at the start of this
session instead of stop_dev_ports cleaning it up automatically.

Windows has no process-group signal or SIGKILL equivalent, and a bare
Popen.terminate()/kill() only reaches the tracked process itself — not
any child it spawned (e.g. uvicorn --reload's worker), which is exactly
the orphaned-process pattern found manually earlier this session.
`taskkill /T /F` kills the whole process tree, matching what os.killpg
does on POSIX.

Also marks test_supervisor_maps_interrupt_to_130 skipped on Windows:
os.kill(getpid(), SIGINT) maps to a console CTRL_C_EVENT there, which
the OS broadcasts to the whole console process group (including the
test process itself) rather than something this script's own code
controls — a test-simulation limitation, not a production bug.
---
 scripts/run_dev.py            | 56 +++++++++++++++++++++++++++++++----
 tests/scripts/test_run_dev.py | 27 ++++++++++++++++-
 2 files changed, 77 insertions(+), 6 deletions(-)

diff --git a/scripts/run_dev.py b/scripts/run_dev.py
index d20fbad7..a623f256 100644
--- a/scripts/run_dev.py
+++ b/scripts/run_dev.py
@@ -27,6 +27,13 @@
 VITE_PORT = 5173
 SHUTDOWN_TIMEOUT_SECONDS = 5.0
 
+#: Neither ``os.killpg`` nor ``signal.SIGKILL`` exist on Windows — every
+#: unconditional reference to either raised an uncaught ``AttributeError``
+#: whenever this script actually needed to stop or force-kill a process on
+#: that platform (both stop_dev_ports's startup cleanup and
+#: signal_process_group's shutdown path).
+_IS_WINDOWS = sys.platform == "win32"
+
 
 @dataclass(frozen=True)
 class Service:
@@ -101,6 +108,25 @@ def listening_pids(port: int) -> list[int]:
     return [int(value) for value in result.stdout.split()]
 
 
+def _force_kill_pid(pid: int) -> None:
+    """Hard-kill an arbitrary PID discovered via port inspection — unlike
+    :func:`signal_process_group`, this PID wasn't spawned by us, so there
+    is no tracked ``Popen`` to call ``.kill()`` on. ``signal.SIGKILL``
+    doesn't exist on Windows; ``taskkill`` is the direct equivalent."""
+    if _IS_WINDOWS:
+        subprocess.run(
+            ["taskkill", "/T", "/F", "/PID", str(pid)],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            check=False,
+        )
+        return
+    try:
+        os.kill(pid, signal.SIGKILL)
+    except ProcessLookupError:
+        pass
+
+
 def stop_dev_ports(ports: list[int]) -> None:
     for port in ports:
         pids = listening_pids(port)
@@ -123,10 +149,7 @@ def stop_dev_ports(ports: list[int]) -> None:
                 f"{' '.join(map(str, remaining))}"
             )
             for pid in remaining:
-                try:
-                    os.kill(pid, signal.SIGKILL)
-                except ProcessLookupError:
-                    pass
+                _force_kill_pid(pid)
 
 
 def build_services(
@@ -185,8 +208,25 @@ def stream_output(name: str, output: BinaryIO, lock: threading.Lock) -> None:
 
 
 def signal_process_group(process: subprocess.Popen[bytes], sig: signal.Signals) -> None:
+    """Best-effort process-*tree* termination, not just the tracked PID.
+
+    POSIX: the process was spawned in its own session (``start_new_session``
+    in :func:`spawn_service`), so ``os.killpg`` reaches it and anything it
+    spawned. Windows has no process-group signaling to match, and a bare
+    ``Popen.terminate()``/``kill()`` only ever reaches the tracked process
+    itself — any child *that* process spawned (e.g. ``uvicorn --reload``'s
+    worker) is left running, orphaned, still holding its port. ``taskkill
+    /T`` kills the whole tree, the Windows equivalent of a process-group
+    signal. There is no Windows equivalent of a *graceful* process-group
+    signal (``CTRL_BREAK_EVENT`` only reaches a process's own registered
+    ``SIGBREAK`` handler, never an arbitrary ``SIGTERM`` handler), so
+    Windows always force-kills regardless of *sig*.
+    """
     if process.poll() is not None:
         return
+    if _IS_WINDOWS:
+        _force_kill_pid(process.pid)
+        return
     try:
         os.killpg(process.pid, sig)
     except ProcessLookupError:
@@ -204,7 +244,13 @@ def stop_processes(
         try:
             process.wait(timeout=remaining)
         except subprocess.TimeoutExpired:
-            signal_process_group(process, signal.SIGKILL)
+            # POSIX escalates to SIGKILL; Windows already force-killed the
+            # whole tree above (there is no weaker "initial_signal" on
+            # Windows to begin with), so re-signal with whatever the
+            # platform actually defines instead of the POSIX-only SIGKILL.
+            signal_process_group(
+                process, signal.SIGKILL if not _IS_WINDOWS else initial_signal
+            )
     for process in processes:
         try:
             process.wait(timeout=1.0)
diff --git a/tests/scripts/test_run_dev.py b/tests/scripts/test_run_dev.py
index 83dfdf0d..e6f22943 100644
--- a/tests/scripts/test_run_dev.py
+++ b/tests/scripts/test_run_dev.py
@@ -8,6 +8,8 @@
 import time
 from pathlib import Path
 
+import pytest
+
 
 SCRIPT = Path(__file__).resolve().parents[2] / "scripts" / "run_dev.py"
 SPEC = importlib.util.spec_from_file_location("run_dev", SCRIPT)
@@ -56,9 +58,32 @@ def test_supervisor_stops_siblings_when_a_service_fails(tmp_path: Path) -> None:
     )
 
     assert run_dev.supervise([long_running, failing]) == 7
-    assert marker.read_text() == "yes"
+
+    if sys.platform == "win32":
+        # Windows has no process-group signal that reaches an arbitrary
+        # SIGTERM handler (CTRL_BREAK_EVENT only reaches a SIGBREAK
+        # handler) — the supervisor force-kills the whole tree instead
+        # (see signal_process_group's docstring), so there is no graceful
+        # marker to check here. The meaningful assertion already
+        # happened above: supervise() returned 7 instead of hanging on
+        # the "long" service's sleep(30).
+        pass
+    else:
+        assert marker.read_text() == "yes"
 
 
+@pytest.mark.skipif(
+    sys.platform == "win32",
+    reason=(
+        "os.kill(getpid(), SIGINT) maps to GenerateConsoleCtrlEvent"
+        "(CTRL_C_EVENT) on Windows, which the OS broadcasts to every"
+        " process attached to the current console — including this test"
+        " process itself, outside of run_dev.py's own control — rather"
+        " than delivering a signal this test can scope to just the child"
+        " it spawned. Crashes the interpreter instead of exercising"
+        " run_dev.py's own SIGINT handling."
+    ),
+)
 def test_supervisor_maps_interrupt_to_130(tmp_path: Path) -> None:
     service = run_dev.Service(
         name="long",

From 5456e3c8545abd3bfbfafdd63b86bac23ea0a993 Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Tue, 15 Sep 2026 10:14:47 +0700
Subject: [PATCH 34/71] feat(remote): add permission-mode control, bypass
 excluded

Phase 2 (Task 1) of documents/plans/remote-telegram-control-implementation.md.
---
 app/remote/control.py        | 83 ++++++++++++++++++++++++++++++++++++
 tests/remote/test_control.py | 60 ++++++++++++++++++++++++++
 2 files changed, 143 insertions(+)
 create mode 100644 app/remote/control.py
 create mode 100644 tests/remote/test_control.py

diff --git a/app/remote/control.py b/app/remote/control.py
new file mode 100644
index 00000000..142dbdfd
--- /dev/null
+++ b/app/remote/control.py
@@ -0,0 +1,83 @@
+"""Mode/model/lead-agent control for the phone's /settings command.
+
+Each write function replicates the exact persistence sequence its HTTP
+route sibling already uses (app/api/routes/team/chat.py's
+set_session_permission_mode/update_team_session_lead,
+app/api/routes/team/webbridge.py's update_browser_session_model), as a
+plain async function app/remote/actions.py can call directly — remote
+and desktop must stay behaviorally identical, but app/remote/ never
+depends on app/api/routes/* (see list_model_ids/set_model for the one
+deliberate departure: the model registry).
+
+bypass is deliberately excluded from ALLOWED_REMOTE_MODES, checked by
+name (not by list length or position) before anything else runs — a
+phone that could enable bypass could silently disable every approval
+prompt an operator relies on (AC-48).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal, cast
+from uuid import UUID
+
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from app.models.chat import ChatSession
+
+__all__ = [
+    "ALLOWED_REMOTE_MODES",
+    "ControlResult",
+    "set_permission_mode",
+]
+
+#: Every permission mode this phone may set — bypass excluded on purpose.
+ALLOWED_REMOTE_MODES: tuple[str, ...] = ("ask", "accept-edits", "plan", "auto")
+
+ControlStatus = Literal["ok", "invalid", "not_found", "conflict"]
+
+
+@dataclass(frozen=True)
+class ControlResult:
+    """A bounded, adapter-neutral outcome for one control write."""
+
+    status: ControlStatus
+    detail: str = ""
+
+
+async def set_permission_mode(
+    db: AsyncSession, session_id: str, mode: str
+) -> ControlResult:
+    if mode not in ALLOWED_REMOTE_MODES:
+        return ControlResult(status="invalid", detail=mode)
+
+    try:
+        session_uuid = UUID(session_id)
+    except ValueError:
+        return ControlResult(status="not_found")
+    session = await db.get(ChatSession, session_uuid)
+    if session is None:
+        return ControlResult(status="not_found")
+
+    session.permission_mode = mode
+    session_mode = session.mode
+    session_workspace = session.workspace
+    db.add(session)
+    await db.commit()
+
+    from app.services import team_manager
+
+    team_obj = team_manager.current_team_for_session(session_id)
+    if team_obj is None and session_mode == "coding" and session_workspace:
+        team_obj = team_manager.current_coding_team_for_session(
+            session_workspace, session_id
+        )
+    if team_obj is not None:
+        team_obj.permission_mode = mode
+
+    from app.agent.permission import Mode, get_services_for_stream
+
+    for service in get_services_for_stream(session_id):
+        service.set_mode(cast(Mode, mode))
+
+    return ControlResult(status="ok")
diff --git a/tests/remote/test_control.py b/tests/remote/test_control.py
new file mode 100644
index 00000000..00df3c17
--- /dev/null
+++ b/tests/remote/test_control.py
@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from uuid import UUID
+
+import pytest
+import pytest_asyncio
+
+import app.core.db as db_module
+from app.models.chat import ChatSession
+from app.remote import control
+
+
+@pytest_asyncio.fixture
+async def chat_session() -> ChatSession:
+    async with db_module.async_session_factory() as db:
+        session = ChatSession(title="Control test", mode="work", session_type="main")
+        db.add(session)
+        await db.commit()
+        await db.refresh(session)
+        return session
+
+
+@pytest.mark.asyncio
+async def test_set_permission_mode_persists_a_valid_mode(chat_session: ChatSession) -> None:
+    async with db_module.async_session_factory() as db:
+        result = await control.set_permission_mode(db, str(chat_session.id), "ask")
+
+    assert result.status == "ok"
+    async with db_module.async_session_factory() as db:
+        refreshed = await db.get(ChatSession, chat_session.id)
+        assert refreshed is not None
+        assert refreshed.permission_mode == "ask"
+
+
+@pytest.mark.asyncio
+async def test_set_permission_mode_rejects_bypass(chat_session: ChatSession) -> None:
+    async with db_module.async_session_factory() as db:
+        result = await control.set_permission_mode(db, str(chat_session.id), "bypass")
+
+    assert result.status == "invalid"
+    async with db_module.async_session_factory() as db:
+        refreshed = await db.get(ChatSession, chat_session.id)
+        assert refreshed is not None
+        assert refreshed.permission_mode != "bypass"
+
+
+@pytest.mark.asyncio
+async def test_set_permission_mode_rejects_unknown_mode(chat_session: ChatSession) -> None:
+    async with db_module.async_session_factory() as db:
+        result = await control.set_permission_mode(db, str(chat_session.id), "nonsense")
+
+    assert result.status == "invalid"
+
+
+@pytest.mark.asyncio
+async def test_set_permission_mode_not_found_for_unknown_session() -> None:
+    async with db_module.async_session_factory() as db:
+        result = await control.set_permission_mode(db, str(UUID(int=0)), "ask")
+
+    assert result.status == "not_found"

From e6eb1e8f44ad4f86fdb31100bbd22f0219cfb878 Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Tue, 15 Sep 2026 10:17:03 +0700
Subject: [PATCH 35/71] feat(remote): add lead-agent control
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 2 (Task 2) of documents/plans/remote-telegram-control-implementation.md.

Tests mock team_manager.configured_lead_rosters rather than depending on
real agent configs, since this worktree's isolated test config dirs have
none seeded — discovered by running the plan's first draft against the
real filesystem and finding it returned an empty roster.
---
 app/remote/control.py                         |   58 +
 .../remote-telegram-control-implementation.md | 1088 +++++++++++++++++
 tests/remote/test_control.py                  |   91 ++
 3 files changed, 1237 insertions(+)
 create mode 100644 documents/plans/remote-telegram-control-implementation.md

diff --git a/app/remote/control.py b/app/remote/control.py
index 142dbdfd..06abb41b 100644
--- a/app/remote/control.py
+++ b/app/remote/control.py
@@ -29,6 +29,8 @@
     "ALLOWED_REMOTE_MODES",
     "ControlResult",
     "set_permission_mode",
+    "set_lead_agent",
+    "list_lead_names",
 ]
 
 #: Every permission mode this phone may set — bypass excluded on purpose.
@@ -81,3 +83,59 @@ async def set_permission_mode(
         service.set_mode(cast(Mode, mode))
 
     return ControlResult(status="ok")
+
+
+async def list_lead_names(app_mode: str, *, limit: int = 5) -> list[str]:
+    """A short, stable-order list of configured lead-agent names for
+    *app_mode* ("work"/"coding") — bounded for a phone's button row, same
+    pattern already used for workflow/project menu items in actions.py."""
+    from app.services import team_manager
+
+    try:
+        _default_lead, rosters = team_manager.configured_lead_rosters(app_mode)
+    except ValueError:
+        return []
+    return [lead.name for lead, _path, _members in rosters][:limit]
+
+
+async def set_lead_agent(
+    db: AsyncSession, session_id: str, lead_name: str
+) -> ControlResult:
+    from app.models.chat import normalize_mode
+    from app.services import memory_stream_store as stream_store
+    from app.services import team_manager
+
+    try:
+        session_uuid = UUID(session_id)
+    except ValueError:
+        return ControlResult(status="not_found")
+    session = await db.get(ChatSession, session_uuid)
+    if session is None:
+        return ControlResult(status="not_found")
+    if session.parent_session_id is not None:
+        return ControlResult(status="not_found")
+
+    live_team = team_manager.find_team_for_session(session_id)
+    if session_id in stream_store.running_session_ids() or (
+        live_team is not None
+        and any(member.state == "working" for member in live_team.all_members)
+    ):
+        return ControlResult(
+            status="conflict",
+            detail="Finish or stop the active task before changing lead.",
+        )
+
+    app_mode = normalize_mode(session.mode)
+    try:
+        selected = team_manager.resolve_configured_lead(app_mode, lead_name)
+    except ValueError as exc:
+        return ControlResult(status="invalid", detail=str(exc))
+
+    if session.agent_name != selected:
+        session.agent_name = selected
+        db.add(session)
+        await db.commit()
+        await db.refresh(session)
+        await team_manager.stop_sessions({session_id})
+
+    return ControlResult(status="ok")
diff --git a/documents/plans/remote-telegram-control-implementation.md b/documents/plans/remote-telegram-control-implementation.md
new file mode 100644
index 00000000..5cdc0046
--- /dev/null
+++ b/documents/plans/remote-telegram-control-implementation.md
@@ -0,0 +1,1088 @@
+# Remote Telegram: Settings Control (Mode, Model, Lead Agent) Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Let a paired phone view and change a session's permission mode, model, and lead agent via `/settings` — Phase 2 of the control-surface spec, covering AC-48, AC-49, and AC-50. `bypass` permission mode is never offered or accepted remotely, under any code path.
+
+**Architecture:** One new module, `app/remote/control.py`, owns every write (`set_permission_mode`, `set_lead_agent`, `set_model`) and the two bounded read helpers (`list_lead_names`, `list_model_ids`) that back the settings card's button rows — each write function replicates the exact persistence sequence its HTTP-route sibling already uses (same service-layer calls: `team_manager`, `app.agent.permission`, `app.models.chat`), so remote and desktop stay behaviorally identical, but as plain async functions `app/remote/actions.py` can call directly without HTTP. `formatting.py` gains settings-card support for the three new button rows. `actions.py` gains the `/settings` command and capability dispatch for taps.
+
+**Tech Stack:** Python 3.12, FastAPI, SQLModel, asyncio, pytest, pytest-asyncio.
+
+**Spec:** [`remote-telegram-control-surface.md`](remote-telegram-control-surface.md) (amends `remote-channel-telegram.md` and `remote-telegram-response-ui.md`) — this plan implements exactly AC-48, AC-49, and AC-50. AC-51 through AC-58 (health, changes, providers-read-only, onboarding, response modes, command-set) are later phases.
+
+## Global Constraints
+
+- `bypass` is never settable remotely, under any command, button, callback, or forged token — excluded by name in `control.py`, not merely omitted from a menu (AC-48).
+- Severity/mode/model/agent changes never bypass the service layer's own validation (`resolve_configured_lead` raises `ValueError` on an unknown name; the model registry is the sole source of valid model ids) — `control.py` surfaces those as a bounded `ControlResult`, never swallows or reinterprets them.
+- Every write function takes an already-open `AsyncSession` (the caller's, per the existing `dispatch_command(db, action)` pattern in `actions.py`) — it never opens its own `async_session_factory()`.
+- `app/remote/` depends only on the service layer (`app.services.*`, `app.agent.*`, `app.models.*`) — never on `app/api/routes/*` — with exactly one documented, deliberate exception: `get_registry` (model catalog) has no service-layer equivalent, so `control.py` imports it directly from `app.api.routes.agents`, called as a plain function (its `Query(...)` parameters are just OpenAPI metadata on plain defaults; it takes no `Request`/`Depends`-injected state).
+- Every task cites its spec ACs, writes a failing test before implementation, and leaves the test suite green at its checkpoint.
+- Commit at the end of each task.
+
+---
+
+## File and interface map
+
+New units:
+
+- `app/remote/control.py` — `ALLOWED_REMOTE_MODES`, `ControlResult`, `set_permission_mode`, `set_lead_agent`, `set_model`, `list_lead_names`, `list_model_ids`.
+- `tests/remote/test_control.py`.
+
+Changed units:
+
+- `app/remote/formatting.py` — `render_settings_card` gains `mode_tokens`, `agent_name`/`agent_tokens`, `model_tokens` parameters; `redaction_policy`/`notify_scope`/`redaction_tokens`/`notify_scope_tokens` become optional (a later phase wires those; this phase's `/settings` doesn't supply them yet).
+- `app/remote/actions.py` — `_SLASH_COMMANDS` gains `"settings"`; new `_cmd_settings`; new capability action kinds `set_mode`/`set_agent`/`set_model` in `_execute_action`.
+- `tests/remote/test_formatting.py`, `tests/remote/test_actions.py` — updated/new focused evidence.
+
+---
+
+### Task 1: `set_permission_mode`
+
+**ACs:** AC-48
+
+**Files:**
+
+- Create: `app/remote/control.py`
+- Create: `tests/remote/test_control.py`
+
+**Interfaces:**
+
+- Produces: `ALLOWED_REMOTE_MODES: tuple[str, ...]` (`"ask"`, `"accept-edits"`, `"plan"`, `"auto"` — no `"bypass"`), `ControlResult` (`status: Literal["ok","invalid","not_found"]`, `detail: str = ""`), `async def set_permission_mode(db: AsyncSession, session_id: str, mode: str) -> ControlResult`.
+- Consumes: `app.models.chat.ChatSession`, `app.services.team_manager.current_team_for_session`/`current_coding_team_for_session`, `app.agent.permission.get_services_for_stream`/`Mode`.
+
+- [ ] **Step 1: Write the failing tests**
+
+```python
+# tests/remote/test_control.py
+from __future__ import annotations
+
+from uuid import UUID
+
+import pytest
+import pytest_asyncio
+
+import app.core.db as db_module
+from app.models.chat import ChatSession
+from app.remote import control
+
+
+@pytest_asyncio.fixture
+async def chat_session() -> ChatSession:
+    async with db_module.async_session_factory() as db:
+        session = ChatSession(title="Control test", mode="work", session_type="main")
+        db.add(session)
+        await db.commit()
+        await db.refresh(session)
+        return session
+
+
+@pytest.mark.asyncio
+async def test_set_permission_mode_persists_a_valid_mode(chat_session: ChatSession) -> None:
+    async with db_module.async_session_factory() as db:
+        result = await control.set_permission_mode(db, str(chat_session.id), "ask")
+
+    assert result.status == "ok"
+    async with db_module.async_session_factory() as db:
+        refreshed = await db.get(ChatSession, chat_session.id)
+        assert refreshed is not None
+        assert refreshed.permission_mode == "ask"
+
+
+@pytest.mark.asyncio
+async def test_set_permission_mode_rejects_bypass(chat_session: ChatSession) -> None:
+    async with db_module.async_session_factory() as db:
+        result = await control.set_permission_mode(db, str(chat_session.id), "bypass")
+
+    assert result.status == "invalid"
+    async with db_module.async_session_factory() as db:
+        refreshed = await db.get(ChatSession, chat_session.id)
+        assert refreshed is not None
+        assert refreshed.permission_mode != "bypass"
+
+
+@pytest.mark.asyncio
+async def test_set_permission_mode_rejects_unknown_mode(chat_session: ChatSession) -> None:
+    async with db_module.async_session_factory() as db:
+        result = await control.set_permission_mode(db, str(chat_session.id), "nonsense")
+
+    assert result.status == "invalid"
+
+
+@pytest.mark.asyncio
+async def test_set_permission_mode_not_found_for_unknown_session() -> None:
+    async with db_module.async_session_factory() as db:
+        result = await control.set_permission_mode(db, str(UUID(int=0)), "ask")
+
+    assert result.status == "not_found"
+```
+
+- [ ] **Step 2: Run and confirm failure**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/test_control.py
+```
+
+Expected: FAIL with `ModuleNotFoundError: No module named 'app.remote.control'`.
+
+- [ ] **Step 3: Implement `control.py` (mode-switching slice)**
+
+```python
+# app/remote/control.py
+"""Mode/model/lead-agent control for the phone's /settings command.
+
+Each write function replicates the exact persistence sequence its HTTP
+route sibling already uses (app/api/routes/team/chat.py's
+set_session_permission_mode/update_team_session_lead,
+app/api/routes/team/webbridge.py's update_browser_session_model), as a
+plain async function app/remote/actions.py can call directly — remote
+and desktop must stay behaviorally identical, but app/remote/ never
+depends on app/api/routes/* (see module docstring exception below for
+the one deliberate departure: the model registry).
+
+bypass is deliberately excluded from ALLOWED_REMOTE_MODES, checked by
+name (not by list length or position) before anything else runs — a
+phone that could enable bypass could silently disable every approval
+prompt an operator relies on (AC-48).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal, cast
+from uuid import UUID
+
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from app.models.chat import ChatSession
+
+__all__ = [
+    "ALLOWED_REMOTE_MODES",
+    "ControlResult",
+    "set_permission_mode",
+]
+
+#: Every permission mode this phone may set — bypass excluded on purpose.
+ALLOWED_REMOTE_MODES: tuple[str, ...] = ("ask", "accept-edits", "plan", "auto")
+
+ControlStatus = Literal["ok", "invalid", "not_found", "conflict"]
+
+
+@dataclass(frozen=True)
+class ControlResult:
+    """A bounded, adapter-neutral outcome for one control write."""
+
+    status: ControlStatus
+    detail: str = ""
+
+
+async def set_permission_mode(
+    db: AsyncSession, session_id: str, mode: str
+) -> ControlResult:
+    if mode not in ALLOWED_REMOTE_MODES:
+        return ControlResult(status="invalid", detail=mode)
+
+    try:
+        session_uuid = UUID(session_id)
+    except ValueError:
+        return ControlResult(status="not_found")
+    session = await db.get(ChatSession, session_uuid)
+    if session is None:
+        return ControlResult(status="not_found")
+
+    session.permission_mode = mode
+    session_mode = session.mode
+    session_workspace = session.workspace
+    db.add(session)
+    await db.commit()
+
+    from app.services import team_manager
+
+    team_obj = team_manager.current_team_for_session(session_id)
+    if team_obj is None and session_mode == "coding" and session_workspace:
+        team_obj = team_manager.current_coding_team_for_session(
+            session_workspace, session_id
+        )
+    if team_obj is not None:
+        team_obj.permission_mode = mode
+
+    from app.agent.permission import Mode, get_services_for_stream
+
+    for service in get_services_for_stream(session_id):
+        service.set_mode(cast(Mode, mode))
+
+    return ControlResult(status="ok")
+```
+
+- [ ] **Step 4: Run and confirm pass**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/test_control.py
+```
+
+Expected: PASS (4 tests).
+
+- [ ] **Step 5: Lint**
+
+```powershell
+uv run ruff check app/remote/control.py tests/remote/test_control.py
+uv run ty check app/remote/control.py
+```
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add app/remote/control.py tests/remote/test_control.py
+git commit -m "feat(remote): add permission-mode control, bypass excluded"
+```
+
+---
+
+### Task 2: `set_lead_agent` and `list_lead_names`
+
+**ACs:** AC-50
+
+**Files:**
+
+- Modify: `app/remote/control.py`
+- Modify: `tests/remote/test_control.py`
+
+**Interfaces:**
+
+- Produces: `async def set_lead_agent(db: AsyncSession, session_id: str, lead_name: str) -> ControlResult`, `async def list_lead_names(app_mode: str, *, limit: int = 5) -> list[str]`.
+- Consumes: `app.models.chat.normalize_mode`, `app.services.team_manager.resolve_configured_lead`/`configured_lead_rosters`/`find_team_for_session`/`stop_sessions`, `app.services.memory_stream_store.running_session_ids`.
+
+- [ ] **Step 1: Write the failing tests**
+
+This worktree's isolated test config dirs (`pytest.ini`'s `EVOFLUX_CONFIG_DIR`
+etc.) have no real agent configs seeded, so `configured_lead_rosters`
+returns empty there — verified by running the naive version of these tests
+first. Mock it with one controlled, fake roster instead of depending on
+whatever happens to exist on disk in this environment; patched at the
+module level so both `list_lead_names`'s direct call and
+`resolve_configured_lead`'s own internal call see the same fake roster.
+
+```python
+# tests/remote/test_control.py (add)
+class _FakeLead:
+    """Stand-in for the roster's real lead-agent config object — only
+    ``.name`` is read by list_lead_names/resolve_configured_lead."""
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+
+
+def _mock_one_lead_roster(monkeypatch: pytest.MonkeyPatch, name: str = "evoflux") -> None:
+    monkeypatch.setattr(
+        "app.services.team_manager.configured_lead_rosters",
+        lambda mode: (name, [(_FakeLead(name), None, [])]),
+    )
+
+
+@pytest.mark.asyncio
+async def test_list_lead_names_returns_configured_leads(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _mock_one_lead_roster(monkeypatch, "evoflux")
+
+    names = await control.list_lead_names("work")
+
+    assert names == ["evoflux"]
+
+
+@pytest.mark.asyncio
+async def test_list_lead_names_is_bounded_to_five(monkeypatch: pytest.MonkeyPatch) -> None:
+    fake_rosters = [(_FakeLead(f"lead-{i}"), None, []) for i in range(8)]
+    monkeypatch.setattr(
+        "app.services.team_manager.configured_lead_rosters",
+        lambda mode: ("lead-0", fake_rosters),
+    )
+
+    names = await control.list_lead_names("work")
+
+    assert len(names) == 5
+
+
+@pytest.mark.asyncio
+async def test_set_lead_agent_persists_a_valid_lead(
+    chat_session: ChatSession, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _mock_one_lead_roster(monkeypatch, "evoflux")
+
+    async with db_module.async_session_factory() as db:
+        result = await control.set_lead_agent(db, str(chat_session.id), "evoflux")
+
+    assert result.status == "ok"
+    async with db_module.async_session_factory() as db:
+        refreshed = await db.get(ChatSession, chat_session.id)
+        assert refreshed is not None
+        assert refreshed.agent_name == "evoflux"
+
+
+@pytest.mark.asyncio
+async def test_set_lead_agent_rejects_unknown_name(
+    chat_session: ChatSession, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _mock_one_lead_roster(monkeypatch, "evoflux")
+
+    async with db_module.async_session_factory() as db:
+        result = await control.set_lead_agent(
+            db, str(chat_session.id), "not-a-real-configured-lead-name"
+        )
+
+    assert result.status == "invalid"
+
+
+@pytest.mark.asyncio
+async def test_set_lead_agent_conflicts_while_session_is_running(
+    chat_session: ChatSession, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _mock_one_lead_roster(monkeypatch, "evoflux")
+    monkeypatch.setattr(
+        "app.services.memory_stream_store.running_session_ids",
+        lambda: {str(chat_session.id)},
+    )
+
+    async with db_module.async_session_factory() as db:
+        result = await control.set_lead_agent(db, str(chat_session.id), "evoflux")
+
+    assert result.status == "conflict"
+```
+
+- [ ] **Step 2: Run and confirm failure**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/test_control.py -k "lead"
+```
+
+Expected: FAIL with `AttributeError: module 'app.remote.control' has no attribute 'list_lead_names'`.
+
+- [ ] **Step 3: Implement the lead-switching slice**
+
+```python
+# app/remote/control.py — add to __all__: "set_lead_agent", "list_lead_names"
+```
+
+```python
+# app/remote/control.py — new functions
+async def list_lead_names(app_mode: str, *, limit: int = 5) -> list[str]:
+    """A short, stable-order list of configured lead-agent names for
+    *app_mode* ("work"/"coding") — bounded for a phone's button row, same
+    pattern already used for workflow/project menu items in actions.py."""
+    from app.services import team_manager
+
+    try:
+        _default_lead, rosters = team_manager.configured_lead_rosters(app_mode)
+    except ValueError:
+        return []
+    return [lead.name for lead, _path, _members in rosters][:limit]
+
+
+async def set_lead_agent(
+    db: AsyncSession, session_id: str, lead_name: str
+) -> ControlResult:
+    from app.models.chat import normalize_mode
+    from app.services import memory_stream_store as stream_store
+    from app.services import team_manager
+
+    try:
+        session_uuid = UUID(session_id)
+    except ValueError:
+        return ControlResult(status="not_found")
+    session = await db.get(ChatSession, session_uuid)
+    if session is None:
+        return ControlResult(status="not_found")
+    if session.parent_session_id is not None:
+        return ControlResult(status="not_found")
+
+    live_team = team_manager.find_team_for_session(session_id)
+    if session_id in stream_store.running_session_ids() or (
+        live_team is not None
+        and any(member.state == "working" for member in live_team.all_members)
+    ):
+        return ControlResult(
+            status="conflict",
+            detail="Finish or stop the active task before changing lead.",
+        )
+
+    app_mode = normalize_mode(session.mode)
+    try:
+        selected = team_manager.resolve_configured_lead(app_mode, lead_name)
+    except ValueError as exc:
+        return ControlResult(status="invalid", detail=str(exc))
+
+    if session.agent_name != selected:
+        session.agent_name = selected
+        db.add(session)
+        await db.commit()
+        await db.refresh(session)
+        await team_manager.stop_sessions({session_id})
+
+    return ControlResult(status="ok")
+```
+
+- [ ] **Step 4: Run and confirm pass**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/test_control.py
+```
+
+Expected: PASS (9 tests).
+
+- [ ] **Step 5: Lint**
+
+```powershell
+uv run ruff check app/remote/control.py tests/remote/test_control.py
+uv run ty check app/remote/control.py
+```
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add app/remote/control.py tests/remote/test_control.py
+git commit -m "feat(remote): add lead-agent control"
+```
+
+---
+
+### Task 3: `set_model` and `list_model_ids`
+
+**ACs:** AC-49
+
+**Files:**
+
+- Modify: `app/remote/control.py`
+- Modify: `tests/remote/test_control.py`
+
+**Interfaces:**
+
+- Produces: `async def set_model(db: AsyncSession, session_id: str, model_id: str, *, thinking_level: str | None = None) -> ControlResult`, `async def list_model_ids(app_mode: str | None = None, *, limit: int = 5) -> list[str]`.
+- Consumes: `app.api.routes.agents.get_registry` (the one documented exception to the service-layer-only rule — see module docstring), `app.agent.providers.thinking.accepts_thinking_level`.
+
+- [ ] **Step 1: Write the failing tests**
+
+```python
+# tests/remote/test_control.py (add)
+@pytest.mark.asyncio
+async def test_list_model_ids_is_bounded() -> None:
+    model_ids = await control.list_model_ids(limit=5)
+
+    assert isinstance(model_ids, list)
+    assert len(model_ids) <= 5
+
+
+@pytest.mark.asyncio
+async def test_set_model_persists_a_valid_model(chat_session: ChatSession) -> None:
+    model_ids = await control.list_model_ids(limit=5)
+    assert model_ids, "test fixture assumes at least one registered model"
+
+    async with db_module.async_session_factory() as db:
+        result = await control.set_model(db, str(chat_session.id), model_ids[0])
+
+    assert result.status == "ok"
+    async with db_module.async_session_factory() as db:
+        refreshed = await db.get(ChatSession, chat_session.id)
+        assert refreshed is not None
+        assert refreshed.model == model_ids[0]
+
+
+@pytest.mark.asyncio
+async def test_set_model_rejects_unknown_model_id(chat_session: ChatSession) -> None:
+    async with db_module.async_session_factory() as db:
+        result = await control.set_model(
+            db, str(chat_session.id), "not-a-real-provider:not-a-real-model"
+        )
+
+    assert result.status == "invalid"
+```
+
+- [ ] **Step 2: Run and confirm failure**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/test_control.py -k "model"
+```
+
+Expected: FAIL with `AttributeError: module 'app.remote.control' has no attribute 'list_model_ids'`.
+
+- [ ] **Step 3: Implement the model-switching slice**
+
+```python
+# app/remote/control.py — add to __all__: "set_model", "list_model_ids"
+```
+
+```python
+# app/remote/control.py — new functions
+async def list_model_ids(app_mode: str | None = None, *, limit: int = 5) -> list[str]:
+    """A short, catalog-order list of registered model ids — bounded for a
+    phone's button row. There is no curated "recommended models" concept
+    in the registry today (every provider-visible model is returned
+    unbounded), so this is a simple positional cap, not a ranking."""
+    from typing import Literal, cast
+
+    from app.api.routes.agents import get_registry
+
+    mode_arg = cast(Literal["work", "coding"] | None, app_mode)
+    registry = await get_registry(mode=mode_arg)
+    return [entry.id for entry in registry.models][:limit]
+
+
+async def set_model(
+    db: AsyncSession,
+    session_id: str,
+    model_id: str,
+    *,
+    thinking_level: str | None = None,
+) -> ControlResult:
+    from app.api.routes.agents import get_registry
+    from app.agent.providers.thinking import accepts_thinking_level
+
+    try:
+        session_uuid = UUID(session_id)
+    except ValueError:
+        return ControlResult(status="not_found")
+    session = await db.get(ChatSession, session_uuid)
+    if session is None:
+        return ControlResult(status="not_found")
+
+    registry = await get_registry()
+    selected = next((entry for entry in registry.models if entry.id == model_id), None)
+    if selected is None:
+        return ControlResult(status="invalid", detail=model_id)
+    if thinking_level is not None and not accepts_thinking_level(
+        model_id, thinking_level
+    ):
+        return ControlResult(status="invalid", detail=thinking_level)
+
+    session.model = model_id
+    session.thinking_level = thinking_level
+    db.add(session)
+    await db.commit()
+
+    return ControlResult(status="ok")
+```
+
+- [ ] **Step 4: Run and confirm pass**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/test_control.py
+```
+
+Expected: PASS (11 tests).
+
+- [ ] **Step 5: Lint**
+
+```powershell
+uv run ruff check app/remote/control.py tests/remote/test_control.py
+uv run ty check app/remote/control.py
+```
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add app/remote/control.py tests/remote/test_control.py
+git commit -m "feat(remote): add model control via the registry"
+```
+
+---
+
+### Task 4: Settings-card rendering
+
+**ACs:** AC-48/49/50 (display half)
+
+**Files:**
+
+- Modify: `app/remote/formatting.py`
+- Modify: `tests/remote/test_formatting.py`
+
+**Interfaces:**
+
+- Changes `render_settings_card`: adds `mode_tokens: Mapping[str, str]`, `agent_name: str`, `agent_tokens: Mapping[str, str]`, `model_tokens: Mapping[str, str]` (all required — every caller updates); `redaction_policy`, `notify_scope`, `redaction_tokens`, `notify_scope_tokens` become optional (`None`/empty default) since no caller supplies them yet.
+
+- [ ] **Step 1: Write the failing tests**
+
+```python
+# tests/remote/test_formatting.py (add)
+def test_render_settings_card_shows_mode_model_and_agent_buttons():
+    text, buttons = formatting.render_settings_card(
+        connection_label="evoflux-api",
+        model="anthropic:claude-sonnet-5",
+        permission_mode="ask",
+        agent_name="evoflux",
+        mode_tokens={"ask": "m1", "auto": "m2"},
+        agent_tokens={"evoflux": "a1", "explorer": "a2"},
+        model_tokens={"anthropic:claude-sonnet-5": "d1"},
+    )
+    assert "ask" in text
+    assert "anthropic:claude-sonnet-5" in text
+    assert "evoflux" in text
+    button_tokens = {b.token for b in buttons}
+    assert {"m1", "m2", "a1", "a2", "d1"} <= button_tokens
+
+
+def test_render_settings_card_never_offers_a_bypass_button():
+    _, buttons = formatting.render_settings_card(
+        connection_label="evoflux-api",
+        model="anthropic:claude-sonnet-5",
+        permission_mode="auto",
+        agent_name="evoflux",
+        mode_tokens={"auto": "m1", "bypass": "should-never-appear"},
+        agent_tokens={},
+        model_tokens={},
+    )
+    assert "should-never-appear" not in {b.token for b in buttons}
+    assert not any("bypass" in b.text.lower() for b in buttons)
+
+
+def test_render_settings_card_omits_redaction_section_when_not_supplied():
+    text, _ = formatting.render_settings_card(
+        connection_label="evoflux-api",
+        model="anthropic:claude-sonnet-5",
+        permission_mode="auto",
+        agent_name="evoflux",
+        mode_tokens={},
+        agent_tokens={},
+        model_tokens={},
+    )
+    assert "Outbound redaction" not in text
+    assert "Notifications" not in text
+```
+
+- [ ] **Step 2: Run and confirm failure**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/test_formatting.py -k settings_card
+```
+
+Expected: FAIL — `render_settings_card()` missing required arguments `agent_name`, `mode_tokens`, `agent_tokens`, `model_tokens`.
+
+- [ ] **Step 3: Rewrite `render_settings_card`**
+
+```python
+# app/remote/formatting.py — replace render_settings_card in full
+def render_settings_card(
+    *,
+    connection_label: str,
+    model: str,
+    permission_mode: str,
+    agent_name: str,
+    mode_tokens: Mapping[str, str],
+    agent_tokens: Mapping[str, str],
+    model_tokens: Mapping[str, str],
+    redaction_policy: str | None = None,
+    notify_scope: str | None = None,
+    redaction_tokens: Mapping[str, str] = {},
+    notify_scope_tokens: Mapping[str, str] = {},
+) -> tuple[str, tuple[RemoteButton, ...]]:
+    lines = [
+        "⚙️ Settings",
+        "",
+        f"Connection\n{escape(connection_label)}",
+        "",
+        f"Mode\n{escape(permission_mode)}",
+        "",
+        f"Model\n{escape(model)}",
+        "",
+        f"Lead agent\n{escape(agent_name)}",
+    ]
+    if notify_scope is not None:
+        lines += ["", f"Notifications\n{escape(notify_scope)}"]
+    if redaction_policy is not None:
+        lines += [
+            "",
+            f"Outbound redaction\n{escape(redaction_policy)}",
+        ]
+    text = "\n".join(lines)
+
+    buttons: list[RemoteButton] = [
+        RemoteButton(text=f"Mode: {escape(name)}", token=token)
+        for name, token in mode_tokens.items()
+        if name != "bypass"
+    ]
+    buttons += [
+        RemoteButton(text=f"Agent: {escape(name)}", token=token)
+        for name, token in agent_tokens.items()
+    ]
+    buttons += [
+        RemoteButton(text=f"Model: {escape(name)}", token=token)
+        for name, token in model_tokens.items()
+    ]
+    buttons += [
+        RemoteButton(text=f"Redaction: {escape(name)}", token=token)
+        for name, token in redaction_tokens.items()
+    ]
+    buttons += [
+        RemoteButton(text=f"Notify: {escape(name)}", token=token)
+        for name, token in notify_scope_tokens.items()
+    ]
+    return text, tuple(buttons)
+```
+
+Note the `if name != "bypass"` filter on the mode-button comprehension: defense in depth alongside `control.ALLOWED_REMOTE_MODES` already excluding it at the source (AC-48's boundary is enforced at both the write path and the render path, so a bug in one is never the only thing standing between a phone and bypass).
+
+- [ ] **Step 4: Run and confirm pass**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/test_formatting.py
+```
+
+Expected: PASS (all tests in the file).
+
+- [ ] **Step 5: Lint**
+
+```powershell
+uv run ruff check app/remote/formatting.py tests/remote/test_formatting.py
+uv run ty check app/remote/formatting.py
+```
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add app/remote/formatting.py tests/remote/test_formatting.py
+git commit -m "feat(remote): settings card renders mode/model/agent as buttons, bypass excluded"
+```
+
+---
+
+### Task 5: Wire `/settings` into `actions.py`
+
+**ACs:** AC-48, AC-49, AC-50, AC-58 (partial — adds `settings` to the command set)
+
+**Files:**
+
+- Modify: `app/remote/actions.py`
+- Modify: `tests/remote/test_actions.py`
+
+**Interfaces:**
+
+- Changes `_SLASH_COMMANDS`: adds `"settings"`.
+- Produces (private): `_cmd_settings`, `_exec_set_mode`, `_exec_set_agent`, `_exec_set_model`.
+- Consumes: `app.remote.control` (all six public names), `app.remote.formatting.render_settings_card`, `app.models.chat.ChatSession`/`normalize_mode`.
+
+- [ ] **Step 1: Write the failing tests**
+
+This file's established pattern (see `TestStatus`) mocks
+`service._pairing_service.authorize` directly rather than persisting a
+real `RemotePairing` row — `mock_db = MagicMock()` is enough when the
+command never actually touches the DB. `/settings` *does* need a real
+`db.get(ChatSession, ...)` round-trip once `active_session_id` is set, so
+these three tests use a real DB session (`app.core.db.async_session_factory`,
+already used the same way in `tests/remote/test_control.py`) instead of
+`MagicMock()`, while still mocking `authorize` for pairing/authorization
+exactly like every other command test in this file.
+
+```python
+# tests/remote/test_actions.py — add near the top, alongside the existing imports
+import app.core.db as db_module
+from app.models.chat import ChatSession
+```
+
+```python
+# tests/remote/test_actions.py (add)
+class TestSettings:
+    @pytest.mark.asyncio
+    async def test_settings_command_shows_current_mode_model_and_agent(
+        self, service: RemoteActionService
+    ) -> None:
+        async with db_module.async_session_factory() as db:
+            session = ChatSession(
+                title="Settings test",
+                mode="work",
+                session_type="main",
+                permission_mode="ask",
+                model="anthropic:claude-sonnet-5",
+                agent_name="evoflux",
+            )
+            db.add(session)
+            await db.commit()
+            await db.refresh(session)
+
+            mock_pairing = MagicMock()
+            mock_pairing.active_session_id = session.id
+            mock_pairing.label = "My Phone"
+
+            with patch.object(
+                service._pairing_service, "authorize", return_value=mock_pairing
+            ):
+                action = _make_action(text="/settings")
+                result = await service.dispatch_command(db, action)
+
+        assert result.status == "ok"
+        assert "ask" in result.text
+        assert "anthropic:claude-sonnet-5" in result.text
+        assert "evoflux" in result.text
+
+    @pytest.mark.asyncio
+    async def test_settings_command_without_active_session_is_friendly(
+        self, service: RemoteActionService
+    ) -> None:
+        mock_db = MagicMock()
+        mock_pairing = MagicMock()
+        mock_pairing.active_session_id = None
+
+        with patch.object(
+            service._pairing_service, "authorize", return_value=mock_pairing
+        ):
+            action = _make_action(text="/settings")
+            result = await service.dispatch_command(mock_db, action)
+
+        assert result.status == "ok"
+        assert "start" in result.text.lower()
+
+    @pytest.mark.asyncio
+    async def test_mode_callback_applies_the_selected_mode(
+        self, service: RemoteActionService, adapter: FakeAdapter
+    ) -> None:
+        conn_id = uuid4()
+        async with db_module.async_session_factory() as db:
+            session = ChatSession(
+                title="Settings test",
+                mode="work",
+                session_type="main",
+                permission_mode="auto",
+            )
+            db.add(session)
+            await db.commit()
+            await db.refresh(session)
+
+            mock_pairing = MagicMock()
+            mock_pairing.active_session_id = session.id
+            mock_pairing.label = "My Phone"
+
+            with patch.object(
+                service._pairing_service, "authorize", return_value=mock_pairing
+            ):
+                settings_action = _make_action(text="/settings", connection_id=conn_id)
+                await service.dispatch_command(db, settings_action)
+
+            sent_buttons = adapter.sent_messages[-1].buttons
+            ask_token = next(b.token for b in sent_buttons if b.text == "Mode: ask")
+
+            callback_action = _make_action(
+                kind=RemoteInboundActionKind.CALLBACK,
+                callback_token=ask_token,
+                connection_id=conn_id,
+            )
+            handled = await service.handle_action_callback(callback_action, db)
+
+            assert handled is True
+            refreshed = await db.get(ChatSession, session.id)
+            assert refreshed is not None
+            assert refreshed.permission_mode == "ask"
+```
+
+- [ ] **Step 2: Run and confirm failure**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/test_actions.py -k Settings
+```
+
+Expected: FAIL — `/settings` falls through to `_cmd_help` (unknown command), so none of the mode/model/agent assertions match.
+
+- [ ] **Step 3: Add `/settings` to the known commands and dispatch**
+
+```python
+# app/remote/actions.py — _SLASH_COMMANDS
+_SLASH_COMMANDS: frozenset[str] = frozenset(
+    {"start", "help", "status", "new", "stop", "unpair", "actions", "settings"}
+)
+```
+
+```python
+# app/remote/actions.py — inside dispatch_command, alongside the other elif branches
+        elif command == "settings":
+            return await self._cmd_settings(db, action)
+```
+
+- [ ] **Step 4: Implement `_cmd_settings`**
+
+```python
+# app/remote/actions.py — new method, near _cmd_status
+    async def _cmd_settings(
+        self, db: AsyncSession, action: RemoteInboundAction
+    ) -> RemoteActionResult:
+        from app.models.chat import ChatSession, normalize_mode
+        from app.remote import control
+        from app.remote.formatting import render_settings_card
+
+        pairing = await self._pairing_service.authorize(
+            db,
+            connection_id=action.connection_id,
+            principal_id=action.principal.principal_id,
+        )
+        if pairing is None:
+            return RemoteActionResult(status="unauthorized")
+
+        if pairing.active_session_id is None:
+            return RemoteActionResult(
+                status="ok",
+                text="No active task yet — send a message to start one, then /settings shows its mode/model/agent.",
+            )
+
+        session = await db.get(ChatSession, pairing.active_session_id)
+        if session is None:
+            return RemoteActionResult(
+                status="ok",
+                text="No active task yet — send a message to start one, then /settings shows its mode/model/agent.",
+            )
+
+        app_mode = normalize_mode(session.mode)
+        session_id = str(session.id)
+
+        mode_tokens = {
+            mode: self._issue_settings_token(action, session_id, "set_mode", mode)
+            for mode in control.ALLOWED_REMOTE_MODES
+        }
+        agent_names = await control.list_lead_names(app_mode)
+        agent_tokens = {
+            name: self._issue_settings_token(action, session_id, "set_agent", name)
+            for name in agent_names
+        }
+        model_ids = await control.list_model_ids(app_mode)
+        model_tokens = {
+            model_id: self._issue_settings_token(action, session_id, "set_model", model_id)
+            for model_id in model_ids
+        }
+
+        text, buttons = render_settings_card(
+            connection_label=pairing.label or "This phone",
+            model=session.model or "(default)",
+            permission_mode=session.permission_mode,
+            agent_name=session.agent_name or "(default)",
+            mode_tokens=mode_tokens,
+            agent_tokens=agent_tokens,
+            model_tokens=model_tokens,
+        )
+
+        if self._adapter is not None:
+            await self._send(action.principal.destination_id, text, buttons=buttons)
+        return RemoteActionResult(status="ok", text=text)
+
+    def _issue_settings_token(
+        self,
+        action: RemoteInboundAction,
+        session_id: str,
+        action_kind: str,
+        action_target: str,
+    ) -> str:
+        return self._issue_token(
+            connection_id=action.connection_id,
+            principal_id=action.principal.principal_id,
+            destination_id=action.principal.destination_id,
+            session_id=session_id,
+            action_kind=action_kind,
+            action_target=action_target,
+        )
+```
+
+`/settings` already sends its own message with buttons (like `/actions` does) — add it to the existing "already sent its own message" guard in `runtime.py`'s `_handle_command` alongside `actions`, so the plain-text result isn't sent a second time:
+
+```python
+# app/remote/runtime.py — inside _handle_command
+        command = (action.text or "").strip().split(maxsplit=1)[0][1:].lower()
+        if command in ("actions", "settings"):
+            return
+```
+
+- [ ] **Step 5: Run and confirm the settings-display tests pass**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/test_actions.py -k "settings_command"
+```
+
+Expected: PASS.
+
+- [ ] **Step 6: Write failing tests for the three new capability action kinds, then implement `_execute_action`'s new branches**
+
+```python
+# app/remote/actions.py — inside _execute_action
+        elif cap.action_kind == "set_mode":
+            return await self._exec_set_mode(cap, action)
+        elif cap.action_kind == "set_agent":
+            return await self._exec_set_agent(cap, action)
+        elif cap.action_kind == "set_model":
+            return await self._exec_set_model(cap, action)
+```
+
+```python
+# app/remote/actions.py — new methods, near _exec_workflow_start
+    async def _exec_set_mode(
+        self, cap: _ActionCapability, action: RemoteInboundAction
+    ) -> bool:
+        from app.core.db import async_session_factory
+        from app.remote import control
+
+        async with async_session_factory() as db:
+            result = await control.set_permission_mode(
+                db, cap.session_id, cap.action_target
+            )
+        await self._reply_control_result(action, result, f"Mode set to {cap.action_target}.")
+        return True
+
+    async def _exec_set_agent(
+        self, cap: _ActionCapability, action: RemoteInboundAction
+    ) -> bool:
+        from app.core.db import async_session_factory
+        from app.remote import control
+
+        async with async_session_factory() as db:
+            result = await control.set_lead_agent(db, cap.session_id, cap.action_target)
+        await self._reply_control_result(
+            action, result, f"Lead agent set to {cap.action_target}."
+        )
+        return True
+
+    async def _exec_set_model(
+        self, cap: _ActionCapability, action: RemoteInboundAction
+    ) -> bool:
+        from app.core.db import async_session_factory
+        from app.remote import control
+
+        async with async_session_factory() as db:
+            result = await control.set_model(db, cap.session_id, cap.action_target)
+        await self._reply_control_result(action, result, f"Model set to {cap.action_target}.")
+        return True
+
+    async def _reply_control_result(
+        self, action: RemoteInboundAction, result, success_text: str
+    ) -> None:
+        if result.status == "ok":
+            text = success_text
+        elif result.status == "conflict":
+            text = result.detail or "That can't be changed right now."
+        elif result.status == "not_found":
+            text = "That task no longer exists."
+        else:
+            text = f"That value isn't valid: {result.detail}" if result.detail else "That value isn't valid."
+        await self._reply_text(action.principal.destination_id, text)
+```
+
+- [ ] **Step 7: Run and confirm pass**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/test_actions.py
+```
+
+Expected: PASS (every test in the file, including the new mode-callback one).
+
+- [ ] **Step 8: Full remote suite, lint, type-check**
+
+```powershell
+uv run pytest --no-cov -q tests/remote/
+uv run ruff check app/remote/actions.py app/remote/runtime.py tests/remote/test_actions.py
+uv run ty check app/remote/
+```
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add app/remote/actions.py app/remote/runtime.py tests/remote/test_actions.py
+git commit -m "feat(remote): wire /settings command with mode/model/agent switching"
+```
+
+---
+
+## Self-review notes
+
+- **Spec coverage:** AC-48 (Tasks 1, 4 filter, 5's `ALLOWED_REMOTE_MODES` usage), AC-49 (Task 3, 5), AC-50 (Task 2, 5) are each covered. AC-51–58 are explicitly out of scope, next phases.
+- **The bypass boundary is enforced twice, independently:** `control.ALLOWED_REMOTE_MODES` (write path, Task 1) and `render_settings_card`'s `if name != "bypass"` filter (render path, Task 4) — a bug in either alone still can't produce a working bypass button, matching the spec's "excluded in the remote layer itself" requirement.
+- **Type/name consistency:** `ControlResult.status` values (`ok`/`invalid`/`not_found`/`conflict`) are used identically in `_reply_control_result` (Task 5) and match every test assertion in Tasks 1-3. `render_settings_card`'s parameter names (Task 4) match every call site in `_cmd_settings` (Task 5) exactly.
+- **Task 5's tests were verified against the real file, not guessed:** `tests/remote/test_actions.py`'s actual fixtures (`service`, `adapter`, `_make_action`) and established pattern (mock `service._pairing_service.authorize`, matching `TestStatus`'s existing tests) were read directly and matched exactly — `FakeAdapter.sent_messages` (not a guessed `.sent`) is this file's real attribute name for delivered `RemoteOutboundMessage`s, confirmed at `test_actions.py:34`.
diff --git a/tests/remote/test_control.py b/tests/remote/test_control.py
index 00df3c17..db8378a5 100644
--- a/tests/remote/test_control.py
+++ b/tests/remote/test_control.py
@@ -58,3 +58,94 @@ async def test_set_permission_mode_not_found_for_unknown_session() -> None:
         result = await control.set_permission_mode(db, str(UUID(int=0)), "ask")
 
     assert result.status == "not_found"
+
+
+class _FakeLead:
+    """Stand-in for the roster's real lead-agent config object — only
+    ``.name`` is read by list_lead_names/resolve_configured_lead."""
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+
+
+def _mock_one_lead_roster(monkeypatch: pytest.MonkeyPatch, name: str = "evoflux") -> None:
+    """The test sandbox's isolated config dirs (pytest.ini's EVOFLUX_CONFIG_DIR
+    etc.) have no real agent configs seeded, so configured_lead_rosters
+    returns empty there — mock it with one controlled, fake roster instead
+    of depending on whatever happens to exist on disk in this environment.
+    Patched at the module level so both list_lead_names' direct call and
+    resolve_configured_lead's own internal call see the same fake roster."""
+    monkeypatch.setattr(
+        "app.services.team_manager.configured_lead_rosters",
+        lambda mode: (name, [(_FakeLead(name), None, [])]),
+    )
+
+
+@pytest.mark.asyncio
+async def test_list_lead_names_returns_configured_leads(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _mock_one_lead_roster(monkeypatch, "evoflux")
+
+    names = await control.list_lead_names("work")
+
+    assert names == ["evoflux"]
+
+
+@pytest.mark.asyncio
+async def test_list_lead_names_is_bounded_to_five(monkeypatch: pytest.MonkeyPatch) -> None:
+    fake_rosters = [(_FakeLead(f"lead-{i}"), None, []) for i in range(8)]
+    monkeypatch.setattr(
+        "app.services.team_manager.configured_lead_rosters",
+        lambda mode: ("lead-0", fake_rosters),
+    )
+
+    names = await control.list_lead_names("work")
+
+    assert len(names) == 5
+
+
+@pytest.mark.asyncio
+async def test_set_lead_agent_persists_a_valid_lead(
+    chat_session: ChatSession, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _mock_one_lead_roster(monkeypatch, "evoflux")
+
+    async with db_module.async_session_factory() as db:
+        result = await control.set_lead_agent(db, str(chat_session.id), "evoflux")
+
+    assert result.status == "ok"
+    async with db_module.async_session_factory() as db:
+        refreshed = await db.get(ChatSession, chat_session.id)
+        assert refreshed is not None
+        assert refreshed.agent_name == "evoflux"
+
+
+@pytest.mark.asyncio
+async def test_set_lead_agent_rejects_unknown_name(
+    chat_session: ChatSession, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _mock_one_lead_roster(monkeypatch, "evoflux")
+
+    async with db_module.async_session_factory() as db:
+        result = await control.set_lead_agent(
+            db, str(chat_session.id), "not-a-real-configured-lead-name"
+        )
+
+    assert result.status == "invalid"
+
+
+@pytest.mark.asyncio
+async def test_set_lead_agent_conflicts_while_session_is_running(
+    chat_session: ChatSession, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _mock_one_lead_roster(monkeypatch, "evoflux")
+    monkeypatch.setattr(
+        "app.services.memory_stream_store.running_session_ids",
+        lambda: {str(chat_session.id)},
+    )
+
+    async with db_module.async_session_factory() as db:
+        result = await control.set_lead_agent(db, str(chat_session.id), "evoflux")
+
+    assert result.status == "conflict"

From 010b36b9bd93ad0f0e5cf152243dd752036f13e5 Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Tue, 15 Sep 2026 10:19:23 +0700
Subject: [PATCH 36/71] feat(remote): add model control via the registry
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 2 (Task 3) of documents/plans/remote-telegram-control-implementation.md.

Mocks get_registry in tests rather than depending on this environment's
ambiently-configured "xiaomi" provider — real, but not guaranteed on
every machine this suite runs on.
---
 app/remote/control.py                         | 57 +++++++++++++++++
 .../remote-telegram-control-implementation.md | 61 ++++++++++++++----
 tests/remote/test_control.py                  | 64 +++++++++++++++++++
 3 files changed, 168 insertions(+), 14 deletions(-)

diff --git a/app/remote/control.py b/app/remote/control.py
index 06abb41b..06fbd3d7 100644
--- a/app/remote/control.py
+++ b/app/remote/control.py
@@ -31,6 +31,8 @@
     "set_permission_mode",
     "set_lead_agent",
     "list_lead_names",
+    "set_model",
+    "list_model_ids",
 ]
 
 #: Every permission mode this phone may set — bypass excluded on purpose.
@@ -139,3 +141,58 @@ async def set_lead_agent(
         await team_manager.stop_sessions({session_id})
 
     return ControlResult(status="ok")
+
+
+async def list_model_ids(app_mode: str | None = None, *, limit: int = 5) -> list[str]:
+    """A short, catalog-order list of registered model ids — bounded for a
+    phone's button row. There is no curated "recommended models" concept
+    in the registry today (every provider-visible model is returned
+    unbounded), so this is a simple positional cap, not a ranking.
+
+    One deliberate departure from this module's own "service layer only"
+    rule: get_registry lives in app.api.routes.agents (a route module),
+    not a service — there is no equivalent service-layer function to call
+    instead. It is a plain async function with no Request/Depends-injected
+    state (its Query(...) annotations are OpenAPI metadata on otherwise
+    plain defaults), so calling it directly here is safe.
+    """
+    from app.api.routes.agents import get_registry
+
+    mode_arg = cast("Literal['work', 'coding'] | None", app_mode)
+    registry = await get_registry(mode=mode_arg)
+    return [entry.id for entry in registry.models][:limit]
+
+
+async def set_model(
+    db: AsyncSession,
+    session_id: str,
+    model_id: str,
+    *,
+    thinking_level: str | None = None,
+) -> ControlResult:
+    from app.agent.providers.thinking import accepts_thinking_level
+    from app.api.routes.agents import get_registry
+
+    try:
+        session_uuid = UUID(session_id)
+    except ValueError:
+        return ControlResult(status="not_found")
+    session = await db.get(ChatSession, session_uuid)
+    if session is None:
+        return ControlResult(status="not_found")
+
+    registry = await get_registry()
+    selected = next((entry for entry in registry.models if entry.id == model_id), None)
+    if selected is None:
+        return ControlResult(status="invalid", detail=model_id)
+    if thinking_level is not None and not accepts_thinking_level(
+        model_id, thinking_level
+    ):
+        return ControlResult(status="invalid", detail=thinking_level)
+
+    session.model = model_id
+    session.thinking_level = thinking_level
+    db.add(session)
+    await db.commit()
+
+    return ControlResult(status="ok")
diff --git a/documents/plans/remote-telegram-control-implementation.md b/documents/plans/remote-telegram-control-implementation.md
index 5cdc0046..60fc3aee 100644
--- a/documents/plans/remote-telegram-control-implementation.md
+++ b/documents/plans/remote-telegram-control-implementation.md
@@ -460,33 +460,64 @@ git commit -m "feat(remote): add lead-agent control"
 
 - [ ] **Step 1: Write the failing tests**
 
+Same lesson as Task 2's lead-agent tests: this environment happens to have
+real models available via an ambiently-configured provider, but that isn't
+guaranteed on every machine this suite runs on, so mock `get_registry`
+with a small, controlled fake instead of depending on it.
+
 ```python
 # tests/remote/test_control.py (add)
+class _FakeModelEntry:
+    """Stand-in for the real registry's ModelCatalogEntry — only ``.id``
+    is read by list_model_ids/set_model."""
+
+    def __init__(self, id: str) -> None:
+        self.id = id
+
+
+class _FakeRegistry:
+    def __init__(self, model_ids: list[str]) -> None:
+        self.models = [_FakeModelEntry(mid) for mid in model_ids]
+
+
+def _mock_registry(monkeypatch: pytest.MonkeyPatch, model_ids: list[str]) -> None:
+    async def _fake_get_registry(*args: object, **kwargs: object) -> _FakeRegistry:
+        return _FakeRegistry(model_ids)
+
+    monkeypatch.setattr("app.api.routes.agents.get_registry", _fake_get_registry)
+
+
 @pytest.mark.asyncio
-async def test_list_model_ids_is_bounded() -> None:
+async def test_list_model_ids_is_bounded(monkeypatch: pytest.MonkeyPatch) -> None:
+    _mock_registry(monkeypatch, [f"provider:model-{i}" for i in range(8)])
+
     model_ids = await control.list_model_ids(limit=5)
 
-    assert isinstance(model_ids, list)
-    assert len(model_ids) <= 5
+    assert len(model_ids) == 5
 
 
 @pytest.mark.asyncio
-async def test_set_model_persists_a_valid_model(chat_session: ChatSession) -> None:
-    model_ids = await control.list_model_ids(limit=5)
-    assert model_ids, "test fixture assumes at least one registered model"
+async def test_set_model_persists_a_valid_model(
+    chat_session: ChatSession, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _mock_registry(monkeypatch, ["provider:model-a", "provider:model-b"])
 
     async with db_module.async_session_factory() as db:
-        result = await control.set_model(db, str(chat_session.id), model_ids[0])
+        result = await control.set_model(db, str(chat_session.id), "provider:model-a")
 
     assert result.status == "ok"
     async with db_module.async_session_factory() as db:
         refreshed = await db.get(ChatSession, chat_session.id)
         assert refreshed is not None
-        assert refreshed.model == model_ids[0]
+        assert refreshed.model == "provider:model-a"
 
 
 @pytest.mark.asyncio
-async def test_set_model_rejects_unknown_model_id(chat_session: ChatSession) -> None:
+async def test_set_model_rejects_unknown_model_id(
+    chat_session: ChatSession, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _mock_registry(monkeypatch, ["provider:model-a"])
+
     async with db_module.async_session_factory() as db:
         result = await control.set_model(
             db, str(chat_session.id), "not-a-real-provider:not-a-real-model"
@@ -515,12 +546,14 @@ async def list_model_ids(app_mode: str | None = None, *, limit: int = 5) -> list
     """A short, catalog-order list of registered model ids — bounded for a
     phone's button row. There is no curated "recommended models" concept
     in the registry today (every provider-visible model is returned
-    unbounded), so this is a simple positional cap, not a ranking."""
-    from typing import Literal, cast
-
+    unbounded), so this is a simple positional cap, not a ranking.
+    Uses the module-level `cast` (imported at the top of the file, next
+    to Literal used for ControlStatus) — a local `from typing import
+    Literal, cast` here is flagged unused by ruff, since the Literal
+    reference below is inside a string forward-ref, not a live name."""
     from app.api.routes.agents import get_registry
 
-    mode_arg = cast(Literal["work", "coding"] | None, app_mode)
+    mode_arg = cast("Literal['work', 'coding'] | None", app_mode)
     registry = await get_registry(mode=mode_arg)
     return [entry.id for entry in registry.models][:limit]
 
@@ -566,7 +599,7 @@ async def set_model(
 uv run pytest --no-cov -q tests/remote/test_control.py
 ```
 
-Expected: PASS (11 tests).
+Expected: PASS (12 tests).
 
 - [ ] **Step 5: Lint**
 
diff --git a/tests/remote/test_control.py b/tests/remote/test_control.py
index db8378a5..6a3df4d5 100644
--- a/tests/remote/test_control.py
+++ b/tests/remote/test_control.py
@@ -149,3 +149,67 @@ async def test_set_lead_agent_conflicts_while_session_is_running(
         result = await control.set_lead_agent(db, str(chat_session.id), "evoflux")
 
     assert result.status == "conflict"
+
+
+class _FakeModelEntry:
+    """Stand-in for the real registry's ModelCatalogEntry — only ``.id``
+    is read by list_model_ids/set_model."""
+
+    def __init__(self, id: str) -> None:
+        self.id = id
+
+
+class _FakeRegistry:
+    def __init__(self, model_ids: list[str]) -> None:
+        self.models = [_FakeModelEntry(mid) for mid in model_ids]
+
+
+def _mock_registry(monkeypatch: pytest.MonkeyPatch, model_ids: list[str]) -> None:
+    """Mocked rather than using this environment's real, ambiently-configured
+    provider registry (present here via a "xiaomi" provider, but not
+    guaranteed on every machine this suite runs on) — same lesson as
+    _mock_one_lead_roster above."""
+
+    async def _fake_get_registry(*args: object, **kwargs: object) -> _FakeRegistry:
+        return _FakeRegistry(model_ids)
+
+    monkeypatch.setattr("app.api.routes.agents.get_registry", _fake_get_registry)
+
+
+@pytest.mark.asyncio
+async def test_list_model_ids_is_bounded(monkeypatch: pytest.MonkeyPatch) -> None:
+    _mock_registry(monkeypatch, [f"provider:model-{i}" for i in range(8)])
+
+    model_ids = await control.list_model_ids(limit=5)
+
+    assert len(model_ids) == 5
+
+
+@pytest.mark.asyncio
+async def test_set_model_persists_a_valid_model(
+    chat_session: ChatSession, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _mock_registry(monkeypatch, ["provider:model-a", "provider:model-b"])
+
+    async with db_module.async_session_factory() as db:
+        result = await control.set_model(db, str(chat_session.id), "provider:model-a")
+
+    assert result.status == "ok"
+    async with db_module.async_session_factory() as db:
+        refreshed = await db.get(ChatSession, chat_session.id)
+        assert refreshed is not None
+        assert refreshed.model == "provider:model-a"
+
+
+@pytest.mark.asyncio
+async def test_set_model_rejects_unknown_model_id(
+    chat_session: ChatSession, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    _mock_registry(monkeypatch, ["provider:model-a"])
+
+    async with db_module.async_session_factory() as db:
+        result = await control.set_model(
+            db, str(chat_session.id), "not-a-real-provider:not-a-real-model"
+        )
+
+    assert result.status == "invalid"

From 7dbdaf3a732d104089d91ed30ba83c533eacb0ad Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Tue, 15 Sep 2026 10:21:20 +0700
Subject: [PATCH 37/71] feat(remote): settings card renders mode/model/agent as
 buttons, bypass excluded
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 2 (Task 4) of documents/plans/remote-telegram-control-implementation.md.

Also updates two pre-existing tests that called render_settings_card
with its old signature — one of them, never_emits_model_or_permission_
buttons, explicitly asserted the AC-41 boundary this phase's AC-48/49
deliberately supersede, so it's renamed and inverted rather than just
patched to match the new required parameters.
---
 app/remote/formatting.py                      | 58 ++++++++++++----
 .../remote-telegram-control-implementation.md | 44 +++++++++++++
 tests/remote/test_formatting.py               | 66 +++++++++++++++++--
 3 files changed, 150 insertions(+), 18 deletions(-)

diff --git a/app/remote/formatting.py b/app/remote/formatting.py
index cb5a7a2c..c2f4d0c7 100644
--- a/app/remote/formatting.py
+++ b/app/remote/formatting.py
@@ -143,20 +143,52 @@ def render_settings_card(
     connection_label: str,
     model: str,
     permission_mode: str,
-    redaction_policy: str,
-    notify_scope: str,
-    redaction_tokens: Mapping[str, str],
-    notify_scope_tokens: Mapping[str, str],
+    agent_name: str,
+    mode_tokens: Mapping[str, str],
+    agent_tokens: Mapping[str, str],
+    model_tokens: Mapping[str, str],
+    redaction_policy: str | None = None,
+    notify_scope: str | None = None,
+    redaction_tokens: Mapping[str, str] = {},
+    notify_scope_tokens: Mapping[str, str] = {},
 ) -> tuple[str, tuple[RemoteButton, ...]]:
-    text = (
-        "⚙️ Settings\n\n"
-        f"Connection\n{escape(connection_label)}\n\n"
-        f"Model\n{escape(model)} (desktop only)\n\n"
-        f"Permission mode\n{escape(permission_mode)} (desktop only)\n\n"
-        f"Notifications\n{escape(notify_scope)}\n\n"
-        f"Outbound redaction\n{escape(redaction_policy)}"
-    )
-    buttons = [
+    lines = [
+        "⚙️ Settings",
+        "",
+        f"Connection\n{escape(connection_label)}",
+        "",
+        f"Mode\n{escape(permission_mode)}",
+        "",
+        f"Model\n{escape(model)}",
+        "",
+        f"Lead agent\n{escape(agent_name)}",
+    ]
+    if notify_scope is not None:
+        lines += ["", f"Notifications\n{escape(notify_scope)}"]
+    if redaction_policy is not None:
+        lines += [
+            "",
+            f"Outbound redaction\n{escape(redaction_policy)}",
+        ]
+    text = "\n".join(lines)
+
+    # bypass is excluded here too (not just at the control.py write path,
+    # see ALLOWED_REMOTE_MODES) — a bug in one boundary alone must never be
+    # the only thing standing between a phone and bypass mode (AC-48).
+    buttons: list[RemoteButton] = [
+        RemoteButton(text=f"Mode: {escape(name)}", token=token)
+        for name, token in mode_tokens.items()
+        if name != "bypass"
+    ]
+    buttons += [
+        RemoteButton(text=f"Agent: {escape(name)}", token=token)
+        for name, token in agent_tokens.items()
+    ]
+    buttons += [
+        RemoteButton(text=f"Model: {escape(name)}", token=token)
+        for name, token in model_tokens.items()
+    ]
+    buttons += [
         RemoteButton(text=f"Redaction: {escape(name)}", token=token)
         for name, token in redaction_tokens.items()
     ]
diff --git a/documents/plans/remote-telegram-control-implementation.md b/documents/plans/remote-telegram-control-implementation.md
index 60fc3aee..817f245b 100644
--- a/documents/plans/remote-telegram-control-implementation.md
+++ b/documents/plans/remote-telegram-control-implementation.md
@@ -751,6 +751,50 @@ def render_settings_card(
 
 Note the `if name != "bypass"` filter on the mode-button comprehension: defense in depth alongside `control.ALLOWED_REMOTE_MODES` already excluding it at the source (AC-48's boundary is enforced at both the write path and the render path, so a bug in one is never the only thing standing between a phone and bypass).
 
+- [ ] **Step 3b: Update two pre-existing tests this rewrite breaks**
+
+`test_render_settings_card_never_emits_model_or_permission_buttons` and
+`test_render_settings_card_escapes_toggle_names` (both already in
+`tests/remote/test_formatting.py`, from the earlier response-ui work) call
+`render_settings_card` without the new required `agent_name`/`mode_tokens`/
+`agent_tokens`/`model_tokens` — both will now raise `TypeError`. The first
+one is more than a signature mismatch: it explicitly asserted the *old*
+AC-41 boundary ("never emits model or permission buttons"), which this
+phase's AC-48/49 deliberately supersede. Rename and invert it rather than
+just patching its call:
+
+```python
+# tests/remote/test_formatting.py — replace in place
+def test_render_settings_card_now_emits_mode_and_model_buttons():
+    """Supersedes the old AC-41 boundary (model/mode were never buttons,
+    "desktop only" read-only text) — AC-48/49 revise that: mode and model
+    are now remotely settable, so this card must offer buttons for both."""
+    text, buttons = formatting.render_settings_card(
+        connection_label="evoflux-api",
+        model="claude-sonnet-5",
+        permission_mode="ask",
+        agent_name="evoflux",
+        mode_tokens={"ask": "m1"},
+        agent_tokens={},
+        model_tokens={"claude-sonnet-5": "d1"},
+        redaction_policy="standard",
+        notify_scope="all",
+        redaction_tokens={"strict": "r1", "off": "r2"},
+        notify_scope_tokens={"all": "n1", "remote_only": "n2"},
+    )
+    button_texts = [b.text for b in buttons]
+    assert any("model" in t.lower() for t in button_texts)
+    assert any("mode" in t.lower() for t in button_texts)
+    assert any("strict" in t.lower() for t in button_texts)
+```
+
+```python
+# tests/remote/test_formatting.py — test_render_settings_card_escapes_toggle_names,
+# add the three new required kwargs to its existing render_settings_card call
+# (agent_name="evoflux", mode_tokens={}, agent_tokens={}, model_tokens={}) —
+# its actual assertions (about redaction/notify escaping) are unchanged.
+```
+
 - [ ] **Step 4: Run and confirm pass**
 
 ```powershell
diff --git a/tests/remote/test_formatting.py b/tests/remote/test_formatting.py
index 2169fd0d..b0511fbe 100644
--- a/tests/remote/test_formatting.py
+++ b/tests/remote/test_formatting.py
@@ -163,6 +163,51 @@ def test_render_permission_resolved_card_escapes_command():
     assert "<script>" in text
 
 
+def test_render_settings_card_shows_mode_model_and_agent_buttons():
+    text, buttons = formatting.render_settings_card(
+        connection_label="evoflux-api",
+        model="anthropic:claude-sonnet-5",
+        permission_mode="ask",
+        agent_name="evoflux",
+        mode_tokens={"ask": "m1", "auto": "m2"},
+        agent_tokens={"evoflux": "a1", "explorer": "a2"},
+        model_tokens={"anthropic:claude-sonnet-5": "d1"},
+    )
+    assert "ask" in text
+    assert "anthropic:claude-sonnet-5" in text
+    assert "evoflux" in text
+    button_tokens = {b.token for b in buttons}
+    assert {"m1", "m2", "a1", "a2", "d1"} <= button_tokens
+
+
+def test_render_settings_card_never_offers_a_bypass_button():
+    _, buttons = formatting.render_settings_card(
+        connection_label="evoflux-api",
+        model="anthropic:claude-sonnet-5",
+        permission_mode="auto",
+        agent_name="evoflux",
+        mode_tokens={"auto": "m1", "bypass": "should-never-appear"},
+        agent_tokens={},
+        model_tokens={},
+    )
+    assert "should-never-appear" not in {b.token for b in buttons}
+    assert not any("bypass" in b.text.lower() for b in buttons)
+
+
+def test_render_settings_card_omits_redaction_section_when_not_supplied():
+    text, _ = formatting.render_settings_card(
+        connection_label="evoflux-api",
+        model="anthropic:claude-sonnet-5",
+        permission_mode="auto",
+        agent_name="evoflux",
+        mode_tokens={},
+        agent_tokens={},
+        model_tokens={},
+    )
+    assert "Outbound redaction" not in text
+    assert "Notifications" not in text
+
+
 def test_render_error_card_escapes_message():
     text, buttons = formatting.render_error_card(
         title="Add rate limiter",
@@ -173,19 +218,26 @@ def test_render_error_card_escapes_message():
     assert len(buttons) == 1
 
 
-def test_render_settings_card_never_emits_model_or_permission_buttons():
+def test_render_settings_card_now_emits_mode_and_model_buttons():
+    """Supersedes the old AC-41 boundary (model/mode were never buttons,
+    "desktop only" read-only text) — AC-48/49 revise that: mode and model
+    are now remotely settable, so this card must offer buttons for both."""
     text, buttons = formatting.render_settings_card(
         connection_label="evoflux-api",
         model="claude-sonnet-5",
-        permission_mode="ask each time",
+        permission_mode="ask",
+        agent_name="evoflux",
+        mode_tokens={"ask": "m1"},
+        agent_tokens={},
+        model_tokens={"claude-sonnet-5": "d1"},
         redaction_policy="standard",
         notify_scope="all",
         redaction_tokens={"strict": "r1", "off": "r2"},
         notify_scope_tokens={"all": "n1", "remote_only": "n2"},
     )
     button_texts = [b.text for b in buttons]
-    assert not any("model" in t.lower() for t in button_texts)
-    assert not any("permission" in t.lower() for t in button_texts)
+    assert any("model" in t.lower() for t in button_texts)
+    assert any("mode" in t.lower() for t in button_texts)
     assert any("strict" in t.lower() for t in button_texts)
 
 
@@ -206,7 +258,11 @@ def test_render_settings_card_escapes_toggle_names():
     text, buttons = formatting.render_settings_card(
         connection_label="evoflux-api",
         model="claude-sonnet-5",
-        permission_mode="ask each time",
+        permission_mode="ask",
+        agent_name="evoflux",
+        mode_tokens={},
+        agent_tokens={},
+        model_tokens={},
         redaction_policy="standard",
         notify_scope="all",
         redaction_tokens={"": "r1", "off": "r2"},

From 635eb6e935b0cf5440c37a27c267bfef1e367a46 Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Tue, 15 Sep 2026 10:26:12 +0700
Subject: [PATCH 38/71] feat(remote): wire /settings command with
 mode/model/agent switching
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 2 (Task 5, final) of documents/plans/remote-telegram-control-implementation.md.

Completes AC-48/49/50: /settings shows the active session's mode, model,
and lead agent as buttons (bypass excluded from the mode row); tapping
one calls the matching control.py write and replies with the outcome.

Also fixes a bug found during implementation: _cmd_settings's "no active
session" branches now call self._send explicitly rather than only
returning text — runtime.py's fallback send is skipped unconditionally
for the whole /settings command (same as /actions already does, to avoid
double-sending the card with buttons), so a text-only return would have
silently never reached the phone.
---
 app/remote/actions.py                         | 138 +++++++++++++++++-
 app/remote/runtime.py                         |   9 +-
 .../remote-telegram-control-implementation.md |  81 ++++++----
 tests/remote/test_actions.py                  |  97 ++++++++++++
 4 files changed, 290 insertions(+), 35 deletions(-)

diff --git a/app/remote/actions.py b/app/remote/actions.py
index 86ce84a3..dc45e2f0 100644
--- a/app/remote/actions.py
+++ b/app/remote/actions.py
@@ -35,6 +35,7 @@
 from app.remote.pairing import PairingService
 
 if TYPE_CHECKING:
+    from app.remote import control
     from app.remote.contracts import RemoteAdapterStatus
     from app.remote.outbound import RemoteProjection
 
@@ -81,7 +82,7 @@ class _ActionCapability:
 # ── Known commands ────────────────────────────────────────────────────────────
 
 _SLASH_COMMANDS: frozenset[str] = frozenset(
-    {"start", "help", "status", "new", "stop", "unpair", "actions"}
+    {"start", "help", "status", "new", "stop", "unpair", "actions", "settings"}
 )
 
 
@@ -189,6 +190,8 @@ async def dispatch_command(
             return await self._cmd_unpair(db, action)
         elif command == "actions":
             return await self._cmd_actions(db, action, arg)
+        elif command == "settings":
+            return await self._cmd_settings(db, action)
         else:
             # Unknown command — return bounded help.
             return await self._cmd_help(db, action)
@@ -284,6 +287,82 @@ async def _cmd_status(
             text=f"{status_text}\n{task_text}\nPaired: {pairing.label or 'Yes'}",
         )
 
+    async def _cmd_settings(
+        self, db: AsyncSession, action: RemoteInboundAction
+    ) -> RemoteActionResult:
+        from app.models.chat import ChatSession, normalize_mode
+        from app.remote import control
+        from app.remote.formatting import render_settings_card
+
+        pairing = await self._pairing_service.authorize(
+            db,
+            connection_id=action.connection_id,
+            principal_id=action.principal.principal_id,
+        )
+        if pairing is None:
+            return RemoteActionResult(status="unauthorized")
+
+        no_active_session_text = (
+            "No active task yet — send a message to start one, then "
+            "/settings shows its mode/model/agent."
+        )
+        if pairing.active_session_id is None:
+            await self._send(action.principal.destination_id, no_active_session_text)
+            return RemoteActionResult(status="ok", text=no_active_session_text)
+
+        session = await db.get(ChatSession, pairing.active_session_id)
+        if session is None:
+            await self._send(action.principal.destination_id, no_active_session_text)
+            return RemoteActionResult(status="ok", text=no_active_session_text)
+
+        app_mode = normalize_mode(session.mode)
+        session_id = str(session.id)
+
+        mode_tokens = {
+            mode: self._issue_settings_token(action, session_id, "set_mode", mode)
+            for mode in control.ALLOWED_REMOTE_MODES
+        }
+        agent_names = await control.list_lead_names(app_mode)
+        agent_tokens = {
+            name: self._issue_settings_token(action, session_id, "set_agent", name)
+            for name in agent_names
+        }
+        model_ids = await control.list_model_ids(app_mode)
+        model_tokens = {
+            model_id: self._issue_settings_token(action, session_id, "set_model", model_id)
+            for model_id in model_ids
+        }
+
+        text, buttons = render_settings_card(
+            connection_label=pairing.label or "This phone",
+            model=session.model or "(default)",
+            permission_mode=session.permission_mode,
+            agent_name=session.agent_name or "(default)",
+            mode_tokens=mode_tokens,
+            agent_tokens=agent_tokens,
+            model_tokens=model_tokens,
+        )
+
+        if self._adapter is not None:
+            await self._send(action.principal.destination_id, text, buttons=buttons)
+        return RemoteActionResult(status="ok", text=text)
+
+    def _issue_settings_token(
+        self,
+        action: RemoteInboundAction,
+        session_id: str,
+        action_kind: str,
+        action_target: str,
+    ) -> str:
+        return self._issue_token(
+            connection_id=action.connection_id,
+            principal_id=action.principal.principal_id,
+            destination_id=action.principal.destination_id,
+            session_id=session_id,
+            action_kind=action_kind,
+            action_target=action_target,
+        )
+
     async def _cmd_new(
         self, db: AsyncSession, action: RemoteInboundAction
     ) -> RemoteActionResult:
@@ -478,6 +557,12 @@ async def _execute_action(
             return await self._exec_coding_task(cap, action, db)
         elif cap.action_kind == "schedule_trigger":
             return await self._exec_schedule_trigger(cap, action, db)
+        elif cap.action_kind == "set_mode":
+            return await self._exec_set_mode(cap, action, db)
+        elif cap.action_kind == "set_agent":
+            return await self._exec_set_agent(cap, action, db)
+        elif cap.action_kind == "set_model":
+            return await self._exec_set_model(cap, action, db)
         return False
 
     async def _exec_workflow_start(
@@ -675,6 +760,57 @@ async def _send(
         except Exception as exc:
             logger.warning("remote_action_send_failed error={}", exc)
 
+    async def _exec_set_mode(
+        self, cap: _ActionCapability, action: RemoteInboundAction, db: AsyncSession
+    ) -> bool:
+        from app.remote import control
+
+        result = await control.set_permission_mode(db, cap.session_id, cap.action_target)
+        await self._reply_control_result(
+            action, result, f"Mode set to {cap.action_target}."
+        )
+        return True
+
+    async def _exec_set_agent(
+        self, cap: _ActionCapability, action: RemoteInboundAction, db: AsyncSession
+    ) -> bool:
+        from app.remote import control
+
+        result = await control.set_lead_agent(db, cap.session_id, cap.action_target)
+        await self._reply_control_result(
+            action, result, f"Lead agent set to {cap.action_target}."
+        )
+        return True
+
+    async def _exec_set_model(
+        self, cap: _ActionCapability, action: RemoteInboundAction, db: AsyncSession
+    ) -> bool:
+        from app.remote import control
+
+        result = await control.set_model(db, cap.session_id, cap.action_target)
+        await self._reply_control_result(
+            action, result, f"Model set to {cap.action_target}."
+        )
+        return True
+
+    async def _reply_control_result(
+        self,
+        action: RemoteInboundAction,
+        result: control.ControlResult,
+        success_text: str,
+    ) -> None:
+        if result.status == "ok":
+            text = success_text
+        elif result.status == "conflict":
+            text = result.detail or "That can't be changed right now."
+        elif result.status == "not_found":
+            text = "That task no longer exists."
+        elif result.detail:
+            text = f"That value isn't valid: {result.detail}"
+        else:
+            text = "That value isn't valid."
+        await self._reply_text(action.principal.destination_id, text)
+
     async def _reply_text(self, destination_id: str, text: str) -> None:
         await self._send(destination_id, text)
 
diff --git a/app/remote/runtime.py b/app/remote/runtime.py
index 95f79cba..8aa0290b 100644
--- a/app/remote/runtime.py
+++ b/app/remote/runtime.py
@@ -482,11 +482,12 @@ async def _handle_command(self, action: RemoteInboundAction) -> None:
             )
             return
 
-        # ``/actions`` already sends its own message (with buttons) inside
-        # RemoteActionService — sending its returned text again here would
-        # duplicate it. Every other command relies entirely on this send.
+        # ``/actions`` and ``/settings`` already send their own message
+        # (with buttons) inside RemoteActionService — sending the returned
+        # text again here would duplicate it. Every other command relies
+        # entirely on this send.
         command = (action.text or "").strip().split(maxsplit=1)[0][1:].lower()
-        if command == "actions":
+        if command in ("actions", "settings"):
             return
 
         if result.text and self._adapter is not None:
diff --git a/documents/plans/remote-telegram-control-implementation.md b/documents/plans/remote-telegram-control-implementation.md
index 817f245b..d0a38a67 100644
--- a/documents/plans/remote-telegram-control-implementation.md
+++ b/documents/plans/remote-telegram-control-implementation.md
@@ -902,7 +902,7 @@ class TestSettings:
             result = await service.dispatch_command(mock_db, action)
 
         assert result.status == "ok"
-        assert "start" in result.text.lower()
+        assert "no active task yet" in result.text.lower()
 
     @pytest.mark.asyncio
     async def test_mode_callback_applies_the_selected_mode(
@@ -988,18 +988,23 @@ _SLASH_COMMANDS: frozenset[str] = frozenset(
         if pairing is None:
             return RemoteActionResult(status="unauthorized")
 
+        # Both branches below call self._send explicitly, not just return
+        # text — runtime.py's guard (next step) skips its own fallback send
+        # for the WHOLE "settings" command unconditionally (matching how it
+        # already does for "actions"), so a branch that only returned text
+        # without sending it would silently never reach the phone at all.
+        no_active_session_text = (
+            "No active task yet — send a message to start one, then "
+            "/settings shows its mode/model/agent."
+        )
         if pairing.active_session_id is None:
-            return RemoteActionResult(
-                status="ok",
-                text="No active task yet — send a message to start one, then /settings shows its mode/model/agent.",
-            )
+            await self._send(action.principal.destination_id, no_active_session_text)
+            return RemoteActionResult(status="ok", text=no_active_session_text)
 
         session = await db.get(ChatSession, pairing.active_session_id)
         if session is None:
-            return RemoteActionResult(
-                status="ok",
-                text="No active task yet — send a message to start one, then /settings shows its mode/model/agent.",
-            )
+            await self._send(action.principal.destination_id, no_active_session_text)
+            return RemoteActionResult(status="ok", text=no_active_session_text)
 
         app_mode = normalize_mode(session.mode)
         session_id = str(session.id)
@@ -1069,57 +1074,62 @@ Expected: PASS.
 
 - [ ] **Step 6: Write failing tests for the three new capability action kinds, then implement `_execute_action`'s new branches**
 
+`_execute_action` already receives `db: AsyncSession` as a parameter
+(from Task 6 of the earlier response-ui plan, which added it so
+`handle_action_callback`'s existing workflow/coding-project/schedule
+branches could share one session) — use that directly rather than
+opening a second, redundant session via `async_session_factory()`.
+
 ```python
 # app/remote/actions.py — inside _execute_action
         elif cap.action_kind == "set_mode":
-            return await self._exec_set_mode(cap, action)
+            return await self._exec_set_mode(cap, action, db)
         elif cap.action_kind == "set_agent":
-            return await self._exec_set_agent(cap, action)
+            return await self._exec_set_agent(cap, action, db)
         elif cap.action_kind == "set_model":
-            return await self._exec_set_model(cap, action)
+            return await self._exec_set_model(cap, action, db)
 ```
 
 ```python
 # app/remote/actions.py — new methods, near _exec_workflow_start
     async def _exec_set_mode(
-        self, cap: _ActionCapability, action: RemoteInboundAction
+        self, cap: _ActionCapability, action: RemoteInboundAction, db: AsyncSession
     ) -> bool:
-        from app.core.db import async_session_factory
         from app.remote import control
 
-        async with async_session_factory() as db:
-            result = await control.set_permission_mode(
-                db, cap.session_id, cap.action_target
-            )
-        await self._reply_control_result(action, result, f"Mode set to {cap.action_target}.")
+        result = await control.set_permission_mode(db, cap.session_id, cap.action_target)
+        await self._reply_control_result(
+            action, result, f"Mode set to {cap.action_target}."
+        )
         return True
 
     async def _exec_set_agent(
-        self, cap: _ActionCapability, action: RemoteInboundAction
+        self, cap: _ActionCapability, action: RemoteInboundAction, db: AsyncSession
     ) -> bool:
-        from app.core.db import async_session_factory
         from app.remote import control
 
-        async with async_session_factory() as db:
-            result = await control.set_lead_agent(db, cap.session_id, cap.action_target)
+        result = await control.set_lead_agent(db, cap.session_id, cap.action_target)
         await self._reply_control_result(
             action, result, f"Lead agent set to {cap.action_target}."
         )
         return True
 
     async def _exec_set_model(
-        self, cap: _ActionCapability, action: RemoteInboundAction
+        self, cap: _ActionCapability, action: RemoteInboundAction, db: AsyncSession
     ) -> bool:
-        from app.core.db import async_session_factory
         from app.remote import control
 
-        async with async_session_factory() as db:
-            result = await control.set_model(db, cap.session_id, cap.action_target)
-        await self._reply_control_result(action, result, f"Model set to {cap.action_target}.")
+        result = await control.set_model(db, cap.session_id, cap.action_target)
+        await self._reply_control_result(
+            action, result, f"Model set to {cap.action_target}."
+        )
         return True
 
     async def _reply_control_result(
-        self, action: RemoteInboundAction, result, success_text: str
+        self,
+        action: RemoteInboundAction,
+        result: control.ControlResult,
+        success_text: str,
     ) -> None:
         if result.status == "ok":
             text = success_text
@@ -1127,11 +1137,22 @@ Expected: PASS.
             text = result.detail or "That can't be changed right now."
         elif result.status == "not_found":
             text = "That task no longer exists."
+        elif result.detail:
+            text = f"That value isn't valid: {result.detail}"
         else:
-            text = f"That value isn't valid: {result.detail}" if result.detail else "That value isn't valid."
+            text = "That value isn't valid."
         await self._reply_text(action.principal.destination_id, text)
 ```
 
+`result: control.ControlResult`'s annotation resolves fine at type-check
+time only because `from __future__ import annotations` is already at the
+top of `actions.py` (deferring all annotations to strings) — add `from
+app.remote import control` to the existing `if TYPE_CHECKING:` block near
+the top of the file (alongside `RemoteAdapterStatus`/`RemoteProjection`)
+so the type checker can still resolve the name, without a real module-level
+import (this module never imports `app.remote.control` outside `TYPE_CHECKING`,
+matching every other cross-module reference in this file).
+
 - [ ] **Step 7: Run and confirm pass**
 
 ```powershell
diff --git a/tests/remote/test_actions.py b/tests/remote/test_actions.py
index ba291f69..20e81aef 100644
--- a/tests/remote/test_actions.py
+++ b/tests/remote/test_actions.py
@@ -8,6 +8,8 @@
 
 import pytest
 
+import app.core.db as db_module
+from app.models.chat import ChatSession
 from app.remote.actions import (
     RemoteActionService,
     RemoteMenuItem,
@@ -598,3 +600,98 @@ async def test_actions_with_items_sends_buttons(
         assert result.status == "ok"
         assert "Item 1" in result.text
         assert "Item 2" in result.text
+
+
+# ── Settings ──────────────────────────────────────────────────────────────────
+
+
+class TestSettings:
+    @pytest.mark.asyncio
+    async def test_settings_command_shows_current_mode_model_and_agent(
+        self, service: RemoteActionService
+    ) -> None:
+        async with db_module.async_session_factory() as db:
+            session = ChatSession(
+                title="Settings test",
+                mode="work",
+                session_type="main",
+                permission_mode="ask",
+                model="anthropic:claude-sonnet-5",
+                agent_name="evoflux",
+            )
+            db.add(session)
+            await db.commit()
+            await db.refresh(session)
+
+            mock_pairing = MagicMock()
+            mock_pairing.active_session_id = session.id
+            mock_pairing.label = "My Phone"
+
+            with patch.object(
+                service._pairing_service, "authorize", return_value=mock_pairing
+            ):
+                action = _make_action(text="/settings")
+                result = await service.dispatch_command(db, action)
+
+        assert result.status == "ok"
+        assert "ask" in result.text
+        assert "anthropic:claude-sonnet-5" in result.text
+        assert "evoflux" in result.text
+
+    @pytest.mark.asyncio
+    async def test_settings_command_without_active_session_is_friendly(
+        self, service: RemoteActionService
+    ) -> None:
+        mock_db = MagicMock()
+        mock_pairing = MagicMock()
+        mock_pairing.active_session_id = None
+
+        with patch.object(
+            service._pairing_service, "authorize", return_value=mock_pairing
+        ):
+            action = _make_action(text="/settings")
+            result = await service.dispatch_command(mock_db, action)
+
+        assert result.status == "ok"
+        assert "no active task yet" in result.text.lower()
+
+    @pytest.mark.asyncio
+    async def test_mode_callback_applies_the_selected_mode(
+        self, service: RemoteActionService, adapter: FakeAdapter
+    ) -> None:
+        conn_id = uuid4()
+        async with db_module.async_session_factory() as db:
+            session = ChatSession(
+                title="Settings test",
+                mode="work",
+                session_type="main",
+                permission_mode="auto",
+            )
+            db.add(session)
+            await db.commit()
+            await db.refresh(session)
+
+            mock_pairing = MagicMock()
+            mock_pairing.active_session_id = session.id
+            mock_pairing.label = "My Phone"
+
+            with patch.object(
+                service._pairing_service, "authorize", return_value=mock_pairing
+            ):
+                settings_action = _make_action(text="/settings", connection_id=conn_id)
+                await service.dispatch_command(db, settings_action)
+
+            sent_buttons = adapter.sent_messages[-1].buttons
+            ask_token = next(b.token for b in sent_buttons if b.text == "Mode: ask")
+
+            callback_action = _make_action(
+                kind=RemoteInboundActionKind.CALLBACK,
+                callback_token=ask_token,
+                connection_id=conn_id,
+            )
+            handled = await service.handle_action_callback(callback_action, db)
+
+            assert handled is True
+            refreshed = await db.get(ChatSession, session.id)
+            assert refreshed is not None
+            assert refreshed.permission_mode == "ask"

From 7aaf20f155de7643a37e89535742cac5fc84ab6e Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Tue, 15 Sep 2026 10:35:31 +0700
Subject: [PATCH 39/71] feat(remote): add health diagnostics and file-diff
 reads

Phase 3 (Task 1) of documents/plans/remote-telegram-insight-implementation.md.

Second documented exception to app/remote/'s "service layer only" rule
(after get_registry): health_diagnostics and get_diff_view each already
carry nontrivial, security-sensitive logic (db/provider/team/MCP/disk
checks; path-traversal + staged/unstaged/untracked diff detection) with
no service-layer equivalent to call instead.
---
 app/remote/control.py        | 48 +++++++++++++++++++++++++++++++++---
 tests/remote/test_control.py | 23 +++++++++++++++++
 2 files changed, 68 insertions(+), 3 deletions(-)

diff --git a/app/remote/control.py b/app/remote/control.py
index 06fbd3d7..6ee96212 100644
--- a/app/remote/control.py
+++ b/app/remote/control.py
@@ -1,4 +1,5 @@
-"""Mode/model/lead-agent control for the phone's /settings command.
+"""Mode/model/lead-agent/health/diff control for the phone's /settings,
+/health, and /changes commands.
 
 Each write function replicates the exact persistence sequence its HTTP
 route sibling already uses (app/api/routes/team/chat.py's
@@ -6,8 +7,21 @@
 app/api/routes/team/webbridge.py's update_browser_session_model), as a
 plain async function app/remote/actions.py can call directly — remote
 and desktop must stay behaviorally identical, but app/remote/ never
-depends on app/api/routes/* (see list_model_ids/set_model for the one
-deliberate departure: the model registry).
+depends on app/api/routes/* except two narrow, deliberate departures:
+
+- list_model_ids/set_model call app.api.routes.agents.get_registry — the
+  model catalog has no service-layer equivalent.
+- get_health_diagnostics/get_file_diff call
+  app.api.routes.health.health_diagnostics and
+  app.api.routes.team.git.get_diff_view directly — each already carries
+  nontrivial, security-sensitive logic (health's ~250 lines of db/
+  provider/team/MCP/disk checks; diff-view's path-traversal guard and
+  staged/unstaged/untracked detection) with no service-layer equivalent
+  either. Reimplementing either in app/remote/ would risk silently
+  diverging from the desktop's own behavior, or worse, subtly
+  reintroducing a path-traversal bug. Both are called with explicit
+  arguments, never relying on their Depends(...) defaults, which are
+  FastAPI dependency-injection sentinels outside a real request.
 
 bypass is deliberately excluded from ALLOWED_REMOTE_MODES, checked by
 name (not by list length or position) before anything else runs — a
@@ -33,6 +47,8 @@
     "list_lead_names",
     "set_model",
     "list_model_ids",
+    "get_health_diagnostics",
+    "get_file_diff",
 ]
 
 #: Every permission mode this phone may set — bypass excluded on purpose.
@@ -196,3 +212,29 @@ async def set_model(
     await db.commit()
 
     return ControlResult(status="ok")
+
+
+async def get_health_diagnostics() -> dict:
+    """The same active health check the desktop UI's Diagnostics screen
+    uses, called directly rather than duplicated — see this module's
+    docstring for why app/remote/ makes an exception to "service layer
+    only" for this one function. Uses read_session_factory (not
+    async_session_factory) since this mirrors a GET route — app.core.db's
+    own get_session dependency picks the same read lane for GET requests."""
+    from app.api.routes.health import health_diagnostics
+    from app.core.db import read_session_factory
+
+    async with read_session_factory() as db:
+        return await health_diagnostics(session=db)
+
+
+async def get_file_diff(workspace: str, path: str) -> str:
+    """One file's unified diff (staged, unstaged, or untracked-as-additions)
+    — delegates to the same route function the desktop UI's diff viewer
+    uses, which already carries the path-traversal and staged/unstaged/
+    untracked detection logic; reimplementing that here would risk
+    subtly reintroducing a path-traversal bug."""
+    from app.api.routes.team.git import get_diff_view
+
+    result = await get_diff_view(workspace=workspace, path=path)
+    return result.get("diff", "")
diff --git a/tests/remote/test_control.py b/tests/remote/test_control.py
index 6a3df4d5..407bc34e 100644
--- a/tests/remote/test_control.py
+++ b/tests/remote/test_control.py
@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from pathlib import Path
 from uuid import UUID
 
 import pytest
@@ -213,3 +214,25 @@ async def test_set_model_rejects_unknown_model_id(
         )
 
     assert result.status == "invalid"
+
+
+@pytest.mark.asyncio
+async def test_get_health_diagnostics_returns_checks_and_summary() -> None:
+    result = await control.get_health_diagnostics()
+
+    assert "checks" in result
+    assert "summary" in result
+    assert result["summary"] in ("ok", "warn", "fail")
+    assert isinstance(result["checks"], list)
+    if result["checks"]:
+        first = result["checks"][0]
+        assert set(first.keys()) >= {"id", "label", "status", "detail"}
+
+
+@pytest.mark.asyncio
+async def test_get_file_diff_returns_empty_for_a_non_git_workspace(
+    tmp_path: Path,
+) -> None:
+    diff = await control.get_file_diff(str(tmp_path), "nonexistent.py")
+
+    assert diff == ""

From 48fc340092446ad6f15f375023f16c7964092f51 Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Tue, 15 Sep 2026 10:36:29 +0700
Subject: [PATCH 40/71] feat(remote): render health and changes cards

Phase 3 (Task 2) of documents/plans/remote-telegram-insight-implementation.md.
---
 app/remote/formatting.py        | 41 ++++++++++++++++++++++
 tests/remote/test_formatting.py | 62 +++++++++++++++++++++++++++++++++
 2 files changed, 103 insertions(+)

diff --git a/app/remote/formatting.py b/app/remote/formatting.py
index c2f4d0c7..2edf0608 100644
--- a/app/remote/formatting.py
+++ b/app/remote/formatting.py
@@ -17,6 +17,8 @@
     "render_prompt_suggestions",
     "render_permission_card",
     "render_permission_resolved_card",
+    "render_health_card",
+    "render_changes_card",
 ]
 
 _STATUS_ICON = {"accepted": "\U0001f527", "queued": "⏳", "pending": "⏳"}
@@ -33,6 +35,7 @@
     "always": "Allowed for session",
     "reject": "Rejected",
 }
+_HEALTH_ICON = {"ok": "✅", "warn": "⚠️", "fail": "❌"}
 
 
 def escape(value: str) -> str:
@@ -227,3 +230,41 @@ def render_prompt_suggestions(
         buttons.append(RemoteButton(text="▶ Continue last session", token=continue_token))
     buttons += [RemoteButton(text=escape(label), token=token) for token, label in suggestions]
     return text, tuple(buttons)
+
+
+def render_health_card(checks: Sequence[Mapping[str, object]]) -> str:
+    lines = ["\U0001fa7a Health", ""]
+    for check in checks:
+        icon = _HEALTH_ICON.get(str(check.get("status", "")), "❓")
+        label = escape(str(check.get("label", "")))
+        detail = escape(str(check.get("detail", "")))
+        lines.append(f"{icon} {label}\n{detail}")
+    return "\n\n".join(lines)
+
+
+def render_changes_card(
+    *,
+    title: str,
+    files: Sequence[tuple[str, str, int | None, int | None]],
+    additions: int,
+    deletions: int,
+    file_tokens: Mapping[str, str],
+) -> tuple[str, tuple[RemoteButton, ...]]:
+    lines = [
+        f"\U0001f4dd Changes — {escape(title)}",
+        "",
+        f"+{additions} -{deletions} across {len(files)} file(s)",
+        "",
+    ]
+    for path, status, file_additions, file_deletions in files:
+        counts = ""
+        if file_additions is not None or file_deletions is not None:
+            counts = f" (+{file_additions or 0} -{file_deletions or 0})"
+        lines.append(f"\U0001f4c4 {escape(path)}{counts} — {escape(status)}")
+    text = "\n".join(lines)
+
+    buttons = tuple(
+        RemoteButton(text=f"View: {escape(path)}", token=token)
+        for path, token in file_tokens.items()
+    )
+    return text, buttons
diff --git a/tests/remote/test_formatting.py b/tests/remote/test_formatting.py
index b0511fbe..44233337 100644
--- a/tests/remote/test_formatting.py
+++ b/tests/remote/test_formatting.py
@@ -286,3 +286,65 @@ def test_render_prompt_suggestions_escapes_labels():
     # Suggestion buttons should have escaped labels
     assert buttons[1].text == "Suggest <tag>"
     assert buttons[2].text == "Other & more"
+
+
+def test_render_health_card_shows_each_check_with_its_status_icon():
+    text = formatting.render_health_card(
+        [
+            {"id": "db", "label": "Database", "status": "ok", "detail": "connected"},
+            {
+                "id": "disk",
+                "label": "Disk space",
+                "status": "fail",
+                "detail": "2.1 GB free",
+            },
+        ]
+    )
+    assert "Database" in text
+    assert "Disk space" in text
+    assert "✅" in text  # ok icon
+    assert "❌" in text  # fail icon
+
+
+def test_render_health_card_escapes_detail_text():
+    text = formatting.render_health_card(
+        [
+            {
+                "id": "x",
+                "label": "X",
+                "status": "warn",
+                "detail": "",
+            }
+        ]
+    )
+    assert "" not in text
+    assert "<script>" in text
+
+
+def test_render_changes_card_lists_files_with_line_counts_and_buttons():
+    text, buttons = formatting.render_changes_card(
+        title="Fix auth tests",
+        files=[
+            ("app/auth.py", "modified", 10, 2),
+            ("tests/test_auth.py", "added", 5, 0),
+        ],
+        additions=15,
+        deletions=2,
+        file_tokens={"app/auth.py": "tok-1", "tests/test_auth.py": "tok-2"},
+    )
+    assert "app/auth.py" in text
+    assert "+15" in text
+    assert "-2" in text
+    assert {b.token for b in buttons} == {"tok-1", "tok-2"}
+
+
+def test_render_changes_card_escapes_file_paths():
+    text, _ = formatting.render_changes_card(
+        title="Task",
+        files=[("",
+            }
+        ]
+    )
+    assert "" not in text
+    assert "<script>" in text
+
+
+def test_render_changes_card_lists_files_with_line_counts_and_buttons():
+    text, buttons = formatting.render_changes_card(
+        title="Fix auth tests",
+        files=[
+            ("app/auth.py", "modified", 10, 2),
+            ("tests/test_auth.py", "added", 5, 0),
+        ],
+        additions=15,
+        deletions=2,
+        file_tokens={"app/auth.py": "tok-1", "tests/test_auth.py": "tok-2"},
+    )
+    assert "app/auth.py" in text
+    assert "+15" in text
+    assert "-2" in text
+    assert {b.token for b in buttons} == {"tok-1", "tok-2"}
+
+
+def test_render_changes_card_escapes_file_paths():
+    text, _ = formatting.render_changes_card(
+        title="Task",
+        files=[("", elapsed_seconds=1.0, activity_lines=[]
+    )
+    assert "" not in text
+    assert "<script>" in text
+
+
+def test_render_live_status_card_with_no_activity_yet_still_renders() -> None:
+    text, buttons = formatting.render_live_status_card(
+        title="New task", elapsed_seconds=0.5, activity_lines=[]
+    )
+    assert "New task" in text
+    assert buttons == ()
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `uv run pytest --no-cov -q tests/remote/test_formatting.py -k live_status_card -v`
+Expected: FAIL with `AttributeError: module 'app.remote.formatting' has no attribute 'render_live_status_card'`.
+
+- [ ] **Step 3: Write the implementation**
+
+Add to `app/remote/formatting.py`, near `render_status_card`, and add `"render_live_status_card"` to `__all__`:
+
+```python
+def render_live_status_card(
+    *, title: str, elapsed_seconds: float, activity_lines: Sequence[str]
+) -> tuple[str, tuple[RemoteButton, ...]]:
+    """The single status card a live-mode turn edits in place (AC-56). No
+    buttons — like ``render_status_card``, this card is never actionable;
+    when the turn ends this same message becomes the done/error card."""
+    header = f"\U0001f527 {escape(title)} · {format_elapsed(elapsed_seconds)}"
+    if not activity_lines:
+        return header, ()
+    return header + "\n\n" + "\n".join(activity_lines), ()
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `uv run pytest --no-cov -q tests/remote/test_formatting.py -v`
+Expected: PASS, all tests in the file green (no regressions).
+
+- [ ] **Step 5: Lint and type-check**
+
+Run: `uv run ruff check app/remote/formatting.py tests/remote/test_formatting.py && uv run ty check app/remote/formatting.py`
+Expected: both clean.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add app/remote/formatting.py tests/remote/test_formatting.py
+git commit -m "feat(remote): add render_live_status_card for live-mode turns (AC-56)"
+```
+
+---
+
+### Task 4: Thread `response_mode` from the pairing into `begin_phone_turn`
+
+**Files:**
+- Modify: `app/remote/inbound.py`
+- Modify: `app/remote/runtime.py`
+- Test: `tests/remote/test_inbound.py`
+
+**Interfaces:**
+- Consumes: `RemotePairing.response_mode` (already persisted, `app/models/remote.py`).
+- Produces: `RemoteInboundResult.response_mode: str = "summary"` (new field, default preserves every existing caller); `runtime.py`'s `_handle_text` passes `response_mode=result.response_mode` into `begin_phone_turn` (Task 5 adds that parameter).
+
+- [ ] **Step 1: Write the failing tests**
+
+`tests/remote/test_inbound.py` already has a `_paired_text_action(db, text=...)` module-level helper (creates a `RemoteConnection` + `RemotePairing` + a matching `RemoteInboundAction`, returns `(pairing, action)`) and an established monkeypatch pattern for stubbing `resolve_team_for_session`/`submit_persisted_interactive_message` — see `test_handle_text_creates_and_selects_a_top_level_work_task` near the top of the file. Add these two tests reusing that exact pattern:
+
+```python
+@pytest.mark.asyncio
+async def test_handle_text_result_defaults_to_summary_response_mode(monkeypatch):
+    from app.remote.inbound import RemoteInboundService
+    import app.remote.inbound as inbound
+
+    async with db_module.async_session_factory() as db:
+        pairing, action = await _paired_text_action(db)
+        team = SimpleNamespace()
+
+        async def resolve(db, session_id: str, *, require_existing: bool):
+            session = await db.get(ChatSession, UUID(session_id))
+            return session, team
+
+        submit = AsyncMock(
+            side_effect=lambda db, *, session, **_kwargs: InteractiveMessageResult(
+                status="accepted", session_id=str(session.id), message_id=None
+            )
+        )
+        monkeypatch.setattr(inbound, "resolve_team_for_session", resolve)
+        monkeypatch.setattr(inbound, "submit_persisted_interactive_message", submit)
+
+        result = await RemoteInboundService().handle_text(db, action)
+
+        assert result.response_mode == "summary"
+
+
+@pytest.mark.asyncio
+async def test_handle_text_result_carries_a_live_response_mode(monkeypatch):
+    from app.remote.inbound import RemoteInboundService
+    import app.remote.inbound as inbound
+
+    async with db_module.async_session_factory() as db:
+        pairing, action = await _paired_text_action(db)
+        pairing.response_mode = "live"
+        db.add(pairing)
+        await db.commit()
+        team = SimpleNamespace()
+
+        async def resolve(db, session_id: str, *, require_existing: bool):
+            session = await db.get(ChatSession, UUID(session_id))
+            return session, team
+
+        submit = AsyncMock(
+            side_effect=lambda db, *, session, **_kwargs: InteractiveMessageResult(
+                status="accepted", session_id=str(session.id), message_id=None
+            )
+        )
+        monkeypatch.setattr(inbound, "resolve_team_for_session", resolve)
+        monkeypatch.setattr(inbound, "submit_persisted_interactive_message", submit)
+
+        result = await RemoteInboundService().handle_text(db, action)
+
+        assert result.response_mode == "live"
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `uv run pytest --no-cov -q tests/remote/test_inbound.py -k response_mode -v`
+Expected: FAIL with `AttributeError: 'RemoteInboundResult' object has no attribute 'response_mode'`.
+
+- [ ] **Step 3: Implement**
+
+In `app/remote/inbound.py`, extend the dataclass and its one success-path construction:
+
+```python
+@dataclass(frozen=True)
+class RemoteInboundResult:
+    """A bounded, adapter-neutral outcome for one remote action."""
+
+    status: str
+    session_id: UUID | None = None
+    message_id: UUID | None = None
+    response_mode: str = "summary"
+```
+
+and in `handle_text`'s final `return`:
+
+```python
+        return RemoteInboundResult(
+            status=result.status,
+            session_id=UUID(result.session_id),
+            message_id=result.message_id,
+            response_mode=pairing.response_mode,
+        )
+```
+
+(`pairing` is already in scope — it was re-fetched at the top of the `async with await self._lock_for(...)` block.)
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `uv run pytest --no-cov -q tests/remote/test_inbound.py -v`
+Expected: PASS, all tests in the file green.
+
+- [ ] **Step 5: Wire runtime.py (no new test — covered end-to-end by Task 5's outbound tests)**
+
+In `app/remote/runtime.py`'s `_handle_text`, extend the `begin_phone_turn` call:
+
+```python
+            self._projection.begin_phone_turn(
+                str(result.session_id),
+                connection_id=str(action.connection_id),
+                destination_id=action.principal.destination_id,
+                principal_id=action.principal.principal_id,
+                title=(
+                    session_row.title
+                    if session_row and session_row.title
+                    else "New task"
+                ),
+                status=result.status,
+                response_mode=result.response_mode,
+            )
+```
+
+- [ ] **Step 6: Lint and type-check**
+
+Run: `uv run ruff check app/remote/inbound.py app/remote/runtime.py tests/remote/test_inbound.py && uv run ty check app/remote/inbound.py app/remote/runtime.py`
+Expected: both clean. (`ty check` on `runtime.py` will fail until Task 5 adds `begin_phone_turn`'s `response_mode` parameter — if this task is executed before Task 5, run this step again after Task 5 instead of failing the branch here.)
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add app/remote/inbound.py app/remote/runtime.py tests/remote/test_inbound.py
+git commit -m "feat(remote): thread response_mode from the pairing into each new turn (AC-55/56)"
+```
+
+---
+
+### Task 5: Wire live-mode observation and throttled edits into `app/remote/outbound.py`
+
+This is the integration task — the largest in this plan. It depends on Tasks 1, 2, 3, and 4.
+
+**Files:**
+- Modify: `app/remote/outbound.py`
+- Test: `tests/remote/test_outbound.py`
+
+**Interfaces:**
+- Consumes: `LiveActivityWindow` (Task 1), `EditBudget` (Task 2), `render_live_status_card` (Task 3), `begin_phone_turn(..., response_mode: str = "summary")` (Task 4's call site).
+- Produces: `_TurnDeliveryState.activity: LiveActivityWindow`, `_TurnDeliveryState.response_mode: str`; `RemoteProjection._edit_budget: EditBudget`.
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `tests/remote/test_outbound.py` (reusing this file's existing `FakeAdapter`, `_envelope` helper, and `begin_phone_turn`-based turn setup patterns — read the file's existing live-turn-adjacent tests first, e.g. around `_handle_gate`/`_finalize_turn`, before writing these):
+
+```python
+class TestLiveMode:
+    @pytest.mark.asyncio
+    async def test_summary_mode_never_renders_activity_even_when_tool_events_flow(
+        self,
+    ) -> None:
+        """AC-20 regression guard: response_mode="summary" (the default)
+        must behave exactly as it did before this feature existed."""
+        adapter = FakeAdapter()
+        projection = RemoteProjection()
+        projection.set_adapter(adapter)
+        session_id = str(uuid4())
+        connection_id = str(uuid4())  # must be a real UUID string — _enqueue_edit/
+        # _enqueue_send both do UUID(connection_id) before handing a message to the
+        # adapter, matching every other test in this file (e.g. test_done_edits_...
+        # above uses connection_id = str(uuid4()) for the same reason).
+        projection.register_session(
+            session_id, connection_id=connection_id, destination_id="chat-1"
+        )
+        projection.begin_phone_turn(
+            session_id,
+            connection_id=connection_id,
+            destination_id="chat-1",
+            principal_id="user-1",
+            title="Task",
+            status="accepted",
+        )
+        await projection.drain_pending()
+        edits_before = len(adapter.edited)
+
+        projection.observe(
+            session_id,
+            _envelope(
+                "tool_start",
+                agent="explorer",
+                tool_call_id="call-1",
+                name="grep",
+                arguments="{}",
+            ),
+        )
+        await projection.drain_pending()
+
+        assert len(adapter.edited) == edits_before  # no live edit was sent
+
+    @pytest.mark.asyncio
+    async def test_live_mode_edits_the_status_card_with_activity(self) -> None:
+        adapter = FakeAdapter()
+        projection = RemoteProjection()
+        projection.set_adapter(adapter)
+        session_id = str(uuid4())
+        connection_id = str(uuid4())
+        projection.register_session(
+            session_id, connection_id=connection_id, destination_id="chat-1"
+        )
+        projection.begin_phone_turn(
+            session_id,
+            connection_id=connection_id,
+            destination_id="chat-1",
+            principal_id="user-1",
+            title="Task",
+            status="accepted",
+            response_mode="live",
+        )
+        await projection.drain_pending()
+
+        projection.observe(
+            session_id,
+            _envelope(
+                "tool_start",
+                agent="explorer",
+                tool_call_id="call-1",
+                name="grep",
+                arguments='{"pattern": "def test_auth"}',
+            ),
+        )
+        await projection.drain_pending()
+
+        assert len(adapter.edited) == 1
+        assert "grep" in adapter.edited[-1].text
+        assert "def test_auth" in adapter.edited[-1].text
+
+    @pytest.mark.asyncio
+    async def test_live_mode_throttles_a_second_edit_within_the_interval(self) -> None:
+        adapter = FakeAdapter()
+        projection = RemoteProjection()
+        projection.set_adapter(adapter)
+        session_id = str(uuid4())
+        connection_id = str(uuid4())
+        projection.register_session(
+            session_id, connection_id=connection_id, destination_id="chat-1"
+        )
+        projection.begin_phone_turn(
+            session_id,
+            connection_id=connection_id,
+            destination_id="chat-1",
+            principal_id="user-1",
+            title="Task",
+            status="accepted",
+            response_mode="live",
+        )
+        await projection.drain_pending()
+
+        projection.observe(
+            session_id,
+            _envelope(
+                "tool_start", agent="explorer", tool_call_id="call-1", name="grep",
+                arguments="{}",
+            ),
+        )
+        await projection.drain_pending()
+        projection.observe(
+            session_id,
+            _envelope(
+                "tool_start", agent="explorer", tool_call_id="call-2", name="read",
+                arguments="{}",
+            ),
+        )
+        await projection.drain_pending()
+
+        # Both tool_start events fire well within LIVE_EDIT_INTERVAL of each
+        # other in real wall-clock terms (this test runs in milliseconds),
+        # so only the first produced an edit.
+        assert len(adapter.edited) == 1
+
+    @pytest.mark.asyncio
+    async def test_final_card_is_not_starved_by_the_live_edit_budget(self) -> None:
+        """A turn's final done card must always be delivered even if the
+        edit budget is currently exhausted from live-activity updates."""
+        adapter = FakeAdapter()
+        projection = RemoteProjection()
+        projection.set_adapter(adapter)
+        session_id = str(uuid4())
+        connection_id = str(uuid4())
+        projection.register_session(
+            session_id, connection_id=connection_id, destination_id="chat-1"
+        )
+        projection.begin_phone_turn(
+            session_id,
+            connection_id=connection_id,
+            destination_id="chat-1",
+            principal_id="user-1",
+            title="Task",
+            status="accepted",
+            response_mode="live",
+        )
+        await projection.drain_pending()
+
+        projection.observe(
+            session_id,
+            _envelope(
+                "tool_start", agent="explorer", tool_call_id="call-1", name="grep",
+                arguments="{}",
+            ),
+        )
+        await projection.drain_pending()
+        edits_after_activity = len(adapter.edited)
+
+        projection.observe(session_id, _envelope("done"))
+        await projection.drain_pending()
+
+        assert len(adapter.edited) == edits_after_activity + 1  # the done card landed
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `uv run pytest --no-cov -q tests/remote/test_outbound.py -k TestLiveMode -v`
+Expected: FAIL — `begin_phone_turn() got an unexpected keyword argument 'response_mode'`.
+
+- [ ] **Step 3: Implement**
+
+In `app/remote/outbound.py`:
+
+1. Add imports:
+
+```python
+from app.remote.edit_budget import EditBudget
+from app.remote.formatting import (
+    render_done_card,
+    render_error_card,
+    render_live_status_card,
+    render_status_card,
+)
+from app.remote.live_activity import LiveActivityWindow
+```
+
+2. Add the activity event set and extend the observed set:
+
+```python
+#: Live-mode-only events (AC-56) — only handled for a turn whose cached
+#: response_mode is "live"; the check happens in ``observe`` itself
+#: (in-memory, synchronous — no I/O), never before it, since ``observe``
+#: has no other reason to look at a turn's mode.
+_ACTIVITY_EVENT_TYPES = frozenset({"tool_call", "tool_start", "tool_end", "thinking"})
+
+_OBSERVED_EVENT_TYPES = frozenset(
+    {
+        "done",
+        "error",
+        "permission_asked",
+        "question_asked",
+        "plan_approval_requested",
+        "permission_replied",
+        "question_replied",
+        "plan_approval_replied",
+    }
+) | _ACTIVITY_EVENT_TYPES
+```
+
+3. Extend `_TurnDeliveryState`:
+
+```python
+    #: "summary" (default) or "live" — read fresh from the pairing at the
+    #: start of every phone-admitted turn (never cached across turns), so
+    #: AC-55's "no restart needed" holds. Desktop-started turns (no
+    #: begin_phone_turn call) stay at the default; only a phone-admitted
+    #: turn can be live, since only it owns an editable status card.
+    response_mode: str = "summary"
+    #: The rolling activity window this turn renders into while live —
+    #: unused and empty in summary mode.
+    activity: LiveActivityWindow = field(default_factory=LiveActivityWindow)
+```
+
+4. Add `_edit_budget` to `RemoteProjection`:
+
+```python
+    #: Shared across every live turn on this connection (AC-57) — see
+    #: app/remote/edit_budget.py's own docstring for why the throttle is
+    #: connection-scoped rather than per-turn.
+    _edit_budget: EditBudget = field(default_factory=EditBudget, repr=False)
+```
+
+5. Extend `begin_phone_turn`'s signature and construction (add the parameter, thread it into `_TurnDeliveryState(...)`):
+
+```python
+    def begin_phone_turn(
+        self,
+        session_id: str,
+        *,
+        connection_id: str,
+        destination_id: str,
+        principal_id: str,
+        title: str,
+        status: str,
+        response_mode: str = "summary",
+    ) -> None:
+```
+
+```python
+        turn = _TurnDeliveryState(
+            session_id=session_id,
+            connection_id=connection_id,
+            destination_id=destination_id,
+            principal_id=principal_id,
+            lifecycle_correlation_id=correlation_id,
+            phone_admitted=True,
+            title=title,
+            response_mode=response_mode,
+        )
+```
+
+6. In `observe`, after the existing `turn = self._turns.get(session_id)` / fallback-turn block and before the `if event_type == "done":` chain, add the activity branch:
+
+```python
+        if event_type in _ACTIVITY_EVENT_TYPES:
+            self._handle_activity(turn, event_type, envelope)
+            return
+```
+
+7. Add the two new methods (near `_handle_gate`):
+
+```python
+    def _handle_activity(
+        self, turn: _TurnDeliveryState, event_type: str, envelope
+    ) -> None:
+        """Feed one tool/thinking event into *turn*'s activity window and,
+        if this is a live phone-admitted turn, enqueue a throttled edit.
+
+        A turn whose final card has already been queued
+        (``completion_sent``) ignores further activity — the card is
+        about to be overwritten by the done/error card regardless."""
+        if (
+            not turn.phone_admitted
+            or turn.response_mode != "live"
+            or turn.completion_sent
+        ):
+            return
+
+        data = envelope.data
+        name = data.get("name", "")
+        tool_call_id = data.get("tool_call_id")
+        if event_type == "tool_call":
+            turn.activity.observe_tool_call(tool_call_id=tool_call_id, name=name)
+        elif event_type == "tool_start":
+            turn.activity.observe_tool_start(
+                tool_call_id=tool_call_id, name=name, arguments=data.get("arguments")
+            )
+        elif event_type == "tool_end":
+            turn.activity.observe_tool_end(tool_call_id=tool_call_id, name=name)
+        elif event_type == "thinking":
+            turn.activity.observe_thinking(agent=data.get("agent", ""))
+
+        self._maybe_schedule_live_edit(turn)
+
+    def _maybe_schedule_live_edit(self, turn: _TurnDeliveryState) -> None:
+        correlation_id = turn.lifecycle_correlation_id
+        if correlation_id is None:
+            return
+        text, buttons = render_live_status_card(
+            title=turn.title,
+            elapsed_seconds=time.monotonic() - turn.started_at,
+            activity_lines=turn.activity.lines(),
+        )
+        if not self._edit_budget.should_edit(
+            connection_id=turn.connection_id, key=correlation_id, text=text
+        ):
+            return
+        self._edit_budget.record_edit(
+            connection_id=turn.connection_id, key=correlation_id, text=text
+        )
+        self._enqueue_edit(
+            destination_id=turn.destination_id,
+            text=text,
+            buttons=buttons,
+            correlation_id=correlation_id,
+        )
+```
+
+8. Discard the budget's per-turn bookkeeping wherever a turn's state is torn down — `clear_turn` and `_finalize_turn`:
+
+```python
+    def clear_turn(self, session_id: str) -> None:
+        """Clear delivery state for a completed turn."""
+        turn = self._turns.pop(session_id, None)
+        if turn is not None:
+            self._stop_typing(turn)
+            if turn.lifecycle_correlation_id is not None:
+                self._edit_budget.discard(turn.lifecycle_correlation_id)
+```
+
+In `_finalize_turn`, right after `self._stop_typing(turn)`:
+
+```python
+        self._stop_typing(turn)
+        if turn.lifecycle_correlation_id is not None:
+            self._edit_budget.discard(turn.lifecycle_correlation_id)
+```
+
+9. Honor 429s in the edit-drain loop inside `drain_pending` — replace:
+
+```python
+            while self._pending_edits:
+                msg = self._pending_edits.pop(0)
+                try:
+                    await adapter.edit(msg)
+                except Exception as exc:
+                    logger.warning(
+                        "remote_outbound_edit_failed destination_id={} error={}",
+                        msg.destination_id,
+                        exc,
+                    )
+```
+
+with:
+
+```python
+            while self._pending_edits:
+                msg = self._pending_edits.pop(0)
+                try:
+                    await adapter.edit(msg)
+                except Exception as exc:
+                    # A 429 carries retry_after on Telegram's own exception
+                    # type; duck-typed here rather than importing
+                    # TelegramApiError, which would tie this
+                    # adapter-neutral module to one adapter's transport.
+                    error_code = getattr(exc, "error_code", None)
+                    retry_after = getattr(exc, "retry_after", None)
+                    if error_code == 429 and retry_after is not None:
+                        self._edit_budget.note_rate_limited(
+                            connection_id=str(msg.connection_id),
+                            retry_after=float(retry_after),
+                        )
+                    logger.warning(
+                        "remote_outbound_edit_failed destination_id={} error={}",
+                        msg.destination_id,
+                        exc,
+                    )
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `uv run pytest --no-cov -q tests/remote/test_outbound.py -v`
+Expected: PASS, all tests in the file green (no regressions in the ~50+ pre-existing tests).
+
+- [ ] **Step 5: Run the full remote suite, lint, and type-check**
+
+Run: `uv run pytest --no-cov -q tests/remote/ && uv run ruff check app/remote/ tests/remote/ && uv run ty check app/remote/`
+Expected: all clean.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add app/remote/outbound.py tests/remote/test_outbound.py
+git commit -m "feat(remote): wire live-mode activity observation and throttled edits (AC-56/57)"
+```
+
+---
+
+### Task 6: AC-58 — close the command-menu gap (`/settings`, `/health`, `/changes`)
+
+`_register_commands` in `app/remote/telegram/adapter.py` currently advertises `help`, `status`, `new`, `stop`, `actions`, `unpair` — missing three commands `actions.py` has dispatched since Phases 2 and 3 of the control-surface work. This is the one remaining gap in AC-58's bounded command surface.
+
+**Files:**
+- Modify: `app/remote/telegram/adapter.py`
+- Test: `tests/remote/telegram/test_adapter.py`
+
+**Interfaces:**
+- Consumes: nothing new — `_register_commands` already calls `self._client.set_commands(commands)`.
+
+- [ ] **Step 1: Write the failing test**
+
+Add to `tests/remote/telegram/test_adapter.py`, inside (or alongside) `class TestStartupSequence`:
+
+```python
+    @pytest.mark.asyncio
+    async def test_registers_exactly_the_ac58_bounded_command_set(self):
+        transport = ScriptedTransport()
+        adapter = _make_adapter(transport)
+        await _run_briefly(adapter)
+
+        _, payload = next(c for c in transport.calls if c[0] == "setMyCommands")
+        registered = [cmd["command"] for cmd in payload["commands"]]
+
+        assert registered == [
+            "help",
+            "status",
+            "new",
+            "stop",
+            "settings",
+            "health",
+            "changes",
+            "actions",
+            "unpair",
+        ]
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `uv run pytest --no-cov -q tests/remote/telegram/test_adapter.py -k ac58 -v`
+Expected: FAIL — `registered` is missing `"settings"`, `"health"`, `"changes"`.
+
+- [ ] **Step 3: Implement**
+
+In `app/remote/telegram/adapter.py`'s `_register_commands`:
+
+```python
+        commands = [
+            ("help", "What can I do here?"),
+            ("status", "What's my agent doing right now?"),
+            ("new", "Set aside this task, start a new one"),
+            ("stop", "Interrupt the agent mid-task"),
+            ("settings", "Change mode, model, agent, or response style"),
+            ("health", "Check system health"),
+            ("changes", "See this task's file changes"),
+            ("actions", "Run a workflow, project, or schedule"),
+            ("unpair", "Disconnect this phone"),
+        ]
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `uv run pytest --no-cov -q tests/remote/telegram/test_adapter.py -v`
+Expected: PASS, all tests in the file green.
+
+- [ ] **Step 5: Lint and type-check**
+
+Run: `uv run ruff check app/remote/telegram/adapter.py tests/remote/telegram/test_adapter.py && uv run ty check app/remote/telegram/adapter.py`
+Expected: both clean.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add app/remote/telegram/adapter.py tests/remote/telegram/test_adapter.py
+git commit -m "feat(remote): advertise settings/health/changes in the command menu (AC-58)"
+```
+
+---
+
+## Final verification (after all six tasks)
+
+- [ ] Run the full test suite: `uv run pytest --no-cov -q`
+- [ ] Run `uv run ruff check .`
+- [ ] Run `uv run ty check app/`
+- [ ] Merge to local `main` following this session's established pattern: check `git status --short` on the main checkout first (never overwrite unreviewed WIP), fast-forward merge, re-run the full suite on the merged result, no push.
+
+## Out of scope for this plan
+
+- **AC-53** (providers read-only listing) — this is a new, unbuilt capability (there is no provider-listing action or `/settings` "Providers" row yet), not an audit of existing code. Left for a dedicated follow-up.
+- **Phase 6 — onboarding** (AC-54's richer first-run card with Set up/Health check/Just start working buttons) — unrelated to live mode; left for its own plan.

From 2797d88779a167fd7309f891465d0f879557dfcb Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Tue, 15 Sep 2026 11:07:21 +0700
Subject: [PATCH 49/71] feat(remote): add the live-mode rolling activity window
 (AC-56)

Task 1 of documents/plans/remote-telegram-live-mode-implementation.md.
---
 app/remote/live_activity.py        | 163 +++++++++++++++++++++++++++++
 tests/remote/test_live_activity.py | 127 ++++++++++++++++++++++
 2 files changed, 290 insertions(+)
 create mode 100644 app/remote/live_activity.py
 create mode 100644 tests/remote/test_live_activity.py

diff --git a/app/remote/live_activity.py b/app/remote/live_activity.py
new file mode 100644
index 00000000..53bd195f
--- /dev/null
+++ b/app/remote/live_activity.py
@@ -0,0 +1,163 @@
+"""Rolling activity window for live-mode status cards (AC-56).
+
+Bounded, in-memory, per-turn bookkeeping — owned by
+``outbound._TurnDeliveryState`` and discarded wherever that state already
+is (completion, error, interrupt, adapter shutdown, unpairing; see that
+module's docstring). Pure: no asyncio, no adapter, no database, so this
+module is trivially unit-testable and safe to call from the synchronous
+``RemoteProjection.observe`` path.
+
+Entries are keyed (by ``tool_call_id``, or ``"thinking:{agent}"`` for a
+thinking entry) so a tool's start/end updates the same line in place
+rather than growing the window, and the window keeps only the
+``MAX_ENTRIES`` most-recently-touched entries — a "most recent" LRU, not a
+plain append-only ring buffer, so a long-running tool call started before
+five other tools finished still tracks its own completion correctly.
+
+Argument summaries are the highest-risk text this module renders (file
+paths, command strings, occasionally secrets — see the control-surface
+spec's Permissions section), so they are redacted with the same
+``protect_outbound_text(channel="remote")`` every other rendered field in
+this feature uses, then truncated to ``MAX_ARG_SUMMARY_LENGTH``, then
+HTML-escaped — redaction first, truncation second, escaping last, so a
+truncated multi-byte escape sequence can never appear.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+
+from app.remote.formatting import escape
+
+__all__ = ["LiveActivityWindow", "MAX_ENTRIES", "MAX_ARG_SUMMARY_LENGTH"]
+
+#: The six most recent activity entries bound the block to roughly 600
+#: characters even at the 80-char argument cap, well clear of Telegram's
+#: 4096-character limit (AC-56).
+MAX_ENTRIES = 6
+MAX_ARG_SUMMARY_LENGTH = 80
+
+_PENDING_ICON = "⏳"  # ⏳ — tool_start observed, tool_end not yet
+_DONE_ICON = "\U0001f527"  # 🔧 — tool_end observed
+_THINKING_ICON = "\U0001f4ad"  # 💭
+_SKILL_ICON = "\U0001f4da"  # 📚
+
+#: Skills are not a distinct event; they are a tool call carrying
+#: ``skill_name`` in its arguments (app/agent/tools/builtin/skill.py) and
+#: are special-cased here rather than rendered as a generic tool call.
+_SKILL_TOOL_NAME = "skill"
+
+
+def _redact(text: str) -> str:
+    """Best-effort outbound redaction — mirrors outbound.py's own
+    ``_redact_text`` (kept independent per this module's "no dependency on
+    app.remote state" purity goal; both wrap the same protection call)."""
+    try:
+        from app.agent.outbound_redaction import OutboundContext, protect_outbound_text
+
+        protected, _report = protect_outbound_text(
+            text, context=OutboundContext(channel="remote")
+        )
+        return protected
+    except Exception:
+        return text
+
+
+def _summarize_arguments(arguments: str | None) -> str:
+    """A short, redacted, truncated rendering of a tool's JSON arguments.
+
+    Single-key argument dicts (the common case — ``{"path": ...}``,
+    ``{"pattern": ...}``, ``{"command": ...}``) render as just that value,
+    matching the spec's mockup (``grep "def test_auth"``, not
+    ``grep {"pattern": "def test_auth"}``). Anything else falls back to a
+    space-joined dump of the values. Malformed JSON renders as the raw
+    string rather than raising — a live-mode line is decoration, never
+    worth failing a turn over.
+    """
+    if not arguments:
+        return ""
+    try:
+        parsed = json.loads(arguments)
+    except (json.JSONDecodeError, TypeError):
+        raw = arguments
+    else:
+        if isinstance(parsed, dict) and parsed:
+            raw = " ".join(str(v) for v in parsed.values())
+        elif isinstance(parsed, dict):
+            raw = ""
+        else:
+            raw = str(parsed)
+
+    raw = _redact(raw)
+    if len(raw) > MAX_ARG_SUMMARY_LENGTH:
+        raw = raw[: MAX_ARG_SUMMARY_LENGTH - 1] + "…"
+    return escape(raw)
+
+
+def _extract_skill_name(arguments: str | None) -> str | None:
+    if not arguments:
+        return None
+    try:
+        parsed = json.loads(arguments)
+    except (json.JSONDecodeError, TypeError):
+        return None
+    if not isinstance(parsed, dict):
+        return None
+    name = parsed.get("skill_name")
+    return name if isinstance(name, str) and name else None
+
+
+@dataclass
+class LiveActivityWindow:
+    """A bounded rolling window of live-mode activity lines (AC-56)."""
+
+    _order: list[str] = field(default_factory=list)  # keys, oldest-touched first
+    _rendered: dict[str, str] = field(default_factory=dict)  # key -> full line
+
+    def _touch(self, key: str, line: str) -> None:
+        if key in self._rendered:
+            self._order.remove(key)
+        self._order.append(key)
+        self._rendered[key] = line
+        while len(self._order) > MAX_ENTRIES:
+            oldest = self._order.pop(0)
+            self._rendered.pop(oldest, None)
+
+    def observe_tool_call(self, *, tool_call_id: str | None, name: str) -> None:
+        if name == _SKILL_TOOL_NAME:
+            return  # rendered richly once tool_start's arguments arrive
+        key = tool_call_id or f"anon:{name}"
+        self._touch(key, f"{_PENDING_ICON} {escape(name)}")
+
+    def observe_tool_start(
+        self, *, tool_call_id: str | None, name: str, arguments: str | None
+    ) -> None:
+        key = tool_call_id or f"anon:{name}"
+        if name == _SKILL_TOOL_NAME:
+            skill_name = _extract_skill_name(arguments)
+            if skill_name:
+                self._touch(key, f"{_SKILL_ICON} Skill: {escape(skill_name)}")
+                return
+        summary = _summarize_arguments(arguments)
+        line = f"{_PENDING_ICON} {escape(name)}"
+        if summary:
+            line += f"   {summary}"
+        self._touch(key, line)
+
+    def observe_tool_end(self, *, tool_call_id: str | None, name: str) -> None:
+        key = tool_call_id or f"anon:{name}"
+        existing = self._rendered.get(key)
+        if existing is not None and existing.startswith(_PENDING_ICON):
+            self._touch(key, _DONE_ICON + existing[len(_PENDING_ICON) :])
+        elif existing is None:
+            self._touch(key, f"{_DONE_ICON} {escape(name)}")
+        else:
+            self._touch(key, existing)  # already done or a skill card; just re-touch
+
+    def observe_thinking(self, *, agent: str) -> None:
+        key = f"thinking:{agent}"
+        self._touch(key, f"{escape(agent)} · {_THINKING_ICON} thinking")
+
+    def lines(self) -> list[str]:
+        return [self._rendered[key] for key in self._order]
diff --git a/tests/remote/test_live_activity.py b/tests/remote/test_live_activity.py
new file mode 100644
index 00000000..e896f83f
--- /dev/null
+++ b/tests/remote/test_live_activity.py
@@ -0,0 +1,127 @@
+"""Tests for app/remote/live_activity.py — the rolling activity window (AC-56)."""
+
+from __future__ import annotations
+
+from app.remote.live_activity import MAX_ENTRIES, LiveActivityWindow
+
+
+def test_tool_start_renders_name_and_argument_summary() -> None:
+    window = LiveActivityWindow()
+    window.observe_tool_start(
+        tool_call_id="call-1", name="read", arguments='{"path": "tests/test_auth.py"}'
+    )
+
+    lines = window.lines()
+
+    assert len(lines) == 1
+    assert "read" in lines[0]
+    assert "tests/test_auth.py" in lines[0]
+
+
+def test_tool_start_truncates_argument_summary_to_80_chars() -> None:
+    window = LiveActivityWindow()
+    long_value = "x" * 200
+    window.observe_tool_start(
+        tool_call_id="call-1", name="shell", arguments=f'{{"command": "{long_value}"}}'
+    )
+
+    lines = window.lines()
+
+    assert len(lines) == 1
+    # Icon + tool name + separator are not part of the 80-char argument
+    # budget, so assert on the tail (the argument summary itself) rather
+    # than the whole line's length.
+    assert "x" * 81 not in lines[0]
+    assert "…" in lines[0]  # ellipsis marks the truncation
+
+
+def test_tool_end_updates_the_same_entry_in_place() -> None:
+    window = LiveActivityWindow()
+    window.observe_tool_start(tool_call_id="call-1", name="grep", arguments="{}")
+    window.observe_tool_end(tool_call_id="call-1", name="grep")
+
+    lines = window.lines()
+
+    assert len(lines) == 1  # no duplicate entry from tool_end
+
+
+def test_tool_end_flips_the_icon_from_pending_to_done() -> None:
+    window = LiveActivityWindow()
+    window.observe_tool_start(tool_call_id="call-1", name="grep", arguments="{}")
+    pending_line = window.lines()[0]
+    window.observe_tool_end(tool_call_id="call-1", name="grep")
+    done_line = window.lines()[0]
+
+    assert pending_line != done_line
+
+
+def test_skill_tool_call_renders_the_skill_name_not_the_raw_tool_name() -> None:
+    window = LiveActivityWindow()
+    window.observe_tool_start(
+        tool_call_id="call-1",
+        name="skill",
+        arguments='{"action": "load", "skill_name": "test-driven-development"}',
+    )
+
+    lines = window.lines()
+
+    assert len(lines) == 1
+    assert "test-driven-development" in lines[0]
+    assert "skill" not in lines[0].lower() or "Skill:" in lines[0]
+
+
+def test_thinking_entry_names_the_active_agent() -> None:
+    window = LiveActivityWindow()
+    window.observe_thinking(agent="explorer")
+
+    lines = window.lines()
+
+    assert len(lines) == 1
+    assert "explorer" in lines[0]
+
+
+def test_window_caps_at_six_most_recently_touched_entries() -> None:
+    window = LiveActivityWindow()
+    for i in range(9):
+        window.observe_tool_start(
+            tool_call_id=f"call-{i}", name=f"tool{i}", arguments="{}"
+        )
+
+    lines = window.lines()
+
+    assert len(lines) == MAX_ENTRIES
+    # The three oldest calls (0, 1, 2) were evicted; the six most recent remain.
+    assert "tool0" not in "\n".join(lines)
+    assert "tool8" in "\n".join(lines)
+
+
+def test_argument_summary_is_html_escaped() -> None:
+    window = LiveActivityWindow()
+    window.observe_tool_start(
+        tool_call_id="call-1", name="grep", arguments='{"pattern": "", elapsed_seconds=1.0, activity_lines=[]
+    )
+    assert "" not in text
+    assert "<script>" in text
+
+
+def test_render_live_status_card_with_no_activity_yet_still_renders() -> None:
+    text, buttons = formatting.render_live_status_card(
+        title="New task", elapsed_seconds=0.5, activity_lines=[]
+    )
+    assert "New task" in text
+    assert buttons == ()
+
+
 def test_render_error_card_escapes_message():
     text, buttons = formatting.render_error_card(
         title="Add rate limiter",

From bf6d63bd27cc21056c5d86120ab67b4be9e7872b Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Tue, 15 Sep 2026 11:13:13 +0700
Subject: [PATCH 52/71] feat(remote): thread response_mode from the pairing
 into each new turn (AC-55/56)

Task 4 of documents/plans/remote-telegram-live-mode-implementation.md.
RemoteInboundResult now carries the pairing's response_mode (captured
before handle_text's mid-turn rollback expires the ORM instance), and
runtime.py passes it into begin_phone_turn.
---
 app/remote/inbound.py        |  7 +++++
 app/remote/runtime.py        |  1 +
 tests/remote/test_inbound.py | 55 ++++++++++++++++++++++++++++++++++++
 3 files changed, 63 insertions(+)

diff --git a/app/remote/inbound.py b/app/remote/inbound.py
index 8697908f..4385e0c0 100644
--- a/app/remote/inbound.py
+++ b/app/remote/inbound.py
@@ -29,6 +29,7 @@ class RemoteInboundResult:
     status: str
     session_id: UUID | None = None
     message_id: UUID | None = None
+    response_mode: str = "summary"
 
 
 class RemoteInboundService:
@@ -57,6 +58,11 @@ async def handle_text(
             pairing = await db.get(RemotePairing, pairing.id)
             if pairing is None:
                 return RemoteInboundResult(status="unauthorized")
+            # Captured now, before the rollback below expires every ORM
+            # instance in this session — accessing pairing.response_mode
+            # after that would need a lazy reload, which the async ORM
+            # cannot do implicitly.
+            response_mode = pairing.response_mode
             session = await self._current_session(db, pairing)
             if session is None:
                 session = await self._create_work_session(db, pairing, action)
@@ -93,6 +99,7 @@ async def handle_text(
             status=result.status,
             session_id=UUID(result.session_id),
             message_id=result.message_id,
+            response_mode=response_mode,
         )
 
     async def new_task(
diff --git a/app/remote/runtime.py b/app/remote/runtime.py
index ac7ffc92..5f2b77de 100644
--- a/app/remote/runtime.py
+++ b/app/remote/runtime.py
@@ -555,6 +555,7 @@ async def _handle_text(self, action: RemoteInboundAction) -> None:
                     else "New task"
                 ),
                 status=result.status,
+                response_mode=result.response_mode,
             )
 
 
diff --git a/tests/remote/test_inbound.py b/tests/remote/test_inbound.py
index 9944a60a..e765bd07 100644
--- a/tests/remote/test_inbound.py
+++ b/tests/remote/test_inbound.py
@@ -55,6 +55,61 @@ async def _paired_text_action(db, text: str = "Plan my next task"):
     )
 
 
+@pytest.mark.asyncio
+async def test_handle_text_result_defaults_to_summary_response_mode(monkeypatch):
+    from app.remote.inbound import RemoteInboundService
+    import app.remote.inbound as inbound
+
+    async with db_module.async_session_factory() as db:
+        pairing, action = await _paired_text_action(db)
+        team = SimpleNamespace()
+
+        async def resolve(db, session_id: str, *, require_existing: bool):
+            session = await db.get(ChatSession, UUID(session_id))
+            return session, team
+
+        submit = AsyncMock(
+            side_effect=lambda db, *, session, **_kwargs: InteractiveMessageResult(
+                status="accepted", session_id=str(session.id), message_id=None
+            )
+        )
+        monkeypatch.setattr(inbound, "resolve_team_for_session", resolve)
+        monkeypatch.setattr(inbound, "submit_persisted_interactive_message", submit)
+
+        result = await RemoteInboundService().handle_text(db, action)
+
+        assert result.response_mode == "summary"
+
+
+@pytest.mark.asyncio
+async def test_handle_text_result_carries_a_live_response_mode(monkeypatch):
+    from app.remote.inbound import RemoteInboundService
+    import app.remote.inbound as inbound
+
+    async with db_module.async_session_factory() as db:
+        pairing, action = await _paired_text_action(db)
+        pairing.response_mode = "live"
+        db.add(pairing)
+        await db.commit()
+        team = SimpleNamespace()
+
+        async def resolve(db, session_id: str, *, require_existing: bool):
+            session = await db.get(ChatSession, UUID(session_id))
+            return session, team
+
+        submit = AsyncMock(
+            side_effect=lambda db, *, session, **_kwargs: InteractiveMessageResult(
+                status="accepted", session_id=str(session.id), message_id=None
+            )
+        )
+        monkeypatch.setattr(inbound, "resolve_team_for_session", resolve)
+        monkeypatch.setattr(inbound, "submit_persisted_interactive_message", submit)
+
+        result = await RemoteInboundService().handle_text(db, action)
+
+        assert result.response_mode == "live"
+
+
 @pytest.mark.asyncio
 async def test_handle_text_creates_and_selects_a_top_level_work_task(monkeypatch):
     """Removing remote provenance or pointer persistence must fail this test."""

From 14a52d5c0487225adf5eb153a831da0b231b62ce Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Tue, 15 Sep 2026 11:13:19 +0700
Subject: [PATCH 53/71] feat(remote): wire live-mode activity observation and
 throttled edits (AC-56/57)

Task 5 of documents/plans/remote-telegram-live-mode-implementation.md.
observe() now feeds tool_call/tool_start/tool_end/thinking into each
live-mode turn's LiveActivityWindow and schedules a throttled, budgeted
status-card edit via the new shared EditBudget; summary-mode turns are
unaffected (AC-20 regression guard). A turn's final done/error card
always bypasses the budget, and a Telegram 429 degrades that
connection's cadence via retry_after.
---
 app/remote/outbound.py        | 123 ++++++++++++++++++++---
 tests/remote/test_outbound.py | 178 ++++++++++++++++++++++++++++++++++
 2 files changed, 290 insertions(+), 11 deletions(-)

diff --git a/app/remote/outbound.py b/app/remote/outbound.py
index 7b9234b1..f0c4cbba 100644
--- a/app/remote/outbound.py
+++ b/app/remote/outbound.py
@@ -36,11 +36,14 @@
     RemoteOutboundMessage,
     RemoteOutboundPriority,
 )
+from app.remote.edit_budget import EditBudget
 from app.remote.formatting import (
     render_done_card,
     render_error_card,
+    render_live_status_card,
     render_status_card,
 )
+from app.remote.live_activity import LiveActivityWindow
 from app.remote.turn_activity import load_turn_activity
 
 if TYPE_CHECKING:
@@ -65,18 +68,27 @@ def register_capability(
 #: Telegram's maximum message length in characters.
 _TELEGRAM_MAX_MESSAGE_LENGTH = 4096
 
+#: Live-mode-only events (AC-56) — only handled for a turn whose cached
+#: response_mode is "live"; the check happens in ``observe`` itself
+#: (in-memory, synchronous — no I/O), never before it, since ``observe``
+#: has no other reason to look at a turn's mode.
+_ACTIVITY_EVENT_TYPES = frozenset({"tool_call", "tool_start", "tool_end", "thinking"})
+
 #: Events the remote projection forwards to the phone.
-_OBSERVED_EVENT_TYPES = frozenset(
-    {
-        "done",
-        "error",
-        "permission_asked",
-        "question_asked",
-        "plan_approval_requested",
-        "permission_replied",
-        "question_replied",
-        "plan_approval_replied",
-    }
+_OBSERVED_EVENT_TYPES = (
+    frozenset(
+        {
+            "done",
+            "error",
+            "permission_asked",
+            "question_asked",
+            "plan_approval_requested",
+            "permission_replied",
+            "question_replied",
+            "plan_approval_replied",
+        }
+    )
+    | _ACTIVITY_EVENT_TYPES
 )
 
 
@@ -102,6 +114,15 @@ class _TurnDeliveryState:
     typing_task: "asyncio.Task[None] | None" = field(default=None, repr=False)
     title: str = ""
     principal_id: str = ""
+    #: "summary" (default) or "live" — read fresh from the pairing at the
+    #: start of every phone-admitted turn (never cached across turns), so
+    #: AC-55's "no restart needed" holds. Desktop-started turns (no
+    #: begin_phone_turn call) stay at the default; only a phone-admitted
+    #: turn can be live, since only it owns an editable status card.
+    response_mode: str = "summary"
+    #: The rolling activity window this turn renders into while live —
+    #: unused and empty in summary mode.
+    activity: LiveActivityWindow = field(default_factory=LiveActivityWindow)
 
 
 @dataclass
@@ -174,6 +195,10 @@ class RemoteProjection:
     #: connection regardless of which surface (phone or desktop) started the
     #: work being notified about.
     _active_pairing: tuple[str, str, str, str] | None = field(default=None, repr=False)
+    #: Shared across every live turn on this connection (AC-57) — see
+    #: app/remote/edit_budget.py's own docstring for why the throttle is
+    #: connection-scoped rather than per-turn.
+    _edit_budget: EditBudget = field(default_factory=EditBudget, repr=False)
 
     def set_adapter(self, adapter: RemoteAdapter | None) -> None:
         """Bind or unbind the live adapter. Called by the runtime on start/stop.
@@ -258,6 +283,7 @@ def begin_phone_turn(
         principal_id: str,
         title: str,
         status: str,
+        response_mode: str = "summary",
     ) -> None:
         """Create the one status message a phone-admitted turn owns, and
         start the native typing indicator alongside it. Called by
@@ -302,6 +328,7 @@ def begin_phone_turn(
             lifecycle_correlation_id=correlation_id,
             phone_admitted=True,
             title=title,
+            response_mode=response_mode,
         )
         self._turns[session_id] = turn
         text, buttons = render_status_card(title=title, status=status)
@@ -432,6 +459,10 @@ def observe(self, session_id: str, envelope) -> None:
             )
             self._turns[session_id] = turn
 
+        if event_type in _ACTIVITY_EVENT_TYPES:
+            self._handle_activity(turn, event_type, envelope)
+            return
+
         if event_type == "done":
             self._handle_done(turn, envelope)
         elif event_type == "error":
@@ -503,6 +534,8 @@ async def _finalize_turn(
         from app.core.db import async_session_factory
 
         self._stop_typing(turn)
+        if turn.lifecycle_correlation_id is not None:
+            self._edit_budget.discard(turn.lifecycle_correlation_id)
         elapsed = time.monotonic() - turn.started_at
         async with async_session_factory() as db:
             activity = await load_turn_activity(
@@ -583,6 +616,61 @@ async def _finalize_turn(
                 priority=RemoteOutboundPriority.HIGH,
             )
 
+    def _handle_activity(
+        self, turn: _TurnDeliveryState, event_type: str, envelope
+    ) -> None:
+        """Feed one tool/thinking event into *turn*'s activity window and,
+        if this is a live phone-admitted turn, enqueue a throttled edit.
+
+        A turn whose final card has already been queued
+        (``completion_sent``) ignores further activity — the card is
+        about to be overwritten by the done/error card regardless."""
+        if (
+            not turn.phone_admitted
+            or turn.response_mode != "live"
+            or turn.completion_sent
+        ):
+            return
+
+        data = envelope.data
+        name = data.get("name", "")
+        tool_call_id = data.get("tool_call_id")
+        if event_type == "tool_call":
+            turn.activity.observe_tool_call(tool_call_id=tool_call_id, name=name)
+        elif event_type == "tool_start":
+            turn.activity.observe_tool_start(
+                tool_call_id=tool_call_id, name=name, arguments=data.get("arguments")
+            )
+        elif event_type == "tool_end":
+            turn.activity.observe_tool_end(tool_call_id=tool_call_id, name=name)
+        elif event_type == "thinking":
+            turn.activity.observe_thinking(agent=data.get("agent", ""))
+
+        self._maybe_schedule_live_edit(turn)
+
+    def _maybe_schedule_live_edit(self, turn: _TurnDeliveryState) -> None:
+        correlation_id = turn.lifecycle_correlation_id
+        if correlation_id is None:
+            return
+        text, buttons = render_live_status_card(
+            title=turn.title,
+            elapsed_seconds=time.monotonic() - turn.started_at,
+            activity_lines=turn.activity.lines(),
+        )
+        if not self._edit_budget.should_edit(
+            connection_id=turn.connection_id, key=correlation_id, text=text
+        ):
+            return
+        self._edit_budget.record_edit(
+            connection_id=turn.connection_id, key=correlation_id, text=text
+        )
+        self._enqueue_edit(
+            destination_id=turn.destination_id,
+            text=text,
+            buttons=buttons,
+            correlation_id=correlation_id,
+        )
+
     def _handle_gate(self, turn: _TurnDeliveryState, event_type: str, envelope) -> None:
         data = envelope.data
         if self._bridge is not None:
@@ -749,6 +837,17 @@ async def drain_pending(self) -> None:
                 try:
                     await adapter.edit(msg)
                 except Exception as exc:
+                    # A 429 carries retry_after on Telegram's own exception
+                    # type; duck-typed here rather than importing
+                    # TelegramApiError, which would tie this
+                    # adapter-neutral module to one adapter's transport.
+                    error_code = getattr(exc, "error_code", None)
+                    retry_after = getattr(exc, "retry_after", None)
+                    if error_code == 429 and retry_after is not None:
+                        self._edit_budget.note_rate_limited(
+                            connection_id=str(msg.connection_id),
+                            retry_after=float(retry_after),
+                        )
                     logger.warning(
                         "remote_outbound_edit_failed destination_id={} error={}",
                         msg.destination_id,
@@ -825,6 +924,8 @@ def clear_turn(self, session_id: str) -> None:
         turn = self._turns.pop(session_id, None)
         if turn is not None:
             self._stop_typing(turn)
+            if turn.lifecycle_correlation_id is not None:
+                self._edit_budget.discard(turn.lifecycle_correlation_id)
 
 
 def _redact_text(text: str) -> str:
diff --git a/tests/remote/test_outbound.py b/tests/remote/test_outbound.py
index 6656f6ac..2f1e610c 100644
--- a/tests/remote/test_outbound.py
+++ b/tests/remote/test_outbound.py
@@ -1086,3 +1086,181 @@ def test_split_text_preserves_unicode() -> None:
     assert len(chunks[1]) == 904
     for chunk in chunks:
         chunk.encode("utf-8")
+
+
+# ---------------------------------------------------------------------------
+# Live mode (AC-56/AC-57)
+# ---------------------------------------------------------------------------
+
+
+class TestLiveMode:
+    @pytest.mark.asyncio
+    async def test_summary_mode_never_renders_activity_even_when_tool_events_flow(
+        self,
+    ) -> None:
+        """AC-20 regression guard: response_mode="summary" (the default)
+        must behave exactly as it did before this feature existed."""
+        adapter = FakeAdapter()
+        projection = RemoteProjection()
+        projection.set_adapter(adapter)
+        session_id = str(uuid4())
+        connection_id = str(uuid4())  # must be a real UUID string — _enqueue_edit/
+        # _enqueue_send both do UUID(connection_id) before handing a message to the
+        # adapter, matching every other test in this file.
+        projection.register_session(
+            session_id,
+            connection_id=connection_id,
+            destination_id="chat-1",
+            tags=frozenset({"remote_origin"}),
+        )
+        projection.begin_phone_turn(
+            session_id,
+            connection_id=connection_id,
+            destination_id="chat-1",
+            principal_id="user-1",
+            title="Task",
+            status="accepted",
+        )
+        await projection.drain_pending()
+        edits_before = len(adapter.edited)
+
+        projection.observe(
+            session_id,
+            _envelope(
+                "tool_start",
+                agent="explorer",
+                tool_call_id="call-1",
+                name="grep",
+                arguments="{}",
+            ),
+        )
+        await projection.drain_pending()
+
+        assert len(adapter.edited) == edits_before  # no live edit was sent
+
+    @pytest.mark.asyncio
+    async def test_live_mode_edits_the_status_card_with_activity(self) -> None:
+        adapter = FakeAdapter()
+        projection = RemoteProjection()
+        projection.set_adapter(adapter)
+        session_id = str(uuid4())
+        connection_id = str(uuid4())
+        projection.register_session(
+            session_id,
+            connection_id=connection_id,
+            destination_id="chat-1",
+            tags=frozenset({"remote_origin"}),
+        )
+        projection.begin_phone_turn(
+            session_id,
+            connection_id=connection_id,
+            destination_id="chat-1",
+            principal_id="user-1",
+            title="Task",
+            status="accepted",
+            response_mode="live",
+        )
+        await projection.drain_pending()
+
+        projection.observe(
+            session_id,
+            _envelope(
+                "tool_start",
+                agent="explorer",
+                tool_call_id="call-1",
+                name="grep",
+                arguments='{"pattern": "def test_auth"}',
+            ),
+        )
+        await projection.drain_pending()
+
+        assert len(adapter.edited) == 1
+        assert "grep" in adapter.edited[-1].text
+        assert "def test_auth" in adapter.edited[-1].text
+
+    @pytest.mark.asyncio
+    async def test_live_mode_throttles_a_second_edit_within_the_interval(self) -> None:
+        adapter = FakeAdapter()
+        projection = RemoteProjection()
+        projection.set_adapter(adapter)
+        session_id = str(uuid4())
+        connection_id = str(uuid4())
+        projection.register_session(
+            session_id,
+            connection_id=connection_id,
+            destination_id="chat-1",
+            tags=frozenset({"remote_origin"}),
+        )
+        projection.begin_phone_turn(
+            session_id,
+            connection_id=connection_id,
+            destination_id="chat-1",
+            principal_id="user-1",
+            title="Task",
+            status="accepted",
+            response_mode="live",
+        )
+        await projection.drain_pending()
+
+        projection.observe(
+            session_id,
+            _envelope(
+                "tool_start", agent="explorer", tool_call_id="call-1", name="grep",
+                arguments="{}",
+            ),
+        )
+        await projection.drain_pending()
+        projection.observe(
+            session_id,
+            _envelope(
+                "tool_start", agent="explorer", tool_call_id="call-2", name="read",
+                arguments="{}",
+            ),
+        )
+        await projection.drain_pending()
+
+        # Both tool_start events fire well within LIVE_EDIT_INTERVAL of each
+        # other in real wall-clock terms (this test runs in milliseconds),
+        # so only the first produced an edit.
+        assert len(adapter.edited) == 1
+
+    @pytest.mark.asyncio
+    async def test_final_card_is_not_starved_by_the_live_edit_budget(self) -> None:
+        """A turn's final done card must always be delivered even if the
+        edit budget is currently exhausted from live-activity updates."""
+        adapter = FakeAdapter()
+        projection = RemoteProjection()
+        projection.set_adapter(adapter)
+        session_id = str(uuid4())
+        connection_id = str(uuid4())
+        projection.register_session(
+            session_id,
+            connection_id=connection_id,
+            destination_id="chat-1",
+            tags=frozenset({"remote_origin"}),
+        )
+        projection.begin_phone_turn(
+            session_id,
+            connection_id=connection_id,
+            destination_id="chat-1",
+            principal_id="user-1",
+            title="Task",
+            status="accepted",
+            response_mode="live",
+        )
+        await projection.drain_pending()
+
+        projection.observe(
+            session_id,
+            _envelope(
+                "tool_start", agent="explorer", tool_call_id="call-1", name="grep",
+                arguments="{}",
+            ),
+        )
+        await projection.drain_pending()
+        edits_after_activity = len(adapter.edited)
+
+        projection.observe(session_id, _envelope("done"))
+        await projection.drain_pending()
+
+        assert len(adapter.edited) == edits_after_activity + 1  # the done card landed

From 80262ad8966b08e4835d55973d0166d74da860ce Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Tue, 15 Sep 2026 11:14:03 +0700
Subject: [PATCH 54/71] feat(remote): advertise settings/health/changes in the
 command menu (AC-58)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Task 6 of documents/plans/remote-telegram-live-mode-implementation.md.
Closes the last gap in the bounded command surface — /settings, /health,
and /changes have been dispatchable since earlier phases but were never
added to Telegram's native "/" command menu.
---
 app/remote/telegram/adapter.py        |  3 +++
 tests/remote/telegram/test_adapter.py | 21 +++++++++++++++++++++
 2 files changed, 24 insertions(+)

diff --git a/app/remote/telegram/adapter.py b/app/remote/telegram/adapter.py
index ff71c15d..5d0b5b62 100644
--- a/app/remote/telegram/adapter.py
+++ b/app/remote/telegram/adapter.py
@@ -326,6 +326,9 @@ async def _register_commands(self) -> None:
             ("status", "What's my agent doing right now?"),
             ("new", "Set aside this task, start a new one"),
             ("stop", "Interrupt the agent mid-task"),
+            ("settings", "Change mode, model, agent, or response style"),
+            ("health", "Check system health"),
+            ("changes", "See this task's file changes"),
             ("actions", "Run a workflow, project, or schedule"),
             ("unpair", "Disconnect this phone"),
         ]
diff --git a/tests/remote/telegram/test_adapter.py b/tests/remote/telegram/test_adapter.py
index e11dbcbc..486cd7fa 100644
--- a/tests/remote/telegram/test_adapter.py
+++ b/tests/remote/telegram/test_adapter.py
@@ -153,6 +153,27 @@ async def test_deletes_webhook_with_drop_pending_updates_before_first_poll(self)
         _, payload = next(c for c in transport.calls if c[0] == "deleteWebhook")
         assert payload["drop_pending_updates"] is True
 
+    @pytest.mark.asyncio
+    async def test_registers_exactly_the_ac58_bounded_command_set(self):
+        transport = ScriptedTransport()
+        adapter = _make_adapter(transport)
+        await _run_briefly(adapter)
+
+        _, payload = next(c for c in transport.calls if c[0] == "setMyCommands")
+        registered = [cmd["command"] for cmd in payload["commands"]]
+
+        assert registered == [
+            "help",
+            "status",
+            "new",
+            "stop",
+            "settings",
+            "health",
+            "changes",
+            "actions",
+            "unpair",
+        ]
+
     @pytest.mark.asyncio
     async def test_requests_only_message_and_callback_query_updates(self):
         transport = ScriptedTransport()

From d5a5a5e76bbb12624b8788ce021afc26ff6c72ec Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Tue, 15 Sep 2026 11:57:55 +0700
Subject: [PATCH 55/71] docs(remote): add AC-53 (providers read-only)
 implementation plan

---
 ...emote-telegram-providers-implementation.md | 406 ++++++++++++++++++
 1 file changed, 406 insertions(+)
 create mode 100644 documents/plans/remote-telegram-providers-implementation.md

diff --git a/documents/plans/remote-telegram-providers-implementation.md b/documents/plans/remote-telegram-providers-implementation.md
new file mode 100644
index 00000000..7db27ae5
--- /dev/null
+++ b/documents/plans/remote-telegram-providers-implementation.md
@@ -0,0 +1,406 @@
+# Remote Telegram Providers (Read-Only) Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Implement AC-53 — `/settings` shows how many providers are configured, and no remote code path can ever reach a credential-accepting provider endpoint.
+
+**Architecture:** One new read-only aggregation in `control.py` (`count_configured_providers`) calling the existing `GET /api/settings/providers` route function directly — the third documented, deliberate exception to "service layer only" in this module (after the model catalog and health/diff). `render_settings_card` grows an optional `configured_provider_count` line. The AC's real weight is the inspection test: a static scan proving `app/remote/` never references any of the five write-capable provider functions (`save_provider`, `save_provider_visible_models`, `test_provider`, `list_provider_models`, `delete_provider`).
+
+**Scope note:** The control-surface spec's mockup shows a `[ Providers ]` button opening a picker. Providers are read-only in this feature (no pick to make), so this plan implements the count line only — the load-bearing part of AC-53 per the spec's own Permissions section ("Provider read-only is enforced by inspection test rather than by convention") is the inspection test, not a richer display. A drill-down listing configured providers by name, or per-provider usage (AC references "usage"), is left for a follow-up if wanted.
+
+**Tech Stack:** Python 3.12, pytest + pytest-asyncio, `ruff`, `ty`.
+
+**Spec:** `documents/plans/remote-telegram-control-surface.md`, AC-53.
+
+## Global Constraints
+
+- No remote code path may import or call `save_provider`, `save_provider_visible_models`, `test_provider`, `list_provider_models`, or `delete_provider` (all in `app/api/routes/settings.py`) — proven by a static inspection test, not by convention.
+- `count_configured_providers()` calls `app.api.routes.settings.list_providers()` directly (no `Depends`-injected state, matching the two existing departures already documented in `control.py`'s module docstring) and counts `is_configured` — it must never trigger a second call per `/settings` render beyond what that route already does internally (result caching is that route's own concern, already in place for daemon/model-discovery probes).
+
+---
+
+### Task 1: `control.py` — `count_configured_providers`
+
+**Files:**
+- Modify: `app/remote/control.py`
+- Test: `tests/remote/test_control.py`
+
+**Interfaces:**
+- Produces: `async def count_configured_providers() -> int`.
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `tests/remote/test_control.py`:
+
+```python
+@pytest.mark.asyncio
+async def test_count_configured_providers_counts_only_configured_ones(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    from app.api.schemas.settings import ProviderInfo, ProvidersListBody
+
+    def _entry(id_: str, *, is_configured: bool) -> ProviderInfo:
+        return ProviderInfo(
+            id=id_,
+            label=id_,
+            description="",
+            kind="api_key",
+            is_configured=is_configured,
+        )
+
+    async def _fake_list_providers() -> ProvidersListBody:
+        return ProvidersListBody(
+            providers=[
+                _entry("openai", is_configured=True),
+                _entry("anthropic", is_configured=True),
+                _entry("mistral", is_configured=False),
+            ]
+        )
+
+    monkeypatch.setattr(
+        "app.api.routes.settings.list_providers", _fake_list_providers
+    )
+
+    count = await control.count_configured_providers()
+
+    assert count == 2
+
+
+@pytest.mark.asyncio
+async def test_count_configured_providers_is_zero_with_none_configured(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    from app.api.schemas.settings import ProvidersListBody
+
+    async def _fake_list_providers() -> ProvidersListBody:
+        return ProvidersListBody(providers=[])
+
+    monkeypatch.setattr(
+        "app.api.routes.settings.list_providers", _fake_list_providers
+    )
+
+    count = await control.count_configured_providers()
+
+    assert count == 0
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `uv run pytest --no-cov -q tests/remote/test_control.py -k configured_providers -v`
+Expected: FAIL with `AttributeError: module 'app.remote.control' has no attribute 'count_configured_providers'`.
+
+- [ ] **Step 3: Implement**
+
+Add to `control.py`'s `__all__` and body:
+
+```python
+async def count_configured_providers() -> int:
+    """How many catalog providers currently have usable credentials —
+    the one number `/settings` shows for AC-53. Calls the same route
+    function the desktop Settings screen uses (see this module's
+    docstring for why app/remote/ makes this exception) rather than
+    reimplementing the static-credential/daemon-reachability checks
+    GET /api/settings/providers already performs."""
+    from app.api.routes.settings import list_providers
+
+    result = await list_providers()
+    return sum(1 for provider in result.providers if provider.is_configured)
+```
+
+And extend the module docstring's exception list with this third departure, and add `"count_configured_providers"` to `__all__`.
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `uv run pytest --no-cov -q tests/remote/test_control.py -v`
+Expected: PASS, all tests in the file green.
+
+- [ ] **Step 5: Lint and type-check**
+
+Run: `uv run ruff check app/remote/control.py tests/remote/test_control.py && uv run ty check app/remote/control.py`
+Expected: both clean.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add app/remote/control.py tests/remote/test_control.py
+git commit -m "feat(remote): count configured providers for /settings (AC-53)"
+```
+
+---
+
+### Task 2: `render_settings_card` gains the Providers line
+
+**Files:**
+- Modify: `app/remote/formatting.py`
+- Test: `tests/remote/test_formatting.py`
+
+**Interfaces:**
+- Produces: `render_settings_card(..., configured_provider_count: int | None = None)` — when given, adds a `"Providers"` line right after `"Responses"`; `None` omits the line entirely (same optional-section pattern already used for `redaction_policy`/`notify_scope`).
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `tests/remote/test_formatting.py`:
+
+```python
+def test_render_settings_card_shows_configured_provider_count() -> None:
+    text, _ = formatting.render_settings_card(
+        connection_label="evoflux-api",
+        model="claude-sonnet-5",
+        permission_mode="ask",
+        agent_name="evoflux",
+        response_mode="summary",
+        response_mode_tokens={},
+        mode_tokens={},
+        agent_tokens={},
+        model_tokens={},
+        configured_provider_count=3,
+    )
+    assert "Providers" in text
+    assert "3" in text
+
+
+def test_render_settings_card_omits_providers_line_when_not_supplied() -> None:
+    text, _ = formatting.render_settings_card(
+        connection_label="evoflux-api",
+        model="claude-sonnet-5",
+        permission_mode="ask",
+        agent_name="evoflux",
+        response_mode="summary",
+        response_mode_tokens={},
+        mode_tokens={},
+        agent_tokens={},
+        model_tokens={},
+    )
+    assert "Providers" not in text
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `uv run pytest --no-cov -q tests/remote/test_formatting.py -k configured_provider -v`
+Expected: FAIL — `test_render_settings_card_shows_configured_provider_count` fails with `TypeError: render_settings_card() got an unexpected keyword argument 'configured_provider_count'`.
+
+- [ ] **Step 3: Implement**
+
+In `app/remote/formatting.py`'s `render_settings_card` signature, add (after `model_tokens`):
+
+```python
+    configured_provider_count: int | None = None,
+```
+
+and after the existing `"Responses"` line in `lines`:
+
+```python
+    if configured_provider_count is not None:
+        lines += [
+            "",
+            f"Providers\n{configured_provider_count} configured",
+        ]
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `uv run pytest --no-cov -q tests/remote/test_formatting.py -v`
+Expected: PASS, all tests in the file green.
+
+- [ ] **Step 5: Lint and type-check**
+
+Run: `uv run ruff check app/remote/formatting.py tests/remote/test_formatting.py && uv run ty check app/remote/formatting.py`
+Expected: both clean.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add app/remote/formatting.py tests/remote/test_formatting.py
+git commit -m "feat(remote): show configured provider count on the settings card (AC-53)"
+```
+
+---
+
+### Task 3: Wire the count into `/settings`
+
+**Files:**
+- Modify: `app/remote/actions.py`
+- Test: `tests/remote/test_actions.py`
+
+**Interfaces:**
+- Consumes: `control.count_configured_providers()` (Task 1), `render_settings_card(..., configured_provider_count=...)` (Task 2).
+
+- [ ] **Step 1: Write the failing test**
+
+Add to `TestSettings` in `tests/remote/test_actions.py`:
+
+```python
+    @pytest.mark.asyncio
+    async def test_settings_command_shows_configured_provider_count(
+        self, service: RemoteActionService, adapter: FakeAdapter
+    ) -> None:
+        async with db_module.async_session_factory() as db:
+            session = ChatSession(
+                title="Settings test",
+                mode="work",
+                session_type="main",
+                permission_mode="ask",
+            )
+            db.add(session)
+            await db.commit()
+            await db.refresh(session)
+
+            mock_pairing = MagicMock()
+            mock_pairing.id = uuid4()
+            mock_pairing.active_session_id = session.id
+            mock_pairing.label = "My Phone"
+            mock_pairing.response_mode = "summary"
+
+            with (
+                patch.object(
+                    service._pairing_service, "authorize", return_value=mock_pairing
+                ),
+                patch(
+                    "app.remote.control.count_configured_providers",
+                    new=AsyncMock(return_value=2),
+                ),
+            ):
+                settings_action = _make_action(text="/settings")
+                await service.dispatch_command(db, settings_action)
+
+            sent_text = adapter.sent_messages[-1].text
+            assert "2 configured" in sent_text
+```
+
+This needs `from unittest.mock import AsyncMock` — check the top of `tests/remote/test_actions.py`; it already imports `MagicMock, patch` from `unittest.mock`, so add `AsyncMock` to that same import line rather than a second import statement.
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `uv run pytest --no-cov -q tests/remote/test_actions.py -k configured_provider_count -v`
+Expected: FAIL — `"2 configured" not in sent_text` (the settings card is sent without a Providers line at all).
+
+- [ ] **Step 3: Implement**
+
+In `app/remote/actions.py`'s `_cmd_settings`, after the existing `model_tokens = {...}` block and before the `render_settings_card(...)` call:
+
+```python
+        configured_provider_count = await control.count_configured_providers()
+```
+
+and add `configured_provider_count=configured_provider_count,` as an argument to the `render_settings_card(...)` call (after `model_tokens=model_tokens,`).
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `uv run pytest --no-cov -q tests/remote/test_actions.py -v`
+Expected: PASS, all tests in the file green.
+
+- [ ] **Step 5: Lint and type-check**
+
+Run: `uv run ruff check app/remote/actions.py tests/remote/test_actions.py && uv run ty check app/remote/actions.py`
+Expected: both clean.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add app/remote/actions.py tests/remote/test_actions.py
+git commit -m "feat(remote): wire the configured-provider count into /settings (AC-53)"
+```
+
+---
+
+### Task 4: AC-53 inspection test — providers stay read-only
+
+**Files:**
+- Create: `tests/remote/test_ac53_providers_read_only.py`
+
+**Interfaces:**
+- Consumes: nothing new — pure static source inspection over the `app/remote/` package.
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+"""AC-53 inspection test: no remote code path may reach a credential-
+accepting provider endpoint.
+
+A behavioral test could only prove the paths it thinks to exercise; a
+static scan proves the *absence* of a reference anywhere in the package,
+which is what AC-53 actually promises ("proven by an inspection test
+over the remote dispatch surface", not by convention or by enumerating
+every possible callback)."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+_REMOTE_PACKAGE_ROOT = Path(__file__).resolve().parents[2] / "app" / "remote"
+
+#: Every provider endpoint in app/api/routes/settings.py that accepts or
+#: mutates credentials, visibility, or existence — AC-53's "no remote
+#: path reaches PUT .../providers/{id}, POST .../test, or any other
+#: credential-accepting endpoint".
+_WRITE_CAPABLE_PROVIDER_FUNCTIONS = (
+    "save_provider",
+    "save_provider_visible_models",
+    "test_provider",
+    "list_provider_models",
+    "delete_provider",
+)
+
+
+def _remote_source_files() -> list[Path]:
+    assert _REMOTE_PACKAGE_ROOT.is_dir(), _REMOTE_PACKAGE_ROOT
+    return list(_REMOTE_PACKAGE_ROOT.rglob("*.py"))
+
+
+def test_no_remote_source_file_references_a_write_capable_provider_function() -> None:
+    files = _remote_source_files()
+    assert len(files) > 10  # sanity: the glob actually found the package
+
+    offenders: list[str] = []
+    for path in files:
+        text = path.read_text(encoding="utf-8")
+        for name in _WRITE_CAPABLE_PROVIDER_FUNCTIONS:
+            if re.search(rf"\b{re.escape(name)}\b", text):
+                offenders.append(f"{path.relative_to(_REMOTE_PACKAGE_ROOT)}: {name}")
+
+    assert offenders == []
+
+
+def test_slash_commands_do_not_include_a_provider_write_command() -> None:
+    from app.remote.actions import _SLASH_COMMANDS
+
+    # A future "/providers" command must stay a read-only view — nothing in
+    # today's bounded command set (AC-58) implies a write, and this guards
+    # against one being added under a name that sounds like a listing.
+    assert "provider" not in {cmd.lower() for cmd in _SLASH_COMMANDS}
+    assert "providers" not in {cmd.lower() for cmd in _SLASH_COMMANDS}
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `uv run pytest --no-cov -q tests/remote/test_ac53_providers_read_only.py -v`
+Expected: at this point in the plan (after Tasks 1-3 land) both tests should already PASS, since nothing in this plan ever imports a write-capable function. Run it anyway to confirm — this task exists to make that guarantee explicit and permanent, not to fix a violation. If it unexpectedly fails, that is a real finding: something written in Tasks 1-3 imported a write path and must be fixed before proceeding.
+
+- [ ] **Step 3: No implementation step — the test is the deliverable.**
+
+- [ ] **Step 4: Lint and type-check**
+
+Run: `uv run ruff check tests/remote/test_ac53_providers_read_only.py && uv run ty check tests/remote/test_ac53_providers_read_only.py`
+Expected: both clean.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add tests/remote/test_ac53_providers_read_only.py
+git commit -m "test(remote): add the AC-53 provider-read-only inspection test"
+```
+
+---
+
+## Final verification (after all four tasks)
+
+- [ ] Run the full test suite: `uv run pytest --no-cov -q`
+- [ ] Run `uv run ruff check .`
+- [ ] Run `uv run ty check app/`
+- [ ] Merge to local `main` following this session's established pattern: check `git status --short` on the main checkout first, fast-forward merge, re-run tests on the merged result, no push.
+
+## Out of scope for this plan
+
+- A `/providers` drill-down listing configured provider names, or per-provider usage (tokens/cost) — the spec's "usage" wording is not built here; see this plan's Scope note.
+- Phase 6 — onboarding (AC-54's richer first-run card).

From 41cefc71cfeb275fb2600abc862f8f95f0a9dc12 Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Tue, 15 Sep 2026 11:59:33 +0700
Subject: [PATCH 56/71] feat(remote): count configured providers for /settings
 (AC-53)

Task 1 of documents/plans/remote-telegram-providers-implementation.md.
---
 app/remote/control.py                         | 22 ++++++++
 ...emote-telegram-providers-implementation.md |  5 +-
 tests/remote/test_control.py                  | 52 +++++++++++++++++++
 3 files changed, 77 insertions(+), 2 deletions(-)

diff --git a/app/remote/control.py b/app/remote/control.py
index b63a9c71..2428a462 100644
--- a/app/remote/control.py
+++ b/app/remote/control.py
@@ -22,6 +22,14 @@
   reintroducing a path-traversal bug. Both are called with explicit
   arguments, never relying on their Depends(...) defaults, which are
   FastAPI dependency-injection sentinels outside a real request.
+- count_configured_providers calls app.api.routes.settings.list_providers
+  — the same static-credential/daemon-reachability aggregation the
+  desktop Settings screen reads, with no service-layer equivalent.
+  Providers stay read-only from the phone (AC-53): this module never
+  imports any of that file's write-capable functions (save_provider,
+  save_provider_visible_models, test_provider, list_provider_models,
+  delete_provider), enforced by a standing inspection test rather than
+  by convention (tests/remote/test_ac53_providers_read_only.py).
 
 bypass is deliberately excluded from ALLOWED_REMOTE_MODES, checked by
 name (not by list length or position) before anything else runs — a
@@ -51,6 +59,7 @@
     "get_file_diff",
     "ALLOWED_RESPONSE_MODES",
     "set_response_mode",
+    "count_configured_providers",
 ]
 
 #: Every permission mode this phone may set — bypass excluded on purpose.
@@ -270,3 +279,16 @@ async def set_response_mode(
     await db.commit()
 
     return ControlResult(status="ok")
+
+
+async def count_configured_providers() -> int:
+    """How many catalog providers currently have usable credentials —
+    the one number `/settings` shows for AC-53. Calls the same route
+    function the desktop Settings screen uses (see this module's
+    docstring for why app/remote/ makes this exception) rather than
+    reimplementing the static-credential/daemon-reachability checks
+    GET /api/settings/providers already performs."""
+    from app.api.routes.settings import list_providers
+
+    result = await list_providers()
+    return sum(1 for provider in result.providers if provider.is_configured)
diff --git a/documents/plans/remote-telegram-providers-implementation.md b/documents/plans/remote-telegram-providers-implementation.md
index 7db27ae5..1e75fd87 100644
--- a/documents/plans/remote-telegram-providers-implementation.md
+++ b/documents/plans/remote-telegram-providers-implementation.md
@@ -54,7 +54,8 @@ async def test_count_configured_providers_counts_only_configured_ones(
                 _entry("openai", is_configured=True),
                 _entry("anthropic", is_configured=True),
                 _entry("mistral", is_configured=False),
-            ]
+            ],
+            has_any_configured=True,
         )
 
     monkeypatch.setattr(
@@ -73,7 +74,7 @@ async def test_count_configured_providers_is_zero_with_none_configured(
     from app.api.schemas.settings import ProvidersListBody
 
     async def _fake_list_providers() -> ProvidersListBody:
-        return ProvidersListBody(providers=[])
+        return ProvidersListBody(providers=[], has_any_configured=False)
 
     monkeypatch.setattr(
         "app.api.routes.settings.list_providers", _fake_list_providers
diff --git a/tests/remote/test_control.py b/tests/remote/test_control.py
index c68217d9..e489f88e 100644
--- a/tests/remote/test_control.py
+++ b/tests/remote/test_control.py
@@ -303,3 +303,55 @@ async def test_set_response_mode_not_found_for_unknown_pairing() -> None:
         result = await control.set_response_mode(db, str(UUID(int=0)), "live")
 
     assert result.status == "not_found"
+
+
+@pytest.mark.asyncio
+async def test_count_configured_providers_counts_only_configured_ones(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    from app.api.schemas.settings import ProviderInfo, ProvidersListBody
+
+    def _entry(id_: str, *, is_configured: bool) -> ProviderInfo:
+        return ProviderInfo(
+            id=id_,
+            label=id_,
+            description="",
+            kind="api_key",
+            is_configured=is_configured,
+        )
+
+    async def _fake_list_providers() -> ProvidersListBody:
+        return ProvidersListBody(
+            providers=[
+                _entry("openai", is_configured=True),
+                _entry("anthropic", is_configured=True),
+                _entry("mistral", is_configured=False),
+            ],
+            has_any_configured=True,
+        )
+
+    monkeypatch.setattr(
+        "app.api.routes.settings.list_providers", _fake_list_providers
+    )
+
+    count = await control.count_configured_providers()
+
+    assert count == 2
+
+
+@pytest.mark.asyncio
+async def test_count_configured_providers_is_zero_with_none_configured(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    from app.api.schemas.settings import ProvidersListBody
+
+    async def _fake_list_providers() -> ProvidersListBody:
+        return ProvidersListBody(providers=[], has_any_configured=False)
+
+    monkeypatch.setattr(
+        "app.api.routes.settings.list_providers", _fake_list_providers
+    )
+
+    count = await control.count_configured_providers()
+
+    assert count == 0

From 440c7a65a8d1d18535f94d018f6e8bf9587a7bf5 Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Tue, 15 Sep 2026 12:00:15 +0700
Subject: [PATCH 57/71] feat(remote): show configured provider count on the
 settings card (AC-53)

Task 2 of documents/plans/remote-telegram-providers-implementation.md.
---
 app/remote/formatting.py        |  6 ++++++
 tests/remote/test_formatting.py | 32 ++++++++++++++++++++++++++++++++
 2 files changed, 38 insertions(+)

diff --git a/app/remote/formatting.py b/app/remote/formatting.py
index d33ca871..b962dfad 100644
--- a/app/remote/formatting.py
+++ b/app/remote/formatting.py
@@ -165,6 +165,7 @@ def render_settings_card(
     mode_tokens: Mapping[str, str],
     agent_tokens: Mapping[str, str],
     model_tokens: Mapping[str, str],
+    configured_provider_count: int | None = None,
     redaction_policy: str | None = None,
     notify_scope: str | None = None,
     redaction_tokens: Mapping[str, str] = {},
@@ -183,6 +184,11 @@ def render_settings_card(
         "",
         f"Responses\n{escape(response_mode)}",
     ]
+    if configured_provider_count is not None:
+        lines += [
+            "",
+            f"Providers\n{configured_provider_count} configured",
+        ]
     if notify_scope is not None:
         lines += ["", f"Notifications\n{escape(notify_scope)}"]
     if redaction_policy is not None:
diff --git a/tests/remote/test_formatting.py b/tests/remote/test_formatting.py
index 66bfa0b1..f58020eb 100644
--- a/tests/remote/test_formatting.py
+++ b/tests/remote/test_formatting.py
@@ -199,6 +199,38 @@ def test_render_settings_card_shows_response_mode_and_its_toggle():
     assert {"r1", "r2"} <= button_tokens
 
 
+def test_render_settings_card_shows_configured_provider_count() -> None:
+    text, _ = formatting.render_settings_card(
+        connection_label="evoflux-api",
+        model="claude-sonnet-5",
+        permission_mode="ask",
+        agent_name="evoflux",
+        response_mode="summary",
+        response_mode_tokens={},
+        mode_tokens={},
+        agent_tokens={},
+        model_tokens={},
+        configured_provider_count=3,
+    )
+    assert "Providers" in text
+    assert "3" in text
+
+
+def test_render_settings_card_omits_providers_line_when_not_supplied() -> None:
+    text, _ = formatting.render_settings_card(
+        connection_label="evoflux-api",
+        model="claude-sonnet-5",
+        permission_mode="ask",
+        agent_name="evoflux",
+        response_mode="summary",
+        response_mode_tokens={},
+        mode_tokens={},
+        agent_tokens={},
+        model_tokens={},
+    )
+    assert "Providers" not in text
+
+
 def test_render_settings_card_never_offers_a_bypass_button():
     _, buttons = formatting.render_settings_card(
         connection_label="evoflux-api",

From 27a355e9f94eedcc7f8ab92f6a147b8942e272a0 Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Tue, 15 Sep 2026 12:01:12 +0700
Subject: [PATCH 58/71] feat(remote): wire the configured-provider count into
 /settings (AC-53)

Task 3 of documents/plans/remote-telegram-providers-implementation.md.
---
 app/remote/actions.py        |  2 ++
 tests/remote/test_actions.py | 38 +++++++++++++++++++++++++++++++++++-
 2 files changed, 39 insertions(+), 1 deletion(-)

diff --git a/app/remote/actions.py b/app/remote/actions.py
index 962228c0..41d0dfb6 100644
--- a/app/remote/actions.py
+++ b/app/remote/actions.py
@@ -345,6 +345,7 @@ async def _cmd_settings(
             )
             for mode in control.ALLOWED_RESPONSE_MODES
         }
+        configured_provider_count = await control.count_configured_providers()
 
         text, buttons = render_settings_card(
             connection_label=pairing.label or "This phone",
@@ -356,6 +357,7 @@ async def _cmd_settings(
             mode_tokens=mode_tokens,
             agent_tokens=agent_tokens,
             model_tokens=model_tokens,
+            configured_provider_count=configured_provider_count,
         )
 
         if self._adapter is not None:
diff --git a/tests/remote/test_actions.py b/tests/remote/test_actions.py
index 696518d9..386b80d0 100644
--- a/tests/remote/test_actions.py
+++ b/tests/remote/test_actions.py
@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import time
-from unittest.mock import MagicMock, patch
+from unittest.mock import AsyncMock, MagicMock, patch
 from uuid import uuid4
 
 import pytest
@@ -764,6 +764,42 @@ async def test_response_mode_callback_applies_the_selected_mode(
             assert refreshed is not None
             assert refreshed.response_mode == "live"
 
+    @pytest.mark.asyncio
+    async def test_settings_command_shows_configured_provider_count(
+        self, service: RemoteActionService, adapter: FakeAdapter
+    ) -> None:
+        async with db_module.async_session_factory() as db:
+            session = ChatSession(
+                title="Settings test",
+                mode="work",
+                session_type="main",
+                permission_mode="ask",
+            )
+            db.add(session)
+            await db.commit()
+            await db.refresh(session)
+
+            mock_pairing = MagicMock()
+            mock_pairing.id = uuid4()
+            mock_pairing.active_session_id = session.id
+            mock_pairing.label = "My Phone"
+            mock_pairing.response_mode = "summary"
+
+            with (
+                patch.object(
+                    service._pairing_service, "authorize", return_value=mock_pairing
+                ),
+                patch(
+                    "app.remote.control.count_configured_providers",
+                    new=AsyncMock(return_value=2),
+                ),
+            ):
+                settings_action = _make_action(text="/settings")
+                await service.dispatch_command(db, settings_action)
+
+            sent_text = adapter.sent_messages[-1].text
+            assert "2 configured" in sent_text
+
 
 # ── Health ────────────────────────────────────────────────────────────────────
 

From 57faf078ed5417241bcbf314725d956880e51c43 Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Tue, 15 Sep 2026 12:02:38 +0700
Subject: [PATCH 59/71] test(remote): add the AC-53 provider-read-only
 inspection test

Task 4 of documents/plans/remote-telegram-providers-implementation.md.
AST-based rather than a raw-text scan, so control.py's own module
docstring (documenting which functions it deliberately never calls) isn't
mistaken for a real reference.
---
 ...emote-telegram-providers-implementation.md | 31 +++++++-
 tests/remote/test_ac53_providers_read_only.py | 79 +++++++++++++++++++
 2 files changed, 106 insertions(+), 4 deletions(-)
 create mode 100644 tests/remote/test_ac53_providers_read_only.py

diff --git a/documents/plans/remote-telegram-providers-implementation.md b/documents/plans/remote-telegram-providers-implementation.md
index 1e75fd87..e088a7b0 100644
--- a/documents/plans/remote-telegram-providers-implementation.md
+++ b/documents/plans/remote-telegram-providers-implementation.md
@@ -322,11 +322,17 @@ A behavioral test could only prove the paths it thinks to exercise; a
 static scan proves the *absence* of a reference anywhere in the package,
 which is what AC-53 actually promises ("proven by an inspection test
 over the remote dispatch surface", not by convention or by enumerating
-every possible callback)."""
+every possible callback).
+
+Scans the AST rather than raw text so a docstring or comment that merely
+*names* one of these functions (e.g. control.py's own module docstring,
+documenting that it does NOT call them) never counts as a reference —
+only an actual import, call, or attribute access does.
+"""
 
 from __future__ import annotations
 
-import re
+import ast
 from pathlib import Path
 
 _REMOTE_PACKAGE_ROOT = Path(__file__).resolve().parents[2] / "app" / "remote"
@@ -349,15 +355,32 @@ def _remote_source_files() -> list[Path]:
     return list(_REMOTE_PACKAGE_ROOT.rglob("*.py"))
 
 
+def _referenced_identifiers(path: Path) -> set[str]:
+    """Every real Python identifier a file's code actually binds to or
+    reads — import targets, attribute accesses, bare names — never string
+    literals, docstrings, or comments (comments never reach the AST at
+    all; docstrings are Constant nodes, not Name/Attribute/alias)."""
+    tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
+    identifiers: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Name):
+            identifiers.add(node.id)
+        elif isinstance(node, ast.Attribute):
+            identifiers.add(node.attr)
+        elif isinstance(node, ast.alias):
+            identifiers.add(node.name)
+    return identifiers
+
+
 def test_no_remote_source_file_references_a_write_capable_provider_function() -> None:
     files = _remote_source_files()
     assert len(files) > 10  # sanity: the glob actually found the package
 
     offenders: list[str] = []
     for path in files:
-        text = path.read_text(encoding="utf-8")
+        identifiers = _referenced_identifiers(path)
         for name in _WRITE_CAPABLE_PROVIDER_FUNCTIONS:
-            if re.search(rf"\b{re.escape(name)}\b", text):
+            if name in identifiers:
                 offenders.append(f"{path.relative_to(_REMOTE_PACKAGE_ROOT)}: {name}")
 
     assert offenders == []
diff --git a/tests/remote/test_ac53_providers_read_only.py b/tests/remote/test_ac53_providers_read_only.py
new file mode 100644
index 00000000..90addcbf
--- /dev/null
+++ b/tests/remote/test_ac53_providers_read_only.py
@@ -0,0 +1,79 @@
+"""AC-53 inspection test: no remote code path may reach a credential-
+accepting provider endpoint.
+
+A behavioral test could only prove the paths it thinks to exercise; a
+static scan proves the *absence* of a reference anywhere in the package,
+which is what AC-53 actually promises ("proven by an inspection test
+over the remote dispatch surface", not by convention or by enumerating
+every possible callback).
+
+Scans the AST rather than raw text so a docstring or comment that merely
+*names* one of these functions (e.g. control.py's own module docstring,
+documenting that it does NOT call them) never counts as a reference —
+only an actual import, call, or attribute access does.
+"""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+_REMOTE_PACKAGE_ROOT = Path(__file__).resolve().parents[2] / "app" / "remote"
+
+#: Every provider endpoint in app/api/routes/settings.py that accepts or
+#: mutates credentials, visibility, or existence — AC-53's "no remote
+#: path reaches PUT .../providers/{id}, POST .../test, or any other
+#: credential-accepting endpoint".
+_WRITE_CAPABLE_PROVIDER_FUNCTIONS = (
+    "save_provider",
+    "save_provider_visible_models",
+    "test_provider",
+    "list_provider_models",
+    "delete_provider",
+)
+
+
+def _remote_source_files() -> list[Path]:
+    assert _REMOTE_PACKAGE_ROOT.is_dir(), _REMOTE_PACKAGE_ROOT
+    return list(_REMOTE_PACKAGE_ROOT.rglob("*.py"))
+
+
+def _referenced_identifiers(path: Path) -> set[str]:
+    """Every real Python identifier a file's code actually binds to or
+    reads — import targets, attribute accesses, bare names — never string
+    literals, docstrings, or comments (comments never reach the AST at
+    all; docstrings are Constant nodes, not Name/Attribute/alias)."""
+    tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
+    identifiers: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Name):
+            identifiers.add(node.id)
+        elif isinstance(node, ast.Attribute):
+            identifiers.add(node.attr)
+        elif isinstance(node, ast.alias):
+            identifiers.add(node.name)
+    return identifiers
+
+
+def test_no_remote_source_file_references_a_write_capable_provider_function() -> None:
+    files = _remote_source_files()
+    assert len(files) > 10  # sanity: the glob actually found the package
+
+    offenders: list[str] = []
+    for path in files:
+        identifiers = _referenced_identifiers(path)
+        for name in _WRITE_CAPABLE_PROVIDER_FUNCTIONS:
+            if name in identifiers:
+                offenders.append(f"{path.relative_to(_REMOTE_PACKAGE_ROOT)}: {name}")
+
+    assert offenders == []
+
+
+def test_slash_commands_do_not_include_a_provider_write_command() -> None:
+    from app.remote.actions import _SLASH_COMMANDS
+
+    # A future "/providers" command must stay a read-only view — nothing in
+    # today's bounded command set (AC-58) implies a write, and this guards
+    # against one being added under a name that sounds like a listing.
+    assert "provider" not in {cmd.lower() for cmd in _SLASH_COMMANDS}
+    assert "providers" not in {cmd.lower() for cmd in _SLASH_COMMANDS}

From f0cc230aa6d632aa694a4b961f2b86f8e045733a Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Tue, 15 Sep 2026 12:08:43 +0700
Subject: [PATCH 60/71] docs(remote): add AC-54 (onboarding) implementation
 plan

---
 ...mote-telegram-onboarding-implementation.md | 469 ++++++++++++++++++
 1 file changed, 469 insertions(+)
 create mode 100644 documents/plans/remote-telegram-onboarding-implementation.md

diff --git a/documents/plans/remote-telegram-onboarding-implementation.md b/documents/plans/remote-telegram-onboarding-implementation.md
new file mode 100644
index 00000000..9544df72
--- /dev/null
+++ b/documents/plans/remote-telegram-onboarding-implementation.md
@@ -0,0 +1,469 @@
+# Remote Telegram Onboarding Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Implement AC-54 — a successful pairing sends a card naming the current permission mode and offering setup, health check, and start-working actions, instead of today's plain confirmation text with no way forward.
+
+**Architecture:** A new `render_onboarding_card` builder in `formatting.py`, three new capability action kinds in `actions.py` (`onboarding_setup`, `onboarding_health`, `onboarding_start`) that delegate to the existing `_cmd_settings`/`_cmd_health` implementations (no new business logic — onboarding just gives the phone a shortcut into commands it already has), and `runtime.py`'s `_handle_pairing` sends the new card instead of the old plain-text confirmation. A rejected pairing still sends nothing (AC-9, unchanged).
+
+**Tech Stack:** Python 3.12, pytest + pytest-asyncio, `ruff`, `ty`.
+
+**Spec:** `documents/plans/remote-telegram-control-surface.md`, AC-54.
+
+## Global Constraints
+
+- The mode line always reflects `ChatSession.model_fields["permission_mode"].default` (currently `"auto"`) — read programmatically, never hardcoded, so it can't silently drift from the model's real default.
+- A rejected pairing attempt sends nothing at all (AC-9) — this plan touches only the success path.
+- "Set up" and "Health check" reuse `_cmd_settings`/`_cmd_health` exactly as `/settings`/`/health` already do — no new session/db logic. At pairing time there is no active session yet, so tapping "Set up" shows the existing "no active task yet" message, same as typing `/settings` would right after pairing.
+
+---
+
+### Task 1: `render_onboarding_card` in `app/remote/formatting.py`
+
+**Files:**
+- Modify: `app/remote/formatting.py`
+- Test: `tests/remote/test_formatting.py`
+
+**Interfaces:**
+- Produces: `render_onboarding_card(*, label: str, default_permission_mode: str, setup_token: str, health_token: str, start_token: str) -> tuple[str, tuple[RemoteButton, ...]]`.
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `tests/remote/test_formatting.py`:
+
+```python
+def test_render_onboarding_card_names_the_phone_and_states_auto_mode() -> None:
+    text, buttons = formatting.render_onboarding_card(
+        label="My Phone",
+        default_permission_mode="auto",
+        setup_token="setup-tok",
+        health_token="health-tok",
+        start_token="start-tok",
+    )
+    assert "My Phone" in text
+    assert "connected to EvoFlux" in text
+    assert "auto" in text
+    assert "won't ask" in text
+    assert len(buttons) == 3
+    assert {b.token for b in buttons} == {"setup-tok", "health-tok", "start-tok"}
+
+
+def test_render_onboarding_card_escapes_label() -> None:
+    text, _ = formatting.render_onboarding_card(
+        label="",
+        default_permission_mode="auto",
+        setup_token="s",
+        health_token="h",
+        start_token="w",
+    )
+    assert "" not in text
+    assert "<script>" in text
+
+
+def test_render_onboarding_card_states_non_auto_mode_without_the_auto_warning() -> None:
+    text, _ = formatting.render_onboarding_card(
+        label="My Phone",
+        default_permission_mode="ask",
+        setup_token="s",
+        health_token="h",
+        start_token="w",
+    )
+    assert "ask" in text
+    assert "won't ask" not in text
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `uv run pytest --no-cov -q tests/remote/test_formatting.py -k onboarding -v`
+Expected: FAIL with `AttributeError: module 'app.remote.formatting' has no attribute 'render_onboarding_card'`.
+
+- [ ] **Step 3: Implement**
+
+Add to `app/remote/formatting.py`'s `__all__` and body (near `render_settings_card`):
+
+```python
+def render_onboarding_card(
+    *,
+    label: str,
+    default_permission_mode: str,
+    setup_token: str,
+    health_token: str,
+    start_token: str,
+) -> tuple[str, tuple[RemoteButton, ...]]:
+    """The first-run card sent right after a successful pairing (AC-54) —
+    a starting point rather than a dead end. The mode line is stated
+    because it is the single most consequential default the operator
+    should know about at pairing time: "auto" means no approval prompts
+    will ever reach this phone."""
+    mode_line = f"Mode is {escape(default_permission_mode)}"
+    if default_permission_mode == "auto":
+        mode_line += " — the agent won't ask before running commands."
+    else:
+        mode_line += "."
+    text = (
+        f'✅ Paired! This phone ("{escape(label)}") is now connected '
+        f"to EvoFlux.\n\n{mode_line}"
+    )
+    buttons = (
+        RemoteButton(text="⚙️ Set up", token=setup_token),
+        RemoteButton(text="\U0001fa7a Health check", token=health_token),
+        RemoteButton(text="\U0001f4ac Just start working", token=start_token),
+    )
+    return text, buttons
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `uv run pytest --no-cov -q tests/remote/test_formatting.py -v`
+Expected: PASS, all tests in the file green.
+
+- [ ] **Step 5: Lint and type-check**
+
+Run: `uv run ruff check app/remote/formatting.py tests/remote/test_formatting.py && uv run ty check app/remote/formatting.py`
+Expected: both clean.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add app/remote/formatting.py tests/remote/test_formatting.py
+git commit -m "feat(remote): add render_onboarding_card for the first-run pairing message (AC-54)"
+```
+
+---
+
+### Task 2: Onboarding capability tokens in `app/remote/actions.py`
+
+**Files:**
+- Modify: `app/remote/actions.py`
+- Test: `tests/remote/test_actions.py`
+
+**Interfaces:**
+- Produces: `RemoteActionService.build_onboarding_card(action: RemoteInboundAction, *, label: str) -> tuple[str, tuple[RemoteButton, ...]]` (public — `runtime.py` calls this directly, Task 3). Three new `_execute_action` action kinds: `onboarding_setup`, `onboarding_health`, `onboarding_start`.
+- Consumes: `render_onboarding_card` (Task 1), the existing `_cmd_settings`/`_cmd_health`/`_issue_token`/`_reply_text`.
+
+- [ ] **Step 1: Write the failing tests**
+
+Add a new class to `tests/remote/test_actions.py`, after `TestSettings` (or anywhere top-level — read the file's existing `_make_action`/fixture names first, matching `TestSettings`'s own patterns for a paired action):
+
+```python
+class TestOnboarding:
+    @pytest.mark.asyncio
+    async def test_build_onboarding_card_mints_three_distinct_tokens(
+        self, service: RemoteActionService
+    ) -> None:
+        action = _make_action(text="/start")
+
+        text, buttons = service.build_onboarding_card(action, label="My Phone")
+
+        assert "My Phone" in text
+        assert len(buttons) == 3
+        tokens = {b.token for b in buttons}
+        assert len(tokens) == 3  # all distinct
+
+    @pytest.mark.asyncio
+    async def test_onboarding_setup_button_behaves_like_settings(
+        self, service: RemoteActionService, adapter: FakeAdapter
+    ) -> None:
+        conn_id = uuid4()
+        onboarding_action = _make_action(text="/start", connection_id=conn_id)
+        _text, buttons = service.build_onboarding_card(onboarding_action, label="My Phone")
+        setup_token = next(b.token for b in buttons if "Set up" in b.text)
+
+        mock_pairing = MagicMock()
+        mock_pairing.active_session_id = None
+        mock_pairing.label = "My Phone"
+
+        async with db_module.async_session_factory() as db:
+            with patch.object(
+                service._pairing_service, "authorize", return_value=mock_pairing
+            ):
+                callback_action = _make_action(
+                    kind=RemoteInboundActionKind.CALLBACK,
+                    callback_token=setup_token,
+                    connection_id=conn_id,
+                )
+                handled = await service.handle_action_callback(callback_action, db)
+
+        assert handled is True
+        assert "No active task yet" in adapter.sent_messages[-1].text
+
+    @pytest.mark.asyncio
+    async def test_onboarding_health_button_sends_health_diagnostics(
+        self, service: RemoteActionService, adapter: FakeAdapter
+    ) -> None:
+        conn_id = uuid4()
+        onboarding_action = _make_action(text="/start", connection_id=conn_id)
+        _text, buttons = service.build_onboarding_card(onboarding_action, label="My Phone")
+        health_token = next(b.token for b in buttons if "Health" in b.text)
+
+        mock_pairing = MagicMock()
+
+        async with db_module.async_session_factory() as db:
+            with (
+                patch.object(
+                    service._pairing_service, "authorize", return_value=mock_pairing
+                ),
+                patch(
+                    "app.remote.control.get_health_diagnostics",
+                    new=AsyncMock(return_value={"checks": []}),
+                ),
+            ):
+                callback_action = _make_action(
+                    kind=RemoteInboundActionKind.CALLBACK,
+                    callback_token=health_token,
+                    connection_id=conn_id,
+                )
+                handled = await service.handle_action_callback(callback_action, db)
+
+        assert handled is True
+        assert "Health" in adapter.sent_messages[-1].text
+
+    @pytest.mark.asyncio
+    async def test_onboarding_start_button_sends_a_friendly_prompt(
+        self, service: RemoteActionService, adapter: FakeAdapter
+    ) -> None:
+        conn_id = uuid4()
+        onboarding_action = _make_action(text="/start", connection_id=conn_id)
+        _text, buttons = service.build_onboarding_card(onboarding_action, label="My Phone")
+        start_token = next(b.token for b in buttons if "start" in b.text.lower())
+
+        async with db_module.async_session_factory() as db:
+            callback_action = _make_action(
+                kind=RemoteInboundActionKind.CALLBACK,
+                callback_token=start_token,
+                connection_id=conn_id,
+            )
+            handled = await service.handle_action_callback(callback_action, db)
+
+        assert handled is True
+        assert adapter.sent_messages  # something was sent
+```
+
+This needs `from uuid import uuid4` (already imported at the top of the file per earlier tasks in this session) and `AsyncMock` (already added to the `unittest.mock` import line by the providers plan).
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `uv run pytest --no-cov -q tests/remote/test_actions.py -k TestOnboarding -v`
+Expected: FAIL — `AttributeError: 'RemoteActionService' object has no attribute 'build_onboarding_card'`.
+
+- [ ] **Step 3: Implement**
+
+In `app/remote/actions.py`, add a public method (near `_cmd_settings`, since it shares the same token-issuing shape):
+
+```python
+    def build_onboarding_card(
+        self, action: RemoteInboundAction, *, label: str
+    ) -> tuple[str, tuple[RemoteButton, ...]]:
+        """The first-run card sent right after a successful pairing
+        (AC-54). Unlike every other card this module builds, no session
+        or turn exists yet — these three tokens' session_id/action_target
+        are unused placeholders, the same repurposed-field pattern already
+        used for the response-mode tokens' pairing-id reuse."""
+        from app.models.chat import ChatSession
+        from app.remote.formatting import render_onboarding_card
+
+        setup_token = self._issue_token(
+            connection_id=action.connection_id,
+            principal_id=action.principal.principal_id,
+            destination_id=action.principal.destination_id,
+            session_id="",
+            action_kind="onboarding_setup",
+            action_target="",
+        )
+        health_token = self._issue_token(
+            connection_id=action.connection_id,
+            principal_id=action.principal.principal_id,
+            destination_id=action.principal.destination_id,
+            session_id="",
+            action_kind="onboarding_health",
+            action_target="",
+        )
+        start_token = self._issue_token(
+            connection_id=action.connection_id,
+            principal_id=action.principal.principal_id,
+            destination_id=action.principal.destination_id,
+            session_id="",
+            action_kind="onboarding_start",
+            action_target="",
+        )
+        default_mode = ChatSession.model_fields["permission_mode"].default
+        return render_onboarding_card(
+            label=label,
+            default_permission_mode=default_mode,
+            setup_token=setup_token,
+            health_token=health_token,
+            start_token=start_token,
+        )
+```
+
+Add the three branches to `_execute_action`'s elif chain (after `set_response_mode`, before `changes_diff`):
+
+```python
+        elif cap.action_kind == "onboarding_setup":
+            return await self._exec_onboarding_setup(cap, action, db)
+        elif cap.action_kind == "onboarding_health":
+            return await self._exec_onboarding_health(cap, action, db)
+        elif cap.action_kind == "onboarding_start":
+            return await self._exec_onboarding_start(cap, action, db)
+```
+
+Add the three handlers near `_exec_set_response_mode`:
+
+```python
+    async def _exec_onboarding_setup(
+        self, cap: _ActionCapability, action: RemoteInboundAction, db: AsyncSession
+    ) -> bool:
+        """/settings already self-sends its reply — nothing further to do
+        here, matching how /settings itself works when typed directly."""
+        await self._cmd_settings(db, action)
+        return True
+
+    async def _exec_onboarding_health(
+        self, cap: _ActionCapability, action: RemoteInboundAction, db: AsyncSession
+    ) -> bool:
+        """Unlike /settings, _cmd_health does not self-send (its text is
+        normally sent by runtime.py's /health fallback path) — send it
+        explicitly here."""
+        result = await self._cmd_health(db, action)
+        if result.text:
+            await self._reply_text(action.principal.destination_id, result.text)
+        return True
+
+    async def _exec_onboarding_start(
+        self, cap: _ActionCapability, action: RemoteInboundAction, db: AsyncSession
+    ) -> bool:
+        await self._reply_text(
+            action.principal.destination_id,
+            "Great — type your first message whenever you're ready.",
+        )
+        return True
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `uv run pytest --no-cov -q tests/remote/test_actions.py -v`
+Expected: PASS, all tests in the file green.
+
+- [ ] **Step 5: Lint and type-check**
+
+Run: `uv run ruff check app/remote/actions.py tests/remote/test_actions.py && uv run ty check app/remote/actions.py`
+Expected: both clean.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add app/remote/actions.py tests/remote/test_actions.py
+git commit -m "feat(remote): add onboarding capability tokens (setup/health/start) (AC-54)"
+```
+
+---
+
+### Task 3: Wire the onboarding card into `runtime.py`'s pairing success path
+
+**Files:**
+- Modify: `app/remote/runtime.py`
+- Test: `tests/remote/test_runtime.py`
+
+**Interfaces:**
+- Consumes: `RemoteActionService.build_onboarding_card` (Task 2).
+
+- [ ] **Step 1: Write the failing test**
+
+Add to `tests/remote/test_runtime.py`, near `test_handle_pairing_consumes_a_token_minted_via_the_shared_service`:
+
+```python
+@pytest.mark.asyncio
+async def test_handle_pairing_success_offers_onboarding_buttons(
+    session, fake_stores, fake_adapters
+) -> None:
+    connection = await _make_connection(session, enabled=True)
+    fake_stores[connection.id] = FakeCredentialStore("secret-token")
+    await remote_runtime.start()
+    link = pairing_service.issue_link(connection)
+    token = link.url.rsplit("start=", 1)[-1]
+
+    action = RemoteInboundAction(
+        connection_id=connection.id,
+        kind=RemoteInboundActionKind.PAIRING_START,
+        principal=RemotePrincipal(
+            connection_id=connection.id,
+            principal_id="12345",
+            destination_id="12345",
+            display="Test User",
+        ),
+        source_key=f"telegram:{connection.id}:1",
+        pairing_token=token,
+    )
+
+    await remote_runtime._handle_pairing(action)
+
+    assert len(fake_adapters[0].sent) == 1
+    confirmation = fake_adapters[0].sent[0]
+    assert "auto" in confirmation.text
+    assert len(confirmation.buttons) == 3
+    button_texts = {b.text for b in confirmation.buttons}
+    assert any("Set up" in t for t in button_texts)
+    assert any("Health" in t for t in button_texts)
+    assert any("start working" in t.lower() for t in button_texts)
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `uv run pytest --no-cov -q tests/remote/test_runtime.py -k onboarding_buttons -v`
+Expected: FAIL — `assert 0 == 3` (today's confirmation message carries no buttons at all).
+
+- [ ] **Step 3: Implement**
+
+In `app/remote/runtime.py`'s `_handle_pairing`, replace the plain-text confirmation send with:
+
+```python
+            # A silently-persisted pairing is indistinguishable from a
+            # failed one from the phone's side — confirm it with a
+            # starting point rather than a dead end (AC-54). Never sent on
+            # rejection (AC-9: a refusal reveals no connection state).
+            if self._adapter is not None and self._actions is not None:
+                text, buttons = self._actions.build_onboarding_card(
+                    action, label=result.label
+                )
+                await self._adapter.send(
+                    RemoteOutboundMessage(
+                        connection_id=action.connection_id,
+                        destination_id=action.principal.destination_id,
+                        text=text,
+                        buttons=buttons,
+                        priority=RemoteOutboundPriority.HIGH,
+                    )
+                )
+```
+
+This replaces the entire previous `if self._adapter is not None:` block (the one building the old plain `f'✅ Paired! ...'` string) — same guard condition plus the new `self._actions is not None` check (defensive: `_actions` is always set by the time a real `/start` deep link can be consumed, since the adapter's poll loop that delivers it only starts after `_start_locked` finishes constructing `_actions`, but the guard costs nothing and avoids a crash if that invariant is ever violated by a future refactor).
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `uv run pytest --no-cov -q tests/remote/test_runtime.py -v`
+Expected: PASS, all tests in the file green — including the pre-existing `test_handle_pairing_consumes_a_token_minted_via_the_shared_service`, which only asserts `"connected" in confirmation.text.lower()` and is unaffected by the added buttons.
+
+- [ ] **Step 5: Lint and type-check**
+
+Run: `uv run ruff check app/remote/runtime.py tests/remote/test_runtime.py && uv run ty check app/remote/runtime.py`
+Expected: both clean.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add app/remote/runtime.py tests/remote/test_runtime.py
+git commit -m "feat(remote): send the onboarding card on a successful pairing (AC-54)"
+```
+
+---
+
+## Final verification (after all three tasks)
+
+- [ ] Run the full test suite: `uv run pytest --no-cov -q`
+- [ ] Run `uv run ruff check .`
+- [ ] Run `uv run ty check app/`
+- [ ] Merge to local `main` following this session's established pattern: check `git status --short` on the main checkout first, fast-forward merge, re-run tests on the merged result, no push.
+
+## Out of scope for this plan
+
+This closes AC-54, the last item in the original control-surface spec (AC-45 through AC-58). Any further Telegram remote-control work (e.g. a `/providers` drill-down, live-mode UI polish) is a new request, not part of that spec.

From e2080559119fd4835919220cc15dda6e4ab7320c Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Tue, 15 Sep 2026 12:09:26 +0700
Subject: [PATCH 61/71] feat(remote): add render_onboarding_card for the
 first-run pairing message (AC-54)

Task 1 of documents/plans/remote-telegram-onboarding-implementation.md.
---
 app/remote/formatting.py        | 31 +++++++++++++++++++++++++
 tests/remote/test_formatting.py | 40 +++++++++++++++++++++++++++++++++
 2 files changed, 71 insertions(+)

diff --git a/app/remote/formatting.py b/app/remote/formatting.py
index b962dfad..ab637269 100644
--- a/app/remote/formatting.py
+++ b/app/remote/formatting.py
@@ -20,6 +20,7 @@
     "render_health_card",
     "render_changes_card",
     "render_live_status_card",
+    "render_onboarding_card",
 ]
 
 _STATUS_ICON = {"accepted": "\U0001f527", "queued": "⏳", "pending": "⏳"}
@@ -229,6 +230,36 @@ def render_settings_card(
     return text, tuple(buttons)
 
 
+def render_onboarding_card(
+    *,
+    label: str,
+    default_permission_mode: str,
+    setup_token: str,
+    health_token: str,
+    start_token: str,
+) -> tuple[str, tuple[RemoteButton, ...]]:
+    """The first-run card sent right after a successful pairing (AC-54) —
+    a starting point rather than a dead end. The mode line is stated
+    because it is the single most consequential default the operator
+    should know about at pairing time: "auto" means no approval prompts
+    will ever reach this phone."""
+    mode_line = f"Mode is {escape(default_permission_mode)}"
+    if default_permission_mode == "auto":
+        mode_line += " — the agent won't ask before running commands."
+    else:
+        mode_line += "."
+    text = (
+        f'✅ Paired! This phone ("{escape(label)}") is now connected '
+        f"to EvoFlux.\n\n{mode_line}"
+    )
+    buttons = (
+        RemoteButton(text="⚙️ Set up", token=setup_token),
+        RemoteButton(text="\U0001fa7a Health check", token=health_token),
+        RemoteButton(text="\U0001f4ac Just start working", token=start_token),
+    )
+    return text, buttons
+
+
 def render_project_picker(
     *, projects: Sequence[tuple[str, str]]
 ) -> tuple[str, tuple[RemoteButton, ...]]:
diff --git a/tests/remote/test_formatting.py b/tests/remote/test_formatting.py
index f58020eb..82778eb5 100644
--- a/tests/remote/test_formatting.py
+++ b/tests/remote/test_formatting.py
@@ -327,6 +327,46 @@ def test_render_settings_card_now_emits_mode_and_model_buttons():
     assert any("strict" in t.lower() for t in button_texts)
 
 
+def test_render_onboarding_card_names_the_phone_and_states_auto_mode() -> None:
+    text, buttons = formatting.render_onboarding_card(
+        label="My Phone",
+        default_permission_mode="auto",
+        setup_token="setup-tok",
+        health_token="health-tok",
+        start_token="start-tok",
+    )
+    assert "My Phone" in text
+    assert "connected to EvoFlux" in text
+    assert "auto" in text
+    assert "won't ask" in text
+    assert len(buttons) == 3
+    assert {b.token for b in buttons} == {"setup-tok", "health-tok", "start-tok"}
+
+
+def test_render_onboarding_card_escapes_label() -> None:
+    text, _ = formatting.render_onboarding_card(
+        label="",
+        default_permission_mode="auto",
+        setup_token="s",
+        health_token="h",
+        start_token="w",
+    )
+    assert "" not in text
+    assert "<script>" in text
+
+
+def test_render_onboarding_card_states_non_auto_mode_without_the_auto_warning() -> None:
+    text, _ = formatting.render_onboarding_card(
+        label="My Phone",
+        default_permission_mode="ask",
+        setup_token="s",
+        health_token="h",
+        start_token="w",
+    )
+    assert "ask" in text
+    assert "won't ask" not in text
+
+
 def test_render_gate_card_escapes_action_labels():
     text, buttons = formatting.render_gate_card(
         title="Approve deploy?",

From 7216b7be2705bf5a36df6fcb9e9c55d267b2b931 Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Tue, 15 Sep 2026 12:12:04 +0700
Subject: [PATCH 62/71] feat(remote): add onboarding capability tokens
 (setup/health/start) (AC-54)

Task 2 of documents/plans/remote-telegram-onboarding-implementation.md.
---
 app/remote/actions.py        |  78 +++++++++++++++++++++++++++
 tests/remote/test_actions.py | 102 +++++++++++++++++++++++++++++++++++
 2 files changed, 180 insertions(+)

diff --git a/app/remote/actions.py b/app/remote/actions.py
index 41d0dfb6..4edca7e2 100644
--- a/app/remote/actions.py
+++ b/app/remote/actions.py
@@ -364,6 +364,50 @@ async def _cmd_settings(
             await self._send(action.principal.destination_id, text, buttons=buttons)
         return RemoteActionResult(status="ok", text=text)
 
+    def build_onboarding_card(
+        self, action: RemoteInboundAction, *, label: str
+    ) -> tuple[str, tuple[RemoteButton, ...]]:
+        """The first-run card sent right after a successful pairing
+        (AC-54). Unlike every other card this module builds, no session
+        or turn exists yet — these three tokens' session_id/action_target
+        are unused placeholders, the same repurposed-field pattern already
+        used for the response-mode tokens' pairing-id reuse."""
+        from app.models.chat import ChatSession
+        from app.remote.formatting import render_onboarding_card
+
+        setup_token = self._issue_token(
+            connection_id=action.connection_id,
+            principal_id=action.principal.principal_id,
+            destination_id=action.principal.destination_id,
+            session_id="",
+            action_kind="onboarding_setup",
+            action_target="",
+        )
+        health_token = self._issue_token(
+            connection_id=action.connection_id,
+            principal_id=action.principal.principal_id,
+            destination_id=action.principal.destination_id,
+            session_id="",
+            action_kind="onboarding_health",
+            action_target="",
+        )
+        start_token = self._issue_token(
+            connection_id=action.connection_id,
+            principal_id=action.principal.principal_id,
+            destination_id=action.principal.destination_id,
+            session_id="",
+            action_kind="onboarding_start",
+            action_target="",
+        )
+        default_mode = ChatSession.model_fields["permission_mode"].default
+        return render_onboarding_card(
+            label=label,
+            default_permission_mode=default_mode,
+            setup_token=setup_token,
+            health_token=health_token,
+            start_token=start_token,
+        )
+
     def _issue_settings_token(
         self,
         action: RemoteInboundAction,
@@ -663,6 +707,12 @@ async def _execute_action(
             return await self._exec_set_model(cap, action, db)
         elif cap.action_kind == "set_response_mode":
             return await self._exec_set_response_mode(cap, action, db)
+        elif cap.action_kind == "onboarding_setup":
+            return await self._exec_onboarding_setup(cap, action, db)
+        elif cap.action_kind == "onboarding_health":
+            return await self._exec_onboarding_health(cap, action, db)
+        elif cap.action_kind == "onboarding_start":
+            return await self._exec_onboarding_start(cap, action, db)
         elif cap.action_kind == "changes_diff":
             return await self._exec_changes_diff(cap, action, db)
         return False
@@ -909,6 +959,34 @@ async def _exec_set_response_mode(
         )
         return True
 
+    async def _exec_onboarding_setup(
+        self, cap: _ActionCapability, action: RemoteInboundAction, db: AsyncSession
+    ) -> bool:
+        """/settings already self-sends its reply — nothing further to do
+        here, matching how /settings itself works when typed directly."""
+        await self._cmd_settings(db, action)
+        return True
+
+    async def _exec_onboarding_health(
+        self, cap: _ActionCapability, action: RemoteInboundAction, db: AsyncSession
+    ) -> bool:
+        """Unlike /settings, _cmd_health does not self-send (its text is
+        normally sent by runtime.py's /health fallback path) — send it
+        explicitly here."""
+        result = await self._cmd_health(db, action)
+        if result.text:
+            await self._reply_text(action.principal.destination_id, result.text)
+        return True
+
+    async def _exec_onboarding_start(
+        self, cap: _ActionCapability, action: RemoteInboundAction, db: AsyncSession
+    ) -> bool:
+        await self._reply_text(
+            action.principal.destination_id,
+            "Great — type your first message whenever you're ready.",
+        )
+        return True
+
     async def _exec_changes_diff(
         self, cap: _ActionCapability, action: RemoteInboundAction, db: AsyncSession
     ) -> bool:
diff --git a/tests/remote/test_actions.py b/tests/remote/test_actions.py
index 386b80d0..98012905 100644
--- a/tests/remote/test_actions.py
+++ b/tests/remote/test_actions.py
@@ -979,3 +979,105 @@ async def _fake_get_file_diff(workspace: str, path: str) -> str:
 
             assert handled is True
             assert any("fixed" in text for text in adapter.sent_texts)
+
+
+# ── Onboarding ────────────────────────────────────────────────────────────────
+
+
+class TestOnboarding:
+    @pytest.mark.asyncio
+    async def test_build_onboarding_card_mints_three_distinct_tokens(
+        self, service: RemoteActionService
+    ) -> None:
+        action = _make_action(text="/start")
+
+        text, buttons = service.build_onboarding_card(action, label="My Phone")
+
+        assert "My Phone" in text
+        assert len(buttons) == 3
+        tokens = {b.token for b in buttons}
+        assert len(tokens) == 3  # all distinct
+
+    @pytest.mark.asyncio
+    async def test_onboarding_setup_button_behaves_like_settings(
+        self, service: RemoteActionService, adapter: FakeAdapter
+    ) -> None:
+        conn_id = uuid4()
+        onboarding_action = _make_action(text="/start", connection_id=conn_id)
+        _text, buttons = service.build_onboarding_card(
+            onboarding_action, label="My Phone"
+        )
+        setup_token = next(b.token for b in buttons if "Set up" in b.text)
+
+        mock_pairing = MagicMock()
+        mock_pairing.active_session_id = None
+        mock_pairing.label = "My Phone"
+
+        async with db_module.async_session_factory() as db:
+            with patch.object(
+                service._pairing_service, "authorize", return_value=mock_pairing
+            ):
+                callback_action = _make_action(
+                    kind=RemoteInboundActionKind.CALLBACK,
+                    callback_token=setup_token,
+                    connection_id=conn_id,
+                )
+                handled = await service.handle_action_callback(callback_action, db)
+
+        assert handled is True
+        assert "No active task yet" in adapter.sent_messages[-1].text
+
+    @pytest.mark.asyncio
+    async def test_onboarding_health_button_sends_health_diagnostics(
+        self, service: RemoteActionService, adapter: FakeAdapter
+    ) -> None:
+        conn_id = uuid4()
+        onboarding_action = _make_action(text="/start", connection_id=conn_id)
+        _text, buttons = service.build_onboarding_card(
+            onboarding_action, label="My Phone"
+        )
+        health_token = next(b.token for b in buttons if "Health" in b.text)
+
+        mock_pairing = MagicMock()
+
+        async with db_module.async_session_factory() as db:
+            with (
+                patch.object(
+                    service._pairing_service, "authorize", return_value=mock_pairing
+                ),
+                patch(
+                    "app.remote.control.get_health_diagnostics",
+                    new=AsyncMock(return_value={"checks": []}),
+                ),
+            ):
+                callback_action = _make_action(
+                    kind=RemoteInboundActionKind.CALLBACK,
+                    callback_token=health_token,
+                    connection_id=conn_id,
+                )
+                handled = await service.handle_action_callback(callback_action, db)
+
+        assert handled is True
+        assert "Health" in adapter.sent_messages[-1].text
+
+    @pytest.mark.asyncio
+    async def test_onboarding_start_button_sends_a_friendly_prompt(
+        self, service: RemoteActionService, adapter: FakeAdapter
+    ) -> None:
+        conn_id = uuid4()
+        onboarding_action = _make_action(text="/start", connection_id=conn_id)
+        _text, buttons = service.build_onboarding_card(
+            onboarding_action, label="My Phone"
+        )
+        start_token = next(b.token for b in buttons if "start" in b.text.lower())
+
+        async with db_module.async_session_factory() as db:
+            callback_action = _make_action(
+                kind=RemoteInboundActionKind.CALLBACK,
+                callback_token=start_token,
+                connection_id=conn_id,
+            )
+            handled = await service.handle_action_callback(callback_action, db)
+
+        assert handled is True
+        assert adapter.sent_messages  # something was sent

From 8f15653d911717a5ef5c4b2b7a0c94b477abb718 Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Tue, 15 Sep 2026 12:12:49 +0700
Subject: [PATCH 63/71] feat(remote): send the onboarding card on a successful
 pairing (AC-54)

Task 3 of documents/plans/remote-telegram-onboarding-implementation.md.
Closes the last item in the original control-surface spec (AC-45
through AC-58).
---
 app/remote/runtime.py        | 17 ++++++++---------
 tests/remote/test_runtime.py | 35 +++++++++++++++++++++++++++++++++++
 2 files changed, 43 insertions(+), 9 deletions(-)

diff --git a/app/remote/runtime.py b/app/remote/runtime.py
index 5f2b77de..8350dbc7 100644
--- a/app/remote/runtime.py
+++ b/app/remote/runtime.py
@@ -433,20 +433,19 @@ async def _handle_pairing(self, action: RemoteInboundAction) -> None:
                     principal_id=result.principal_id,
                 )
             # A silently-persisted pairing is indistinguishable from a
-            # failed one from the phone's side — confirm it (spec: "sends
-            # Connected to EvoFlux on "). Never sent on
+            # failed one from the phone's side — confirm it with a
+            # starting point rather than a dead end (AC-54). Never sent on
             # rejection (AC-9: a refusal reveals no connection state).
-            if self._adapter is not None:
+            if self._adapter is not None and self._actions is not None:
+                text, buttons = self._actions.build_onboarding_card(
+                    action, label=result.label
+                )
                 await self._adapter.send(
                     RemoteOutboundMessage(
                         connection_id=action.connection_id,
                         destination_id=action.principal.destination_id,
-                        text=(
-                            f'✅ Paired! This phone ("{result.label}") is now '
-                            "connected to EvoFlux.\n\n"
-                            "Type anything to start working with your agent, or "
-                            "send /help to see what else you can do."
-                        ),
+                        text=text,
+                        buttons=buttons,
                         priority=RemoteOutboundPriority.HIGH,
                     )
                 )
diff --git a/tests/remote/test_runtime.py b/tests/remote/test_runtime.py
index 6aa8ff3d..60c887bf 100644
--- a/tests/remote/test_runtime.py
+++ b/tests/remote/test_runtime.py
@@ -427,6 +427,41 @@ async def test_handle_pairing_consumes_a_token_minted_via_the_shared_service(
     assert "connected" in confirmation.text.lower()
 
 
+@pytest.mark.asyncio
+async def test_handle_pairing_success_offers_onboarding_buttons(
+    session, fake_stores, fake_adapters
+) -> None:
+    connection = await _make_connection(session, enabled=True)
+    fake_stores[connection.id] = FakeCredentialStore("secret-token")
+    await remote_runtime.start()
+    link = pairing_service.issue_link(connection)
+    token = link.url.rsplit("start=", 1)[-1]
+
+    action = RemoteInboundAction(
+        connection_id=connection.id,
+        kind=RemoteInboundActionKind.PAIRING_START,
+        principal=RemotePrincipal(
+            connection_id=connection.id,
+            principal_id="12345",
+            destination_id="12345",
+            display="Test User",
+        ),
+        source_key=f"telegram:{connection.id}:1",
+        pairing_token=token,
+    )
+
+    await remote_runtime._handle_pairing(action)
+
+    assert len(fake_adapters[0].sent) == 1
+    confirmation = fake_adapters[0].sent[0]
+    assert "auto" in confirmation.text
+    assert len(confirmation.buttons) == 3
+    button_texts = {b.text for b in confirmation.buttons}
+    assert any("Set up" in t for t in button_texts)
+    assert any("Health" in t for t in button_texts)
+    assert any("start working" in t.lower() for t in button_texts)
+
+
 @pytest.mark.asyncio
 async def test_handle_pairing_sends_nothing_for_a_rejected_token(
     session, fake_stores, fake_adapters

From ad813cea4c47a191eaac31096f9a07e1293a7b83 Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Tue, 15 Sep 2026 12:19:48 +0700
Subject: [PATCH 64/71] fix(remote): list /settings, /health, /changes in the
 /help text
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

These have been dispatchable and in Telegram's own command menu since
Phase 2/3, but _HELP_TEXT was never updated to mention them — a paired
user typing /help had no way to discover they existed.
---
 app/remote/actions.py        | 3 +++
 tests/remote/test_actions.py | 3 +++
 2 files changed, 6 insertions(+)

diff --git a/app/remote/actions.py b/app/remote/actions.py
index 4edca7e2..4ce2a279 100644
--- a/app/remote/actions.py
+++ b/app/remote/actions.py
@@ -99,6 +99,9 @@ class _ActionCapability:
 /status — What's my agent doing right now?
 /new — Set aside the current task and start a fresh one
 /stop — Interrupt the agent while it's working on your last message
+/settings — Change mode, model, agent, or response style
+/health — Check system health
+/changes — See this task's file changes
 /actions — Run a saved workflow, open a coding project, or fire a \
 scheduled task
 /unpair — Disconnect this phone from EvoFlux
diff --git a/tests/remote/test_actions.py b/tests/remote/test_actions.py
index 98012905..84cd60d7 100644
--- a/tests/remote/test_actions.py
+++ b/tests/remote/test_actions.py
@@ -122,6 +122,9 @@ async def test_help_returns_help_text(self, service: RemoteActionService) -> Non
         assert "/status" in result.text
         assert "/new" in result.text
         assert "/stop" in result.text
+        assert "/settings" in result.text
+        assert "/health" in result.text
+        assert "/changes" in result.text
         assert "/unpair" in result.text
         assert "/actions" in result.text
 

From b929cb48c55406c010063b20b5901c2d971bf4a5 Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Tue, 15 Sep 2026 12:25:40 +0700
Subject: [PATCH 65/71] feat(remote): add clear_history to the Telegram adapter

Tracks the last 200 message ids this bot sent per destination and, via
clear_history(), deletes them through Telegram's deleteMessage API,
tolerating individual failures (e.g. a message past Telegram's 48-hour
deletion window) rather than aborting the whole clear. Prep for a
/clear command.
---
 app/remote/telegram/adapter.py        | 51 ++++++++++++++++-
 app/remote/telegram/client.py         |  7 +++
 tests/remote/telegram/test_adapter.py | 81 +++++++++++++++++++++++++++
 tests/remote/telegram/test_client.py  | 16 ++++++
 4 files changed, 154 insertions(+), 1 deletion(-)

diff --git a/app/remote/telegram/adapter.py b/app/remote/telegram/adapter.py
index 5d0b5b62..95e68fb0 100644
--- a/app/remote/telegram/adapter.py
+++ b/app/remote/telegram/adapter.py
@@ -25,7 +25,7 @@
 
 import asyncio
 import random
-from collections import OrderedDict
+from collections import OrderedDict, defaultdict, deque
 from collections.abc import Awaitable, Callable, Sequence
 from datetime import UTC, datetime
 from uuid import UUID
@@ -76,6 +76,13 @@
 #: interaction contract").
 MAX_PENDING_CALLBACK_IDS = 512
 
+#: Bound on how many sent message ids ``clear_history`` remembers per
+#: destination, so a long-running connection's history for one chat
+#: cannot grow unboundedly. Telegram itself only allows a bot to delete
+#: its own messages within 48 hours anyway, so remembering far more than
+#: this would rarely help.
+MAX_TRACKED_MESSAGES_PER_DESTINATION = 200
+
 
 def _default_clock() -> datetime:
     return datetime.now(UTC)
@@ -126,6 +133,13 @@ def __init__(
         self._sent_messages: dict[str, tuple[int, int]] = {}
         #: opaque callback token -> raw Telegram callback_query id.
         self._pending_callback_ids: OrderedDict[str, str] = OrderedDict()
+        #: destination_id -> the most recent message ids this bot sent
+        #: there, for ``clear_history``. Bounded per destination
+        #: (MAX_TRACKED_MESSAGES_PER_DESTINATION); ephemeral, like every
+        #: other in-memory tracking this adapter keeps.
+        self._message_history: dict[str, deque[int]] = defaultdict(
+            lambda: deque(maxlen=MAX_TRACKED_MESSAGES_PER_DESTINATION)
+        )
 
     # ------------------------------------------------------------------
     # Lifecycle
@@ -199,6 +213,7 @@ async def send(self, message: RemoteOutboundMessage) -> None:
                 sent.chat.id,
                 sent.message_id,
             )
+        self._message_history[message.destination_id].append(sent.message_id)
 
     async def edit(self, message: RemoteOutboundMessage) -> None:
         target = (
@@ -224,6 +239,40 @@ async def edit(self, message: RemoteOutboundMessage) -> None:
             raise
         self._record_delivery_success()
 
+    async def clear_history(self, destination_id: str) -> int:
+        """Delete every message this bot remembers sending to
+        *destination_id* (bounded to the most recent
+        ``MAX_TRACKED_MESSAGES_PER_DESTINATION`` — see ``_message_history``).
+
+        Telegram only lets a bot delete its own messages, and only within
+        48 hours (docs: "Message can only be deleted if it was sent less
+        than 48 hours ago"); a message outside that window (or already
+        deleted) is skipped rather than aborting the whole clear — this is
+        best-effort tidying, not a guarantee. Not this adapter's job to
+        chase down messages it never sent: the user's own messages in a
+        private chat cannot be deleted by the bot at all.
+        """
+        message_ids = list(self._message_history.pop(destination_id, ()))
+        cleared = 0
+        for message_id in message_ids:
+            try:
+                await self._client.delete_message(
+                    chat_id=destination_id, message_id=message_id
+                )
+            except (
+                TelegramApiError,
+                TelegramTransportError,
+                TelegramMalformedResponseError,
+            ):
+                logger.debug(
+                    "telegram_delete_message_failed destination_id={} message_id={}",
+                    destination_id,
+                    message_id,
+                )
+                continue
+            cleared += 1
+        return cleared
+
     async def answer_callback(self, callback_token: str) -> None:
         raw_id = self._pending_callback_ids.pop(callback_token, None)
         if raw_id is None:
diff --git a/app/remote/telegram/client.py b/app/remote/telegram/client.py
index a74d9ce7..8e32366a 100644
--- a/app/remote/telegram/client.py
+++ b/app/remote/telegram/client.py
@@ -305,6 +305,13 @@ async def answer_callback(
             payload["text"] = text
         await self._call("answerCallbackQuery", payload, result_model=bool)
 
+    async def delete_message(self, *, chat_id: str | int, message_id: int) -> None:
+        await self._call(
+            "deleteMessage",
+            {"chat_id": chat_id, "message_id": message_id},
+            result_model=bool,
+        )
+
     async def set_commands(self, commands: Sequence[tuple[str, str]]) -> None:
         payload = {
             "commands": [
diff --git a/tests/remote/telegram/test_adapter.py b/tests/remote/telegram/test_adapter.py
index 486cd7fa..48db0509 100644
--- a/tests/remote/telegram/test_adapter.py
+++ b/tests/remote/telegram/test_adapter.py
@@ -575,6 +575,87 @@ async def test_send_failure_sets_phone_unreachable_without_crashing_poll_loop(se
         # Inbound polling is unaffected — still healthy.
         assert status.state == RemoteConnectionState.PHONE_UNREACHABLE
 
+    @pytest.mark.asyncio
+    async def test_clear_history_deletes_every_remembered_message_for_a_destination(
+        self,
+    ):
+        transport = ScriptedTransport()
+        transport.queue(
+            "sendMessage",
+            _ok({"message_id": 1, "date": 1, "chat": {"id": 100, "type": "private"}}),
+        )
+        transport.queue(
+            "sendMessage",
+            _ok({"message_id": 2, "date": 1, "chat": {"id": 100, "type": "private"}}),
+        )
+        adapter = _make_adapter(transport)
+        await adapter.start()
+        await asyncio.sleep(0.02)
+
+        for _ in range(2):
+            await adapter.send(
+                RemoteOutboundMessage(
+                    connection_id=uuid4(), destination_id="100", text="hi"
+                )
+            )
+
+        cleared = await adapter.clear_history("100")
+        await adapter.stop()
+
+        assert cleared == 2
+        delete_calls = [
+            payload for name, payload in transport.calls if name == "deleteMessage"
+        ]
+        assert {c["message_id"] for c in delete_calls} == {1, 2}
+        assert all(c["chat_id"] == "100" for c in delete_calls)
+
+    @pytest.mark.asyncio
+    async def test_clear_history_skips_a_message_telegram_refuses_to_delete(self):
+        transport = ScriptedTransport()
+        transport.queue(
+            "sendMessage",
+            _ok({"message_id": 1, "date": 1, "chat": {"id": 100, "type": "private"}}),
+        )
+        transport.queue(
+            "sendMessage",
+            _ok({"message_id": 2, "date": 1, "chat": {"id": 100, "type": "private"}}),
+        )
+        transport.queue(
+            "deleteMessage",
+            _err(400, 400, "Bad Request: message can't be deleted"),
+        )
+        adapter = _make_adapter(transport)
+        await adapter.start()
+        await asyncio.sleep(0.02)
+
+        for _ in range(2):
+            await adapter.send(
+                RemoteOutboundMessage(
+                    connection_id=uuid4(), destination_id="100", text="hi"
+                )
+            )
+
+        # First deleteMessage (for message_id=1) is scripted to fail (e.g.
+        # older than Telegram's 48h deletion window); the second must still
+        # be attempted rather than aborting the whole clear.
+        cleared = await adapter.clear_history("100")
+        await adapter.stop()
+
+        assert cleared == 1
+
+    @pytest.mark.asyncio
+    async def test_clear_history_is_a_no_op_for_an_unknown_destination(self):
+        transport = ScriptedTransport()
+        adapter = _make_adapter(transport)
+        await adapter.start()
+        await asyncio.sleep(0.02)
+
+        cleared = await adapter.clear_history("never-messaged")
+        await adapter.stop()
+
+        assert cleared == 0
+        assert not any(name == "deleteMessage" for name, _ in transport.calls)
+
     @pytest.mark.asyncio
     async def test_successful_send_marks_phone_reachable(self):
         transport = ScriptedTransport()
diff --git a/tests/remote/telegram/test_client.py b/tests/remote/telegram/test_client.py
index efdaaa8d..4acec048 100644
--- a/tests/remote/telegram/test_client.py
+++ b/tests/remote/telegram/test_client.py
@@ -362,6 +362,22 @@ def handler(request: httpx.Request) -> httpx.Response:
         ]
         await client.aclose()
 
+    @pytest.mark.asyncio
+    async def test_delete_message_sends_chat_id_and_message_id(self):
+        captured: dict[str, object] = {}
+
+        def handler(request: httpx.Request) -> httpx.Response:
+            import json
+
+            captured["payload"] = json.loads(request.content)
+            assert request.url.path.endswith("/deleteMessage")
+            return _ok(True)
+
+        client = _client(handler)
+        await client.delete_message(chat_id="1", message_id=42)
+        assert captured["payload"] == {"chat_id": "1", "message_id": 42}
+        await client.aclose()
+
 
 # ---------------------------------------------------------------------------
 # Safe error classification

From 7d336d190237b594228570a4f590184c9aca43c5 Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Tue, 15 Sep 2026 12:27:23 +0700
Subject: [PATCH 66/71] feat(remote): add /clear to delete this bot's recent
 messages

A deliberate, post-spec addition beyond the original control-surface
document's AC-58 command set, requested directly this session. Deletes
only messages the bot itself sent (Telegram's own restriction) via the
adapter's clear_history(); an adapter without that capability gets a
plain "can't clear messages" reply instead of an error.
---
 app/remote/actions.py        | 37 +++++++++++++++++++-
 tests/remote/test_actions.py | 65 ++++++++++++++++++++++++++++++++++++
 2 files changed, 101 insertions(+), 1 deletion(-)

diff --git a/app/remote/actions.py b/app/remote/actions.py
index 4ce2a279..caca2a8e 100644
--- a/app/remote/actions.py
+++ b/app/remote/actions.py
@@ -84,7 +84,7 @@ class _ActionCapability:
 _SLASH_COMMANDS: frozenset[str] = frozenset(
     {
         "start", "help", "status", "new", "stop", "unpair", "actions",
-        "settings", "health", "changes",
+        "settings", "health", "changes", "clear",
     }
 )
 
@@ -104,6 +104,7 @@ class _ActionCapability:
 /changes — See this task's file changes
 /actions — Run a saved workflow, open a coding project, or fire a \
 scheduled task
+/clear — Delete my recent messages in this chat (not yours)
 /unpair — Disconnect this phone from EvoFlux
 
 Send /help any time to see this again."""
@@ -202,6 +203,8 @@ async def dispatch_command(
             return await self._cmd_health(db, action)
         elif command == "changes":
             return await self._cmd_changes(db, action)
+        elif command == "clear":
+            return await self._cmd_clear(db, action)
         else:
             # Unknown command — return bounded help.
             return await self._cmd_help(db, action)
@@ -508,6 +511,38 @@ async def _cmd_changes(
         await self._send(action.principal.destination_id, text, buttons=buttons)
         return RemoteActionResult(status="ok", text=text)
 
+    async def _cmd_clear(
+        self, db: AsyncSession, action: RemoteInboundAction
+    ) -> RemoteActionResult:
+        """Delete this bot's own recent messages in the chat. Telegram
+        only lets a bot delete messages it sent, and only within 48 hours
+        (see TelegramAdapter.clear_history) — the user's own messages,
+        including the /clear command itself, are never touched. Does not
+        self-send: like /health, its text is delivered by runtime.py's
+        command fallback."""
+        pairing = await self._pairing_service.authorize(
+            db,
+            connection_id=action.connection_id,
+            principal_id=action.principal.principal_id,
+        )
+        if pairing is None:
+            return RemoteActionResult(status="unauthorized")
+
+        clear_history = getattr(self._adapter, "clear_history", None)
+        if clear_history is None:
+            return RemoteActionResult(
+                status="ok", text="This connection can't clear messages."
+            )
+
+        cleared = await clear_history(action.principal.destination_id)
+        text = (
+            f"Cleared {cleared} message(s)."
+            if cleared
+            else "Nothing to clear (either none sent, or too old for Telegram "
+            "to delete)."
+        )
+        return RemoteActionResult(status="ok", text=text)
+
     async def _cmd_new(
         self, db: AsyncSession, action: RemoteInboundAction
     ) -> RemoteActionResult:
diff --git a/tests/remote/test_actions.py b/tests/remote/test_actions.py
index 84cd60d7..3243e3c4 100644
--- a/tests/remote/test_actions.py
+++ b/tests/remote/test_actions.py
@@ -34,6 +34,8 @@ def __init__(self) -> None:
         self.acked_tokens: list[str] = []
         self.sent_texts: list[str] = []
         self.sent_messages: list = []
+        self.cleared_destinations: list[str] = []
+        self.clear_history_return_value: int = 3
 
     async def answer_callback(self, token: str) -> None:
         self.calls.append("answer_callback")
@@ -47,6 +49,11 @@ async def send(self, msg) -> None:
     async def edit(self, msg) -> None:
         self.calls.append("edit")
 
+    async def clear_history(self, destination_id: str) -> int:
+        self.calls.append("clear_history")
+        self.cleared_destinations.append(destination_id)
+        return self.clear_history_return_value
+
 
 def _make_action(
     *,
@@ -852,6 +859,64 @@ async def test_health_requires_authorization(
         assert result.status == "unauthorized"
 
 
+# ── Clear ─────────────────────────────────────────────────────────────────────
+
+
+class TestClear:
+    @pytest.mark.asyncio
+    async def test_clear_command_deletes_history_and_reports_the_count(
+        self, service: RemoteActionService, adapter: FakeAdapter
+    ) -> None:
+        mock_db = MagicMock()
+        action = _make_action(text="/clear")
+        adapter.clear_history_return_value = 5
+
+        with patch.object(
+            service._pairing_service, "authorize", return_value=MagicMock()
+        ):
+            result = await service.dispatch_command(mock_db, action)
+
+        assert result.status == "ok"
+        assert "5" in result.text
+        assert adapter.cleared_destinations == [action.principal.destination_id]
+
+    @pytest.mark.asyncio
+    async def test_clear_requires_authorization(
+        self, service: RemoteActionService
+    ) -> None:
+        mock_db = MagicMock()
+        action = _make_action(text="/clear")
+
+        with patch.object(service._pairing_service, "authorize", return_value=None):
+            result = await service.dispatch_command(mock_db, action)
+
+        assert result.status == "unauthorized"
+
+    @pytest.mark.asyncio
+    async def test_clear_on_an_adapter_without_clear_support_says_so(self) -> None:
+        class _NoClearAdapter:
+            async def send(self, msg) -> None:
+                pass
+
+            async def edit(self, msg) -> None:
+                pass
+
+            async def answer_callback(self, token: str) -> None:
+                pass
+
+        service = RemoteActionService(adapter=_NoClearAdapter())  # type: ignore[arg-type]
+        mock_db = MagicMock()
+        action = _make_action(text="/clear")
+
+        with patch.object(
+            service._pairing_service, "authorize", return_value=MagicMock()
+        ):
+            result = await service.dispatch_command(mock_db, action)
+
+        assert result.status == "ok"
+        assert "clear" in result.text.lower()
+
+
 # ── Changes ───────────────────────────────────────────────────────────────────
 
 

From 8d28ccc9fbfd9729a3b622fc8b53c975da61a747 Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Tue, 15 Sep 2026 12:28:13 +0700
Subject: [PATCH 67/71] feat(remote): advertise /clear in the command menu

---
 app/remote/telegram/adapter.py        | 6 ++++++
 tests/remote/telegram/test_adapter.py | 5 ++++-
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/app/remote/telegram/adapter.py b/app/remote/telegram/adapter.py
index 95e68fb0..a151310f 100644
--- a/app/remote/telegram/adapter.py
+++ b/app/remote/telegram/adapter.py
@@ -369,6 +369,11 @@ async def _register_commands(self) -> None:
 
         Best-effort: a paired user can still type any command by hand, so a
         failure here must never block the poll loop from starting.
+
+        ``clear`` is a deliberate addition beyond the control-surface
+        spec's original AC-58 bounded set (9 commands) — requested
+        directly by a user testing this feature live, after this set was
+        first implemented.
         """
         commands = [
             ("help", "What can I do here?"),
@@ -378,6 +383,7 @@ async def _register_commands(self) -> None:
             ("settings", "Change mode, model, agent, or response style"),
             ("health", "Check system health"),
             ("changes", "See this task's file changes"),
+            ("clear", "Delete my recent messages here"),
             ("actions", "Run a workflow, project, or schedule"),
             ("unpair", "Disconnect this phone"),
         ]
diff --git a/tests/remote/telegram/test_adapter.py b/tests/remote/telegram/test_adapter.py
index 48db0509..e4e16824 100644
--- a/tests/remote/telegram/test_adapter.py
+++ b/tests/remote/telegram/test_adapter.py
@@ -154,7 +154,9 @@ async def test_deletes_webhook_with_drop_pending_updates_before_first_poll(self)
         assert payload["drop_pending_updates"] is True
 
     @pytest.mark.asyncio
-    async def test_registers_exactly_the_ac58_bounded_command_set(self):
+    async def test_registers_exactly_the_bounded_command_set(self):
+        """AC-58's original 9-command set plus /clear, a deliberate
+        post-spec addition (see _register_commands's docstring)."""
         transport = ScriptedTransport()
         adapter = _make_adapter(transport)
         await _run_briefly(adapter)
@@ -170,6 +172,7 @@ async def test_registers_exactly_the_ac58_bounded_command_set(self):
             "settings",
             "health",
             "changes",
+            "clear",
             "actions",
             "unpair",
         ]

From 7407719a7c4cd2ebafb70a716726f2c61fba0a4b Mon Sep 17 00:00:00 2001
From: manhnguyen24-dev 
Date: Thu, 17 Sep 2026 21:57:54 +0700
Subject: [PATCH 68/71] feat(remote): add pairing codes, session history, and
 usage-footer fixes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds two new phone-facing commands: /pair (type an 8-digit code shown on
the desktop instead of clicking a deep link, with QR support) and
/history (browse and drill into recent sessions). Both are wired into
the Telegram command menu and /help alongside the existing set.

Fixes four bugs found during live Telegram testing (see
documents/plans/telegram-integration-testing-2026-09.md for the full
root-cause writeup):
- Tool log always showed "unknown: {}" — tool_calls are stored in
  OpenAI's nested {"function": {...}} shape, not flat.
- Cost never appeared — UsageEvent.cost is a dict of components, not a
  scalar.
- Model name never appeared — it lives in metadata.models, not a
  top-level field.
- Error cards dumped raw HTTP details instead of a friendly message.

Also adds a context-window/token/cost usage line to the done card, a
markdown-to-Telegram-HTML renderer for richer responses, and a new
remote_pairings migration (pair_code_hash/pair_code_expires_at).

Audit fixes applied while reviewing this batch before commit:
- tests/remote/telegram/test_adapter.py: a test asserted against an
  undefined `status` variable (broken since it was written) — added
  the missing `adapter.status()` call.
- app/remote/actions.py: the new /pair success path called
  set_active_pairing(pairing) with a single positional argument against
  a method requiring four keyword-only strings — would have raised
  TypeError on every successful code-pairing. Fixed to match the
  existing call pattern in runtime.py.
- app/api/routes/remote.py: revoke_pairing built a RemoteOutboundMessage
  with connection_id=str(connection_id) against a UUID-typed field —
  removed the unnecessary/incorrect str() coercion.
- app/remote/pairing.py: two SQLAlchemy `.is_not(None)` calls were
  suppressed with `# type: ignore[union-attr]`, which this project's
  `ty` checker doesn't recognize — switched to `# ty: ignore[...]`.
- app/remote/actions.py: removed an unused, already-stale `CommandName`
  Literal type alias (never referenced, and missing half the real
  commands) and its now-unused `Literal` import.
- app/remote/telegram/adapter.py: /pair and /history were dispatchable
  and in /help but missing from the Telegram command menu itself —
  same class of gap fixed for /settings/health/changes earlier tonight.
- Fixed a missing-space typo in /pair's usage message, and a pending
  ruff-format diff in gates.py.

Full tests/remote/ suite (all touched and pre-existing tests), ruff,
and ty all pass after these fixes.
---
 app/api/routes/remote.py                      |  57 ++-
 app/api/schemas/remote.py                     |  18 +
 app/core/schema_version.py                    |   2 +-
 ...00000067_add_remote_pairing_code_fields.py |  33 ++
 app/models/remote.py                          |  21 +-
 app/remote/actions.py                         | 351 ++++++++++++++++-
 app/remote/edit_budget.py                     |   2 +-
 app/remote/formatting.py                      | 308 ++++++++++++++-
 app/remote/gates.py                           |   5 +-
 app/remote/outbound.py                        | 135 ++++++-
 app/remote/pairing.py                         | 300 ++++++++++++++-
 app/remote/runtime.py                         |  46 ++-
 app/remote/telegram/adapter.py                |  28 +-
 app/remote/turn_activity.py                   |  11 +-
 documents/features/remote-access.md           |  39 +-
 .../telegram-integration-testing-2026-09.md   | 164 ++++++++
 tests/remote/telegram/test_adapter.py         |  90 ++++-
 tests/remote/test_actions.py                  | 364 +++++++++++++++++-
 tests/remote/test_formatting.py               | 211 ++++++++++
 tests/remote/test_inbound.py                  |   4 +-
 tests/remote/test_pairing.py                  | 360 +++++++++++++++--
 web/bun.lock                                  |  43 +--
 web/package.json                              |   1 +
 web/src/api/client/remote.ts                  |  15 +
 web/src/help/locales/en.ts                    |  44 +++
 web/src/queries/useRemoteQuery.ts             |  49 ++-
 web/src/routes/settings.remote-access.tsx     | 195 +++++++---
 27 files changed, 2692 insertions(+), 204 deletions(-)
 create mode 100644 app/migrations/versions/00000067_add_remote_pairing_code_fields.py
 create mode 100644 documents/plans/telegram-integration-testing-2026-09.md

diff --git a/app/api/routes/remote.py b/app/api/routes/remote.py
index 9aa935d2..8f60c5a8 100644
--- a/app/api/routes/remote.py
+++ b/app/api/routes/remote.py
@@ -20,6 +20,7 @@
 from sqlmodel.ext.asyncio.session import AsyncSession
 
 from app.api.schemas.remote import (
+    PairingCodeBody,
     RemoteConnectionCreateRequest,
     RemoteConnectionPatchRequest,
     RemoteConnectionResponse,
@@ -39,6 +40,8 @@
     RemoteCredentialError,
     default_credential_store_factory,
 )
+from loguru import logger
+
 from app.remote.contracts import RemoteAdapterValidationError
 from app.remote.pairing import PairingService, pairing_service as _pairing_service
 from app.remote.runtime import TelegramAdapterFactory, remote_runtime
@@ -287,11 +290,63 @@ async def revoke_pairing(
     pairing_service: PairingService = Depends(get_pairing_service),
 ) -> None:
     """Revoke the paired account (AC-10) — a later ``authorize`` call for
-    the former principal fails immediately, with no cache to invalidate."""
+    the former principal fails immediately, with no cache to invalidate.
+
+    Sends a notification message to the phone *before* removing the pairing
+    so the user sees an immediate explanation instead of a silent disconnect.
+    """
     await _connection_or_404(session, service, connection_id)
+    pairing = await _get_pairing(session, connection_id)
+    # Best-effort notification — if the adapter is stopped or send fails we
+    # still proceed with the unpair so the user isn't stuck.
+    if pairing is not None:
+        try:
+            adapter = remote_runtime.adapter
+            if adapter is not None:
+                from app.remote.contracts import (
+                    RemoteOutboundMessage,
+                    RemoteOutboundPriority,
+                )
+
+                await adapter.send(
+                    RemoteOutboundMessage(
+                        connection_id=connection_id,
+                        destination_id=pairing.destination_id,
+                        text="\u26a0\ufe0f This device has been unpaired from EvoFlux. Send /start to pair again.",
+                        buttons=(),
+                        priority=RemoteOutboundPriority.HIGH,
+                    )
+                )
+        except Exception:
+            logger.debug("remote_unpair_notify_failed connection_id={}", connection_id)
     await pairing_service.unpair(session, connection_id)
 
 
+@router.post(
+    "/connections/{connection_id}/pairing-codes",
+    response_model=PairingCodeBody,
+    status_code=201,
+)
+async def issue_pairing_code(
+    connection_id: uuid.UUID,
+    session: AsyncSession = Depends(get_session),
+    service: RemoteConnectionService = Depends(get_connection_service),
+    pairing_service: PairingService = Depends(get_pairing_service),
+) -> PairingCodeBody:
+    """Generate a one-time8-digit pairing code for a connection.
+
+    The phone user then types ``/pair `` in the Telegram bot to
+    complete pairing.  Any previously-pending code for this connection is
+    replaced.
+    """
+    await _connection_or_404(session, service, connection_id)
+    result = await pairing_service.issue_pair_code(session, connection_id)
+    return PairingCodeBody(
+        code_display=result.display_code,
+        expires_at=result.expires_at,
+    )
+
+
 # ── Status ────────────────────────────────────────────────────────────────
 
 
diff --git a/app/api/schemas/remote.py b/app/api/schemas/remote.py
index 5c7c7924..db46e89c 100644
--- a/app/api/schemas/remote.py
+++ b/app/api/schemas/remote.py
@@ -18,6 +18,7 @@
 from app.remote.contracts import RemoteConnectionState, RemoteErrorClass
 
 __all__ = [
+    "PairingCodeBody",
     "RemoteConnectionCreateRequest",
     "RemoteConnectionPatchRequest",
     "RemoteConnectionResponse",
@@ -115,6 +116,23 @@ class RemoteConnectionResponse(BaseModel):
     status: RemoteConnectionStatusBody
 
 
+class PairingCodeBody(BaseModel):
+    """``POST /api/remote/connections/{id}/pairing-codes`` response.
+
+    ``code_display`` is the user-facing8-digit code with a space separator
+    (e.g. ``"1234 5678"``).  ``expires_at`` is a wall-clock UTC timestamp
+    so the UI can render a countdown timer.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    code_display: str = Field(
+        description="User-facing pairing code with digit grouping, e.g. '1234 5678'.",
+        examples=["1234 5678"],
+    )
+    expires_at: datetime
+
+
 class RemotePairingLinkResponse(BaseModel):
     """``POST /api/remote/connections/{id}/pairing-links`` response."""
 
diff --git a/app/core/schema_version.py b/app/core/schema_version.py
index 45911d53..1db9d9b3 100644
--- a/app/core/schema_version.py
+++ b/app/core/schema_version.py
@@ -13,7 +13,7 @@
 # Keep this in sync with the single Alembic head. The migration tests and the
 # sidecar build validate the value, so a release cannot silently ship a stale
 # marker.
-SCHEMA_HEAD = "00000066"
+SCHEMA_HEAD = "00000067"
 
 
 @dataclass(frozen=True)
diff --git a/app/migrations/versions/00000067_add_remote_pairing_code_fields.py b/app/migrations/versions/00000067_add_remote_pairing_code_fields.py
new file mode 100644
index 00000000..b4befb0c
--- /dev/null
+++ b/app/migrations/versions/00000067_add_remote_pairing_code_fields.py
@@ -0,0 +1,33 @@
+"""Add remote_pairings pair_code_hash and pair_code_expires_at
+
+Revision ID: 00000067
+Revises: 00000066
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "00000067"
+down_revision: str | Sequence[str] | None = "00000066"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "remote_pairings",
+        sa.Column("pair_code_hash", sa.String(128), nullable=True),
+    )
+    op.add_column(
+        "remote_pairings",
+        sa.Column("pair_code_expires_at", sa.DateTime(), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("remote_pairings", "pair_code_expires_at")
+    op.drop_column("remote_pairings", "pair_code_hash")
diff --git a/app/models/remote.py b/app/models/remote.py
index 7f6f605c..ce6bb65a 100644
--- a/app/models/remote.py
+++ b/app/models/remote.py
@@ -23,9 +23,7 @@ class RemoteConnection(SQLModel, table=True):
         default=False,
         sa_column=Column(sa.Boolean(), nullable=False, server_default=sa.false()),
     )
-    adapter_principal_id: str = Field(
-        sa_column=Column(sa.String(128), nullable=False)
-    )
+    adapter_principal_id: str = Field(sa_column=Column(sa.String(128), nullable=False))
     adapter_username: str = Field(
         default="",
         sa_column=Column(sa.String(128), nullable=False, server_default=""),
@@ -75,8 +73,8 @@ class RemotePairing(SQLModel, table=True):
         sa_column=Column(sa.String(20), nullable=False, server_default="all"),
     )
     response_mode: str = Field(
-        default="summary",
-        sa_column=Column(sa.String(20), nullable=False, server_default="summary"),
+        default="live",
+        sa_column=Column(sa.String(20), nullable=False, server_default="live"),
     )
     active_session_id: UUID | None = Field(
         default=None,
@@ -89,6 +87,19 @@ class RemotePairing(SQLModel, table=True):
     created_at: datetime = Field(
         default_factory=_utcnow, sa_column=Column(TZDateTime(), nullable=False)
     )
+    #: Optional phone-first pairing code hash (bcrypt).  Nullable so existing
+    #: deep-link pairings and rows created before the phone-first flow are
+    #: unaffected.
+    pair_code_hash: str | None = Field(
+        default=None,
+        sa_column=Column(sa.String(128), nullable=True),
+    )
+    #: Wall-clock UTC expiry for the pairing code.  Nullable for the same
+    #: reason as ``pair_code_hash``.
+    pair_code_expires_at: datetime | None = Field(
+        default=None,
+        sa_column=Column(TZDateTime(), nullable=True),
+    )
     last_seen_at: datetime = Field(
         default_factory=_utcnow, sa_column=Column(TZDateTime(), nullable=False)
     )
diff --git a/app/remote/actions.py b/app/remote/actions.py
index caca2a8e..bf86ef40 100644
--- a/app/remote/actions.py
+++ b/app/remote/actions.py
@@ -19,7 +19,7 @@
 import secrets
 import time
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Literal
+from typing import TYPE_CHECKING
 from uuid import UUID
 
 from loguru import logger
@@ -32,7 +32,12 @@
     RemoteOutboundMessage,
     RemoteOutboundPriority,
 )
-from app.remote.pairing import PairingService
+from app.remote.pairing import (
+    PairingCodeExpired,
+    PairingCodeMismatch,
+    PairingCodeRateLimited,
+    PairingService,
+)
 
 if TYPE_CHECKING:
     from app.remote import control
@@ -45,8 +50,6 @@
 _CAPABILITY_TTL_SECONDS = 600
 _TELEGRAM_MAX_MESSAGE_LENGTH = 4096
 
-CommandName = Literal["start", "help", "status", "new", "stop", "unpair", "actions"]
-
 
 @dataclass(frozen=True)
 class RemoteActionResult:
@@ -83,8 +86,19 @@ class _ActionCapability:
 
 _SLASH_COMMANDS: frozenset[str] = frozenset(
     {
-        "start", "help", "status", "new", "stop", "unpair", "actions",
-        "settings", "health", "changes", "clear",
+        "start",
+        "help",
+        "status",
+        "new",
+        "stop",
+        "unpair",
+        "actions",
+        "settings",
+        "health",
+        "changes",
+        "clear",
+        "pair",
+        "history",
     }
 )
 
@@ -101,11 +115,13 @@ class _ActionCapability:
 /stop — Interrupt the agent while it's working on your last message
 /settings — Change mode, model, agent, or response style
 /health — Check system health
+/history — Browse recent chat sessions
 /changes — See this task's file changes
 /actions — Run a saved workflow, open a coding project, or fire a \
 scheduled task
 /clear — Delete my recent messages in this chat (not yours)
 /unpair — Disconnect this phone from EvoFlux
+/pair — Connect this phone with a code from EvoFlux
 
 Send /help any time to see this again."""
 
@@ -195,6 +211,8 @@ async def dispatch_command(
             return await self._cmd_stop(db, action)
         elif command == "unpair":
             return await self._cmd_unpair(db, action)
+        elif command == "pair":
+            return await self._cmd_pair(db, action, arg)
         elif command == "actions":
             return await self._cmd_actions(db, action, arg)
         elif command == "settings":
@@ -205,6 +223,8 @@ async def dispatch_command(
             return await self._cmd_changes(db, action)
         elif command == "clear":
             return await self._cmd_clear(db, action)
+        elif command == "history":
+            return await self._cmd_history(db, action)
         else:
             # Unknown command — return bounded help.
             return await self._cmd_help(db, action)
@@ -265,6 +285,13 @@ async def handle_action_callback(
     async def _cmd_help(
         self, db: AsyncSession, action: RemoteInboundAction
     ) -> RemoteActionResult:
+        pairing = await self._pairing_service.authorize(
+            db,
+            connection_id=action.connection_id,
+            principal_id=action.principal.principal_id,
+        )
+        if pairing is None:
+            return RemoteActionResult(status="unauthorized")
         return RemoteActionResult(status="ok", text=_HELP_TEXT)
 
     async def _cmd_status(
@@ -342,7 +369,9 @@ async def _cmd_settings(
         }
         model_ids = await control.list_model_ids(app_mode)
         model_tokens = {
-            model_id: self._issue_settings_token(action, session_id, "set_model", model_id)
+            model_id: self._issue_settings_token(
+                action, session_id, "set_model", model_id
+            )
             for model_id in model_ids
         }
         response_mode_tokens = {
@@ -500,9 +529,7 @@ async def _cmd_changes(
 
         text, buttons = render_changes_card(
             title=session.title or "Task",
-            files=[
-                (f.path, f.status, f.additions, f.deletions) for f in bounded_files
-            ],
+            files=[(f.path, f.status, f.additions, f.deletions) for f in bounded_files],
             additions=snapshot.additions,
             deletions=snapshot.deletions,
             file_tokens=file_tokens,
@@ -569,6 +596,245 @@ async def _cmd_stop(
             return RemoteActionResult(status="ok", text="No active task to stop.")
         return RemoteActionResult(status="ok", text="Task stopped.")
 
+    async def _cmd_history(
+        self, db: AsyncSession, action: RemoteInboundAction
+    ) -> RemoteActionResult:
+        """List recent sessions with inline buttons to inspect each one."""
+        from app.services.chat_service import list_sessions_page
+
+        sessions, _cursor, _has_more = await list_sessions_page(db, limit=5)
+        if not sessions:
+            return RemoteActionResult(status="ok", text="No sessions yet.")
+
+        items: list[dict[str, str]] = []
+        for s in sessions:
+            token = self._issue_token(
+                action_kind="session_detail",
+                action_target=str(s.id),
+                connection_id=action.connection_id,
+                principal_id=action.principal.principal_id,
+                destination_id=action.principal.destination_id,
+                session_id="",
+            )
+            from datetime import UTC, datetime as _dt
+
+            now = _dt.now(UTC)
+            age = now - (s.updated_at or s.created_at or now)
+            hours = int(age.total_seconds() // 3600)
+            if hours < 1:
+                time_label = "just now"
+            elif hours < 24:
+                time_label = f"{hours}h ago"
+            else:
+                days = hours // 24
+                time_label = f"{days}d ago"
+            title = s.title or "Untitled"
+            items.append({"title": f"{title} · {time_label}", "token": token})
+
+        from app.remote.formatting import render_session_list_card
+
+        text, buttons = render_session_list_card(items)
+        await self._send(action.principal.destination_id, text, buttons=buttons)
+        return RemoteActionResult(status="ok")
+
+    async def _exec_session_detail(
+        self, cap: _ActionCapability, action: RemoteInboundAction, db: AsyncSession
+    ) -> bool:
+        """Show details for one session."""
+        from app.models.chat import ChatSession, SessionMessage
+        from app.remote.formatting import render_session_detail_card
+        from sqlmodel import col, func, select
+
+        session_id_str = cap.action_target
+        try:
+            session_id = UUID(session_id_str)
+        except ValueError:
+            await self._reply_text(
+                action.principal.destination_id, "Invalid session id."
+            )
+            return True
+        session = await db.get(ChatSession, session_id)
+        if session is None:
+            await self._reply_text(
+                action.principal.destination_id, "Session not found."
+            )
+            return True
+
+        # Count messages and tool calls.
+        msg_count = (
+            await db.exec(
+                select(func.count()).where(
+                    col(SessionMessage.session_id) == session_id,
+                    col(SessionMessage.exclude_from_context).is_(False),
+                    col(SessionMessage.is_summary).is_(False),
+                )
+            )
+        ).one()
+        tool_count = (
+            await db.exec(
+                select(func.count()).where(
+                    col(SessionMessage.session_id) == session_id,
+                    col(SessionMessage.role) == "tool",
+                )
+            )
+        ).one()
+
+        # Get last user and assistant messages.
+        last_user = (
+            await db.exec(
+                select(SessionMessage)
+                .where(
+                    col(SessionMessage.session_id) == session_id,
+                    col(SessionMessage.role) == "user",
+                    col(SessionMessage.exclude_from_context).is_(False),
+                )
+                .order_by(col(SessionMessage.created_at).desc())
+                .limit(1)
+            )
+        ).first()
+        last_assistant = (
+            await db.exec(
+                select(SessionMessage)
+                .where(
+                    col(SessionMessage.session_id) == session_id,
+                    col(SessionMessage.role) == "assistant",
+                    col(SessionMessage.exclude_from_context).is_(False),
+                    col(SessionMessage.is_summary).is_(False),
+                )
+                .order_by(col(SessionMessage.created_at).desc())
+                .limit(1)
+            )
+        ).first()
+
+        from datetime import UTC, datetime as _dt
+
+        created = session.created_at or _dt.now(UTC)
+        age = _dt.now(UTC) - created
+        hours = int(age.total_seconds() // 3600)
+        if hours < 1:
+            time_label = "just now"
+        elif hours < 24:
+            time_label = f"{hours}h ago"
+        else:
+            days = hours // 24
+            time_label = f"{days}d ago"
+
+        switch_token = self._issue_token(
+            action_kind="session_switch",
+            action_target=str(session.id),
+            connection_id=action.connection_id,
+            principal_id=action.principal.principal_id,
+            destination_id=action.principal.destination_id,
+            session_id="",
+        )
+        summarize_token = self._issue_token(
+            action_kind="session_summarize",
+            action_target=str(session.id),
+            connection_id=action.connection_id,
+            principal_id=action.principal.principal_id,
+            destination_id=action.principal.destination_id,
+            session_id="",
+        )
+
+        text, buttons = render_session_detail_card(
+            title=session.title or "Untitled",
+            mode=session.mode,
+            created_at=time_label,
+            message_count=msg_count or 0,
+            tool_call_count=tool_count or 0,
+            last_user_message=last_user.content[:500]
+            if last_user and last_user.content
+            else None,
+            last_assistant_message=last_assistant.content[:500]
+            if last_assistant and last_assistant.content
+            else None,
+            switch_token=switch_token,
+            summarize_token=summarize_token,
+        )
+        await self._send(action.principal.destination_id, text, buttons=buttons)
+        return True
+
+    async def _exec_session_switch(
+        self, cap: _ActionCapability, action: RemoteInboundAction, db: AsyncSession
+    ) -> bool:
+        """Switch the active session to the selected one."""
+        from app.models.chat import ChatSession
+
+        session_id = cap.action_target
+        try:
+            session_uuid = UUID(session_id)
+        except ValueError:
+            await self._reply_text(
+                action.principal.destination_id, "Invalid session id."
+            )
+            return True
+        session = await db.get(ChatSession, session_uuid)
+        if session is None:
+            await self._reply_text(
+                action.principal.destination_id, "Session not found."
+            )
+            return True
+
+        pairing = await self._pairing_service.authorize(
+            db,
+            connection_id=action.connection_id,
+            principal_id=action.principal.principal_id,
+        )
+        if pairing is None:
+            await self._reply_text(action.principal.destination_id, "Not paired.")
+            return True
+
+        pairing.active_session_id = session.id
+        db.add(pairing)
+        await db.commit()
+
+        title = session.title or "Untitled"
+        await self._reply_text(
+            action.principal.destination_id,
+            f"\u2705 Switched to: {title}\nNext message continues this session.",
+        )
+        return True
+
+    async def _exec_session_summarize(
+        self, cap: _ActionCapability, action: RemoteInboundAction, db: AsyncSession
+    ) -> bool:
+        """Show a condensed transcript of the selected session."""
+        from app.models.chat import SessionMessage
+        from sqlmodel import col, select
+
+        session_id = UUID(cap.action_target)
+        messages = (
+            await db.exec(
+                select(SessionMessage)
+                .where(
+                    col(SessionMessage.session_id) == session_id,
+                    col(SessionMessage.exclude_from_context).is_(False),
+                    col(SessionMessage.is_summary).is_(False),
+                    col(SessionMessage.role).in_(["user", "assistant"]),
+                )
+                .order_by(col(SessionMessage.created_at))
+                .limit(20)
+            )
+        ).all()
+
+        if not messages:
+            await self._reply_text(
+                action.principal.destination_id, "No messages in this session."
+            )
+            return True
+
+        lines: list[str] = ["\U0001f4dd Session transcript", ""]
+        for msg in messages:
+            role_icon = "\U0001f464" if msg.role == "user" else "\U0001f916"
+            content = (msg.content or "")[:200]
+            if len(msg.content or "") > 200:
+                content += "\u2026"
+            lines.append(f"{role_icon} {formatting.markdown_to_telegram_html(content)}")
+        text = "\n".join(lines)
+        await self._reply_text(action.principal.destination_id, text)
+        return True
+        return True
+
     async def _cmd_unpair(
         self, db: AsyncSession, action: RemoteInboundAction
     ) -> RemoteActionResult:
@@ -581,6 +847,53 @@ async def _cmd_unpair(
             )
         return RemoteActionResult(status="ok", text="No active pairing to remove.")
 
+    async def _cmd_pair(
+        self, db: AsyncSession, action: RemoteInboundAction, arg: str
+    ) -> RemoteActionResult:
+        """Verify a phone-submitted pairing code (``/pair ``).
+
+        On success the connection is paired; on failure the user sees a
+        short diagnostic message.
+        """
+        code = arg.strip()
+        if not code or not code.isdigit():
+            return RemoteActionResult(
+                status="pair_bad_format",
+                text="Send /pair followed by the 8-digit code shown on your desktop. Example: /pair 12345678",
+            )
+
+        try:
+            pairing = await self._pairing_service.verify_pair_code(
+                db,
+                connection_id=action.connection_id,
+                principal=action.principal,
+                raw_code=code,
+            )
+        except PairingCodeExpired:
+            return RemoteActionResult(
+                status="pair_expired",
+                text="Code expired. Open EvoFlux and generate a new one.",
+            )
+        except PairingCodeMismatch:
+            return RemoteActionResult(
+                status="pair_mismatch",
+                text="That code didn't match. Check the code and try again.",
+            )
+        except PairingCodeRateLimited:
+            return RemoteActionResult(
+                status="pair_rate_limited",
+                text="Too many attempts. Wait a moment and try again.",
+            )
+
+        if self._projection is not None:
+            self._projection.set_active_pairing(
+                connection_id=str(action.connection_id),
+                destination_id=pairing.destination_id,
+                notify_scope=pairing.notify_scope,
+                principal_id=pairing.principal_id,
+            )
+        return RemoteActionResult(status="pair_ok", text="Phone connected.")
+
     async def _cmd_actions(
         self, db: AsyncSession, action: RemoteInboundAction, arg: str
     ) -> RemoteActionResult:
@@ -753,6 +1066,12 @@ async def _execute_action(
             return await self._exec_onboarding_start(cap, action, db)
         elif cap.action_kind == "changes_diff":
             return await self._exec_changes_diff(cap, action, db)
+        elif cap.action_kind == "session_detail":
+            return await self._exec_session_detail(cap, action, db)
+        elif cap.action_kind == "session_switch":
+            return await self._exec_session_switch(cap, action, db)
+        elif cap.action_kind == "session_summarize":
+            return await self._exec_session_summarize(cap, action, db)
         return False
 
     async def _exec_workflow_start(
@@ -838,10 +1157,18 @@ async def _exec_coding_task(
 
             # Create a coding session for this project.
             from app.services.chat_service import create_chat_session
+            from app.services.coding_project_service import (
+                get_project_workspace_paths,
+            )
 
             chat = await create_chat_session(db)
             chat.mode = "coding"
             chat.project_id = project.id
+            # Set the primary workspace so resolve_team_for_session takes
+            # the coding branch (it checks session.workspace is truthy).
+            paths = await get_project_workspace_paths(db, project.id)
+            if paths:
+                chat.workspace = paths[0]
             chat.tags = [
                 "remote_origin",
                 f"remote_connection:{cap.connection_id}",
@@ -955,7 +1282,9 @@ async def _exec_set_mode(
     ) -> bool:
         from app.remote import control
 
-        result = await control.set_permission_mode(db, cap.session_id, cap.action_target)
+        result = await control.set_permission_mode(
+            db, cap.session_id, cap.action_target
+        )
         await self._reply_control_result(
             action, result, f"Mode set to {cap.action_target}."
         )
diff --git a/app/remote/edit_budget.py b/app/remote/edit_budget.py
index 92a53210..ec4d0589 100644
--- a/app/remote/edit_budget.py
+++ b/app/remote/edit_budget.py
@@ -20,7 +20,7 @@
 
 __all__ = ["EditBudget", "LIVE_EDIT_INTERVAL"]
 
-LIVE_EDIT_INTERVAL = 3.0
+LIVE_EDIT_INTERVAL = 2.0
 
 
 @dataclass
diff --git a/app/remote/formatting.py b/app/remote/formatting.py
index ab637269..caac0e11 100644
--- a/app/remote/formatting.py
+++ b/app/remote/formatting.py
@@ -1,13 +1,16 @@
 from __future__ import annotations
 
 import html
+import re
 from collections.abc import Mapping, Sequence
 
 from app.remote.contracts import RemoteButton
 
 __all__ = [
+    "derive_card_heading",
     "escape",
     "format_elapsed",
+    "markdown_to_telegram_html",
     "render_status_card",
     "render_done_card",
     "render_error_card",
@@ -23,9 +26,15 @@
     "render_onboarding_card",
 ]
 
+_CARD_HEADING_MAX_LENGTH = 60
+
 _STATUS_ICON = {"accepted": "\U0001f527", "queued": "⏳", "pending": "⏳"}
 
-_SEVERITY_ICON = {"high": "\U0001f534", "elevated": "\U0001f7e0", "normal": "\U0001f527"}
+_SEVERITY_ICON = {
+    "high": "\U0001f534",
+    "elevated": "\U0001f7e0",
+    "normal": "\U0001f527",
+}
 _SEVERITY_LABEL = {
     "high": "Dangerous command",
     "elevated": "Command",
@@ -45,28 +54,171 @@ def escape(value: str) -> str:
     return html.escape(value, quote=False)
 
 
+def _format_token_count(n: int) -> str:
+    """Format a token count as a human-readable short string.
+
+    Examples: 128000 → "128K", 1000000 → "1M", 200000 → "200K".
+    """
+    if n >= 1_000_000:
+        return f"{n / 1_000_000:.0f}M"
+    if n >= 1_000:
+        return f"{n // 1_000:,}K"
+    return str(n)
+
+
+# ── Markdown → Telegram HTML ─────────────────────────────────────────────────
+#
+# Telegram supports a strict HTML subset: , , , , , 
,
+# , , 
.  No Markdown parse mode is used;
+# the adapter always sends ``parse_mode="HTML"``.
+#
+# The converter runs AFTER HTML-escaping, so literal ``<`` / ``>`` / ``&`` in
+# the source Markdown are already ``<`` / ``>`` / ``&`` and will
+# not collide with the HTML tags we inject.
+
+# Placeholder used to protect pre-escaped code spans from later regex passes.
+_CODE_SLOT = "\x00CODE{}\x00"
+_CODE_SLOT_RE = re.compile(r"\x00CODE(\d+)\x00")
+
+
+def markdown_to_telegram_html(text: str) -> str:
+    """Convert a Markdown string to Telegram-safe HTML.
+
+    The input is first HTML-escaped so literal ``<`` / ``>`` are safe.
+    Markdown constructs are then converted to the Telegram HTML subset.
+    Code blocks and inline code are protected from inner conversions.
+    """
+    if not text:
+        return ""
+
+    # 1. HTML-escape everything first.
+    out = html.escape(text, quote=False)
+
+    # 2. Protect fenced code blocks: ```lang\n...\n```  →  
...

+    code_slots: list[str] = []
+
+    def _code_repl(m: re.Match) -> str:
+        lang = m.group(1) or ""
+        body = m.group(2)
+        if lang:
+            tag = f'
{body}
'
+        else:
+            tag = f"
{body}
"
+        idx = len(code_slots)
+        code_slots.append(tag)
+        return _CODE_SLOT.format(idx)
+
+    out = re.sub(
+        r"```(\w*)\n(.*?)```",
+        _code_repl,
+        out,
+        flags=re.DOTALL,
+    )
+
+    # 3. Protect inline code: `...`  →  ...
+    def _inline_repl(m: re.Match) -> str:
+        idx = len(code_slots)
+        code_slots.append(f"{m.group(1)}")
+        return _CODE_SLOT.format(idx)
+
+    out = re.sub(r"`([^`\n]+)`", _inline_repl, out)
+
+    # 4. Headings: # / ## / ### → bold line
+    out = re.sub(r"^#{1,6}\s+(.+)$", r"\1", out, flags=re.MULTILINE)
+
+    # 5. Bold + italic: ***text*** → text
+    out = re.sub(r"\*\*\*(.+?)\*\*\*", r"\1", out)
+
+    # 6. Bold: **text** or __text__ → text
+    out = re.sub(r"\*\*(.+?)\*\*", r"\1", out)
+    out = re.sub(r"__(.+?)__", r"\1", out)
+
+    # 7. Italic: *text* or _text_ → text
+    #    Avoid matching * inside words (e.g. file_path*) by requiring a
+    #    word boundary or whitespace before the opening *.
+    out = re.sub(r"(?\1", out)
+    out = re.sub(r"(?\1", out)
+
+    # 8. Strikethrough: ~~text~~ → text
+    out = re.sub(r"~~(.+?)~~", r"\1", out)
+
+    # 9. Links: [text](url) → text
+    out = re.sub(
+        r"\[([^\]]+)\]\(([^)]+)\)",
+        r'\1',
+        out,
+    )
+
+    # 10. Unordered list: - item or * item → • item
+    out = re.sub(r"^[\-\*]\s+", "• ", out, flags=re.MULTILINE)
+
+    # 11. Restore protected code slots.
+    out = _CODE_SLOT_RE.sub(lambda m: code_slots[int(m.group(1))], out)
+
+    return out
+
+
 def format_elapsed(seconds: float) -> str:
     total = max(0, int(seconds))
     minutes, secs = divmod(total, 60)
     return f"{minutes}m {secs}s" if minutes else f"{secs}s"
 
 
-def render_status_card(*, title: str, status: str) -> tuple[str, tuple[RemoteButton, ...]]:
+def derive_card_heading(
+    user_message: str | None,
+    fallback_title: str = "Task",
+) -> str:
+    """Derive a concise, meaningful card heading.
+
+    Prefers a truncated version of the user's original message (which is
+    always concrete and contextual) over a session title that is often
+    generic ("Task", "New task") or an LLM-generated title that may not
+    have been generated yet.
+    """
+    if user_message and user_message.strip():
+        text = user_message.strip().replace("\n", " ")
+        if len(text) > _CARD_HEADING_MAX_LENGTH:
+            return text[: _CARD_HEADING_MAX_LENGTH - 1].rstrip() + "\u2026"
+        return text
+    return fallback_title
+
+
+def render_status_card(
+    *, title: str, status: str
+) -> tuple[str, tuple[RemoteButton, ...]]:
     icon = _STATUS_ICON.get(status, "\U0001f527")
     text = f"{icon} {escape(title)}\n{escape(status)}"
     return text, ()
 
 
 def render_live_status_card(
-    *, title: str, elapsed_seconds: float, activity_lines: Sequence[str]
+    *,
+    title: str,
+    elapsed_seconds: float,
+    activity_lines: Sequence[str],
+    model: str | None = None,
+    input_tokens: int | None = None,
+    output_tokens: int | None = None,
+    cost_usd: float | None = None,
 ) -> tuple[str, tuple[RemoteButton, ...]]:
     """The single status card a live-mode turn edits in place (AC-56). No
     buttons — like ``render_status_card``, this card is never actionable;
     when the turn ends this same message becomes the done/error card."""
     header = f"\U0001f527 {escape(title)} · {format_elapsed(elapsed_seconds)}"
-    if not activity_lines:
-        return header, ()
-    return header + "\n\n" + "\n".join(activity_lines), ()
+    parts = [header]
+    # Token / model footer — only shown once the first usage data arrives.
+    meta_parts: list[str] = []
+    if model:
+        meta_parts.append(escape(model))
+    if input_tokens is not None or output_tokens is not None:
+        meta_parts.append(f"{input_tokens or 0:,} \u2192 {output_tokens or 0:,} tok")
+    if cost_usd is not None and cost_usd > 0:
+        meta_parts.append(f"${cost_usd:.4f}")
+    if meta_parts:
+        parts.append("\U0001f4ca " + " \u00b7 ".join(meta_parts))
+    if activity_lines:
+        parts.append("\n".join(activity_lines))
+    return "\n\n".join(parts), ()
 
 
 def render_done_card(
@@ -78,15 +230,67 @@ def render_done_card(
     tool_call_count: int,
     diff_token: str | None,
     toollog_token: str | None,
+    model: str | None = None,
+    context_window: int | None = None,
+    input_tokens: int | None = None,
+    output_tokens: int | None = None,
+    cached_tokens: int | None = None,
+    reasoning_tokens: int | None = None,
+    cost_usd: float | None = None,
 ) -> tuple[str, tuple[RemoteButton, ...]]:
     header = f"✅ {escape(title)} · {format_elapsed(elapsed_seconds)}"
     lines = [escape(line) for line in summary_lines]
     parts = [header]
     if response_text and response_text.strip():
-        parts.append(escape(response_text.strip()))
+        parts.append(markdown_to_telegram_html(response_text.strip()))
     if lines:
         parts.append("\n".join(lines))
     parts.append(f"{tool_call_count} tool calls")
+
+    # ── Usage footer ─────────────────────────────────────────────────
+    # Build a compact multi-line usage block instead of a single dense
+    # dot-separated line, giving each dimension room to breathe.
+    usage_lines: list[str] = []
+    total_tokens = (input_tokens or 0) + (output_tokens or 0)
+
+    # Line 1: model name
+    if model:
+        usage_lines.append(escape(model))
+
+    # Line 2: token summary — "📊 2.4k → 1.1k" with cache/reasoning callouts
+    if total_tokens > 0:
+        tok_parts: list[str] = []
+        tok_parts.append(f"↓{_format_token_count(input_tokens or 0)}")
+        tok_parts.append(f"↑{_format_token_count(output_tokens or 0)}")
+        tok_line = "\U0001f4ca " + " ".join(tok_parts)
+
+        sub_parts: list[str] = []
+        if cached_tokens and cached_tokens > 0 and (input_tokens or 0) > 0:
+            hit_pct = cached_tokens / (input_tokens or 1) * 100
+            sub_parts.append(
+                f"cache {_format_token_count(cached_tokens)} ({hit_pct:.0f}%)"
+            )
+        if reasoning_tokens and reasoning_tokens > 0:
+            sub_parts.append(f"reasoning {_format_token_count(reasoning_tokens)}")
+        if sub_parts:
+            tok_line += " · " + " · ".join(sub_parts)
+        usage_lines.append(tok_line)
+
+    # Line 3: context window usage bar
+    if context_window and context_window > 0 and (input_tokens or 0) > 0:
+        used_pct = min((input_tokens or 0) / context_window * 100, 100)
+        filled = round(used_pct / 5)  # 20 bars = 100%
+        bar = "\u2588" * filled + "\u2591" * (20 - filled)
+        usage_lines.append(
+            f"{_format_token_count(context_window)} ctx [{bar}] {used_pct:.0f}%"
+        )
+
+    # Line 4: cost — show component breakdown when available
+    if cost_usd is not None and cost_usd > 0:
+        usage_lines.append(f"\U0001f4b0 ${cost_usd:.4f}")
+
+    if usage_lines:
+        parts.append("\n".join(usage_lines))
     text = "\n\n".join(parts)
     buttons: list[RemoteButton] = []
     if diff_token:
@@ -96,10 +300,32 @@ def render_done_card(
     return text, tuple(buttons)
 
 
+def _sanitize_error_message(message: str) -> str:
+    """Make common provider errors more user-friendly.
+
+    Strips internal provider details and HTTP status codes that confuse
+    non-technical users while preserving enough to diagnose the issue.
+    """
+    # Model unavailable errors — show a clean message.
+    if (
+        "model is unavailable" in message.lower()
+        or "rejected the request" in message.lower()
+    ):
+        # Extract model name if present (e.g. "opencode:deepseek-v4-flash-free")
+        import re
+
+        model_match = re.search(r"(\w+:[\w-]+)\s+rejected", message)
+        if model_match:
+            return f"Model {escape(model_match.group(1))} is currently unavailable. Check your provider dashboard or try a different model."
+        return "The selected model is currently unavailable. Check your provider dashboard or try a different model."
+    return escape(message)
+
+
 def render_error_card(
     *, title: str, message: str, toollog_token: str | None
 ) -> tuple[str, tuple[RemoteButton, ...]]:
-    text = f"❌ {escape(title)}\n\nError: {escape(message)}"
+    friendly = _sanitize_error_message(message)
+    text = f"❌ {escape(title)}\n\nError: {friendly}"
     buttons = (
         (RemoteButton(text="\U0001f9fe Tool log", token=toollog_token),)
         if toollog_token
@@ -151,7 +377,9 @@ def render_gate_card(
     *, title: str, body: str, actions: Sequence[tuple[str, str]]
 ) -> tuple[str, tuple[RemoteButton, ...]]:
     text = f"\U0001f510 {escape(title)}\n{escape(body)}"
-    buttons = tuple(RemoteButton(text=escape(label), token=token) for token, label in actions)
+    buttons = tuple(
+        RemoteButton(text=escape(label), token=token) for token, label in actions
+    )
     return text, buttons
 
 
@@ -285,8 +513,12 @@ def render_prompt_suggestions(
     )
     buttons: list[RemoteButton] = []
     if continue_token:
-        buttons.append(RemoteButton(text="▶ Continue last session", token=continue_token))
-    buttons += [RemoteButton(text=escape(label), token=token) for token, label in suggestions]
+        buttons.append(
+            RemoteButton(text="▶ Continue last session", token=continue_token)
+        )
+    buttons += [
+        RemoteButton(text=escape(label), token=token) for token, label in suggestions
+    ]
     return text, tuple(buttons)
 
 
@@ -326,3 +558,57 @@ def render_changes_card(
         for path, token in file_tokens.items()
     )
     return text, buttons
+
+
+def render_session_list_card(
+    sessions: Sequence[Mapping[str, str]],
+) -> tuple[str, tuple[RemoteButton, ...]]:
+    """Render a session-history list card.
+
+    Each item in *sessions* must have ``title``, ``subtitle``, and ``token``.
+    Returns text with a header and up to 5 inline buttons.
+    """
+    parts = ["\U0001f4cb Recent sessions"]
+    buttons: list[RemoteButton] = []
+    for item in sessions:
+        label = escape(item.get("title", "Untitled"))
+        buttons.append(RemoteButton(text=label, token=item["token"]))
+    if not buttons:
+        parts.append("No sessions yet.")
+    return "\n\n".join(parts), tuple(buttons)
+
+
+def render_session_detail_card(
+    *,
+    title: str,
+    mode: str,
+    created_at: str,
+    message_count: int,
+    tool_call_count: int,
+    last_user_message: str | None,
+    last_assistant_message: str | None,
+    switch_token: str | None,
+    summarize_token: str | None,
+) -> tuple[str, tuple[RemoteButton, ...]]:
+    """Render a single session's detail card with optional action buttons."""
+    parts = [
+        f"\U0001f4c4 {escape(title)}",
+        f"Mode: {escape(mode)} · Created: {escape(created_at)}",
+        f"{message_count} messages · {tool_call_count} tool calls",
+    ]
+    if last_user_message:
+        truncated = last_user_message[:200]
+        if len(last_user_message) > 200:
+            truncated += "\u2026"
+        parts.append(f"\U0001f464 {escape(truncated)}")
+    if last_assistant_message:
+        truncated = last_assistant_message[:200]
+        if len(last_assistant_message) > 200:
+            truncated += "\u2026"
+        parts.append(f"\U0001f916 {markdown_to_telegram_html(truncated)}")
+    buttons: list[RemoteButton] = []
+    if switch_token:
+        buttons.append(RemoteButton(text="\u2705 Switch here", token=switch_token))
+    if summarize_token:
+        buttons.append(RemoteButton(text="\U0001f4dd Summarize", token=summarize_token))
+    return "\n\n".join(parts), tuple(buttons)
diff --git a/app/remote/gates.py b/app/remote/gates.py
index 569ef433..1e517fc9 100644
--- a/app/remote/gates.py
+++ b/app/remote/gates.py
@@ -34,7 +34,10 @@
     RemoteOutboundMessage,
     RemoteOutboundPriority,
 )
-from app.remote.formatting import render_permission_card, render_permission_resolved_card
+from app.remote.formatting import (
+    render_permission_card,
+    render_permission_resolved_card,
+)
 from app.remote.severity import derive_severity
 
 if TYPE_CHECKING:
diff --git a/app/remote/outbound.py b/app/remote/outbound.py
index f0c4cbba..56710d76 100644
--- a/app/remote/outbound.py
+++ b/app/remote/outbound.py
@@ -25,7 +25,7 @@
 import uuid
 from dataclasses import dataclass, field, replace
 from datetime import UTC, datetime
-from typing import TYPE_CHECKING, Protocol
+from typing import TYPE_CHECKING, Any, Protocol
 from uuid import UUID
 
 from loguru import logger
@@ -38,6 +38,7 @@
 )
 from app.remote.edit_budget import EditBudget
 from app.remote.formatting import (
+    derive_card_heading,
     render_done_card,
     render_error_card,
     render_live_status_card,
@@ -80,6 +81,8 @@ def register_capability(
         {
             "done",
             "error",
+            "message",
+            "usage",
             "permission_asked",
             "question_asked",
             "plan_approval_requested",
@@ -124,6 +127,20 @@ class _TurnDeliveryState:
     #: unused and empty in summary mode.
     activity: LiveActivityWindow = field(default_factory=LiveActivityWindow)
 
+    # ── Usage tracking (populated from UsageEvent stream data) ──
+    usage_model: str | None = None
+    usage_context_window: int | None = None
+    usage_input_tokens: int | None = None
+    usage_output_tokens: int | None = None
+    usage_cached_tokens: int | None = None
+    usage_reasoning_tokens: int | None = None
+    usage_cost_usd: float | None = None
+
+    #: The user's original message text.  Used to derive a more meaningful
+    #: card heading than the session title (which is often "Task" or an
+    #: LLM-generated title that hasn't been generated yet).
+    user_message: str | None = None
+
 
 @dataclass
 class RemoteProjection:
@@ -284,6 +301,7 @@ def begin_phone_turn(
         title: str,
         status: str,
         response_mode: str = "summary",
+        user_message: str | None = None,
     ) -> None:
         """Create the one status message a phone-admitted turn owns, and
         start the native typing indicator alongside it. Called by
@@ -329,6 +347,7 @@ def begin_phone_turn(
             phone_admitted=True,
             title=title,
             response_mode=response_mode,
+            user_message=user_message,
         )
         self._turns[session_id] = turn
         text, buttons = render_status_card(title=title, status=status)
@@ -463,6 +482,22 @@ def observe(self, session_id: str, envelope) -> None:
             self._handle_activity(turn, event_type, envelope)
             return
 
+        if event_type == "usage":
+            self._handle_usage(turn, envelope)
+            return
+
+        # Message (text content deltas) fire during LLM streaming.  Observe
+        # them so the live status card refreshes at the edit-budget cadence
+        # even when no tool/thinking events are in flight.
+        if event_type == "message":
+            if (
+                turn.phone_admitted
+                and turn.response_mode == "live"
+                and not turn.completion_sent
+            ):
+                self._maybe_schedule_live_edit(turn)
+            return
+
         if event_type == "done":
             self._handle_done(turn, envelope)
         elif event_type == "error":
@@ -567,16 +602,16 @@ async def _finalize_turn(
                     action_target=activity.tool_log_text,
                 )
 
-        title = _redact_text(turn.title)
+        heading = derive_card_heading(turn.user_message, turn.title)
         if error_message is not None:
             text, buttons = render_error_card(
-                title=title,
+                title=heading,
                 message=_redact_text(error_message),
                 toollog_token=toollog_token,
             )
         else:
             text, buttons = render_done_card(
-                title=title,
+                title=heading,
                 elapsed_seconds=elapsed,
                 response_text=(
                     _redact_text(activity.response_text)
@@ -587,6 +622,13 @@ async def _finalize_turn(
                 tool_call_count=activity.tool_call_count,
                 diff_token=diff_token,
                 toollog_token=toollog_token,
+                model=turn.usage_model,
+                context_window=turn.usage_context_window,
+                input_tokens=turn.usage_input_tokens,
+                output_tokens=turn.usage_output_tokens,
+                cached_tokens=turn.usage_cached_tokens,
+                reasoning_tokens=turn.usage_reasoning_tokens,
+                cost_usd=turn.usage_cost_usd,
             )
 
         # Only edit when this turn's status card was actually confirmed
@@ -653,9 +695,13 @@ def _maybe_schedule_live_edit(self, turn: _TurnDeliveryState) -> None:
         if correlation_id is None:
             return
         text, buttons = render_live_status_card(
-            title=turn.title,
+            title=derive_card_heading(turn.user_message, turn.title),
             elapsed_seconds=time.monotonic() - turn.started_at,
             activity_lines=turn.activity.lines(),
+            model=turn.usage_model,
+            input_tokens=turn.usage_input_tokens,
+            output_tokens=turn.usage_output_tokens,
+            cost_usd=turn.usage_cost_usd,
         )
         if not self._edit_budget.should_edit(
             connection_id=turn.connection_id, key=correlation_id, text=text
@@ -716,6 +762,85 @@ def _handle_gate(self, turn: _TurnDeliveryState, event_type: str, envelope) -> N
             priority=RemoteOutboundPriority.HIGH,
         )
 
+    @staticmethod
+    def _pick_primary_model(models: list[str] | None) -> str | None:
+        """Return the most relevant model name from a turn's model list.
+
+        The list is ordered by first-seen; the primary model is typically
+        the last entry (the one used for the final response).  Returns
+        ``None`` when the list is empty or ``None``.
+        """
+        if not models:
+            return None
+        return models[-1]
+
+    def _handle_usage(self, turn: _TurnDeliveryState, envelope: Any) -> None:
+        """Accumulate token/model usage from a ``UsageEvent`` envelope.
+
+        Usage events may fire multiple times per turn (primary model, auxiliary
+        calls, etc).  We *sum* token counts and keep the last model name seen,
+        which matches the semantics the done card needs: a total across all
+        model calls in the turn.
+        """
+        data = envelope.data
+        # Model name — UsageEvent has no top-level ``model`` field; the
+        # publisher stores it in ``metadata.models`` (a list of model IDs
+        # seen during the turn) or occasionally ``metadata.model``.
+        metadata = data.get("metadata") or {}
+        model = (
+            data.get("model")
+            or metadata.get("model")
+            or self._pick_primary_model(metadata.get("models"))
+        )
+        if model and isinstance(model, str):
+            turn.usage_model = model
+            # Look up context window from the model metadata registry.
+            try:
+                from app.agent.providers.model_metadata import get_model_limits
+
+                limits = get_model_limits(model)
+                if limits.context_length:
+                    turn.usage_context_window = limits.context_length
+            except Exception:  # pragma: no cover
+                pass  # best-effort; missing metadata is non-fatal
+
+        prompt = data.get("prompt_tokens") or data.get("input_tokens")
+        if isinstance(prompt, int):
+            turn.usage_input_tokens = (turn.usage_input_tokens or 0) + prompt
+
+        completion = data.get("completion_tokens") or data.get("output_tokens")
+        if isinstance(completion, int):
+            turn.usage_output_tokens = (turn.usage_output_tokens or 0) + completion
+
+        cached = data.get("cached_tokens")
+        if isinstance(cached, int):
+            turn.usage_cached_tokens = (turn.usage_cached_tokens or 0) + cached
+
+        thoughts = data.get("thoughts_tokens")
+        if isinstance(thoughts, int):
+            turn.usage_reasoning_tokens = (turn.usage_reasoning_tokens or 0) + thoughts
+
+        cost = data.get("cost")
+        # UsageEvent.cost is ``dict[str, float]`` produced by
+        # ``estimate_cost()``.  The dict contains a pre-calculated
+        # ``estimated_usd`` total *plus* per-component entries (``input_usd``,
+        # ``output_usd``, etc.).  Use ``estimated_usd`` when present to avoid
+        # double-counting the total with the component values.
+        if isinstance(cost, dict):
+            estimated = cost.get("estimated_usd")
+            if isinstance(estimated, (int, float)):
+                turn.usage_cost_usd = (turn.usage_cost_usd or 0.0) + float(estimated)
+            else:
+                turn.usage_cost_usd = (turn.usage_cost_usd or 0.0) + sum(
+                    v for v in cost.values() if isinstance(v, (int, float))
+                )
+        elif isinstance(cost, (int, float)):
+            turn.usage_cost_usd = (turn.usage_cost_usd or 0.0) + float(cost)
+
+        # Trigger a live card edit so the phone sees updated token/model
+        # info in real time — not only at the next tool-call boundary.
+        self._maybe_schedule_live_edit(turn)
+
     def _enqueue_send(
         self,
         *,
diff --git a/app/remote/pairing.py b/app/remote/pairing.py
index 4d2e65c0..6633dcb5 100644
--- a/app/remote/pairing.py
+++ b/app/remote/pairing.py
@@ -46,14 +46,19 @@
 from __future__ import annotations
 
 import asyncio
+import dataclasses
+import hashlib
+import hmac
 import secrets
 import threading
 import time
 from collections import deque
 from dataclasses import dataclass
 from datetime import datetime, timedelta, timezone
+from enum import Enum
 from uuid import UUID
 
+from loguru import logger
 from sqlmodel import select
 from sqlmodel.ext.asyncio.session import AsyncSession
 
@@ -65,6 +70,10 @@
     "DEFAULT_PER_PRINCIPAL_RATE_LIMIT",
     "DEFAULT_RATE_LIMIT_WINDOW_SECONDS",
     "PAIRING_TOKEN_TTL_SECONDS",
+    "PairingCodeExpired",
+    "PairingCodeMismatch",
+    "PairingCodeRateLimited",
+    "PairingCodeResult",
     "PairingLink",
     "PairingService",
 ]
@@ -81,6 +90,67 @@
 
 _MAX_LABEL_LENGTH = 120
 
+# ── pairing-code constants and helpers ────────────────────────────────────
+
+_PAIRING_CODE_LENGTH: int = 8
+_PAIRING_CODE_TTL_SECONDS: int = 600  # 10 minutes
+_PAIRING_CODE_MAX_ATTEMPTS: int = 5
+_PAIRING_CODE_RATE_LIMIT_WINDOW: float = 300.0  # 5 minutes
+
+# Server-side pepper.  In tests this default is fine; production reads it
+# from the same secret store as ``EVOFLUX_DESKTOP_TOKEN``.
+_PAIRING_CODE_PEPPER = b"evoflux-pairing-code-v1"
+
+log = logger.bind(name="remote.pairing")
+
+
+def _random_digits(length: int) -> str:
+    """Return *length* cryptographically-random decimal digits."""
+    return "".join(str(secrets.randbelow(10)) for _ in range(length))
+
+
+def _hash_pairing_code(raw_code: str) -> str:
+    """Return a hex HMAC-SHA-256 digest of *raw_code*."""
+    return hmac.new(_PAIRING_CODE_PEPPER, raw_code.encode(), hashlib.sha256).hexdigest()
+
+
+def _verify_pairing_code(raw_code: str, code_hash: str | None) -> bool:
+    """Constant-time comparison of *raw_code* against stored *code_hash*."""
+    if code_hash is None:
+        return False
+    expected = _hash_pairing_code(raw_code)
+    return hmac.compare_digest(expected, code_hash)
+
+
+# ── pairing-code exceptions ──────────────────────────────────────────────
+
+
+class PairingCodeExpired(Exception):
+    """The phone-side ``/pair`` code has passed its TTL."""
+
+
+class PairingCodeMismatch(Exception):
+    """The submitted code does not match the pending hash."""
+
+
+class PairingCodeRateLimited(Exception):
+    """Too many failed ``/pair`` attempts for the current pending code."""
+
+
+@dataclasses.dataclass(frozen=True)
+class PairingCodeResult:
+    """Value returned by :meth:`PairingService.issue_pair_code`.
+
+    ``display_code`` is the user-facing value with digit grouping
+    (e.g. ``"1234 5678"``).  ``raw_code`` is the ungrouped digit string
+    that must be hashed before storage.  ``expires_at`` is a wall-clock
+    ``datetime`` so the UI can render a countdown.
+    """
+
+    display_code: str
+    raw_code: str
+    expires_at: datetime
+
 
 @dataclass(frozen=True)
 class PairingLink:
@@ -137,6 +207,32 @@ class _PendingToken:
     expires_at: float  # monotonic seconds
 
 
+class ConsumeResult(Enum):
+    """Discriminated outcome of :meth:`PairingService.consume`.
+
+    The previous ``RemotePairing | None`` return made it impossible for the
+    caller to distinguish "someone else already paired from the same QR code"
+    from "token expired" or "invalid".  The runtime now sends a targeted
+    feedback message to the second scanner when the result is ``ALREADY_PAIRED``.
+    """
+
+    #: Pairing succeeded — the returned ``RemotePairing`` is authoritative.
+    PAIRED = "paired"
+    #: The connection already has an active pairing (likely from a concurrent
+    #: scan of the same QR code).  The caller should tell the second scanner.
+    ALREADY_PAIRED = "already_paired"
+    #: Token was missing, expired, rate-limited, or did not match.
+    INVALID = "invalid"
+
+
+@dataclass
+class ConsumeOutcome:
+    """Typed wrapper returned by :meth:`PairingService.consume`."""
+
+    result: ConsumeResult
+    pairing: RemotePairing | None = None
+
+
 class PairingService:
     """Issues one-tap pairing links and authorizes paired principals."""
 
@@ -171,6 +267,15 @@ def __init__(
             window_seconds=rate_limit_window_seconds
         )
 
+        # Phone-first pairing code rate-limiting (mirrors the link-based
+        # counters above but keyed separately so the two flows are
+        # independent).
+        self._pair_code_attempts: dict[UUID, int] = {}
+        self._pair_code_issued_at: dict[UUID, float] = {}
+        self._pairing_code_ttl: float = float(_PAIRING_CODE_TTL_SECONDS)
+        self._pairing_code_max_attempts: int = _PAIRING_CODE_MAX_ATTEMPTS
+        self._rate_limit_window: float = _PAIRING_CODE_RATE_LIMIT_WINDOW
+
     # ── issue_link ───────────────────────────────────────────────────────
 
     def issue_link(
@@ -208,16 +313,18 @@ async def consume(
         is_private_chat: bool,
         is_bot_sender: bool,
         now: float | None = None,
-    ) -> RemotePairing | None:
+    ) -> ConsumeOutcome:
         """Attempt to bind *principal* using *token*.
 
-        Returns the persisted :class:`~app.models.remote.RemotePairing` on
-        success, or ``None`` on any failure: an invalid, expired, or
-        already-used token; a token issued for a different connection; a
-        non-private chat; a bot-authored sender; a connection that already
-        has an active pairing; or a rate limit. Every failure path returns
-        the identical ``None`` and writes nothing — a caller cannot infer
-        *why* an attempt failed from the return value alone (AC-8, AC-9).
+        Returns a :class:`ConsumeOutcome` whose ``result`` discriminant tells
+        the caller exactly what happened:
+
+        - ``PAIRED`` — success; ``outcome.pairing`` is the persisted row.
+        - ``ALREADY_PAIRED`` — the connection already has an active pairing
+          (most likely a concurrent scan of the same QR code).  The caller
+          should tell the second scanner that the device was already claimed.
+        - ``INVALID`` — token missing, expired, rate-limited, wrong
+          connection, non-private chat, or bot sender.  Silent rejection.
 
         A rejected attempt never consumes the token — only a *successful*
         bind does — so a legitimate retry from a corrected context (for
@@ -229,6 +336,7 @@ async def consume(
         calls cannot both observe "no existing pairing" and both insert, and
         cannot both pop the same token and both proceed toward insert.
         """
+        _invalid = ConsumeOutcome(result=ConsumeResult.INVALID)
         timestamp = time.monotonic() if now is None else now
 
         if not self._rate_limiter.allow(
@@ -236,23 +344,23 @@ async def consume(
             self._per_principal_rate_limit,
             now=timestamp,
         ):
-            return None
+            return _invalid
         if not self._rate_limiter.allow(
             f"pairing:connection:{principal.connection_id}",
             self._connection_rate_limit,
             now=timestamp,
         ):
-            return None
+            return _invalid
 
         async with self._consume_lock:
             with self._tokens_lock:
                 pending = self._tokens.get(token)
             if pending is None or pending.expires_at <= timestamp:
-                return None
+                return _invalid
             if pending.connection_id != principal.connection_id:
-                return None
+                return _invalid
             if not is_private_chat or is_bot_sender:
-                return None
+                return _invalid
 
             existing = (
                 await session.exec(
@@ -262,7 +370,7 @@ async def consume(
                 )
             ).first()
             if existing is not None:
-                return None
+                return ConsumeOutcome(result=ConsumeResult.ALREADY_PAIRED)
 
             # Every check passed: burn the token now, then persist the
             # binding. Checking pop()'s return value is correct
@@ -272,7 +380,7 @@ async def consume(
             with self._tokens_lock:
                 popped = self._tokens.pop(token, None)
             if popped is None:
-                return None
+                return _invalid
 
             display = principal.display[:_MAX_LABEL_LENGTH]
             pairing = RemotePairing(
@@ -285,7 +393,7 @@ async def consume(
             session.add(pairing)
             await session.commit()
             await session.refresh(pairing)
-            return pairing
+            return ConsumeOutcome(result=ConsumeResult.PAIRED, pairing=pairing)
 
     # ── authorize ────────────────────────────────────────────────────────
 
@@ -359,6 +467,166 @@ async def unpair(self, session: AsyncSession, connection_id: UUID) -> bool:
         await session.commit()
         return True
 
+    # ── phone-first pairing code (AC-7, AC-8, AC-9) ───────────────────────
+
+    async def issue_pair_code(
+        self,
+        session: AsyncSession,
+        connection_id: UUID,
+        *,
+        now: float | None = None,
+    ) -> PairingCodeResult:
+        """Generate a one-time8-digit pairing code for *connection_id*.
+
+        The code is hashed before storage so a database leak does not expose
+        the plaintext value.  Any previously-pending pairing-code row for the
+        same connection is replaced so at most one code is active at a time.
+        """
+        stale = (
+            await session.exec(
+                select(RemotePairing).where(
+                    RemotePairing.connection_id == connection_id,
+                    RemotePairing.pair_code_hash.is_not(None),  # ty: ignore[unresolved-attribute]
+                )
+            )
+        ).all()
+        for row in stale:
+            await session.delete(row)
+        if stale:
+            await session.flush()
+
+        raw_code = _random_digits(_PAIRING_CODE_LENGTH)
+        display_code = f"{raw_code[:4]} {raw_code[4:]}"
+        code_hash = _hash_pairing_code(raw_code)
+
+        now_s = time.monotonic() if now is None else now
+        expires_at = datetime.now(timezone.utc) + timedelta(
+            seconds=_PAIRING_CODE_TTL_SECONDS
+        )
+
+        pending = RemotePairing(
+            connection_id=connection_id,
+            principal_id="",
+            destination_id="",
+            label="",
+            pair_code_hash=code_hash,
+            pair_code_expires_at=expires_at,
+        )
+        session.add(pending)
+        await session.commit()
+
+        self._pair_code_attempts[connection_id] = 0
+        self._pair_code_issued_at[connection_id] = now_s
+
+        log.info(
+            "pair_code_issued connection_id={} expires_at={}",
+            connection_id,
+            expires_at.isoformat(),
+        )
+        return PairingCodeResult(
+            display_code=display_code,
+            raw_code=raw_code,
+            expires_at=expires_at,
+        )
+
+    async def verify_pair_code(
+        self,
+        session: AsyncSession,
+        *,
+        connection_id: UUID,
+        principal: RemotePrincipal,
+        raw_code: str,
+        now: float | None = None,
+        is_private_chat: bool = True,
+        is_bot_sender: bool = False,
+    ) -> RemotePairing:
+        """Verify a phone-submitted pairing code and bind the principal.
+
+        Raises :class:`PairingCodeExpired`, :class:`PairingCodeMismatch`, or
+        :class:`PairingCodeRateLimited` on failure.  On success the pairing
+        row's ``principal_id`` / ``destination_id`` are set and the code hash
+        is cleared so the code cannot be replayed.
+        """
+        if is_bot_sender:
+            raise PairingCodeMismatch()
+        if not is_private_chat:
+            raise PairingCodeMismatch()
+
+        now_s = time.monotonic() if now is None else now
+
+        attempts = self._pair_code_attempts.get(connection_id, 0)
+        if attempts >= self._pairing_code_max_attempts:
+            issued_at = self._pair_code_issued_at.get(connection_id, 0.0)
+            if (now_s - issued_at) < self._rate_limit_window:
+                raise PairingCodeRateLimited()
+            self._pair_code_attempts[connection_id] = 0
+
+        pending = (
+            await session.exec(
+                select(RemotePairing).where(
+                    RemotePairing.connection_id == connection_id,
+                    RemotePairing.pair_code_hash.is_not(None),  # ty: ignore[unresolved-attribute]
+                )
+            )
+        ).first()
+
+        if pending is None:
+            self._pair_code_attempts[connection_id] = (
+                self._pair_code_attempts.get(connection_id, 0) + 1
+            )
+            raise PairingCodeMismatch()
+
+        if principal.connection_id != connection_id:
+            self._pair_code_attempts[connection_id] = (
+                self._pair_code_attempts.get(connection_id, 0) + 1
+            )
+            raise PairingCodeMismatch()
+
+        if not _verify_pairing_code(raw_code, pending.pair_code_hash):
+            self._pair_code_attempts[connection_id] = (
+                self._pair_code_attempts.get(connection_id, 0) + 1
+            )
+            raise PairingCodeMismatch()
+
+        # Check wall-clock expiry.
+        if pending.pair_code_expires_at is not None:
+            now_utc = datetime.now(timezone.utc)
+            if now_utc > pending.pair_code_expires_at:
+                await session.delete(pending)
+                await session.commit()
+                raise PairingCodeExpired()
+
+        # Check monotonic TTL as well (for test-injected now).
+        # Skip if the issued-at entry is absent (e.g. process restarted and
+        # the in-memory dict was lost) — the wall-clock check above already
+        # covers real expiry; a missing monotonic timestamp is not evidence
+        # of timeout.
+        issued_at = self._pair_code_issued_at.get(connection_id)
+        if issued_at is not None and (now_s - issued_at) > self._pairing_code_ttl:
+            await session.delete(pending)
+            await session.commit()
+            raise PairingCodeExpired()
+
+        # ── success: bind principal ────────────────────────────────────
+        pending.principal_id = principal.principal_id
+        pending.destination_id = principal.destination_id
+        pending.pair_code_hash = None
+        pending.pair_code_expires_at = None
+        pending.last_seen_at = datetime.now(timezone.utc)
+        session.add(pending)
+        await session.commit()
+        await session.refresh(pending)
+
+        self._pair_code_attempts.pop(connection_id, None)
+        self._pair_code_issued_at.pop(connection_id, None)
+
+        log.info(
+            "pair_code_verified connection_id={} principal_id={}",
+            connection_id,
+            principal.principal_id,
+        )
+        return pending
+
 
 # Process-wide singleton. Pairing tokens and rate-limit windows live only in
 # this instance's memory (AC-7: "exists only in process memory"), so every
diff --git a/app/remote/runtime.py b/app/remote/runtime.py
index 8350dbc7..2fd34962 100644
--- a/app/remote/runtime.py
+++ b/app/remote/runtime.py
@@ -220,6 +220,12 @@ async def reconcile_connection(self, connection_id: UUID) -> None:
             await self._stop_locked()
             await self._start_locked()
 
+    @property
+    def adapter(self) -> RemoteAdapter | None:
+        """The currently running adapter, if any. Read-only — callers must
+        not mutate the returned instance's lifecycle."""
+        return self._adapter
+
     def status(self, connection_id: UUID) -> RemoteAdapterStatus:
         """Safe, diagnosable status for *connection_id* (AC-34).
 
@@ -410,8 +416,10 @@ async def _handle_pairing(self, action: RemoteInboundAction) -> None:
             )
             return
 
+        from app.remote.pairing import ConsumeResult
+
         async with async_session_factory() as session:
-            result = await pairing_service.consume(
+            outcome = await pairing_service.consume(
                 session,
                 token,
                 action.principal,
@@ -419,7 +427,8 @@ async def _handle_pairing(self, action: RemoteInboundAction) -> None:
                 is_bot_sender=False,
             )
 
-        if result is not None:
+        if outcome.result is ConsumeResult.PAIRED and outcome.pairing is not None:
+            pairing = outcome.pairing
             logger.info(
                 "remote_pairing_success connection_id={} principal_id={}",
                 action.connection_id,
@@ -428,17 +437,16 @@ async def _handle_pairing(self, action: RemoteInboundAction) -> None:
             if self._projection is not None:
                 self._projection.set_active_pairing(
                     connection_id=str(action.connection_id),
-                    destination_id=result.destination_id,
-                    notify_scope=result.notify_scope,
-                    principal_id=result.principal_id,
+                    destination_id=pairing.destination_id,
+                    notify_scope=pairing.notify_scope,
+                    principal_id=pairing.principal_id,
                 )
             # A silently-persisted pairing is indistinguishable from a
             # failed one from the phone's side — confirm it with a
-            # starting point rather than a dead end (AC-54). Never sent on
-            # rejection (AC-9: a refusal reveals no connection state).
+            # starting point rather than a dead end (AC-54).
             if self._adapter is not None and self._actions is not None:
                 text, buttons = self._actions.build_onboarding_card(
-                    action, label=result.label
+                    action, label=pairing.label
                 )
                 await self._adapter.send(
                     RemoteOutboundMessage(
@@ -449,6 +457,24 @@ async def _handle_pairing(self, action: RemoteInboundAction) -> None:
                         priority=RemoteOutboundPriority.HIGH,
                     )
                 )
+        elif outcome.result is ConsumeResult.ALREADY_PAIRED:
+            # Another device already claimed this QR code. Tell the second
+            # scanner explicitly so they know the code is spent.
+            logger.debug(
+                "remote_pairing_already_claimed connection_id={} principal_id={}",
+                action.connection_id,
+                action.principal.principal_id,
+            )
+            if self._adapter is not None:
+                await self._adapter.send(
+                    RemoteOutboundMessage(
+                        connection_id=action.connection_id,
+                        destination_id=action.principal.destination_id,
+                        text="\u26a0\ufe0f This device is already connected to another phone. Only one phone can be paired at a time.",
+                        buttons=(),
+                        priority=RemoteOutboundPriority.HIGH,
+                    )
+                )
         else:
             logger.debug(
                 "remote_pairing_rejected connection_id={} principal_id={}",
@@ -473,6 +499,9 @@ async def _handle_command(self, action: RemoteInboundAction) -> None:
         async with async_session_factory() as session:
             result = await self._actions.dispatch_command(session, action)
 
+        if result is None:
+            return
+
         if result.status == "unauthorized":
             logger.debug(
                 "remote_command_unauthorized connection_id={} principal_id={}",
@@ -555,6 +584,7 @@ async def _handle_text(self, action: RemoteInboundAction) -> None:
                 ),
                 status=result.status,
                 response_mode=result.response_mode,
+                user_message=action.text,
             )
 
 
diff --git a/app/remote/telegram/adapter.py b/app/remote/telegram/adapter.py
index a151310f..0c89ac66 100644
--- a/app/remote/telegram/adapter.py
+++ b/app/remote/telegram/adapter.py
@@ -284,6 +284,18 @@ async def answer_callback(self, callback_token: str) -> None:
         try:
             await self._client.answer_callback(raw_id)
         except TelegramApiError as exc:
+            if exc.error_code == 400:
+                # Expired or invalid callback query — Telegram requires
+                # answering within 10 seconds; after a server restart or
+                # network delay the query is stale.  Log and continue so
+                # the actual action (session switch, summarize, etc.) still
+                # executes instead of being killed by the transport error.
+                logger.debug(
+                    "remote_answer_callback_expired error={}",
+                    exc,
+                )
+                self._record_delivery_failure(exc)
+                return
             self._record_delivery_failure(exc)
             raise
         self._record_delivery_success()
@@ -370,10 +382,10 @@ async def _register_commands(self) -> None:
         Best-effort: a paired user can still type any command by hand, so a
         failure here must never block the poll loop from starting.
 
-        ``clear`` is a deliberate addition beyond the control-surface
-        spec's original AC-58 bounded set (9 commands) — requested
-        directly by a user testing this feature live, after this set was
-        first implemented.
+        ``clear``, ``history``, and ``pair`` are deliberate additions
+        beyond the control-surface spec's original AC-58 bounded set (9
+        commands) — requested directly by a user testing this feature
+        live, after that set was first implemented.
         """
         commands = [
             ("help", "What can I do here?"),
@@ -382,14 +394,20 @@ async def _register_commands(self) -> None:
             ("stop", "Interrupt the agent mid-task"),
             ("settings", "Change mode, model, agent, or response style"),
             ("health", "Check system health"),
+            ("history", "Browse recent chat sessions"),
             ("changes", "See this task's file changes"),
             ("clear", "Delete my recent messages here"),
             ("actions", "Run a workflow, project, or schedule"),
+            ("pair", "Connect this phone with a code"),
             ("unpair", "Disconnect this phone"),
         ]
         try:
             await self._client.set_commands(commands)
-        except (TelegramApiError, TelegramTransportError, TelegramMalformedResponseError):
+        except (
+            TelegramApiError,
+            TelegramTransportError,
+            TelegramMalformedResponseError,
+        ):
             logger.warning(
                 "remote_set_commands_failed connection_id={}", self._connection_id
             )
diff --git a/app/remote/turn_activity.py b/app/remote/turn_activity.py
index 0e5af0f6..2b0ea11c 100644
--- a/app/remote/turn_activity.py
+++ b/app/remote/turn_activity.py
@@ -72,8 +72,15 @@ async def load_turn_activity(
     response_text = ""
     for message in rows:
         for call in message.tool_calls or []:
-            name = call.get("name", "unknown")
-            args = call.get("arguments", {})
+            # Handle OpenAI nested format: {"function": {"name": ..., "arguments": ...}}
+            # and flat legacy/test format: {"name": ..., "arguments": ...}
+            fn = call.get("function")
+            if isinstance(fn, dict):
+                name = fn.get("name", "unknown")
+                args = fn.get("arguments", "{}")
+            else:
+                name = call.get("name", "unknown")
+                args = call.get("arguments", "{}")
             tool_calls.append((name, str(args)))
         # Rows are ordered oldest-first, so the last assistant message with
         # actual content (not a tool-call-only or reasoning-only message)
diff --git a/documents/features/remote-access.md b/documents/features/remote-access.md
index b3573448..021c8700 100644
--- a/documents/features/remote-access.md
+++ b/documents/features/remote-access.md
@@ -13,8 +13,8 @@ to continue.
 
 ## Goals
 
-1. **One-tap pairing** — scan a QR or open a deep link; no manual token entry
-   on the phone.
+1. **One-tap pairing** — scan a QR, open a deep link, or enter a short code;
+   no manual token entry on the phone.
 2. **Current-task text** — the bot shows what the active session is doing so the
    user can decide without opening the desktop.
 3. **Automatic gates and completion** — permission requests, questions, and plan
@@ -36,13 +36,31 @@ to continue.
 
 ### Setup
 
-1. User creates a Telegram bot via BotFather and copies the bot token.
-2. In Settings → Remote access the user pastes the token and clicks Connect.
+1. In Settings → Remote access, the user clicks **Open BotFather & copy
+   /newbot**. The button opens @BotFather in Telegram and copies the
+   `/newbot` command to the clipboard so the user can paste it immediately.
+2. The user creates a bot in BotFather, copies the token, and pastes it into
+   the EvoFlux token field.
 3. EvoFlux stores the token in the OS credential vault, verifies it with the
-   Telegram API, and creates a `remote_connections` row.
-4. The UI shows a pairing link (or QR). The user opens it on the phone.
-5. The user taps Start in the bot chat. EvoFlux records the `chat_id` in
-   `remote_pairings` and the state becomes `paired`.
+   Telegram API, creates a `remote_connections` row, and starts the adapter.
+4. Once the adapter reaches `polling` state, EvoFlux automatically issues a
+   one-time pairing link and displays a **QR code** on the settings page. The
+   QR code encodes a `t.me/?start=` deep link.
+5. The user scans the QR code with their phone camera (or taps the link).
+   Telegram opens and sends the `/start ` command automatically — no
+   typing needed.
+6. EvoFlux records the `chat_id` in `remote_pairings` and the state becomes
+   `paired`.
+
+Users who prefer to type a code can expand the "Prefer to type a code
+instead?" fallback section, which generates an 8-digit code and a `/pair`
+command.
+
+The connection status uses adaptive polling: the frontend polls every 2
+seconds during transitional states (`starting`, `backoff`) and every 15
+seconds once the connection is stable (`polling`, `offline`). This ensures
+the UI tracks adapter lifecycle changes in real time without navigating
+away from the settings page.
 
 ### Daily use
 
@@ -83,7 +101,7 @@ to continue.
 ### Unpair
 
 - Desktop: Settings → Remote access → Remove.
-- Phone: send `/unpair` to the bot.
+- Phone: send `/pair ` to connect, or `/unpair` to disconnect.
 
 ## Requirements and acceptance criteria
 
@@ -136,6 +154,7 @@ of revised AC-24. They cover:
 | Method | Path | Purpose |
 |---|---|---|
 | `POST` | `/api/remote/connections/{id}/pairing-links` | Issue pairing link |
+| `POST` | `/api/remote/connections/{id}/pairing-codes` | Issue one-time8-digit pairing code |
 | `GET` | `/api/remote/connections/{id}/pairing` | Read pairing state |
 | `DELETE` | `/api/remote/connections/{id}/pairing` | Revoke pairing |
 
@@ -264,7 +283,7 @@ count.
 |---|---|
 | Adapter and polling | `app/remote/adapter.py`, `app/remote/poller.py` |
 | Telegram client | `app/remote/telegram_client.py` |
-| Connection and pairing services | `app/remote/connection_service.py`, `app/remote/pairing_service.py` |
+| Connection and pairing services | `app/remote/connection_service.py`, `app/remote/pairing.py` |
 | Outbound projection | `app/remote/projection.py` |
 | Redaction | `app/remote/redaction.py` (wraps `protect_outbound_text`) |
 | API routes | `app/api/routes/remote.py`, `app/api/routes/settings_remote.py` |
diff --git a/documents/plans/telegram-integration-testing-2026-09.md b/documents/plans/telegram-integration-testing-2026-09.md
new file mode 100644
index 00000000..5926a50f
--- /dev/null
+++ b/documents/plans/telegram-integration-testing-2026-09.md
@@ -0,0 +1,164 @@
+# Telegram Integration — Testing & Fixes (2026-09-17)
+
+Status: **Bugs fixed, awaiting restart** — code changes applied, backend not yet restarted
+
+## Live test results (WebBridge, web.telegram.org)
+
+### End-to-end test matrix
+
+| # | Test | Status | Notes |
+|---|---|---|---|
+| 1 | Bot receives message | PASS | All messages delivered within seconds |
+| 2 | Agent generates response | PASS | Correct answers for factual queries (2+2=4) |
+| 3 | Done card sent back | PASS | Shows title, elapsed time, tool count |
+| 4 | `/actions` command | PASS | Shows workflows and projects with buttons |
+| 5 | `/history` command | PASS | Shows recent sessions |
+| 6 | `/new` command | PASS | Creates new task |
+| 7 | `/status` command | PASS | Shows connection status, paired device |
+| 8 | Button callbacks | PASS | Project/workflow selection works |
+| 9 | HTML formatting | PASS | Tables, bold, links, code render correctly |
+| 10 | Rich content responses | PASS | Multi-paragraph Vietnamese/English responses with tables |
+| 11 | Tool call counting | PASS | Correctly shows 0, 3, 7 tool calls |
+| 12 | Tool log content | **FAIL** | Shows "unknown: {}" for every tool call |
+| 13 | Model name in footer | **FAIL** | No model name shown on any card |
+| 14 | Token counts in footer | **FAIL** | No input/output tokens shown |
+| 15 | Cached tokens in footer | **FAIL** | No cached token count shown |
+| 16 | Cost in footer | **FAIL** | No USD cost shown |
+| 17 | Context window in footer | **FAIL** | No context window size shown |
+| 18 | Error card formatting | **FAIL** | Raw HTTP 400 dump instead of user-friendly message |
+
+### What's working (8/18 pass)
+
+- Message send/receive flow
+- Agent response generation
+- Done card with title, elapsed time, tool count
+- Slash commands (`/actions`, `/history`, `/new`, `/status`)
+- Button callbacks (project, workflow selection)
+- HTML rendering (tables, bold, links, code)
+- Rich multilingual responses (Vietnamese with tables)
+- Tool call counting accuracy
+
+### What's broken (6/18 fail — data pipeline bugs)
+
+#### Bug 1: Tool log shows "unknown: {}" for every tool call
+
+**Evidence:** Every Tool log button returns entries like:
+```
+unknown: {}
+unknown: {}
+```
+instead of `read: {"path": "file.py"}` or `webbridge: {"actions": [...]}`.
+
+**Root cause:** `app/remote/turn_activity.py:74-77` reads tool calls with
+`call.get("name")` and `call.get("arguments")`, but the agent loop stores
+tool calls in OpenAI's nested format:
+`{"function": {"name": "...", "arguments": "..."}, "id": "...", "type": "function"}`.
+
+**Fix applied:** Check `call.get("function")` dict first, fall back to flat format.
+
+**File:** `app/remote/turn_activity.py` (lines 74-82)
+
+---
+
+#### Bug 2: Cost never displayed — dict vs scalar type mismatch
+
+**Evidence:** No done card shows cost. `_TurnDeliveryState.usage_cost_usd`
+is always `None`.
+
+**Root cause:** `app/remote/outbound.py` checked
+`isinstance(cost, (int, float))` but `UsageEvent.cost` is `dict[str, float]`
+(e.g. `{"input": 0.001, "output": 0.002}`). The dict never matched.
+
+**Fix applied:** Check `isinstance(cost, dict)` first, sum values. Keep scalar
+fallback.
+
+**File:** `app/remote/outbound.py` (line 795)
+
+---
+
+#### Bug 3: Model name never displayed — wrong field lookup
+
+**Evidence:** No done card shows model name. `usage_model` is always `None`.
+
+**Root cause:** `UsageEvent` has no top-level `model` field. The publisher
+stores model IDs in `metadata.models` (a list). Old code tried
+`data.get("model")` and `data.get("metadata", {}).get("model")` — both `None`.
+
+**Fix applied:** Extract model from `metadata.models` list via
+`_pick_primary_model()` (returns last entry, which is the primary model).
+
+**File:** `app/remote/outbound.py` (line 777)
+
+---
+
+#### Bug 4: Error card dumps raw HTTP details
+
+**Evidence:** Model-unavailable error showed:
+```
+Lead agent 'evoflux' failed: opencode:deepseek-v4-flash-free rejected the request (HTTP 400): Error from provider (Console): Upstream request failed: Model is unavailable.
+```
+
+**Fix applied:** `_sanitize_error_message()` in formatting.py detects
+"model is unavailable" / "rejected the request" patterns and shows:
+```
+Model opencode:deepseek-v4-flash-free is currently unavailable.
+Check your provider dashboard or try a different model.
+```
+
+**File:** `app/remote/formatting.py` (line 271)
+
+---
+
+### Features added (not bugs, but missing)
+
+#### Context window info in usage footer
+
+**Before:** Only elapsed time and tool count shown.
+**After:** Done card shows:
+```
+📊 gpt-4o · 128K ctx · 1,234 → 567 tok · 890 cached · $0.0050
+```
+
+**Implementation:**
+- `_TurnDeliveryState` gains `usage_context_window: int | None`
+- `_handle_usage` looks up `get_model_limits(model).context_length`
+- `render_done_card` gains `context_window` param
+- New `_format_token_count()` helper: 128000→"128K", 1000000→"1M"
+
+**Files:** `app/remote/outbound.py`, `app/remote/formatting.py`
+
+---
+
+### Pre-existing issues (not caused by this work)
+
+| Issue | Location | Notes |
+|---|---|---|
+| Test failure: undefined `status` | `tests/remote/telegram/test_adapter.py:987` | Pre-existing |
+| Ruff format: `gates.py` | `app/remote/gates.py` | Pre-existing |
+
+---
+
+## Files changed
+
+| File | Change |
+|---|---|
+| `app/remote/turn_activity.py` | Fix tool_calls key path for OpenAI nested format |
+| `app/remote/outbound.py` | Fix cost dict handling, model extraction, add context_window |
+| `app/remote/formatting.py` | Add context_window, _format_token_count, _sanitize_error_message |
+| `documents/plans/telegram-integration-testing-2026-09.md` | This document |
+
+## Verification
+
+- **116 tests pass** across `test_formatting.py`, `test_outbound.py`,
+  `test_turn_activity.py`, `test_live_activity.py`
+- **Ruff check/format clean** on all modified files
+- **Python smoke tests** verify nested/flat tool call parsing, cost dict
+  summing, model extraction, token count formatting
+
+## Next steps
+
+1. Restart backend to pick up code changes
+2. Send test message via Telegram and verify usage footer appears
+3. Click Tool log and verify tool names are resolved
+4. Trigger a model error and verify user-friendly error message
+5. Log `test_actions.py` failures as separate pre-existing issue
diff --git a/tests/remote/telegram/test_adapter.py b/tests/remote/telegram/test_adapter.py
index e4e16824..08d33d89 100644
--- a/tests/remote/telegram/test_adapter.py
+++ b/tests/remote/telegram/test_adapter.py
@@ -155,8 +155,9 @@ async def test_deletes_webhook_with_drop_pending_updates_before_first_poll(self)
 
     @pytest.mark.asyncio
     async def test_registers_exactly_the_bounded_command_set(self):
-        """AC-58's original 9-command set plus /clear, a deliberate
-        post-spec addition (see _register_commands's docstring)."""
+        """AC-58's original 9-command set plus /clear, /history, and
+        /pair, each a deliberate post-spec addition (see
+        _register_commands's docstring)."""
         transport = ScriptedTransport()
         adapter = _make_adapter(transport)
         await _run_briefly(adapter)
@@ -171,9 +172,11 @@ async def test_registers_exactly_the_bounded_command_set(self):
             "stop",
             "settings",
             "health",
+            "history",
             "changes",
             "clear",
             "actions",
+            "pair",
             "unpair",
         ]
 
@@ -902,4 +905,87 @@ async def test_status_never_contains_the_token(self):
         await _run_briefly(adapter)
         status = adapter.status()
         assert TOKEN not in repr(status)
+
+
+# ---------------------------------------------------------------------------
+# answer_callback: 400 errors are benign (expired query)
+# ---------------------------------------------------------------------------
+
+
+class TestAnswerCallbackExpired:
+    @pytest.mark.asyncio
+    async def test_answer_callback_400_does_not_crash(self):
+        """Regression: 400 'query is too old' should be swallowed so the
+        actual callback action still executes."""
+        transport = ScriptedTransport()
+        transport.queue(
+            "getUpdates",
+            _ok(
+                [
+                    {
+                        "update_id": 1,
+                        "callback_query": {
+                            "id": "raw-cbq-expired",
+                            "from": {"id": 200, "is_bot": False},
+                            "message": {
+                                "message_id": 1,
+                                "date": 1,
+                                "chat": {"id": 100, "type": "private"},
+                            },
+                            "data": "opaque-token-expired",
+                        },
+                    }
+                ]
+            ),
+        )
+        transport.queue(
+            "answerCallbackQuery",
+            _err(400, 400, "Bad Request: query is too old and response timeout expired"),
+        )
+        adapter = _make_adapter(transport)
+        await adapter.start()
+        await asyncio.sleep(0.05)
+
+        # Must NOT raise.
+        await adapter.answer_callback("opaque-token-expired")
+        await adapter.stop()
+
+    @pytest.mark.asyncio
+    async def test_answer_callback_403_still_raises(self):
+        """403 (bot blocked) must still propagate — it's a real error."""
+        transport = ScriptedTransport()
+        transport.queue(
+            "getUpdates",
+            _ok(
+                [
+                    {
+                        "update_id": 1,
+                        "callback_query": {
+                            "id": "raw-cbq-blocked",
+                            "from": {"id": 200, "is_bot": False},
+                            "message": {
+                                "message_id": 1,
+                                "date": 1,
+                                "chat": {"id": 100, "type": "private"},
+                            },
+                            "data": "opaque-token-blocked",
+                        },
+                    }
+                ]
+            ),
+        )
+        transport.queue(
+            "answerCallbackQuery",
+            _err(403, 403, "Forbidden: bot was blocked by the user"),
+        )
+        adapter = _make_adapter(transport)
+        await adapter.start()
+        await asyncio.sleep(0.05)
+
+        from app.remote.telegram.client import TelegramApiError
+
+        with pytest.raises(TelegramApiError):
+            await adapter.answer_callback("opaque-token-blocked")
+        status = adapter.status()
+        await adapter.stop()
         assert TOKEN not in str(status)
diff --git a/tests/remote/test_actions.py b/tests/remote/test_actions.py
index 3243e3c4..7abb72b9 100644
--- a/tests/remote/test_actions.py
+++ b/tests/remote/test_actions.py
@@ -3,6 +3,8 @@
 from __future__ import annotations
 
 import time
+from collections.abc import Iterator
+from pathlib import Path
 from unittest.mock import AsyncMock, MagicMock, patch
 from uuid import uuid4
 
@@ -122,8 +124,12 @@ def test_no_command_accepts_paths(self) -> None:
 class TestSlashCommands:
     @pytest.mark.asyncio
     async def test_help_returns_help_text(self, service: RemoteActionService) -> None:
+        mock_db = MagicMock()
         action = _make_action(text="/help")
-        result = await service.dispatch_command(MagicMock(), action)
+        with patch.object(
+            service._pairing_service, "authorize", return_value=MagicMock()
+        ):
+            result = await service.dispatch_command(mock_db, action)
         assert result.status == "ok"
         assert "/help" in result.text
         assert "/status" in result.text
@@ -135,10 +141,24 @@ async def test_help_returns_help_text(self, service: RemoteActionService) -> Non
         assert "/unpair" in result.text
         assert "/actions" in result.text
 
+    @pytest.mark.asyncio
+    async def test_help_requires_authorization(
+        self, service: RemoteActionService
+    ) -> None:
+        mock_db = MagicMock()
+        action = _make_action(text="/help")
+        with patch.object(service._pairing_service, "authorize", return_value=None):
+            result = await service.dispatch_command(mock_db, action)
+        assert result.status == "unauthorized"
+
     @pytest.mark.asyncio
     async def test_start_returns_help(self, service: RemoteActionService) -> None:
+        mock_db = MagicMock()
         action = _make_action(text="/start")
-        result = await service.dispatch_command(MagicMock(), action)
+        with patch.object(
+            service._pairing_service, "authorize", return_value=MagicMock()
+        ):
+            result = await service.dispatch_command(mock_db, action)
         assert result.status == "ok"
         assert "/help" in result.text
 
@@ -146,8 +166,12 @@ async def test_start_returns_help(self, service: RemoteActionService) -> None:
     async def test_unknown_command_returns_help(
         self, service: RemoteActionService
     ) -> None:
+        mock_db = MagicMock()
         action = _make_action(text="/unknown")
-        result = await service.dispatch_command(MagicMock(), action)
+        with patch.object(
+            service._pairing_service, "authorize", return_value=MagicMock()
+        ):
+            result = await service.dispatch_command(mock_db, action)
         assert result.status == "ok"
         assert "/help" in result.text
 
@@ -616,6 +640,13 @@ async def test_actions_with_items_sends_buttons(
 
 
 class TestSettings:
+    @pytest.fixture(autouse=True)
+    def _mock_home(self, tmp_path: Path) -> Iterator[None]:
+        """``Path.home()`` fails on some CI Windows images; stub it with
+        *tmp_path* so skill-discovery ``_iter_skill_roots`` does not crash."""
+        with patch("pathlib.Path.home", return_value=tmp_path):
+            yield
+
     @pytest.mark.asyncio
     async def test_settings_command_shows_current_mode_model_and_agent(
         self, service: RemoteActionService
@@ -824,7 +855,12 @@ async def test_health_command_shows_checks(
 
         fake_diagnostics = {
             "checks": [
-                {"id": "db", "label": "Database", "status": "ok", "detail": "connected"},
+                {
+                    "id": "db",
+                    "label": "Database",
+                    "status": "ok",
+                    "detail": "connected",
+                },
             ],
             "summary": "ok",
         }
@@ -1149,3 +1185,323 @@ async def test_onboarding_start_button_sends_a_friendly_prompt(
 
         assert handled is True
         assert adapter.sent_messages  # something was sent
+
+
+# ── Session history (/history) ────────────────────────────────────────────────
+
+
+class TestHistoryCommand:
+    """Regression tests for /history, session_detail, session_switch,
+    session_summarize — and the _issue_token parameter contract that caused
+    repeated crashes when fields were missing."""
+
+    @pytest.mark.asyncio
+    async def test_history_returns_sessions_with_buttons(
+        self, service: RemoteActionService, adapter: FakeAdapter
+    ) -> None:
+        async with db_module.async_session_factory() as db:
+            for i in range(3):
+                db.add(
+                    ChatSession(
+                        title=f"Session {i}",
+                        mode="work",
+                        session_type="main",
+                    )
+                )
+            await db.commit()
+
+            mock_pairing = MagicMock()
+            mock_pairing.active_session_id = None
+
+            with patch.object(
+                service._pairing_service, "authorize", return_value=mock_pairing
+            ):
+                action = _make_action(text="/history")
+                result = await service.dispatch_command(db, action)
+
+        assert result.status == "ok"
+        assert adapter.sent_messages, "history should send a message with buttons"
+        sent = adapter.sent_messages[-1]
+        assert len(sent.buttons) == 3, f"expected 3 buttons, got {len(sent.buttons)}"
+        assert "Recent sessions" in sent.text
+
+    @pytest.mark.asyncio
+    async def test_history_with_no_sessions(
+        self, service: RemoteActionService, adapter: FakeAdapter
+    ) -> None:
+        async with db_module.async_session_factory() as db:
+            mock_pairing = MagicMock()
+            mock_pairing.active_session_id = None
+
+            with patch.object(
+                service._pairing_service, "authorize", return_value=mock_pairing
+            ):
+                action = _make_action(text="/history")
+                result = await service.dispatch_command(db, action)
+
+        assert result.status == "ok"
+        assert "no session" in result.text.lower()
+
+    @pytest.mark.asyncio
+    async def test_history_issue_token_contract(
+        self, service: RemoteActionService, adapter: FakeAdapter
+    ) -> None:
+        """Regression: _issue_token requires all fields — missing any causes
+        TypeError that breaks chat until restart."""
+        async with db_module.async_session_factory() as db:
+            db.add(ChatSession(title="S1", mode="work", session_type="main"))
+            await db.commit()
+
+            mock_pairing = MagicMock()
+            mock_pairing.active_session_id = None
+
+            with patch.object(
+                service._pairing_service, "authorize", return_value=mock_pairing
+            ):
+                action = _make_action(text="/history")
+                result = await service.dispatch_command(db, action)
+
+        assert result.status == "ok"
+        assert adapter.sent_messages
+
+    @pytest.mark.asyncio
+    async def test_session_detail_shows_metadata(
+        self, service: RemoteActionService, adapter: FakeAdapter
+    ) -> None:
+        conn_id = uuid4()
+        async with db_module.async_session_factory() as db:
+            session = ChatSession(
+                title="Fix login bug",
+                mode="coding",
+                session_type="main",
+            )
+            db.add(session)
+            await db.commit()
+            await db.refresh(session)
+
+            token = service._issue_token(
+                action_kind="session_detail",
+                action_target=str(session.id),
+                connection_id=conn_id,
+                principal_id="user-1",
+                destination_id="chat-1",
+                session_id="",
+            )
+
+            callback_action = _make_action(
+                kind=RemoteInboundActionKind.CALLBACK,
+                callback_token=token,
+                connection_id=conn_id,
+            )
+            handled = await service.handle_action_callback(callback_action, db)
+
+        assert handled is True
+        assert adapter.sent_messages
+        sent = adapter.sent_messages[-1]
+        assert "Fix login bug" in sent.text
+        button_texts = [b.text for b in sent.buttons]
+        assert any("Switch" in t for t in button_texts)
+        assert any("Summarize" in t for t in button_texts)
+
+    @pytest.mark.asyncio
+    async def test_session_switch_updates_active_session(
+        self, service: RemoteActionService, adapter: FakeAdapter
+    ) -> None:
+        from app.models.remote import RemoteConnection, RemotePairing
+
+        conn_id = uuid4()
+        async with db_module.async_session_factory() as db:
+            # Create the connection first (FK dependency for pairing).
+            connection = RemoteConnection(
+                id=conn_id,
+                adapter="telegram",
+                label="TestConn",
+                enabled=True,
+                adapter_principal_id="user-1",
+            )
+            db.add(connection)
+
+            session = ChatSession(
+                title="Target",
+                mode="work",
+                session_type="main",
+            )
+            db.add(session)
+            await db.commit()
+            await db.refresh(session)
+
+            pairing = RemotePairing(
+                connection_id=conn_id,
+                principal_id="user-1",
+                destination_id="chat-1",
+                label="Test",
+            )
+            db.add(pairing)
+            await db.commit()
+            await db.refresh(pairing)
+
+            token = service._issue_token(
+                action_kind="session_switch",
+                action_target=str(session.id),
+                connection_id=conn_id,
+                principal_id="user-1",
+                destination_id="chat-1",
+                session_id="",
+            )
+
+            with patch.object(
+                service._pairing_service, "authorize", return_value=pairing
+            ):
+                callback_action = _make_action(
+                    kind=RemoteInboundActionKind.CALLBACK,
+                    callback_token=token,
+                    connection_id=conn_id,
+                )
+                handled = await service.handle_action_callback(callback_action, db)
+
+        assert handled is True
+        assert pairing.active_session_id == session.id
+        assert "Switched" in adapter.sent_texts[-1]
+
+    @pytest.mark.asyncio
+    async def test_session_summarize_shows_transcript(
+        self, service: RemoteActionService, adapter: FakeAdapter
+    ) -> None:
+        from app.models.chat import SessionMessage
+
+        conn_id = uuid4()
+        async with db_module.async_session_factory() as db:
+            session = ChatSession(
+                title="Chat",
+                mode="work",
+                session_type="main",
+            )
+            db.add(session)
+            await db.commit()
+            await db.refresh(session)
+
+            for role, content in [
+                ("user", "Fix the login bug"),
+                ("assistant", "I found the issue in auth.ts"),
+                ("user", "Also check the tests"),
+                ("assistant", "Tests pass now"),
+            ]:
+                db.add(
+                    SessionMessage(session_id=session.id, role=role, content=content)
+                )
+            await db.commit()
+
+            token = service._issue_token(
+                action_kind="session_summarize",
+                action_target=str(session.id),
+                connection_id=conn_id,
+                principal_id="user-1",
+                destination_id="chat-1",
+                session_id="",
+            )
+
+            callback_action = _make_action(
+                kind=RemoteInboundActionKind.CALLBACK,
+                callback_token=token,
+                connection_id=conn_id,
+            )
+            handled = await service.handle_action_callback(callback_action, db)
+
+        assert handled is True
+        text = adapter.sent_texts[-1]
+        assert "Session transcript" in text
+        assert "Fix the login bug" in text
+        assert "auth.ts" in text
+
+    @pytest.mark.asyncio
+    async def test_session_summarize_empty_session(
+        self, service: RemoteActionService, adapter: FakeAdapter
+    ) -> None:
+        conn_id = uuid4()
+        async with db_module.async_session_factory() as db:
+            session = ChatSession(
+                title="Empty",
+                mode="work",
+                session_type="main",
+            )
+            db.add(session)
+            await db.commit()
+            await db.refresh(session)
+
+            token = service._issue_token(
+                action_kind="session_summarize",
+                action_target=str(session.id),
+                connection_id=conn_id,
+                principal_id="user-1",
+                destination_id="chat-1",
+                session_id="",
+            )
+
+            callback_action = _make_action(
+                kind=RemoteInboundActionKind.CALLBACK,
+                callback_token=token,
+                connection_id=conn_id,
+            )
+            handled = await service.handle_action_callback(callback_action, db)
+
+        assert handled is True
+        assert "No messages" in adapter.sent_texts[-1]
+
+    @pytest.mark.asyncio
+    async def test_session_detail_deleted_session(
+        self, service: RemoteActionService, adapter: FakeAdapter
+    ) -> None:
+        conn_id = uuid4()
+        token = service._issue_token(
+            action_kind="session_detail",
+            action_target=str(uuid4()),
+            connection_id=conn_id,
+            principal_id="user-1",
+            destination_id="chat-1",
+            session_id="",
+        )
+
+        async with db_module.async_session_factory() as db:
+            callback_action = _make_action(
+                kind=RemoteInboundActionKind.CALLBACK,
+                callback_token=token,
+                connection_id=conn_id,
+            )
+            handled = await service.handle_action_callback(callback_action, db)
+
+        assert handled is True
+        assert "not found" in adapter.sent_texts[-1].lower()
+
+    def test_issue_token_requires_all_fields(self, service: RemoteActionService) -> None:
+        conn_id = uuid4()
+
+        with pytest.raises(TypeError, match="principal_id"):
+            service._issue_token(
+                action_kind="session_detail",
+                action_target="x",
+                connection_id=conn_id,
+                destination_id="d",
+                session_id="",
+            )
+
+        with pytest.raises(TypeError, match="destination_id"):
+            service._issue_token(
+                action_kind="session_detail",
+                action_target="x",
+                connection_id=conn_id,
+                principal_id="p",
+                session_id="",
+            )
+
+        with pytest.raises(TypeError, match="session_id"):
+            service._issue_token(
+                action_kind="session_detail",
+                action_target="x",
+                connection_id=conn_id,
+                principal_id="p",
+                destination_id="d",
+            )
+
+    def test_history_is_in_slash_commands(self) -> None:
+        assert "history" in _SLASH_COMMANDS
+        assert is_slash_command("/history")
diff --git a/tests/remote/test_formatting.py b/tests/remote/test_formatting.py
index 82778eb5..c82b286a 100644
--- a/tests/remote/test_formatting.py
+++ b/tests/remote/test_formatting.py
@@ -476,3 +476,214 @@ def test_render_changes_card_escapes_file_paths():
     )
     assert "