Summary

Give chat sessions real management across the gateway and the mobile apps: pin, archive (with a reachable archived list), rename, and search.

Problem to solve

The iOS and Android apps show chat sessions as a flat, recency-ordered list with create/switch/reset only. There is no way from the apps to pin an important session, rename one to something meaningful, archive old ones (or see archived sessions at all), or search across sessions. On gateways with many sessions this makes the session list hard to use.

The gateway session store already persists the needed metadata (label, pinnedAt, archivedAt) and sessions.list already supports search and archived filters with pinned-first ordering, but the only mutation surface (sessions.patch) requires the operator.admin scope. The Android app intentionally connects as a bounded operator without admin scope, so it cannot pin, rename, or archive sessions even though the store supports it.

Proposed solution

• Gateway: allow operator.write clients to mutate the user-level chat-organization fields only (label, pinned, archived) via the existing sessions.patch method, using a params-aware scope check (same mechanism as plugins.sessionAction). Patches touching any other field keep requiring operator.admin (fail closed). Keep existing guards: no archiving sessions with active runs, no archiving an agent's main session, webchat mutations stay rejected. Make session list ordering fully deterministic (stable tiebreaker for equal timestamps). Add RPC test coverage for pin/rename/archive/search flows.
• iOS: session list management UI — swipe/context actions for pin/archive/rename, pinned-first ordering, an archived section, and a search field backed by server-side sessions.list search with local filtering fallback for cached lists.
• Android: same feature set via ChatController + the sessions screen, with the same server search and cached-list fallback.
• Control UI parity (pin/archive/rename/search in the web UI) is a follow-up, not part of this work.

No protocol schema changes are needed: sessions.patch params already include label/pinned/archived, sessions.list already accepts search/archived, and session rows already project those fields.

Alternatives considered

• New dedicated write-scoped RPC (for example sessions.update) carrying only the safe fields: rejected because it duplicates the existing mutation path for the same fields and adds protocol/codegen surface for no behavioral gain.
• Granting mobile clients operator.admin: rejected; the Android operator session is deliberately least-privilege, and rename/pin/archive do not justify admin.

Impact

• Affected: all iOS/Android app users managing more than a handful of sessions
• Severity: medium (organizational pain, grows with session count)
• Frequency: daily for multi-session users
• Consequence: sessions are hard to find; archived sessions are unreachable from the apps; no durable naming

Evidence/examples

• Store metadata: src/config/sessions/types.ts (pinnedAt, archivedAt, label)
• Mutation surface and guards: src/gateway/server-methods/sessions.ts (sessions.patch handler)
• List search/ordering: src/gateway/session-utils.ts (filterSessionEntries, compareSessionEntryPairs)
• Scope policy: src/gateway/method-scopes.ts, src/gateway/methods/core-descriptors.ts
• Android bounded operator scopes: apps/android/app/src/main/java/ai/openclaw/app/node/ConnectionManager.kt (nativeClientOperatorScopes)
• iOS session list: apps/ios/Sources/Design/CommandCenterTab.swift (CommandSessionsScreen)

Additional information

Planned landing order: gateway PR first, then iOS and Android client PRs stacked on it.