code-context-control 2.124.0__py3-none-any.whl → 2.125.0__py3-none-any.whl

cli/c3.py

@@ -92,7 +92,7 @@ console = Console() if HAS_RICH else None
 # Config
 CONFIG_DIR = ".c3"
 CONFIG_FILE = ".c3/config.json"
-__version__ = "2.124.0"
+__version__ = "2.125.0"
 
 
 def _compress_file_cli(compressor, path, mode="smart", **kw):

{code_context_control-2.124.0.dist-info → code_context_control-2.125.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-context-control
-Version: 2.124.0
+Version: 2.125.0
 Summary: Local MCP code-intelligence for AI coding tools: surgical search/read/edit, agent-config version history, path-level access + masking guards, and a multi-project hub.
 Author-email: Dimitri Tselenchuk <dtselenc@gmail.com>
 License-Expression: Apache-2.0
@@ -380,7 +380,7 @@ C3 also records real per-tool usage to `.c3/tool_telemetry.jsonl`, so estimates
 ## Security & privacy
 
 - **All web servers bind `127.0.0.1` by default** and are guarded against browser-based attacks even on loopback — a Host-header allowlist (defeats DNS rebinding) plus an Origin/Referer check on every request (defeats cross-origin CSRF), with scoped, non-wildcard CORS. There is still **no user authentication**, so do not expose these servers to an untrusted network without auth/TLS in front. Binding to a non-loopback interface is opt-in and warned at startup. *(Hardening added in v2.33.0.)*
-- **Mobile gateway (`/api/mobile/*`)** — the Oracle exposes a companion-app surface for the C3 mobile app: merged cross-project feed, project overview, PM board read/write, digest, notification ack, plus the security surface (credential vault, Access Guard rules and masks, tool discipline). Unlike the legacy Oracle GETs it requires the **Discovery Bearer token on every method, GETs included**, validates every project path against the registry, and audits every write to the project's activity log and edit ledger. Pair the app from Oracle Settings → *Mobile app* (QR code carrying URL + token). Remote reachability is the same recipe as the Discovery API: set `bind_host` to the Tailscale/LAN interface IP (avoid `0.0.0.0`) and list that address in `allowed_hosts`, both in `~/.c3/oracle/config.json`. Disable the whole surface with `"mobile_api_enabled": false`, or any subsystem with `mobile_credentials_enabled` / `mobile_access_enabled` / their `_write` twins.
+- **Mobile gateway (`/api/mobile/*`)** — the Oracle exposes a companion-app surface for the C3 mobile app: merged cross-project feed, project overview, PM board read/write, digest, notification ack, plus the security surface (credential vault, Access Guard rules and masks, tool discipline). Unlike the legacy Oracle GETs it requires a **Bearer token on every method, GETs included** — the Discovery token, or (v2.125.0+) a **per-client token**: one credential per paired device, stored hashed in `~/.c3/oracle/clients.json`, revocable one at a time, and carrying a kind (`mobile` or `desk`) that override decisions are audited under. It validates every project path against the registry, and audits every write to the project's activity log and edit ledger. Pair the app from Oracle Settings → *Mobile app* (the QR carries the URL and a freshly minted per-device token; a legacy Discovery-token code is one button away). A same-machine client such as C3 Desk pairs itself with `POST /api/mobile/clients` and the owner-only `~/.c3/oracle/bootstrap.key`. Remote reachability is the same recipe as the Discovery API: set `bind_host` to the Tailscale/LAN interface IP (avoid `0.0.0.0`) and list that address in `allowed_hosts`, both in `~/.c3/oracle/config.json`; with such a bind the Oracle also listens on `127.0.0.1` (`loopback_listener`, default on) so local clients are not refused. Disable the whole surface with `"mobile_api_enabled": false`, or any subsystem with `mobile_credentials_enabled` / `mobile_access_enabled` / their `_write` twins.
 - **The mobile gateway never returns a credential value.** It has no reveal route by design: entries cross the wire through an allowlist serializer, and a value can only be identified by its length and an on-demand fingerprint. Two further levers ship **off** — `mobile_creds_agent_readable_raise` (raising `agent_readable` from the phone) and `mobile_access_global_scope` (machine-wide access rules) — because each exceeds what a leaked Bearer token could otherwise reach. Deliberately absent from the surface: bulk `.env` import, denial-counter clearing, `set_builtin_disabled`, and the raw-content access preview.
 - **No telemetry by default.** The OSS package collects nothing. Opt-in Sentry crash reporting requires the `[telemetry]` extra plus both `SENTRY_DSN` and `C3_TELEMETRY_OPT_IN=1`; even then request bodies, local variables, and prompts are stripped.
 - **LLM memory distillation is local-first.** Cloud distillation (v2.51.0) is off by default and opt-in per project.

{code_context_control-2.124.0.dist-info → code_context_control-2.125.0.dist-info}/RECORD

@@ -1,7 +1,7 @@
 cli/__init__.py,sha256=ec66drCZGNMRU4V6ov0zVhYZph1us12Vn8OvG_LJyRY,22
 cli/_hook_utils.py,sha256=e48F6FQloFReUIMtmWsih2t54j9SROzAaHtMkEuttDs,20489
 cli/_shell_writes.py,sha256=XzUNlUDljmg-wZxK03xHnRe36WeQxe4tpO9HKVFwP5o,5090
-cli/c3.py,sha256=TRLSfHOBi-9AxQUAaXYq46tFgaBd4WMKw0WIBnFijHI,416843
+cli/c3.py,sha256=C6fQM1K-pxXJFCuqdqjRVfDyXy5J19BdVlgh2gDa5kk,416843
 cli/docs.html,sha256=X9M7qC7LWi8pPJNF-4yEM57jhuZ3WeTESECbdDOeNaA,143172
 cli/edits.html,sha256=UjAhoCmBmQ89cklGvJqzC6eyNP2tc8H6T-e01DVkLvE,43418
 cli/hook_access_guard.py,sha256=ba8-un6G9Ap8HCzx7nyhVq3c_G4sOtiVXRy0BzzX8-Y,23349
@@ -123,7 +123,7 @@ cli/ui/components/sessions.js,sha256=FIKtil76B8tCkAmcFV7hlj6GQ_DCJK2jCzvEmdK7NBE
 cli/ui/components/settings.js,sha256=ATbAjBlVIwCNpxq7s191b49a_INQV38iwmySqtJLYwY,79066
 cli/ui/components/sidebar.js,sha256=K2ym2kUgpbyG-EBA_wBIIiqQY8qTatsiBZwzseMWuIQ,9939
 cli/ui/components/tasks.js,sha256=vyKQ3uwoppMwvdEaHlhWXW4oWcAisx4NveqzMhsYqHo,38438
-code_context_control-2.124.0.dist-info/licenses/LICENSE,sha256=l8Kh5QCNWNvR6kIt8L0BUZvc2LAFiHv2c-FnsGnUZf4,11301
+code_context_control-2.125.0.dist-info/licenses/LICENSE,sha256=l8Kh5QCNWNvR6kIt8L0BUZvc2LAFiHv2c-FnsGnUZf4,11301
 core/__init__.py,sha256=TSDCEcM4V7gcZVM3w2ykJaqEUch4Dkon-rivV17T73s,2501
 core/codex_patch.py,sha256=CxvT_rQIwPNTRJZj9EHJmx0ZdOeSLxjiixuLI3Z7lPc,2107
 core/config.py,sha256=YmkcZwedz_lfDM0ZuI_f4xpe98ixPLcSQFcTCHgRiRg,19206
@@ -132,17 +132,19 @@ core/ide.py,sha256=y9J6dGTD_FpNDSHY38nn_UduP_Ey2iP5XZ9fU_rhY10,6227
 core/mcp_toml.py,sha256=VNZCjJsr4II_jX3cmjYzDh_OQ7Nk34mLnkg528Tl1GM,7047
 core/web_security.py,sha256=HwgK5aBATfvRIeO_4gWgzK77gKwGuzVlmiuNGm4gGxI,7884
 oracle/__init__.py,sha256=-OTD7Jh4mUMA4QgPGthPLWXttgZLpkIPhGQ87ZfHBx0,63
-oracle/config.py,sha256=F2m9GfgJbpkmXEecglWF3GYeHtPSVDY6HOXQpiMJ3B8,6324
+oracle/config.py,sha256=cypUJHKAj1AODIuRKefdGI-myHrvEEi4OuNzTcsfMwo,6645
+oracle/listeners.py,sha256=lV59aFuMddq-H8l8328NmDyfI79LaB-rcFyrv5cFmog,8054
 oracle/mcp_oracle.py,sha256=B5B-qSxi37outsuRHn1Ns6Gj8e7W593rmL34LMzuE8M,8980
-oracle/oracle_server.py,sha256=gL0DBXXmkGZPFSV54wQmy8hbeGPU662qBS-0nlHYMs0,49468
-oracle/oracle_ui.html,sha256=bfW7t9cgax-HNT5a41duYSUS_w0orSX3uinwPv-Fffs,71766
+oracle/oracle_server.py,sha256=cSv-a7CrqyZCAlKEqJGXm3TPBep6zyULYmY6lOeu5hM,53344
+oracle/oracle_ui.html,sha256=C4NZbQzo1QDx93EZk9kJaeD4IRWUz7OikYZRcaacI4E,72360
 oracle/services/__init__.py,sha256=Nb4POd1_YIwLVYsGfr-DiK-iKTelkU0fh9m7wjeLQHA,23
 oracle/services/activity_reporter.py,sha256=ZAxNFyUy7QRP28anQLRbKEwm5SGG97KIQYFQDLjYqlM,11729
 oracle/services/api_auth.py,sha256=1PW3pG--1DJb_F6qMhP3gBTYHxxPE2bsHmVmIhC81Y8,3566
 oracle/services/c3_bridge.py,sha256=67v_l44Yjep4Ibh_xwQVLlz9lEifqiDUoXBWIxcfKzQ,18878
 oracle/services/chat_engine.py,sha256=zvjyFsXGwqRHsvggBwQ6L0hcOovQe0AKyOy2ZdOU0No,55974
-oracle/services/chat_poll.py,sha256=GZJdYvB09ifFxSmbwEb52tLZm28wYmYIwQh48e6SmkU,15597
+oracle/services/chat_poll.py,sha256=VrfWjBrJQgAdwNZuHAy7qzN-qAqNByG3Q7WqoItCnfs,15859
 oracle/services/chat_store.py,sha256=mXH-eWo78dKnVUcPVW_1i0JD2nZYVss5xcyd3HM1KGc,10065
+oracle/services/client_tokens.py,sha256=upPr7ssTb0HK40Wd1E2O-r0JXSgPrZGXghM_thujTOY,8358
 oracle/services/cross_memory.py,sha256=F8JeYkEFSwQL3iGS9KV1onaMSFj3opr6f3nCxwvznV0,5484
 oracle/services/discovery_audit.py,sha256=zhKJfLfedTS9LIjNimLERidg0iqAC565svEvp8-IA98,5778
 oracle/services/federated_graph.py,sha256=QTaP31Z1pa_J2rlI9BOBBtDHta887AAs4v4sCaDSN8g,20660
@@ -151,14 +153,14 @@ oracle/services/insight_engine.py,sha256=lwcdXtjt3CSZLqHVpXx6SG5gDhZYUKwXt4Z8dGy
 oracle/services/local_session.py,sha256=nkawOjDbotUp5wtZQnC1wPDw3HopNYMkoYqWpP5ToCU,9227
 oracle/services/memory_reader.py,sha256=rSEmoIXQu2JkolHJIQWpn0piPJpyuf1KZvW_9liQwkU,3727
 oracle/services/memory_writer.py,sha256=hpvYsxjhl293jEjGcRKfjG5njUaAOXKqbmJaUu1WdUU,6997
-oracle/services/mobile_api.py,sha256=9nYE84FRHtgiwv6b9Hs17o3pKYXtPlYCn1Xny_gMLhk,120326
+oracle/services/mobile_api.py,sha256=Mpp9dU-OlGyWgizV0aQRWH0mdjXjBeQseLCWkdeky3Y,128103
 oracle/services/project_scanner.py,sha256=PkYJtwOLRME1EzwRy3GIkYk6Xw0u1_BzFcaMJ5gJ1_s,6118
 oracle/services/review_agent.py,sha256=m_fzoHowpiibf0_iz3dF72LWSrwB_FbDd1am-SbeWXg,11273
 oracle/services/tool_executor.py,sha256=xtAkBWkclh_FwOgzprjGkyRIV8-A7Lc3bz0UFPShrv0,1113
 oracle/services/tool_registry.py,sha256=mJUZSS99PDH8whkndNxcQXT1uoNxPviE3MotGzj2jtk,26046
 oracle/ui/activity.js,sha256=zbJjqkY-tTQS4YKcdSEr2Z5zAbwbOIPyTNzldQSPU7I,4830
 oracle/ui/agents.js,sha256=RNnsGUVg5DlRYiv-Ovzb3W4yyP4z0qTX3o7Y1_BgZpo,4538
-oracle/ui/app.js,sha256=fyfFL7YNbl_z1WSUOMXScp4qcavuFVg5cnA7D1i3zYU,795
+oracle/ui/app.js,sha256=Ry_V4qn7WnxmeTFN7xutMQJTgGVaR0vZzidgCxtwp1c,816
 oracle/ui/busy.js,sha256=ePFGqEheHpn-E971pN_9DbQvvkxD-d2V7Efbw68bpo0,4122
 oracle/ui/core.js,sha256=sDrD1hWKMliOO6rjmTsaTULXauKzphc5tm9NEcNTcd4,5478
 oracle/ui/crossgraph.js,sha256=7yBCciuEzZ0LYspWMO0xTe_GuPQ_NccnIeRrqEq5Qxs,9234
@@ -166,7 +168,7 @@ oracle/ui/header.js,sha256=xMymi7x7mvoImlL-1iOfEwmwp7AJkiCp31xNLlGoIgE,4189
 oracle/ui/insights.js,sha256=zACyfGz9-4y2eFd6OM1IE-L_HyL1wnqo46nJDyRx7-M,2408
 oracle/ui/projects.js,sha256=ULE6Py1iULVmRGy0mCnEAxKNwHvn-baUYlNDF5xGYM8,13002
 oracle/ui/qrcode.js,sha256=GK45n4EYK8nekW6cd7GV3yDMWNby1VpisIWimfG_F4A,56694
-oracle/ui/settings.js,sha256=rPm18C6QmVJBPICxABou2MPjCITnmo8Xdkgo8klrU8E,9432
+oracle/ui/settings.js,sha256=EzKtxDbTL2SwqfPhRJlb7n2znb-77_a9npuGle1z1h8,12401
 oracle/ui/suggestions.js,sha256=ItQTlyd6LS_QxvbJmNMYeHY3cl0lSRgBdR53XKkBpP0,2332
 oracle/ui/theme_tabs.js,sha256=sIFnBLgI_Hp7c-GRZrWN2v4pvRBJUnIhhwGG91qydKI,3347
 oracle/ui/chat/conversations.js,sha256=FOpXNrIeiJUR9VueBYEuLml-VfJfuHo05ZVkT-x7XRI,5907
@@ -306,8 +308,8 @@ tui/screens/search_view.py,sha256=MMHjVdlk3HZSuDBSvq8IGrqv_Mh5Us6YqXQ80bcWSMk,19
 tui/screens/session_view.py,sha256=eZ1eDwHTvPOck1wCCviixtOaCxIkBT_95ytNNNriGNA,5991
 tui/screens/stats.py,sha256=p81PjzdaIv7hllb8f45-rlVe4lJZwSdIMqu7e86_u5s,6223
 tui/screens/ui_view.py,sha256=1QJCgLh2YfgWIpvzRG1KOGXYEaOYX6ojN61Azjf2oX0,2125
-code_context_control-2.124.0.dist-info/METADATA,sha256=aoNZXvOHSJK4ylPra3DMz2K2FMUEkKIKiAYLOUYOWcg,27067
-code_context_control-2.124.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-code_context_control-2.124.0.dist-info/entry_points.txt,sha256=7kX_WUsDCF2hbXzvbNyscyaBb9AeA-DJY5v_5hN0DlU,93
-code_context_control-2.124.0.dist-info/top_level.txt,sha256=wRt41zBybVF3qAiNXHz9BURbkKvUvfhmWWtKMhaw6eE,29
-code_context_control-2.124.0.dist-info/RECORD,,
+code_context_control-2.125.0.dist-info/METADATA,sha256=ft9Vv4PsE9GmO_Triq-bEAuOHO-EJT9XzIOMob1UjvQ,27648
+code_context_control-2.125.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+code_context_control-2.125.0.dist-info/entry_points.txt,sha256=7kX_WUsDCF2hbXzvbNyscyaBb9AeA-DJY5v_5hN0DlU,93
+code_context_control-2.125.0.dist-info/top_level.txt,sha256=wRt41zBybVF3qAiNXHz9BURbkKvUvfhmWWtKMhaw6eE,29
+code_context_control-2.125.0.dist-info/RECORD,,

oracle/config.py

@@ -11,6 +11,11 @@ DEFAULTS = {
     "port": 3331,
     # ── Discovery API (external LLM tool surface, v2.32.0) ──
     "bind_host": "127.0.0.1",       # loopback only by default (was 0.0.0.0)
+    # When bind_host is a specific non-loopback address (a Tailscale / LAN
+    # IP), ALSO serve the same app on 127.0.0.1 so same-machine clients (the
+    # desk tray client, `c3 oracle open`, curl) are not refused. No effect on
+    # a loopback or wildcard bind. See oracle/listeners.py.
+    "loopback_listener": True,
     "api_enabled": True,            # expose /api/discovery/* REST surface
     "api_require_auth": True,       # require Bearer token on /api/discovery/*
     "api_max_tier": "action",       # cap exposed tools: "read" | "action"

oracle/listeners.py

@@ -0,0 +1,210 @@
+"""Serve the Oracle on its configured bind host AND on loopback.
+
+Why
+---
+``bind_host`` exists so a phone on the tailnet can reach the Oracle: set it
+to the Tailscale address and the server listens there — and ONLY there. A
+process on the same machine dialling ``http://127.0.0.1:3331`` was refused,
+which broke every same-box client that reasonably assumes loopback: the
+desk tray client, ``c3 oracle open``'s health probe, the single-instance
+check in ``run_oracle``, curl in a terminal.
+
+So when the bind host is a specific non-loopback address, the same Flask app
+is served a second time on ``127.0.0.1``, same port. Same app object means
+the same guards: the Host allowlist (``core.web_security``) always admits
+``localhost`` / ``127.0.0.1``, the Bearer gates do not care which socket a
+request arrived on, and ``local_session.is_local`` already treats loopback
+as same-machine. A wildcard bind (``0.0.0.0`` / ``::``) already answers on
+loopback, and a loopback bind needs no second socket, so neither gets one.
+
+Config: ``loopback_listener`` in ``~/.c3/oracle/config.json`` (default
+true). Off = the pre-v2.125.0 behaviour, one socket on ``bind_host``.
+
+Shape
+-----
+``werkzeug.serving.make_server`` builds one threaded WSGI server per host;
+every listener but the first runs ``serve_forever`` in a daemon thread, the
+first blocks the calling thread exactly as ``app.run`` did. ``shutdown()``
+stops every listener, and ``serve_forever`` calls it on the way out
+(Ctrl-C included) so a secondary socket never outlives the primary.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import logging
+import threading
+
+LOOPBACK_HOST = "127.0.0.1"
+
+# Binds that already answer on loopback, so a second socket would only
+# collide with the first.
+_WILDCARD_HOSTS = frozenset({"", "0.0.0.0", "::", "*"})
+
+_log = logging.getLogger("oracle.listeners")
+
+
+def is_loopback_host(host: str | None) -> bool:
+    """True for ``localhost`` and any loopback IP literal (v4 or v6)."""
+    h = (host or "").strip().lower()
+    if h == "localhost":
+        return True
+    try:
+        return ipaddress.ip_address(h.strip("[]")).is_loopback
+    except ValueError:
+        return False
+
+
+def listener_hosts(bind_host: str | None, loopback_listener: bool = True) -> list[str]:
+    """The hosts to listen on, primary first.
+
+    >>> listener_hosts("100.77.40.101")
+    ['100.77.40.101', '127.0.0.1']
+    >>> listener_hosts("127.0.0.1")
+    ['127.0.0.1']
+    >>> listener_hosts("0.0.0.0")
+    ['0.0.0.0']
+    >>> listener_hosts("100.77.40.101", loopback_listener=False)
+    ['100.77.40.101']
+    """
+    primary = (bind_host or "").strip() or LOOPBACK_HOST
+    hosts = [primary]
+    if not loopback_listener:
+        return hosts
+    if primary.lower() in _WILDCARD_HOSTS or is_loopback_host(primary):
+        return hosts
+    hosts.append(LOOPBACK_HOST)
+    return hosts
+
+
+class OracleListeners:
+    """One Flask app, N sockets. See the module docstring."""
+
+    def __init__(self, app, hosts: list[str], port: int, *, threaded: bool = True):
+        if not hosts:
+            raise ValueError("at least one host is required")
+        self.app = app
+        self.hosts = list(hosts)
+        self.port = int(port)
+        self.threaded = threaded
+        self.servers: list = []
+        # Servers whose serve_forever loop has been entered. socketserver's
+        # shutdown() waits on an Event that only serve_forever sets, so
+        # calling it on a server that was never served blocks forever.
+        self._serving: list = []
+        self._threads: list[threading.Thread] = []
+        self._lock = threading.Lock()
+        self._started = False
+        self._stopped = False
+
+    # ── lifecycle ──────────────────────────────────────────
+
+    def start(self) -> OracleListeners:
+        """Bind every socket. The primary is NOT served yet — call
+        :meth:`serve_forever` (blocking) or :meth:`serve_in_background`.
+
+        A secondary bind that fails (something else already holds the port on
+        loopback, say) is logged and skipped; the primary failing raises, as
+        ``app.run`` would have.
+        """
+        from werkzeug.serving import make_server
+
+        with self._lock:
+            if self._started:
+                return self
+            self._started = True
+        primary_host = self.hosts[0]
+        primary = make_server(primary_host, self.port, self.app, threaded=self.threaded)
+        self.servers.append(primary)
+        # A port of 0 asks the OS for one; every secondary must then share it.
+        if self.port == 0:
+            self.port = int(primary.socket.getsockname()[1])
+        for host in self.hosts[1:]:
+            try:
+                srv = make_server(host, self.port, self.app, threaded=self.threaded)
+            except (OSError, SystemExit) as exc:
+                # werkzeug turns a failed bind into sys.exit(1) after printing
+                # the reason; for a SECONDARY socket that is a warning, not
+                # the end of the server.
+                _log.warning("loopback listener on %s:%s not started: %s",
+                             host, self.port, exc)
+                continue
+            self.servers.append(srv)
+            self._serving.append(srv)
+            t = threading.Thread(target=srv.serve_forever, daemon=True,
+                                 name=f"oracle-listener-{host}")
+            t.start()
+            self._threads.append(t)
+        return self
+
+    def serve_forever(self) -> None:
+        """Serve the primary listener on the calling thread until shutdown.
+
+        Every other listener is stopped on the way out, whichever way the
+        primary exits (``shutdown()`` from another thread, Ctrl-C, an error).
+        """
+        if not self._started:
+            self.start()
+        primary = self.servers[0]
+        self._serving.append(primary)
+        try:
+            primary.serve_forever()
+        finally:
+            self.shutdown()
+
+    def serve_in_background(self) -> OracleListeners:
+        """Serve the primary on a daemon thread too (tests, embedders)."""
+        if not self._started:
+            self.start()
+        primary = self.servers[0]
+        self._serving.append(primary)
+        t = threading.Thread(target=primary.serve_forever, daemon=True,
+                             name=f"oracle-listener-{self.hosts[0]}")
+        t.start()
+        self._threads.insert(0, t)
+        return self
+
+    def shutdown(self) -> None:
+        """Stop every listener and close its socket. Idempotent, and safe to
+        call from any thread that is not itself inside ``serve_forever``."""
+        with self._lock:
+            if self._stopped:
+                return
+            self._stopped = True
+        for srv in self.servers:
+            if srv in self._serving:
+                try:
+                    srv.shutdown()
+                except Exception:
+                    pass
+            try:
+                srv.server_close()
+            except Exception:
+                pass
+        for t in self._threads:
+            if t is not threading.current_thread():
+                t.join(timeout=5)
+
+    # ── introspection ──────────────────────────────────────
+
+    @property
+    def addresses(self) -> list[tuple[str, int]]:
+        """``(host, port)`` per live listener, primary first."""
+        out = []
+        for srv in self.servers:
+            try:
+                name = srv.socket.getsockname()
+                out.append((str(name[0]), int(name[1])))
+            except OSError:
+                continue
+        return out
+
+    @property
+    def urls(self) -> list[str]:
+        out = []
+        for host, port in self.addresses:
+            shown = "127.0.0.1" if host in ("0.0.0.0", "") else host
+            if ":" in shown and not shown.startswith("["):
+                shown = f"[{shown}]"
+            out.append(f"http://{shown}:{port}")
+        return out

oracle/oracle_server.py

@@ -19,8 +19,9 @@ if str(_PROJECT_ROOT) not in sys.path:
 from flask import Flask, Response, jsonify, redirect, request, url_for  # noqa: E402
 
 from oracle.config import ORACLE_DIR, load_config, save_config  # noqa: E402
+from oracle.listeners import OracleListeners, listener_hosts  # noqa: E402
 from oracle.mcp_oracle import mcp_url, start_mcp_thread  # noqa: E402
-from oracle.services import api_auth, local_session  # noqa: E402
+from oracle.services import api_auth, client_tokens, local_session  # noqa: E402
 from oracle.services.activity_reporter import ActivityReporter  # noqa: E402
 from oracle.services.api_auth import extract_bearer  # noqa: E402
 from oracle.services.api_auth import verify as verify_api_key  # noqa: E402
@@ -233,6 +234,14 @@ def _local_write_guard():
     path = request.path or ""
     if not path.startswith("/api/") or path.startswith("/api/discovery"):
         return None
+    # The mobile gateway authenticates itself: both of its blueprints gate
+    # EVERY method (GETs included) on a Bearer — the Discovery token or a
+    # per-client token (v2.125.0) — and the one route that takes no Bearer,
+    # ``POST /api/mobile/clients``, runs its own local-address + bootstrap-key
+    # check. Applying this cookie-or-Discovery gate on top would refuse every
+    # per-client token before the blueprint ever saw it.
+    if path.startswith("/api/mobile/"):
+        return None
     if request.method in ("GET", "HEAD", "OPTIONS"):
         return None
     # The bootstrap mint is how a browser ACQUIRES the cookie, so it cannot
@@ -1086,6 +1095,63 @@ def api_apikey_clear():
         return jsonify({"error": str(e)}), 500
 
 
+# ── Paired clients (dashboard side of oracle/services/client_tokens.py) ──
+# Cookie-authenticated like the apikey routes: the mutations sit behind
+# _local_write_guard, the list is a GET and returns no secret. The QR the
+# Settings tab renders now carries a per-device token minted here, so
+# rotating the Discovery token no longer un-pairs every phone.
+
+@app.route("/api/pair/clients", methods=["GET"])
+def api_pair_clients():
+    """Every paired client (never a hash or token). Signed-in dashboard only
+    — the list names devices, which is more than an anonymous local process
+    should learn."""
+    if not (verify_api_key(extract_bearer(request.headers.get("Authorization")))
+            or local_session.verify(request.cookies.get(local_session.COOKIE_NAME))):
+        return jsonify({"error": "unauthorized"}), 401
+    try:
+        return jsonify({"clients": client_tokens.list_clients()})
+    except Exception as e:
+        return jsonify({"error": str(e)}), 500
+
+
+@app.route("/api/pair/mobile", methods=["POST"])
+def api_pair_mobile():
+    """Mint a per-device ``mobile`` client token for the pairing QR.
+
+    Body ``{label?}``. The token is revealed exactly once, here, for the QR;
+    the store keeps only its hash. ``url`` is what the phone should dial —
+    the dashboard overrides it with the Tailscale/LAN address it entered.
+    """
+    data = request.get_json(silent=True) or {}
+    try:
+        row, token = client_tokens.mint("mobile", str(data.get("label") or "phone"))
+    except ValueError as e:
+        return jsonify({"error": str(e)}), 400
+    except Exception as e:
+        return jsonify({"error": str(e)}), 500
+    return jsonify({
+        "client_id": row["client_id"],
+        "kind": row["kind"],
+        "label": row["label"],
+        "created": row["created"],
+        "token": token,
+        "url": request.host_url.rstrip("/"),
+    }), 201
+
+
+@app.route("/api/pair/clients/<client_id>", methods=["DELETE"])
+def api_pair_revoke(client_id):
+    """Un-pair one device. Its token fails on the next request."""
+    try:
+        row = client_tokens.revoke(str(client_id))
+    except Exception as e:
+        return jsonify({"error": str(e)}), 500
+    if row is None:
+        return jsonify({"error": "unknown client"}), 404
+    return jsonify({"client": row, "revoked": True})
+
+
 # ── Error handlers ────────────────────────────────────────
 @app.errorhandler(404)
 def not_found(e):
@@ -1215,7 +1281,27 @@ def run_oracle(port: int = None, open_browser: bool = None):
         signed_in = f"{url}/?{local_session.BOOTSTRAP_PARAM}={local_session.mint_code()}"
         threading.Timer(0.8, lambda: webbrowser.open(signed_in)).start()
 
-    app.run(host=cfg.get("bind_host", "127.0.0.1"), port=actual_port, debug=False, use_reloader=False)
+    _serve(bind_host, actual_port,
+           loopback_listener=bool(cfg.get("loopback_listener", True)))
+
+
+def _serve(bind_host: str, port: int, *, loopback_listener: bool = True) -> None:
+    """Block serving ``app`` on ``bind_host`` — and on loopback too when the
+    bind is a specific non-loopback address (``oracle/listeners.py``).
+
+    Replaces ``app.run``: the same threaded werkzeug server, minus the
+    dev-server banner, plus the second socket. Every listener is stopped on
+    the way out (Ctrl-C, service stop, an error) and at interpreter exit.
+    """
+    hosts = listener_hosts(bind_host, loopback_listener)
+    listeners = OracleListeners(app, hosts, port).start()
+    atexit.register(listeners.shutdown)
+    if len(listeners.servers) > 1:
+        print(f"Loopback listener  →  {listeners.urls[-1]}  (same app, same guards)")
+    elif len(hosts) > 1:
+        print(f"Warning: loopback listener on 127.0.0.1:{port} could not start "
+              f"(port in use?) — same-machine clients must dial {bind_host}.")
+    listeners.serve_forever()
 
 
 if __name__ == "__main__":

oracle/oracle_ui.html

@@ -1198,19 +1198,25 @@
     <!-- ── Mobile pairing (companion app) ── -->
     <h2 style="font-size:16px;font-weight:600;margin:28px 0 16px">Mobile app <span style="font-size:11px;color:var(--text2);font-weight:400">— pair the C3 companion app</span></h2>
     <div class="card">
-      <p style="font-size:12px;color:var(--text2);margin:0 0 14px;line-height:1.5">Scan a QR code from the C3 mobile companion to pair it with this Oracle. The code carries the server URL and the <b>Discovery API token</b> above — treat it like a password, and note that rotating the token un-pairs every client that uses it.</p>
+      <p style="font-size:12px;color:var(--text2);margin:0 0 14px;line-height:1.5">Scan a QR code from the C3 mobile companion to pair it with this Oracle. The code carries the server URL and a <b>per-device token</b> minted for that phone — treat it like a password. Each device gets its own token, so one can be revoked below without touching the others, and rotating the Discovery API token above no longer un-pairs phones.</p>
       <div class="field">
         <label>Server URL (as reachable from the phone)</label>
         <input id="mpUrl" type="text" placeholder="e.g. http://100.x.y.z:3331 (Tailscale IP)">
         <div style="font-size:11px;color:var(--text2);margin-top:6px">Defaults to this page's origin — replace it with the Tailscale/LAN address the phone can reach. Remote access needs <code>bind_host</code> and <code>allowed_hosts</code> set in <code>~/.c3/oracle/config.json</code>.</div>
       </div>
-      <div style="display:flex;gap:8px;margin-top:4px">
+      <div style="display:flex;gap:8px;margin-top:4px;flex-wrap:wrap">
         <button class="btn btn-primary" onclick="showMobilePairQr()">Show pairing code</button>
+        <button class="btn btn-ghost" onclick="showDiscoveryPairQr()" title="Legacy: the shared Discovery token, for an app build that predates per-device tokens">Discovery-token code (legacy)</button>
         <button class="btn btn-ghost" id="mpHideBtn" onclick="hideMobilePairQr()" style="display:none">Hide</button>
       </div>
       <div id="mpQrWrap" style="display:none;margin-top:14px">
         <div id="mpQr" style="display:inline-block;background:#fff;padding:14px;border-radius:8px;line-height:0"></div>
-        <div style="font-size:11px;color:var(--text2);margin-top:8px">Contains the raw API token — don't screenshot or share it.</div>
+        <div id="mpQrNote" style="font-size:11px;color:var(--text2);margin-top:8px"></div>
+        <div style="font-size:11px;color:var(--text2);margin-top:4px">Contains a raw Bearer token — don't screenshot or share it.</div>
+      </div>
+      <div style="margin-top:16px">
+        <label style="font-size:12px;font-weight:600">Paired devices</label>
+        <div id="mpClients" style="margin-top:6px"></div>
       </div>
     </div>
   </div>

oracle/services/chat_poll.py

@@ -33,9 +33,8 @@ import threading
 import time
 import uuid
 
-from flask import Blueprint, jsonify, request
+from flask import Blueprint, g, jsonify, request
 
-from oracle.services import api_auth
 from oracle.services.api_auth import extract_bearer
 
 #: Capability advertised on ``/api/mobile/info``. Wired into
@@ -115,8 +114,14 @@ def _chat_auth_guard():
         return None  # CORS preflight
     if not _cfg().get("mobile_api_enabled", True):
         return jsonify({"error": "mobile API disabled"}), 404
-    if not api_auth.verify(extract_bearer(request.headers.get("Authorization"))):
+    # Same credential set as the gateway proper (Discovery token OR a live
+    # per-client token, v2.125.0), resolved by the one shared function so a
+    # device paired with a client token can chat too.
+    from oracle.services import mobile_api
+    who = mobile_api.authenticate(extract_bearer(request.headers.get("Authorization")))
+    if who is None:
         return jsonify({"error": "unauthorized"}), 401
+    g.c3_client = who
     return None
 
 

oracle/services/client_tokens.py

@@ -0,0 +1,239 @@
+"""Per-client Bearer tokens for the mobile gateway (``~/.c3/oracle/clients.json``).
+
+Why this exists
+---------------
+Until v2.125.0 the only credential the ``/api/mobile/*`` gateway accepted was
+the single Discovery token (``api_auth``). Every phone carried that one token,
+so rotating it un-paired every device at once, and the server could not tell
+one client from another: every override decision was audited as
+``decided_by="mobile"`` whether a phone or a desktop tray client tapped it.
+
+A *client token* is one credential per paired device. It is minted once (by
+the dashboard's pairing QR, or by ``POST /api/mobile/clients`` with the
+on-disk bootstrap key), returned exactly once, and stored here only as a
+SHA-256 hash. Revoking one device revokes one device.
+
+What is stored, and where
+-------------------------
+``~/.c3/oracle/clients.json`` — a JSON array of rows::
+
+    {"client_id": "desk-3f9a2c1b0d4e", "kind": "desk", "label": "office pc",
+     "token_hash": "<sha256 hex>", "created": "<iso utc>",
+     "last_seen": "<iso utc>|null", "revoked_at": "<iso utc>|null"}
+
+``kind`` is one of :data:`KINDS`. The file is written through
+``services.atomic_json.write_json_atomic`` and chmod'd owner-only, the same
+posture as ``bootstrap.key`` beside it (``local_session.write_bootstrap_key``
+explains why chmod is enough on Windows too). The plaintext token never
+touches disk.
+
+Verification is a constant-time compare of the presented token's hash against
+EVERY stored hash — no early exit, so timing does not leak which row matched.
+``last_seen`` is touched at most once a minute per client so a long-poll
+client does not rewrite the file on every request.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import secrets
+import threading
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+from services.atomic_json import write_json_atomic
+
+CLIENTS_FILENAME = "clients.json"
+
+#: The client kinds the gateway knows how to attribute. ``mobile`` is the
+#: phone (and the principal the legacy Discovery token maps to); ``desk`` is
+#: the C3 Desk tray client. Hub stays ``desktop`` and the CLI stays ``cli`` —
+#: those are not gateway clients and never hold a client token.
+KINDS = ("mobile", "desk")
+
+#: The principal a request authenticated by the Discovery token gets. Kind
+#: ``mobile`` keeps every existing phone's audit attribution byte-identical.
+DISCOVERY_PRINCIPAL = {"kind": "mobile", "client_id": "discovery"}
+
+_MAX_LABEL = 64
+_DEFAULT_LABELS = {"mobile": "phone", "desk": "desk"}
+
+#: Minimum seconds between two ``last_seen`` writes for one client.
+LAST_SEEN_INTERVAL_S = 60.0
+
+_lock = threading.RLock()
+# client_id -> monotonic time of the last last_seen write this process made.
+_last_touch: dict[str, float] = {}
+
+
+def store_path() -> Path:
+    """``~/.c3/oracle/clients.json`` — resolved per call so tests that patch
+    ``Path.home`` redirect it, exactly like the override-request store."""
+    return Path.home() / ".c3" / "oracle" / CLIENTS_FILENAME
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def hash_token(token: str) -> str:
+    return hashlib.sha256((token or "").encode("utf-8")).hexdigest()
+
+
+def _load() -> list[dict]:
+    path = store_path()
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError:
+        return []
+    try:
+        rows = json.loads(raw)
+    except ValueError:
+        # A corrupt store fails CLOSED for verification (no row matches) but
+        # must not take the whole gateway down: the Discovery token still
+        # authenticates, and the next mint rewrites the file whole.
+        return []
+    if not isinstance(rows, list):
+        return []
+    return [r for r in rows if isinstance(r, dict) and r.get("client_id")]
+
+
+def _save(rows: list[dict]) -> None:
+    path = store_path()
+    write_json_atomic(path, rows, indent=2)
+    try:
+        os.chmod(path, 0o600)
+    except OSError:
+        pass
+
+
+def _public(row: dict) -> dict:
+    """The row for the wire: everything except the hash. Never the token."""
+    return {
+        "client_id": row.get("client_id"),
+        "kind": row.get("kind"),
+        "label": row.get("label") or "",
+        "created": row.get("created"),
+        "last_seen": row.get("last_seen"),
+        "revoked_at": row.get("revoked_at"),
+    }
+
+
+def _clean_label(kind: str, label: str | None) -> str:
+    text = " ".join(str(label or "").split())[:_MAX_LABEL]
+    return text or _DEFAULT_LABELS.get(kind, kind)
+
+
+def mint(kind: str, label: str | None = None) -> tuple[dict, str]:
+    """Create a client. Returns ``(public_row, token)``.
+
+    The token is the ONLY copy that will ever exist in plaintext: the store
+    keeps its SHA-256, so a later read of ``clients.json`` (or of this
+    process's memory after the request returns) cannot recover it.
+    """
+    kind = str(kind or "").strip().lower()
+    if kind not in KINDS:
+        raise ValueError(f"kind must be one of {', '.join(KINDS)}")
+    token = secrets.token_urlsafe(32)
+    row = {
+        "client_id": f"{kind}-{secrets.token_hex(6)}",
+        "kind": kind,
+        "label": _clean_label(kind, label),
+        "token_hash": hash_token(token),
+        "created": _now_iso(),
+        "last_seen": None,
+        "revoked_at": None,
+    }
+    with _lock:
+        rows = _load()
+        rows.append(row)
+        _save(rows)
+    return _public(row), token
+
+
+def verify(token: str | None) -> dict | None:
+    """The live row a presented token belongs to, or ``None``.
+
+    Compares against every stored hash in constant time — a revoked row is
+    still compared (so timing does not reveal revocation either) and only
+    rejected afterwards. Touches ``last_seen`` at most once per
+    :data:`LAST_SEEN_INTERVAL_S` per client; that write is best-effort.
+    """
+    if not token:
+        return None
+    presented = hash_token(token)
+    with _lock:
+        rows = _load()
+        matched: dict | None = None
+        for row in rows:
+            stored = str(row.get("token_hash") or "")
+            # Compare against a same-length string when the row is malformed
+            # so the loop cost does not depend on which rows are well-formed.
+            if secrets.compare_digest(presented, stored or "0" * len(presented)):
+                matched = row
+        if matched is None or matched.get("revoked_at"):
+            return None
+        cid = str(matched["client_id"])
+        now = time.monotonic()
+        if now - _last_touch.get(cid, -LAST_SEEN_INTERVAL_S) >= LAST_SEEN_INTERVAL_S:
+            _last_touch[cid] = now
+            matched["last_seen"] = _now_iso()
+            try:
+                _save(rows)
+            except OSError:
+                pass
+        return _public(matched)
+
+
+def principal_for(token: str | None) -> dict | None:
+    """``{"kind", "client_id"}`` for a live client token, else ``None``.
+
+    The shape every guard stashes on ``flask.g.c3_client``; the Discovery
+    token's equivalent is :data:`DISCOVERY_PRINCIPAL`.
+    """
+    row = verify(token)
+    if row is None:
+        return None
+    return {"kind": row["kind"], "client_id": row["client_id"]}
+
+
+def list_clients(include_revoked: bool = True) -> list[dict]:
+    """Every row, hashes stripped, oldest first."""
+    with _lock:
+        rows = _load()
+    out = [_public(r) for r in rows
+           if include_revoked or not r.get("revoked_at")]
+    return out
+
+
+def get(client_id: str) -> dict | None:
+    with _lock:
+        for row in _load():
+            if row.get("client_id") == client_id:
+                return _public(row)
+    return None
+
+
+def revoke(client_id: str) -> dict | None:
+    """Mark a client revoked. Its token fails :func:`verify` from the next
+    call on. Returns the public row, or ``None`` when unknown. Revoking an
+    already-revoked client is a no-op that returns the row."""
+    with _lock:
+        rows = _load()
+        for row in rows:
+            if row.get("client_id") == client_id:
+                if not row.get("revoked_at"):
+                    row["revoked_at"] = _now_iso()
+                    _save(rows)
+                _last_touch.pop(str(client_id), None)
+                return _public(row)
+    return None
+
+
+def reset_touch_cache() -> None:
+    """Forget the per-process ``last_seen`` throttle (tests)."""
+    with _lock:
+        _last_touch.clear()

oracle/services/mobile_api.py

@@ -50,10 +50,10 @@ import time
 from datetime import datetime, timezone
 from pathlib import Path
 
-from flask import Blueprint, Response, jsonify, request
+from flask import Blueprint, Response, g, jsonify, request
 
 from oracle.config import ORACLE_DIR, load_config
-from oracle.services import api_auth, discovery_audit
+from oracle.services import api_auth, client_tokens, discovery_audit, local_session
 from oracle.services.api_auth import extract_bearer
 from oracle.services.tool_registry import _c3_version
 from services.atomic_json import write_json_atomic
@@ -66,11 +66,16 @@ from services.atomic_json import write_json_atomic
 # 4: the ops surface — /edits, /locks, /status, /insights, /suggestions,
 #    /review. Reads are always on; the two capabilities that WRITE
 #    (insight dismissal, suggestion approval) carry their own switches.
-API_VERSION = 4
+# 5: per-client tokens (`clients` capability, /clients routes). A request
+#    is authenticated by the Discovery token OR a live client token, /info
+#    reports the caller as `client: {kind, client_id}`, and override
+#    decisions are attributed to that kind ("desk" for the tray client,
+#    "mobile" for a phone or the legacy Discovery token).
+API_VERSION = 5
 
 CAPABILITIES = [
     "feed", "feed_wait", "projects", "health", "pm", "pm_events", "digest",
-    "notifications_ack",
+    "notifications_ack", "clients",
     "credentials", "credentials_write",
     "access", "access_write",
     "enforcement", "enforcement_write",
@@ -133,9 +138,49 @@ _WAIT_TICK_S = 1.0
 # serves the desktop UI and discovery off the same pool. Past the cap `wait`
 # degrades to an ordinary immediate answer rather than queueing behind other
 # waiters. One phone needs one slot; four leaves room for the watch and a
-# spare.
-_MAX_WAITERS = 4
+# spare. Since v2.125.0 the desk tray client holds a slot too, so the total
+# is eight with a per-KIND cap of four: a phone that reconnects in a loop
+# cannot take the desk's slots, and vice versa. The kind is the authenticated
+# principal's (`g.c3_client["kind"]`), never a client-supplied field.
+_MAX_WAITERS = 8
+_MAX_WAITERS_PER_KIND = 4
 _waiters = threading.Semaphore(_MAX_WAITERS)
+_kind_waiters: dict[str, threading.Semaphore] = {}
+_kind_waiters_lock = threading.Lock()
+
+
+def _kind_semaphore(kind: str) -> threading.Semaphore:
+    with _kind_waiters_lock:
+        sem = _kind_waiters.get(kind)
+        if sem is None:
+            sem = threading.Semaphore(_MAX_WAITERS_PER_KIND)
+            _kind_waiters[kind] = sem
+        return sem
+
+
+def _acquire_waiter(kind: str) -> bool:
+    """Take one long-poll slot for *kind*. False when either the per-kind or
+    the global budget is spent — the caller then answers immediately."""
+    per_kind = _kind_semaphore(kind)
+    if not per_kind.acquire(blocking=False):
+        return False
+    if not _waiters.acquire(blocking=False):
+        per_kind.release()
+        return False
+    return True
+
+
+def _release_waiter(kind: str) -> None:
+    _waiters.release()
+    _kind_semaphore(kind).release()
+
+
+def _reset_waiters() -> None:
+    """Fresh semaphores (tests)."""
+    global _waiters
+    with _kind_waiters_lock:
+        _waiters = threading.Semaphore(_MAX_WAITERS)
+        _kind_waiters.clear()
 
 #: Files whose mtime means "the feed may have changed" — the same set
 #: ``_last_activity`` reports on, kept literal in both places on purpose. Here
@@ -177,6 +222,36 @@ def _cfg() -> dict:
 
 # ── Auth guard ────────────────────────────────────────────
 
+#: The one route a client may reach WITHOUT a Bearer: it is how a client
+#: obtains one. It carries its own gate (local address + bootstrap key) in
+#: the handler, plus the shared rate bucket applied below.
+_PAIR_ENDPOINT = "mobile.mobile_clients_mint"
+
+
+def authenticate(token: str | None) -> dict | None:
+    """Principal for a presented Bearer, or ``None``.
+
+    The Discovery token authenticates as the legacy ``mobile``/``discovery``
+    principal so every phone paired before per-client tokens keeps working
+    and keeps its audit attribution. Otherwise the token must belong to a
+    live (un-revoked) row in ``clients.json``. Shared with ``chat_poll`` so
+    the two mobile blueprints cannot drift on what counts as a credential.
+    """
+    if not token:
+        return None
+    if api_auth.verify(token):
+        return dict(client_tokens.DISCOVERY_PRINCIPAL)
+    return client_tokens.principal_for(token)
+
+
+def principal() -> dict:
+    """The authenticated caller for this request (set by the guard).
+
+    Falls back to the Discovery principal so a route exercised outside the
+    blueprint guard (a test calling a view directly) still has a kind."""
+    return getattr(g, "c3_client", None) or dict(client_tokens.DISCOVERY_PRINCIPAL)
+
+
 @bp.before_request
 def _mobile_auth_guard():
     """Bearer gate for the whole mobile surface — every method, GETs included.
@@ -184,14 +259,28 @@ def _mobile_auth_guard():
     Deliberately stricter than ``_discovery_auth_guard``: there is no
     ``require_auth`` opt-out and no session-cookie fallback. Mutating methods
     additionally consume from the shared Discovery rate-limit bucket.
+
+    Two credentials satisfy it (api_version 5): the Discovery token, or a
+    per-client token minted by ``POST /clients``. Whichever matched is
+    stashed as ``g.c3_client = {"kind", "client_id"}`` for the routes that
+    attribute what they do.
     """
     if request.method == "OPTIONS":
         return None  # CORS preflight
     if not _cfg().get("mobile_api_enabled", True):
         return jsonify({"error": "mobile API disabled"}), 404
     token = extract_bearer(request.headers.get("Authorization"))
-    if not api_auth.verify(token):
-        return jsonify({"error": "unauthorized"}), 401
+    if request.endpoint == _PAIR_ENDPOINT:
+        # No Bearer yet by definition. The handler checks address + key; the
+        # rate bucket below still applies, keyed on the caller's address, so
+        # a key-guessing loop is throttled like any other mutation.
+        g.c3_client = None
+        token = None
+    else:
+        who = authenticate(token)
+        if who is None:
+            return jsonify({"error": "unauthorized"}), 401
+        g.c3_client = who
     if request.method in ("POST", "PUT", "DELETE") and _get_limiter is not None:
         limiter = _get_limiter()
         allowed, retry_after = limiter.check(
@@ -389,9 +478,101 @@ def mobile_info():
         "c3_version": _c3_version(),
         "server_time": datetime.now(timezone.utc).isoformat(),
         "capabilities": _capabilities(),
+        # Who the server thinks is asking (api_version 5). A client uses it
+        # to confirm its pairing survived and to label itself in its own UI.
+        "client": principal(),
     })
 
 
+# ── Clients (per-device tokens, api_version 5) ───────────
+#
+# One Bearer per paired device, stored hashed in ~/.c3/oracle/clients.json
+# (oracle/services/client_tokens.py). Minting needs proof of same-OS-user
+# access to this machine — the on-disk bootstrap key, presented from a local
+# address — the same boundary `POST /api/session/bootstrap` enforces for the
+# dashboard cookie. The token crosses the wire exactly once, in the 201.
+
+def _client_row_for_wire(row: dict, caller: dict | None) -> dict:
+    out = dict(row)
+    out["current"] = bool(caller and caller.get("client_id") == row.get("client_id"))
+    return out
+
+
+@bp.route("/clients", methods=["POST"])
+def mobile_clients_mint():
+    """Exchange the bootstrap key for a per-client token.
+
+    Body ``{"bootstrap_key": str, "kind": "desk"|"mobile", "label": str}``.
+    No Bearer (this is how a client obtains one); instead the request must
+    come from a local address AND carry the key ``~/.c3/oracle/bootstrap.key``
+    holds, compared in constant time. 201 ``{client_id, token, kind, label}``.
+    """
+    gate = _security_gate()
+    if gate:
+        return gate
+    if not local_session.is_local(request.remote_addr, _cfg().get("bind_host")):
+        return jsonify({"error": "local requests only"}), 403
+    data = request.get_json(silent=True) or {}
+    presented = str(data.get("bootstrap_key") or "").strip() or \
+        request.headers.get("X-C3-Bootstrap-Key", "")
+    if not local_session.verify_bootstrap_key(presented):
+        _gw_audit("mobile.clients.mint", {"kind": str(data.get("kind") or "")},
+                  status="refused")
+        return jsonify({"error": "unauthorized"}), 401
+    kind = str(data.get("kind") or "").strip().lower()
+    if kind not in client_tokens.KINDS:
+        return jsonify({"error": f"kind must be one of "
+                                 f"{', '.join(client_tokens.KINDS)}"}), 400
+    try:
+        row, token = client_tokens.mint(kind, str(data.get("label") or ""))
+    except ValueError as exc:
+        return jsonify({"error": str(exc)}), 400
+    except Exception as exc:
+        return _svc_error(exc)
+    _gw_audit("mobile.clients.mint", {"kind": kind, "client_id": row["client_id"]})
+    return jsonify({
+        "client_id": row["client_id"],
+        "token": token,
+        "kind": row["kind"],
+        "label": row["label"],
+        "created": row["created"],
+    }), 201
+
+
+@bp.route("/clients", methods=["GET"])
+def mobile_clients_list():
+    """Every paired client, hashes and tokens never included. ``current``
+    marks the row the presenting token belongs to (false for the Discovery
+    token, which has no row)."""
+    caller = principal()
+    try:
+        rows = client_tokens.list_clients()
+    except Exception as exc:
+        return _svc_error(exc)
+    return jsonify({
+        "clients": [_client_row_for_wire(r, caller) for r in rows],
+        "client": caller,
+    })
+
+
+@bp.route("/clients/<client_id>", methods=["DELETE"])
+def mobile_clients_revoke(client_id):
+    """Revoke one client. Its token fails auth from the next request on.
+    Revoking yourself is allowed — that is how a client signs out."""
+    gate = _security_gate()
+    if gate:
+        return gate
+    try:
+        row = client_tokens.revoke(str(client_id))
+    except Exception as exc:
+        return _svc_error(exc)
+    if row is None:
+        return jsonify({"error": "unknown client"}), 404
+    _gw_audit("mobile.clients.revoke", {"client_id": str(client_id)})
+    return jsonify({"client": _client_row_for_wire(row, principal()),
+                    "revoked": True})
+
+
 # ── Projects overview ─────────────────────────────────────
 
 def _last_activity(path: Path) -> str | None:
@@ -565,12 +746,13 @@ def _hold_for_items(targets: list, collect, wait_s: int):
     matching item — a severity this client filters out, say — re-baselines
     instead of re-scanning on every subsequent tick.
 
-    Returns immediately when every waiter slot is taken. The caller then
-    behaves exactly as if ``wait`` had not been passed: a slower client, not a
-    wrong one.
+    Returns immediately when every waiter slot is taken — globally, or for
+    this caller's kind. The caller then behaves exactly as if ``wait`` had
+    not been passed: a slower client, not a wrong one.
     """
     started = time.monotonic()
-    if not _waiters.acquire(blocking=False):
+    kind = str(principal().get("kind") or "mobile")
+    if not _acquire_waiter(kind):
         return [], 0.0
     try:
         seen = _feed_mtime(targets)
@@ -588,7 +770,7 @@ def _hold_for_items(targets: list, collect, wait_s: int):
             if found:
                 return found, time.monotonic() - started
     finally:
-        _waiters.release()
+        _release_waiter(kind)
 
 
 @bp.route("/feed")
@@ -1815,8 +1997,12 @@ _OVERRIDE_FIELDS = (
     "justification", "resolved_at", "decided_by", "decision_note",
 )
 
-#: Decisions made here are always attributed to the phone (§3.3 decided_by).
-_DECIDED_BY = "mobile"
+#: Decisions made here are attributed to the authenticated principal's kind
+#: (§3.3 decided_by): "mobile" for a phone or the legacy Discovery token,
+#: "desk" for the tray client. Never a client-supplied field — a body key
+#: cannot make a phone look like the desk.
+def _decided_by() -> str:
+    return str(principal().get("kind") or "mobile")
 
 
 def _override_row(row: dict) -> dict:
@@ -2243,7 +2429,7 @@ def mobile_override_decide(request_id):
         result = orq.decide(
             str(request_id), decision, uses=requested_uses,
             ttl_s=requested_ttl, note=str(data.get("note") or ""),
-            decided_by=_DECIDED_BY, confirm=confirm, mode=mode,
+            decided_by=_decided_by(), confirm=confirm, mode=mode,
             mute=bool(data.get("mute")))
     except orq.OverrideError as exc:
         _override_audit(f"{decision}_refused", row)
@@ -2313,7 +2499,7 @@ def mobile_override_mute(request_id):
     try:
         result = orq.decide(str(request_id), orq.DECISION_DENY,
                             note=str(data.get("note") or ""),
-                            decided_by=_DECIDED_BY, mute=True)
+                            decided_by=_decided_by(), mute=True)
     except orq.OverrideError as exc:
         return jsonify({"error": str(exc)}), 400
     except Exception as exc:

oracle/ui/app.js

@@ -3,7 +3,7 @@
 // ── Init ──
 // ═══════════════════════════════════════════════════════════
 (async function init() {
-  await Promise.all([refreshHeader(), loadProjects(), loadInsights(), loadSuggestions(), loadSettings(), loadDiscoveryKey(), chatLoadConversations(), chatLoadCommands()]);
+  await Promise.all([refreshHeader(), loadProjects(), loadInsights(), loadSuggestions(), loadSettings(), loadDiscoveryKey(), loadPairedClients(), chatLoadConversations(), chatLoadCommands()]);
   // Restore persisted UI preferences (loadSettings cached the config).
   restoreLastTab(window.oracleConfig || {});
   // Auto-refresh every 60s

oracle/ui/settings.js

@@ -185,12 +185,55 @@ async function _dkCopy(text, okMsg) {
 
 // ── Mobile pairing (companion app QR) ──
 // Renders {v, kind, url, token} as a QR for the C3 mobile app scanner.
-// The token is the Discovery Bearer key — the QR only renders on explicit
-// click, and never on page load.
+// Since v2.125.0 the token is a PER-DEVICE client token minted by
+// POST /api/pair/mobile (revealed exactly once, stored hashed), so rotating
+// the Discovery token no longer un-pairs every phone and one device can be
+// revoked on its own. The Discovery-token code remains as a fallback for an
+// app build that predates client tokens. Nothing renders on page load.
 
-async function showMobilePairQr() {
+function _renderPairQr(payload) {
+  try {
+    const qr = qrcode(0, 'M'); // type auto, medium error correction
+    qr.addData(JSON.stringify(payload));
+    qr.make();
+    document.getElementById('mpQr').innerHTML = qr.createSvgTag({ cellSize: 4, margin: 0 });
+  } catch (e) {
+    toast('QR render failed', String(e), 'error');
+    return false;
+  }
+  document.getElementById('mpQrWrap').style.display = '';
+  document.getElementById('mpHideBtn').style.display = '';
+  return true;
+}
+
+function _pairUrl() {
   const urlInput = document.getElementById('mpUrl');
   if (!urlInput.value.trim()) urlInput.value = window.location.origin;
+  return urlInput.value.trim().replace(/\/+$/, '');
+}
+
+async function showMobilePairQr() {
+  const url = _pairUrl();
+  const answer = prompt('Name this device (shown in the paired-devices list):', 'phone');
+  if (answer === null) return; // cancelled — mint nothing
+  const label = answer.trim() || 'phone';
+  let minted;
+  try {
+    minted = await api('/api/pair/mobile', { method: 'POST', body: { label: label || 'phone' } });
+  } catch (e) {
+    toast('Pairing failed', e.message || String(e), 'error');
+    return;
+  }
+  if (_renderPairQr({ v: 1, kind: 'c3-oracle', url, token: minted.token })) {
+    const note = document.getElementById('mpQrNote');
+    if (note) note.textContent = `Device token for "${minted.label}" (${minted.client_id}) — shown once. Revoke it below if the phone is lost.`;
+    toast('Pairing code ready', `Scan it now; the token for "${minted.label}" is not shown again.`, 'success', 4000);
+  }
+  loadPairedClients();
+}
+
+async function showDiscoveryPairQr() {
+  const url = _pairUrl();
   let s = window._discoveryKey;
   if (!s) { await loadDiscoveryKey(); s = window._discoveryKey; }
   if (!s || !s.exists) {
@@ -201,23 +244,10 @@ async function showMobilePairQr() {
     toast('Token unavailable', 'Open the dashboard via "c3 oracle open" so this session may reveal the token.', 'warning');
     return;
   }
-  const payload = JSON.stringify({
-    v: 1,
-    kind: 'c3-oracle',
-    url: urlInput.value.trim().replace(/\/+$/, ''),
-    token: s.key,
-  });
-  try {
-    const qr = qrcode(0, 'M'); // type auto, medium error correction
-    qr.addData(payload);
-    qr.make();
-    document.getElementById('mpQr').innerHTML = qr.createSvgTag({ cellSize: 4, margin: 0 });
-  } catch (e) {
-    toast('QR render failed', String(e), 'error');
-    return;
+  if (_renderPairQr({ v: 1, kind: 'c3-oracle', url, token: s.key })) {
+    const note = document.getElementById('mpQrNote');
+    if (note) note.textContent = 'Discovery token (legacy) — rotating it un-pairs every phone that scanned this.';
   }
-  document.getElementById('mpQrWrap').style.display = '';
-  document.getElementById('mpHideBtn').style.display = '';
 }
 
 function hideMobilePairQr() {
@@ -226,4 +256,30 @@ function hideMobilePairQr() {
   document.getElementById('mpHideBtn').style.display = 'none';
 }
 
+// ── Paired devices (client tokens) ──
+
+async function loadPairedClients() {
+  const el = document.getElementById('mpClients');
+  if (!el) return;
+  let rows;
+  try { rows = (await api('/api/pair/clients')).clients || []; }
+  catch { el.innerHTML = '<div style="font-size:11px;color:var(--text2)">Sign in (c3 oracle open) to list paired devices.</div>'; return; }
+  const live = rows.filter(r => !r.revoked_at);
+  if (!live.length) { el.innerHTML = '<div style="font-size:11px;color:var(--text2)">No paired devices yet.</div>'; return; }
+  el.innerHTML = live.map(r => `
+    <div style="display:flex;align-items:center;gap:10px;padding:6px 0;border-top:1px solid var(--border);font-size:12px">
+      <span style="font-family:monospace;color:var(--text2)">${esc(r.kind)}</span>
+      <span style="flex:1">${esc(r.label || r.client_id)} <span style="color:var(--text2);font-size:11px">· ${esc(r.client_id)}${r.last_seen ? ' · seen ' + esc(r.last_seen.slice(0, 16).replace('T', ' ')) : ' · never used'}</span></span>
+      <button class="btn btn-ghost" style="font-size:11px" onclick="revokePairedClient('${esc(r.client_id)}')">Revoke</button>
+    </div>`).join('');
+}
+
+async function revokePairedClient(clientId) {
+  if (!confirm(`Revoke ${clientId}? That device stops working on its next request.`)) return;
+  await tracked('Revoking device', async () => {
+    await api('/api/pair/clients/' + encodeURIComponent(clientId), { method: 'DELETE' });
+    await loadPairedClients();
+  }, { successMsg: 'Device revoked' });
+}
+
 // ═══════════════════════════════════════════════════════════