feat(pools): channel parity (REST + Telegram) and refresh-grant token-host scoping (#47)

* feat(poolops): extract channel-agnostic pool operations

Move pool create/list/status/rotate/remove logic into internal/poolops
so CLI, REST, and Telegram share one implementation. Adds structured
errors (already-pooled member, live-member removal, delete conflict)
returned channel-neutrally.

* feat(cli): wire pool subcommand through poolops

sluice pool create|list|status|rotate|remove now delegate to the
shared poolops package; rotate-race hint points to 'sluice pool status'.

* feat(api): rest endpoints for credential pools

Add /api/pools CRUD plus status/rotate via poolops; pool-create
honors the 409 conflict contract and returns structured
pool-delete conflict payloads. Token-host grant parse restricted
to form bodies.

* feat(telegram): /pool create|list|status|rotate|remove commands

Telegram bot reaches pool management through poolops, matching CLI
and REST channel parity.

* fix(proxy): scope pool token-host phantom expansion to refresh_token grants

Restrict the pool token-host phantom split-host expansion to
refresh_token grant requests so non-refresh traffic is unaffected;
parse only form bodies.

* feat(telegram): friendlier pool failover notification text

Reword the pool failover Telegram notice into human-readable text
(task 4b).

* docs: document /pool and /api/pools surfaces; channel-parity plan

Document the pool management surfaces across CLI/REST/Telegram in
CLAUDE.md and README, and record the channel-feature-parity plan
(incl. task 4b) as completed.

* fix(api): dedicated pool-referenced 409 schema; build create 201 from request data

split the pool-delete 409 body into PoolReferencedErrorResponse so the
generic ErrorResponse envelope is no longer coupled to one endpoint
(regenerated api.gen.go via oapi-codegen). PostApiPools now builds the
201 body from the request members + failover default instead of gating
on a store read-back, so a read-back error can no longer report a
successful create as a 500. poolStatusError no longer checks
ErrCredentialInUseByPool, which is unreachable from the pool handlers
(raised only by the credential-removal path).

* fix(proxy): gate grant_type probe to token-host POSTs; raise+observe probe cap

requestFlowGrantType now skips the string(body)+ParseQuery grant_type
probe unless the request is an HTTP POST whose scheme+host matches a
known OAuth token endpoint (new OAuthIndex.MatchesHost), removing the
per-request body parse on the hot path for non-OAuth traffic. The
form/JSON parsers in extractRequestRefreshToken and requestGrantType no
longer double-stringify the body for an explicit form Content-Type. The
probe cap is raised 8KiB->64KiB so a large RFC 7523 refresh payload at a
pool token host is still expanded, with a rate-limited WARNING when the
cap truncates a probe. StreamRequestModifier's buffered-path-only
limitation is documented explicitly.

* fix(proxy): drop awkward parenthetical from empty-reason failover notice

FormatFailoverNotice rendered '(unknown reason)' / 'after unknown
reason' when the reason tag was empty. Drop the reason clause entirely
in that case for both the exhausted and normal messages. The
cred_failover / pool_exhausted audit Reason format is unchanged.

* fix(telegram): escape pool name in rotate-race hint; assert pool removal

the /pool status hint in the rotate-race message wrote the raw pool name
into an HTML-parsed reply, so a name with <,>,& would break rendering;
htmlCode it like the other occurrence. The pool-remove test guarded on
'err == nil', which GetPool returns even for a missing pool; assert the
pool row is actually gone instead.

* docs(readme): note bearer auth required for REST API examples

the /api/* curl examples omit the Authorization header though the
endpoints are behind BearerAuth; add a single leading note covering the
credential, pool, and rule examples.

* fix(telegram): drop dead ErrCredentialInUseByPool branch in poolRemove

* fix(api): map internal pool-create failures to 500 not 400

Invert poolCreateError: conflict sentinels stay 409, genuine client-input
validation sentinels are 400, and everything else (tx/DB/INSERT failures
inside store.CreatePoolWithMembers, which are wrapped fmt.Errorf strings
with no sentinel) now defaults to 500 instead of being misclassified as a
client 400. Add typed, errors.Is-able sentinels in internal/store for the
client-validation cases that previously had only wrapped messages
(ErrPoolNoMembers, ErrPoolStrategyInvalid, ErrPoolMemberDuplicate,
ErrPoolMemberNotFound, ErrPoolMemberNotOAuth), wrapped at origin so the
existing human-readable text is preserved verbatim. Document the new 500
response on POST /api/pools in the OpenAPI spec and regenerate.

* fix(proxy): make unknown failover reason read naturally; drop dead empty case

humanizeFailoverReason now renders an unknown tag as 'unknown reason
(<tag>)' so the surrounding 'failed over ... after %s.' and exhausted
'... to (%s).' clauses read naturally instead of the redundant 'failed
over ... after failover (<tag>).'. Remove the unreachable case "":
branch: FormatFailoverNotice is the sole caller and short-circuits an
empty reason before ever calling here, so the empty-tag wording has a
single source of truth there. Update the notice/humanize tests
accordingly.

* fix(telegram): HTML-escape pool member LastFailureReason in status

poolStatus sends with HTML parse mode (htmlCode emits <code>), but
appended m.LastFailureReason (upstream error text, may contain < > &)
raw, which breaks rendering or is rejected by the Bot API. Escape it
with htmlEscape (prose, not an identifier, so not htmlCode) consistent
with every other user-facing value on that line. Add a test asserting a
reason with < > & is rendered escaped.

* fix(telegram): html-escape bind hint in pool create reply

Author: nnemirovsky

CLAUDE.md

@@ -181,6 +181,8 @@ sluice pool rotate <name>     # operator override: advance active member
 sluice pool remove <name>
 ```
 
+Pools are reachable from all channels — CLI `sluice pool`, REST `/api/pools` (`GET`/`POST`, `GET`/`DELETE /api/pools/{name}`, `POST /api/pools/{name}/rotate`), and Telegram `/pool` — all via the channel-agnostic `internal/poolops`.
+
 Auto-failover on 429/401 is primary; `pool rotate` is an override.
 
 **Data model (migration `000006_credential_pools`):** `credential_pools` (name, strategy reserved `failover`), `credential_pool_members` (ordered, pool->credential FK), `credential_health` (`healthy|cooldown`, `cooldown_until`, `last_failure_reason`), all CHECK-constrained. Store API in `internal/store/pools.go`. `reloadAll` loads pool+health into an atomic-pointer-swapped `PoolResolver` (`internal/vault/pool.go`), rewired via `srv.StorePool`/`SetPoolResolver` on SIGHUP and the 2s data-version watcher.

README.md

@@ -329,6 +329,11 @@ Manage sluice from your phone. Approve connections and tool calls, add credentia
 | `/mcp list` | List registered MCP upstreams |
 | `/mcp add <name> --command <cmd> [flags]` | Register a new MCP upstream (stdio/http/websocket, see `/help`; chat message auto-deleted because `--env` may carry secrets) |
 | `/mcp remove <name>` | Remove an MCP upstream |
+| `/pool create <name> <a,b[,c]>` | Create a credential pool (ordered OAuth members, failover order) |
+| `/pool list` | List credential pools |
+| `/pool status <name>` | Active member and per-member health |
+| `/pool rotate <name>` | Operator override: advance the active member |
+| `/pool remove <name>` | Remove a credential pool |
 | `/status` | Proxy stats and pending approvals |
 | `/audit recent [N]` | Last N audit entries |
 
@@ -338,6 +343,11 @@ Manage sluice from your phone. Approve connections and tool calls, add credentia
 
 REST API on port 3000 for programmatic approval integration. `GET /api/approvals` lists pending requests, `POST /api/approvals/{id}/resolve` resolves them. Use this to build custom approval UIs or integrate with existing workflows.
 
+All `/api/*` endpoints below are protected by bearer auth. Every request must
+send `Authorization: Bearer $SLUICE_API_TOKEN` (the token sluice prints at
+startup). The curl examples omit the header for brevity, but it is required
+for the credential, pool, and rule calls shown here.
+
 Credential management endpoints support both static and OAuth types:
 
 ```bash
@@ -350,6 +360,26 @@ curl -X POST http://localhost:3000/api/credentials \
   -d '{"name":"openai_oauth","type":"oauth","token_url":"https://auth.example.com/token","access_token":"at-xxx","refresh_token":"rt-xxx","destination":"api.openai.com","env_var":"OPENAI_API_KEY"}'
 ```
 
+Credential pools are managed over the same REST surface as the CLI `sluice pool` and Telegram `/pool` commands:
+
+```bash
+# List pools
+curl http://localhost:3000/api/pools
+
+# Create a pool (members are ordered OAuth credential names; strategy defaults to "failover")
+curl -X POST http://localhost:3000/api/pools \
+  -d '{"name":"openai","members":["codex_a","codex_b"]}'
+
+# Pool status (active member + per-member health)
+curl http://localhost:3000/api/pools/openai
+
+# Operator override: advance the active member
+curl -X POST http://localhost:3000/api/pools/openai/rotate
+
+# Remove a pool
+curl -X DELETE http://localhost:3000/api/pools/openai
+```
+
 ## Data Loss Prevention
 
 Two complementary inspection layers protect against credential leakage and dangerous tool use:

api/openapi.yaml

@@ -519,6 +519,139 @@ paths:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
 
+  /api/pools:
+    get:
+      operationId: getApiPools
+      summary: List credential pools
+      tags: [pools]
+      responses:
+        "200":
+          description: Credential pools
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Pool"
+    post:
+      operationId: postApiPools
+      summary: Create a credential pool
+      tags: [pools]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreatePoolRequest"
+      responses:
+        "201":
+          description: Pool created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Pool"
+        "400":
+          description: Invalid request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "409":
+          description: Pool name collides or a member is already pooled
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "500":
+          description: Internal error creating the pool (transaction/DB failure)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+
+  /api/pools/{name}:
+    get:
+      operationId: getApiPoolsName
+      summary: Pool status (active member + per-member health)
+      tags: [pools]
+      parameters:
+        - name: name
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Pool status
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PoolStatus"
+        "404":
+          description: Pool not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+    delete:
+      operationId: deleteApiPoolsName
+      summary: Remove a credential pool
+      tags: [pools]
+      parameters:
+        - name: name
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "204":
+          description: Pool removed
+        "404":
+          description: Pool not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "409":
+          description: >-
+            Pool still referenced by one or more bindings. The response body's
+            `bindings` field lists the blocking bindings (id + destination).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PoolReferencedErrorResponse"
+
+  /api/pools/{name}/rotate:
+    post:
+      operationId: postApiPoolsNameRotate
+      summary: Operator override — advance the active pool member
+      tags: [pools]
+      parameters:
+        - name: name
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Rotation result
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PoolRotateResult"
+        "404":
+          description: Pool not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "409":
+          description: Rotate raced a concurrent membership change
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+
   /api/audit/recent:
     get:
       operationId: getApiAuditRecent
@@ -619,6 +752,36 @@ components:
         code:
           type: string
 
+    PoolReferencedErrorResponse:
+      description: >-
+        409 body for DELETE /api/pools/{name} when the pool is still
+        referenced by one or more bindings. Carries the generic error/code
+        plus the structured list of blocking bindings (id + destination); the
+        CLI and Telegram surfaces render the same list (channel parity). This
+        is a dedicated schema so the generic ErrorResponse envelope is not
+        coupled to one endpoint.
+      type: object
+      required: [error, bindings]
+      properties:
+        error:
+          type: string
+        code:
+          type: string
+        bindings:
+          type: array
+          items:
+            $ref: "#/components/schemas/PoolReferencingBinding"
+
+    PoolReferencingBinding:
+      type: object
+      required: [id, destination]
+      properties:
+        id:
+          type: integer
+          format: int64
+        destination:
+          type: string
+
     HealthResponse:
       type: object
       required: [status]
@@ -1009,6 +1172,98 @@ components:
         timeout_sec:
           type: integer
 
+    Pool:
+      type: object
+      required: [name, strategy, members]
+      properties:
+        name:
+          type: string
+        strategy:
+          type: string
+          description: "Pool strategy (only 'failover' is supported)"
+        created_at:
+          type: string
+          format: date-time
+        members:
+          type: array
+          items:
+            $ref: "#/components/schemas/PoolMember"
+
+    PoolMember:
+      type: object
+      required: [credential, position]
+      properties:
+        credential:
+          type: string
+        position:
+          type: integer
+
+    CreatePoolRequest:
+      type: object
+      required: [name, members]
+      properties:
+        name:
+          type: string
+        strategy:
+          type: string
+          description: "Pool strategy; defaults to 'failover' when omitted"
+        members:
+          type: array
+          description: "Ordered member credential names (failover order)"
+          items:
+            type: string
+
+    PoolStatus:
+      type: object
+      required: [name, strategy, active, members]
+      properties:
+        name:
+          type: string
+        strategy:
+          type: string
+        active:
+          type: string
+          description: "Currently active member credential name"
+        members:
+          type: array
+          items:
+            $ref: "#/components/schemas/PoolMemberStatus"
+
+    PoolMemberStatus:
+      type: object
+      required: [credential, position, active, state]
+      properties:
+        credential:
+          type: string
+        position:
+          type: integer
+        active:
+          type: boolean
+        state:
+          type: string
+          description: "healthy, cooldown, or healthy (cooldown expired)"
+        cooldown_until:
+          type: string
+          format: date-time
+        last_failure_reason:
+          type: string
+
+    PoolRotateResult:
+      type: object
+      required: [pool, from, to]
+      properties:
+        pool:
+          type: string
+        from:
+          type: string
+          description: "Member that was active and is now parked"
+        to:
+          type: string
+          description: "New active member after the rotation"
+        parked_until:
+          type: string
+          format: date-time
+
     AuditEntry:
       type: object
       required: [timestamp, verdict]

cmd/sluice/main.go

@@ -516,12 +516,7 @@ func main() {
 				// Exhausted: no distinct member to fail over to (every
 				// member cooling) — report it as pool exhaustion, NOT a
 				// self-referential "X -> X" transition.
-				msg := fmt.Sprintf("pool %s failed over %s -> %s (%s)",
-					ev.Pool, ev.From, ev.To, ev.Reason)
-				if ev.Exhausted {
-					msg = fmt.Sprintf("pool %s exhausted: all members cooling down (%s); no healthy account to fail over to",
-						ev.Pool, ev.Reason)
-				}
+				msg := proxy.FormatFailoverNotice(ev)
 				ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
 				defer cancel()
 				for _, ch := range failoverBroker.Channels() {