test: cover recent thread commands across channels

Author: Pyiner

docs/agents/repository-contracts.md

@@ -46,15 +46,43 @@ reinterpreted in feature code.
 
 - Mobile recent-thread lists read the gateway SQLite `recent_threads`
   projection only.
+- A task backing thread durably carries `thread_kind="task"` from creation
+  through task overlay deletion. `recent_threads.thread_type` and
+  `thread_meta.thread_type` derive from that canonical kind and therefore
+  remain `"task"` after the task itself is deleted. Do not infer task identity
+  from a live task projection, a title, or a title prefix.
 - Keep `recent_threads` current by writing it from the thread-store write path;
   do not make `GET /api/recent-threads` rescan router/thread files.
+- Bot `/threads` and `/bindthread` reads go through the injected
+  `RecentThreadPageReader`, backed by the same SQLite projection. A missing or
+  failed reader is an explicit temporary-unavailable result; never add a
+  thread-store scan fallback.
 - Provider bridge run persistence must use the same thread store as the
   gateway/router (the `SqliteThreadStore`) so active run state derives into
   `recent_threads` inside the same write transaction.
 - Do not repair stale `active_run_id` or `run_state` in read routes.
-- The only startup recovery is `clear_stale_active_runs`: one SQL pass that
-  settles running rows orphaned by the previous process (the bridge run
-  index is empty at boot). There is no other startup reconciliation.
+- The only recurring startup recovery is `clear_stale_active_runs`: one SQL
+  pass that settles running rows orphaned by the previous process (the bridge
+  run index is empty at boot). Versioned, transactional one-shot cutovers such
+  as `recent_task_thread_kind_v1` and `endpoint_holder_dedup_v1` run after the
+  boot import and record a durable marker; they are not read-time or recurring
+  reconciliation.
+
+## Endpoint Binding Ownership
+
+- Each endpoint key has at most one holder in canonical `thread_records`.
+  `endpoint_holder_dedup_v1` established this invariant for legacy data; every
+  later bind or detach must preserve it through the serialized
+  `EndpointBindingMutator` service.
+- Runtime bind/detach paths point-read the previous owner from
+  `thread_channel_endpoints`, validate known target records, and point-write
+  only the known previous/target records. HTTP bind/detach, `/newthread`, and
+  `/bindthread` must share this service. Do not reintroduce `list_keys` or
+  record-body scans to find endpoint holders.
+- When an endpoint has no projected owner, construct its first binding from
+  inbound or known-endpoint metadata. Persist binding-related delivery context
+  using the already-known record ids; absence of an owner is not permission to
+  scan.
 
 ## Transcript Rendering
 

docs/architecture/command-list-design.md

@@ -8,7 +8,7 @@ command list.
 Garyx currently has exactly two interaction command kinds:
 
 - `channel_native`: built-in channel-only management commands, such as
-  `/threads`, `/newthread`, `/threadprev`, and `/threadnext`.
+  `/newthread`, `/threads [page|next|prev]`, and `/bindthread <n>`.
 - `shortcut`: global prompt shortcuts configured by the user, such as
   `/summary -> "Summarize the active thread"`.
 
@@ -40,16 +40,17 @@ Response shape:
   "revision": "v1:...",
   "commands": [
     {
-      "id": "builtin.router.newthread",
-      "name": "newthread",
-      "slash": "/newthread",
+      "id": "builtin.router.threads",
+      "name": "threads",
+      "slash": "/threads",
       "aliases": [],
-      "description": "Start a new thread",
+      "description": "Browse recent threads",
       "category": "Thread",
       "kind": "channel_native",
       "source": "builtin",
       "surfaces": ["plugin", "telegram"],
-      "dispatch": { "type": "router_native", "key": "router.native.newthread" },
+      "dispatch": { "type": "router_native", "key": "router.native.threads" },
+      "args_hint": "[page|next|prev]",
       "visibility": "visible",
       "warnings": []
     }
@@ -68,6 +69,27 @@ Response shape:
   `channel_native` and `shortcut` commands.
 - Shortcuts are globally visible wherever shortcut execution is supported.
 
+The visible thread-management menu is `newthread`, `threads`, and
+`bindthread`. `threadprev` and `threadnext` remain reserved and recognizable
+for one compatibility release, but are hidden from normal command lists and
+Telegram menus. They return migration guidance instead of switching threads:
+use `/threads prev|next`, then `/bindthread <n>`. Callers requesting
+`include_hidden=true` may inspect those compatibility entries.
+
+## Thread Command Semantics
+
+- `/threads`, `/threads <page>`, `/threads next`, and `/threads prev` browse
+  the global recent non-task thread projection in pages of 10. Addressed forms
+  such as `/threads@bot_name 2` preserve the same arguments.
+- `/bindthread <n>` switches to an absolute row number from pages successfully
+  shown to that endpoint. A canonical `thread::<id>` may also be supplied for
+  compatibility; either form is revalidated before binding.
+- `/newthread` creates and binds a fresh thread, then clears the endpoint's
+  accumulated recent-list snapshot.
+
+`args_hint` is `[page|next|prev]` for `threads` and `<n>` for `bindthread`.
+Invalid arguments are handled locally and never become model prompts.
+
 ## Plugin Contract
 
 Channel plugins fetch the command list through host RPC:
@@ -117,4 +139,6 @@ Gateway core does not expose a manual Telegram command-sync endpoint.
 - Payload uses `revision`.
 - Plugin RPC uses `commands/list` and returns the command-list shape.
 - Telegram sync includes both `channel_native` and `shortcut` commands.
+- Telegram's visible native menu contains `newthread`, `threads`, and
+  `bindthread`; deprecated navigation commands remain hidden.
 - Mac app settings manage only prompt shortcuts.

docs/concepts/threads-and-workspaces.md

@@ -38,6 +38,25 @@ endpoint reads only the SQLite projection and returns pagination metadata
 (`total`, `offset`, and `has_more`) alongside the requested page. It must not
 rescan router thread files on the read path.
 
+The optional `tasks` query parameter selects the filtering domain before
+pagination:
+
+- `tasks=include` includes task and non-task threads and is the default when
+  the parameter is omitted.
+- `tasks=exclude` returns only non-task threads.
+- `tasks=only` returns only task threads.
+
+Unknown values return HTTP 400. `total`, `offset`, and `has_more` always
+describe the selected domain. Existing clients that omit `tasks` retain the
+same member set, ordering, pagination, envelope, and row schema.
+
+Channel bots use this same projection for thread management. The
+`/threads [page|next|prev]` command browses recent non-task threads in pages of
+10, and `/bindthread <n>` binds an absolute row number from pages that endpoint
+has already seen. `/newthread` creates a fresh thread. The former
+`/threadprev` and `/threadnext` commands are hidden compatibility commands that
+now point users to the browse-then-bind flow.
+
 ## How a chat becomes a thread
 
 When a message arrives on a channel, Garyx looks up the right thread by: