palmier 0.8.10 → 0.9.2

package/palmier-server/pwa/src/pages/PairSetup.tsx

@@ -1,71 +1,130 @@
 import { useEffect, useState } from "react";
+import { createPortal } from "react-dom";
 import { useNavigate } from "react-router-dom";
 import { useHostConnection } from "../contexts/HostConnectionContext";
 import { useHostStore } from "../contexts/HostStoreContext";
 import CapabilityToggles from "../components/CapabilityToggles";
+import { Device } from "../native/Device";
 
 interface HostInfoResponse {
-  capability_tokens?: Record<string, string | null>;
   lan_url?: string | null;
+  linked_client_token?: string | null;
 }
 
+type Phase = "loading" | "confirming" | "linking" | "wizard" | "linkError";
+
 export default function PairSetup() {
   const navigate = useNavigate();
-  const { connected, request } = useHostConnection();
-  const { getActiveHost, setHostLanUrl } = useHostStore();
-  const activeHost = getActiveHost();
-  const activeClientToken = activeHost?.clientToken ?? null;
+  const { connected, request, activeHost } = useHostConnection();
+  const { setHostLanUrl, pairedHosts } = useHostStore();
+  const isFirstHost = pairedHosts.length <= 1;
+
+  const [phase, setPhase] = useState<Phase>("loading");
+  const [linkedClientToken, setLinkedClientToken] = useState<string | null>(null);
+  const [linkError, setLinkError] = useState<string | null>(null);
 
-  const [capabilityTokens, setCapabilityTokens] = useState<Record<string, string | null>>({});
-  const [loaded, setLoaded] = useState(false);
+  function goToHost() {
+    navigate(`/hosts/${encodeURIComponent(activeHost.hostId)}`, { replace: true });
+  }
 
-  // If the user lands here without an active host (direct URL, refresh), bounce
-  // back to the dashboard — setup only makes sense right after pairing.
+  // Phase: loading → fetch host.info, then transition.
   useEffect(() => {
-    if (!activeHost) navigate("/", { replace: true });
-  }, [activeHost, navigate]);
+    if (!connected || phase !== "loading") return;
+    let cancelled = false;
+    request<HostInfoResponse>("host.info").catch(() => ({} as HostInfoResponse)).then((info) => {
+      if (cancelled) return;
+      setHostLanUrl(activeHost.hostId, info.lan_url ?? undefined);
+      const linked = info.linked_client_token ?? null;
+      setLinkedClientToken(linked);
+      const otherDeviceLinked = !!linked && linked !== activeHost.clientToken;
+      setPhase(otherDeviceLinked ? "confirming" : "linking");
+    });
+    return () => { cancelled = true; };
+  }, [connected, phase, activeHost, request, setHostLanUrl]);
 
+  // Phase: linking → call device.link, then either show wizard (first host)
+  // or navigate (subsequent host).
   useEffect(() => {
-    if (!connected || !activeHost) return;
-    const activeHostId = activeHost.hostId;
+    if (phase !== "linking") return;
     let cancelled = false;
-    request<HostInfoResponse>("host.info")
-      .then((res) => {
+    (async () => {
+      try {
+        if (Device) {
+          const { token: fcmToken } = await Device.getFcmToken();
+          if (!fcmToken) throw new Error("Could not read FCM token");
+          await request("device.link", { fcmToken });
+        }
         if (cancelled) return;
-        setCapabilityTokens(res.capability_tokens ?? {});
-        setHostLanUrl(activeHostId, res.lan_url ?? undefined);
-        setLoaded(true);
-      })
-      .catch(() => { if (!cancelled) setLoaded(true); });
+        if (isFirstHost) setPhase("wizard");
+        else goToHost();
+      } catch (err) {
+        if (cancelled) return;
+        setLinkError(err instanceof Error ? err.message : String(err));
+        setPhase("linkError");
+      }
+    })();
     return () => { cancelled = true; };
-  }, [connected, activeHost, request, setHostLanUrl]);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [phase]);
+
+  function confirmLink() { setPhase("linking"); }
+  function cancelLink() { goToHost(); }
+  function retryLink() { setLinkError(null); setPhase("linking"); }
+
+  const linkModal = phase === "confirming" && createPortal(
+    <div className="confirm-modal-overlay" onClick={cancelLink}>
+      <div className="confirm-modal" onClick={(e) => e.stopPropagation()}>
+        <h2 className="confirm-modal-title">Link this device?</h2>
+        <p className="confirm-modal-message">
+          Only one device can be linked at a time — switching will disable those capabilities on the currently linked device.
+        </p>
+        <div className="confirm-modal-actions">
+          <button className="btn btn-secondary" onClick={cancelLink}>Cancel</button>
+          <button className="btn btn-primary" onClick={confirmLink}>Link</button>
+        </div>
+      </div>
+    </div>,
+    document.body,
+  );
+
+  if (phase === "loading" || phase === "confirming" || phase === "linking" || phase === "linkError") {
+    const isWizardCandidate = isFirstHost;
+    return (
+      <div className="pair-setup">
+        <div className="pair-setup-inner">
+          {isWizardCandidate && <h1 className="pair-setup-title">Device Capabilities</h1>}
+          <div className="pair-setup-loading">
+            {phase === "loading" && "Connecting to host…"}
+            {phase === "confirming" && "Awaiting confirmation…"}
+            {phase === "linking" && "Linking device…"}
+            {phase === "linkError" && (
+              <>
+                <p className="pair-error">{linkError}</p>
+                <button className="btn btn-primary" onClick={retryLink}>Retry</button>
+                <button className="btn btn-secondary" onClick={goToHost} style={{ marginTop: 8 }}>Skip linking</button>
+              </>
+            )}
+          </div>
+        </div>
+        {linkModal}
+      </div>
+    );
+  }
 
+  // phase === "wizard"
+  void linkedClientToken;
   return (
     <div className="pair-setup">
       <div className="pair-setup-inner">
-        <h1 className="pair-setup-title">What capabilities of this device do you want your host computer to have?</h1>
+        <h1 className="pair-setup-title">Device Capabilities</h1>
         <p className="pair-setup-description">
-          You can change these later from the menu.
+          Choose what the host can use this device for. You can change these later from the menu.
         </p>
 
-        {!loaded ? (
-          <div className="pair-setup-loading">Connecting to host…</div>
-        ) : (
-          <CapabilityToggles
-            capabilityTokens={capabilityTokens}
-            activeClientToken={activeClientToken}
-            request={request}
-            onCapabilityTokensChange={setCapabilityTokens}
-          />
-        )}
+        <CapabilityToggles />
 
         <div className="pair-setup-actions">
-          <button
-            className="btn btn-primary btn-full"
-            onClick={() => navigate("/", { replace: true })}
-          >
-            Finish
-          </button>
+          <button className="btn btn-primary btn-full" onClick={goToHost}>Finish</button>
         </div>
       </div>
     </div>

package/palmier-server/pwa/src/service-worker.ts

@@ -104,14 +104,17 @@ self.addEventListener("notificationclick", (event) => {
     );
   } else {
     // User tapped the notification body — open the PWA.
-    // For task-complete/fail notifications, deep-link to the result view.
+    // For task-complete/fail notifications, deep-link to the result view
+    // scoped to the originating host so the PWA switches hosts automatically.
+    const hostId = data.host_id;
     const taskId = data.task_id;
     const runId = data.run_id;
-    const targetUrl = taskId && runId
-      ? `/runs/${encodeURIComponent(taskId)}/${encodeURIComponent(runId)}`
-      : taskId
-        ? `/runs/${encodeURIComponent(taskId)}/latest`
-        : "/";
+    const hostPrefix = hostId ? `/hosts/${encodeURIComponent(hostId)}` : "";
+    const targetUrl = hostPrefix && taskId && runId
+      ? `${hostPrefix}/runs/${encodeURIComponent(taskId)}/${encodeURIComponent(runId)}`
+      : hostPrefix && taskId
+        ? `${hostPrefix}/runs/${encodeURIComponent(taskId)}/latest`
+        : hostPrefix || "/";
 
     event.waitUntil(
       self.clients

package/palmier-server/pwa/src/types.ts

@@ -68,4 +68,6 @@ export interface PairedHost {
   directUrl?: string;
   /** Host's LAN URL, refreshed from each `host.info` response so laptop/DHCP IP changes propagate. Native Capacitor app probes for reachability and routes RPC over HTTP when reachable; events stay on NATS. */
   lanUrl?: string;
+  /** Last-used agent key for this host. Seeds the agent picker on the session composer and task form. */
+  lastAgent?: string;
 }

package/palmier-server/spec.md

@@ -27,7 +27,7 @@ The host supports **Linux** (systemd), **macOS** (launchd user LaunchAgent), and
   - **Battery**: `BatteryHandler` — no permission required
   - **Ringer mode**: `RingerHandler` — requires Do Not Disturb access (system settings toggle)
 
-  The notification listener excludes Palmier's own task notifications (channel `palmier_tasks`) and the default SMS app's notifications (to avoid duplicates with the SMS resource). Each capability can be toggled on/off via the app's settings menu; toggles are backed by SharedPreferences flags that handlers check before executing. See the `palmier-android` repo.
+  The notification listener excludes Palmier's own task notifications (channel `palmier_tasks`) and the default SMS app's notifications (to avoid duplicates with the SMS resource). Each capability can be toggled on/off from the drawer when the device is the host's **linked device** (the one device the host talks to for device capabilities); toggles are backed by SharedPreferences flags that handlers check before executing. See the `palmier-android` repo.
 
 * **PWA (React):** The user-facing frontend, primarily targeting mobile devices. Connects to the NATS server via **WebSockets** at `nats.palmier.me` (DNS only, not Cloudflare proxied, to avoid interference with persistent connections). No user accounts — paired hosts are stored in localStorage.
 
@@ -59,15 +59,15 @@ The Android app is a thin native shell over the remotely-hosted PWA. The design
 
 - **Server mode only.** LAN and Local modes are browser-only. The WebView blocks cleartext `http://<host-ip>:<port>` requests as mixed content, so LAN users must open the PWA from Chrome/Safari directly.
 - **Offline fallback.** When `app.palmier.me` is unreachable, the WebView loads `www/offline.html` (configured via `server.errorPath`), which auto-reloads when connectivity returns.
-- **PWA ships ahead of the APK.** The PWA may reference permission types or native methods that the installed APK doesn't implement yet. `Device.getSupportedPermissions()` returns the set the APK understands; `checkPermission` / `requestPermission` resolve with `{ granted: false, supported: false }` for unknown types rather than throwing. The PWA uses this to hide toggles it can't fulfill.
+- **PWA ships ahead of the APK.** The PWA may reference capabilities or native methods that the installed APK doesn't implement yet. `Device.getCapabilityStatus()` only returns capabilities the APK knows about, so the PWA naturally hides toggles it can't fulfill. Calls to `setCapabilityEnabled` for unknown capabilities resolve with `{ enabled: false, reason: "unsupported" }` rather than throwing.
 
-**Unified `Device` Capacitor plugin.** A single plugin (`DevicePlugin.kt`) exposes the entire native surface — FCM token, permission gate, capability whitelist, installed-app enumeration, email-client availability, deep-link events. This replaces seven per-capability permission plugins. Methods: `getFcmToken`, `getSupportedPermissions`, `checkPermission({type})`, `requestPermission({type})`, `setEnabledCapabilities({capabilities})`, `getInstalledApps`, `hasEmailClient`, `addListener("deepLink", ...)`. Permission types: `location`, `smsRead`, `smsSend`, `contacts`, `calendar`, `notificationListener`, `dnd`, `fullScreenIntent`, `postNotifications`.
+**Unified `Device` Capacitor plugin.** A single plugin (`DevicePlugin.kt`) exposes the entire native surface — FCM token, capability gating (with internal permission orchestration), installed-app enumeration, deep-link events. Methods: `getFcmToken`, `getCapabilityStatus`, `setCapabilityEnabled({capability, enabled})`, `getInstalledApps`, `addListener("deepLink", ...)`. Capabilities: `sms-read`, `sms-send`, `send-email`, `notifications`, `contacts`, `calendar`, `location`, `dnd`, `alarm`.
 
-**Capability kill-switch (`CapabilityState`).** Local whitelist persisted as a JSON-array string under `enabledCapabilities` in `CapacitorStorage` SharedPreferences, written only by `DevicePlugin.setEnabledCapabilities` from the PWA's derived state. Native receivers (`SmsBroadcastReceiver`, `DeviceNotificationListenerService`) and all FCM handlers consult this before acting — a second line of defense beyond the server-side capability token. If the user disables a capability in the drawer, the native side refuses to relay events or respond to requests even if the server still asks.
+**Capability kill-switch (`CapabilityState`).** Local whitelist persisted as a JSON-array string under `enabledCapabilities` in `CapacitorStorage` SharedPreferences. Native receivers (`SmsBroadcastReceiver`, `DeviceNotificationListenerService`) and all FCM handlers consult `CapabilityState.isEnabled` before acting — a second line of defense beyond the server-side linked-device check. The plugin owns reads and writes through `setCapabilityEnabled` (writes only after permission grant) and prunes the set on every app resume so any permission revoked in system Settings auto-flips the corresponding toggle off. Battery is the one capability without a kill-switch — it's always allowed.
 
 **FCM token flow.** The PWA reads the current token on demand via `Device.getFcmToken()`; no cached copy in SharedPreferences. `PalmierFirebaseMessagingService.onNewToken` still re-registers with the relay server itself (using the stored `hostId`) because background token refreshes can fire while the PWA isn't running.
 
-**Deep links.** FCM notification taps pass a relative path (e.g. `/runs/:taskId/:runId`) via an `Intent` extra named `deepLink`. `MainActivity.handleDeepLink` forwards the path to `DevicePlugin.emitDeepLink`, which emits a `deepLink` event the PWA's router handles client-side. If the plugin isn't ready yet (intent arrives before `onPostCreate`), `MainActivity` buffers the path and flushes in `onPostCreate`. No external `intent-filter` is registered — Android 11+ `<queries>` entries are declared so `hasEmailClient` and installed-app enumeration work without `QUERY_ALL_PACKAGES`.
+**Deep links.** FCM notification taps pass a host-scoped relative path (e.g. `/hosts/:hostId/runs/:taskId/:runId`) via an `Intent` extra named `deepLink`. Including the host in the path ensures the PWA switches to the originating host even if the user was viewing a different one when the notification arrived. `MainActivity.handleDeepLink` forwards the path to `DevicePlugin.emitDeepLink`, which emits a `deepLink` event the PWA's router handles client-side. If the plugin isn't ready yet (intent arrives before `onPostCreate`), `MainActivity` buffers the path and flushes in `onPostCreate`. No external `intent-filter` is registered — Android 11+ `<queries>` entries are declared so `hasEmailClient` and installed-app enumeration work without `QUERY_ALL_PACKAGES`.
 
 **Notification listener filtering and debounce.** `DeviceNotificationListenerService` drops notifications from (a) Palmier's own `palmier_tasks` channel to avoid feedback loops and (b) the default SMS app (SMS is captured separately via `SmsBroadcastReceiver`, which arrives before the SMS app's notification). Empty-title+body notifications are skipped. A 2-second debounce per `packageName:title` key dedupes rapid updates; the debounce map is LRU-capped at 200 entries.
 
@@ -75,7 +75,7 @@ The Android app is a thin native shell over the remotely-hosted PWA. The design
 
 **Alarm capability.** `AlarmHandler` posts a `CATEGORY_ALARM` notification on the DND-bypassing `palmier_alarms` channel with a full-screen intent targeting `AlarmActivity`. `AlarmActivity` extends `AppCompatActivity`, shows over the lock screen (`setShowWhenLocked`/`setTurnScreenOn` on O_MR1+, legacy window flags below), and plays the default alarm ringtone on the alarm audio stream via `RingtoneManager`. Requires `USE_FULL_SCREEN_INTENT`; Android 14+ requires the user to grant it in per-app settings.
 
-**Email capability.** FCM `send-email` messages post a "Pending email" notification whose tap launches `EmailActivity` — a translucent `Activity` (not `AppCompatActivity`, so `Theme.Translucent` applies) that builds a `mailto:` URI and starts the email app with `ACTION_SENDTO`. The activity auto-finishes on result, returning the user to the previous screen. `hasEmailClient` gates the toggle in the PWA to avoid enabling a capability no installed app can fulfill.
+**Email capability.** FCM `send-email` messages post a "Pending email" notification whose tap launches `EmailActivity` — a translucent `Activity` (not `AppCompatActivity`, so `Theme.Translucent` applies) that builds a `mailto:` URI and starts the email app with `ACTION_SENDTO`. The activity auto-finishes on result, returning the user to the previous screen. `setCapabilityEnabled("send-email", true)` checks for an installed `mailto:` resolver before granting; if none exists it returns `{ enabled: false, reason: "no-email-client" }` so the PWA can prompt the user to install one.
 
 **Location capability.** `GeolocationForegroundService` briefly starts as a foreground service (`FOREGROUND_SERVICE_TYPE_LOCATION` on U+) and uses `FusedLocationProviderClient.getCurrentLocation(PRIORITY_HIGH_ACCURACY)` for a single fix before stopping itself. Requires both `ACCESS_FINE_LOCATION` and `ACCESS_BACKGROUND_LOCATION` on Q+; the plugin requests them sequentially.
 
@@ -91,13 +91,16 @@ Each host machine is provisioned via `palmier init`, an interactive wizard that
 
 1. Detects installed agent CLIs.
 2. Asks which HTTP port to use (default 7256).
-3. Shows a summary of task storage directory, local access URL, detected agents, and any existing tasks to recover. Asks for confirmation before proceeding.
-4. Registers with the Palmier server via `POST <url>/api/hosts/register` — server returns `{ hostId, natsUrl, natsWsUrl, natsJwt, natsNkeySeed }`.
-5. Saves config to `~/.config/palmier/host.json` (includes `httpPort`, NATS credentials).
-6. Installs a systemd user service (Linux), user LaunchAgent (macOS), or Task Scheduler entry (Windows) and auto-enters pair mode.
+3. Detects the OS default network interface (used as the source for the host's LAN URL in `host.info` responses).
+4. Shows a summary of task storage directory, local access URL, detected agents, and any existing tasks to recover. Asks for confirmation before proceeding.
+5. Registers with the Palmier server via `POST <url>/api/hosts/register` — server returns `{ hostId, natsUrl, natsWsUrl, natsJwt, natsNkeySeed }`.
+6. Saves config to `~/.config/palmier/host.json` (includes `httpPort`, `defaultInterface`, NATS credentials).
+7. Installs a systemd user service (Linux), user LaunchAgent (macOS), or Task Scheduler entry (Windows) and auto-enters pair mode.
 
 The daemon automatically recovers existing tasks by reinstalling their system timers on startup.
 
+`defaultInterface` is captured once at `init` time. On each `host.info` RPC, the host re-reads the current IPv4 of that interface (`getInterfaceIpv4(config.defaultInterface)`) so DHCP-assigned IP changes on the same adapter propagate to clients without a re-pair. Users should re-run `palmier init` if they physically switch adapters (e.g., Ethernet ↔ WiFi, adding a new tethered interface).
+
 The `serve` daemon always starts an HTTP server bound to `0.0.0.0:<port>`. Two access modes are available:
 
 **Local mode** (always available, loopback only):
@@ -137,6 +140,17 @@ Client tokens are stored on the host in `~/.config/palmier/clients.json`. Each t
 
 If no clients exist, the host skips client validation (backward compatibility for unpaired hosts).
 
+### 2.3.1 Linked Device
+
+Each host tracks a single **linked device** — the one paired device responsible for answering device capability requests (SMS, contacts, calendar, location, alarm, ringer, email, battery). The host stores only `{ clientToken, fcmToken }` in `~/.config/palmier/linked-device.json`; it has no knowledge of which capabilities are actually enabled on the device. That set lives in Android SharedPreferences on the linked device itself and is consulted by the FCM handlers as a local kill-switch.
+
+- **Opt-in at pair time.** The PWA shows a "Link this device" checkbox during pairing (native only, default on). If checked, the pair flow continues to a setup step that calls `device.link` with the FCM token. On the very first host pair (when the device has no other paired hosts), that step also shows a one-time "Device Capabilities" screen with all toggles default OFF; the user opts into each one, and Finish writes the set to SharedPreferences. On subsequent host pairs the capability screen is skipped — the device-wide enabled set is host-agnostic and set once.
+- **Reassignment.** Any paired device can take over as the linked device from the drawer's "Link this device" button. This displaces the previous linked device (its drawer toggles go dark).
+- **Loss.** If the linked device is unpaired (via `clients.revoke_self` or CLI `palmier clients revoke`), `linked-device.json` is cleared and capability tools return "No linked device configured" until the user picks a new one.
+- **Routing.** MCP capability tools look up the linked device once per invocation and publish FCM to its token (via `host.<host_id>.fcm.<capability>` relayed by the server). Non-linked devices aren't woken and don't receive capability FCMs.
+
+Battery reads don't have a Settings toggle — capability is always on — but still route to the linked device (which is where the Android handler runs).
+
 ### 2.4 NATS Communication
 
 All communication is scoped per host. **Request-reply** is used for RPC-style calls (task CRUD, status queries) — the PWA publishes a request and receives a response on an auto-generated inbox, eliminating the need for separate response subjects.
@@ -149,7 +163,10 @@ The **RPC method is derived from the NATS subject**, not the message body. The h
 
 | Method | Params | Description |
 |---|---|---|
-| `host.info` | *(none)* | Bootstrap metadata fetched once per connection. Returns `{ agents, version, host_platform, capability_tokens, pending_prompts }`. `pending_prompts` is an array of prompts already waiting when the PWA reconnects (each `{ key, type, params?, meta? }`), so modals can render without replaying events. |
+| `host.info` | *(none)* | Bootstrap metadata fetched once per connection. Returns `{ agents, version, host_platform, linked_client_token, pending_prompts, lan_url }`. `linked_client_token` is the clientToken of the device currently linked to the host (or `null`); device capability requests route to that device's FCM token. `pending_prompts` is an array of prompts already waiting when the PWA reconnects (each `{ key, type, params?, meta? }`), so modals can render without replaying events. |
+| `device.link` | `fcmToken` | Mark the calling client as the host's linked device. Stores `{ clientToken, fcmToken }` in `~/.config/palmier/linked-device.json` and replaces any existing linked device. Device capability tools (`device-geolocation`, `read-contacts`, `send-sms-message`, etc.) route FCM to this device. |
+| `device.unlink` | *(none)* | Clear the linked device if the caller is currently linked. No-op otherwise. |
+| `clients.revoke_self` | *(none)* | Revoke the calling client's token. Also clears the linked device when the caller was the linked one. Called by the PWA when the user unpairs the currently-active host. |
 | `task.list` | *(none)* | List all tasks with frontmatter, created_at, and current status. |
 | `task.get` | `id` | Get a single task with frontmatter and current status. |
 | `task.create` | `user_prompt`, `agent`, `schedule_type?`, `schedule_values?`, `schedule_enabled?`, `requires_confirmation?`, `yolo_mode?`, `foreground_mode?`, `command?` | Create a new task with auto-generated name (30s timeout for prompts > 50 chars), install system timers if a schedule is present. |
@@ -291,7 +308,7 @@ Task lifecycle status is persisted to a `status.json` file in the task directory
 
 The `task.list` RPC includes each task's current status (read from `status.json`). The `task.status` RPC returns the status for a single task.
 
-The PWA receives initial statuses from `task.list` on load. It subscribes to `host-event.<activeHostId>.>` for live updates; on each notification it parses the `event_type` field and calls the host's `task.status` RPC to fetch the current status. Task cards display the `user_prompt` as the title (truncated to 2 lines) and a status indicator: a marching dots animation when running (`started`), a red dot for errors (`aborted` or `failed`), a gray dot when the schedule is disabled or absent, and a green dot when idle (no entry or `finished`). When the last run was successful (`finished`), a "View Result" button loads the task's result file in a popup dialog. The `specific_times` date/time picker only allows selecting future dates and times.
+The PWA receives initial statuses from `task.list` on load. It subscribes to `host-event.<hostId>.>` for live updates; on each notification it parses the `event_type` field and calls the host's `task.status` RPC to fetch the current status. Task cards display the `user_prompt` as the title (truncated to 2 lines) and a status indicator: a marching dots animation when running (`started`), a red dot for errors (`aborted` or `failed`), a gray dot when the schedule is disabled or absent, and a green dot when idle (no entry or `finished`). When the last run was successful (`finished`), a "View Result" button loads the task's result file in a popup dialog. The `specific_times` date/time picker only allows selecting future dates and times.
 
 The Web Server subscribes to `host-event.>` and sends push notifications based on `event_type`: confirmation pushes for `confirm-request`, dismiss pushes for `confirm-resolved`, permission pushes for `permission-request`, dismiss pushes for `permission-resolved`, and report-ready/failure pushes for `report-generated` events.
 
@@ -317,7 +334,7 @@ The PWA connects to **one host at a time**. A host menu (hamburger drawer) lets
 
 2. If hosts are paired, PWA fetches host-scoped NATS credentials from `GET /api/nats-credentials/<hostId>` (returns `{ natsWsUrl, natsJwt, natsNkeySeed }`) and connects to NATS via WebSocket using JWT auth. The credentials are scoped to the paired host's subjects only.
 
-3. PWA sends a `host.info` request using NATS request-reply, including the `clientToken` in the payload. The response carries bootstrap metadata (`agents`, `host_platform`, `version`, `capability_tokens`) and `pending_prompts` — any prompts already open on the host when the PWA connected. The Dashboard consumes this once per connection; both tabs read from it.
+3. PWA sends a `host.info` request using NATS request-reply, including the `clientToken` in the payload. The response carries bootstrap metadata (`agents`, `host_platform`, `version`, `linked_client_token`) and `pending_prompts` — any prompts already open on the host when the PWA connected. The Dashboard consumes this once per connection; both tabs read from it.
 
 4. PWA lands on the Sessions tab and fetches run history via `taskrun.list`. `task.list` is not called at startup — it fires lazily the first time the user opens the Tasks tab. If either RPC fails with NATS 503 ("no responders"), the PWA shows an empty state — this is not treated as an error.
 
@@ -327,12 +344,24 @@ The PWA connects to **one host at a time**. A host menu (hamburger drawer) lets
 
 ### 4.2 UI Layout: Sessions & Tasks Tabs
 
-The PWA has two tabs: **Sessions** (default, at `/`) and **Tasks** (secondary, at `/tasks`). Sessions is the primary workflow — it lists all run history across tasks (a "session" is a single run) and includes a session composer at the top of the list.
+All authenticated views are scoped under `/hosts/:hostId/` so the URL is the source of truth for "which host am I looking at":
+
+- `/hosts/:hostId` — Sessions tab (default)
+- `/hosts/:hostId/tasks` — Tasks tab
+- `/hosts/:hostId/runs/:taskId` — latest run for a task
+- `/hosts/:hostId/runs/:taskId/:runId` — specific run
+- `/hosts/:hostId/pair/setup` — capability setup right after pairing (native only)
+- `/pair` — enter a pairing code
+- `/` — redirects to `/hosts/<firstPairedHostId>`, or to `/pair` if no hosts are paired. No "last visited" state is persisted; the URL is the source of truth for the active host.
+
+Unknown or stale `:hostId` values redirect back to `/`. This lets notification deep links (`/hosts/:hostId/runs/...`) switch the active host automatically instead of opening a run against whatever host happens to be selected.
+
+The PWA has two tabs: **Sessions** (default) and **Tasks** (secondary). Sessions is the primary workflow — it lists all run history across tasks (a "session" is a single run) and includes a session composer at the top of the list.
 
 * **Session composer:** An inline textarea with an agent picker, a yolo-mode toggle, and a round play button. Entering text and clicking play dispatches `task.run_oneoff`, starting an immediate unsaved session. The composer never opens a dialog; typing is direct. When the textarea has content, navigating away (tab switch, host switch, browser reload, clicking a session row) triggers a confirmation dialog so the draft isn't lost silently.
 * **Tasks tab:** Lists saved tasks (scheduled or reusable). A floating round `+` button in the bottom-right of the screen opens the task form, which is used only to create/edit saved or scheduled tasks — it has no Run button (run one-offs via the session composer instead). The form's primary action is "Save" (no schedule) or "Schedule" (when a schedule is configured).
 
-Bootstrap data (agents, host version, host platform, capability tokens) is fetched once per connection at the Dashboard level via `host.info` — independent of which tab is active. `task.list` is called lazily on the Tasks tab mount; `taskrun.list` is called lazily on the Sessions tab mount. Neither list RPC carries bootstrap metadata.
+Bootstrap data (agents, host version, host platform, linked device) is fetched once per connection at the Dashboard level via `host.info` — independent of which tab is active. `task.list` is called lazily on the Tasks tab mount; `taskrun.list` is called lazily on the Sessions tab mount. Neither list RPC carries bootstrap metadata.
 
 Dashboard owns the always-on NATS event subscription and renders pending `confirm-request` / `permission-request` / `input-request` modals via React portal, so prompts surface regardless of which tab is active. Initial pending prompts (those already open when the PWA connects) are seeded from `host.info`'s `pending_prompts` field — each entry carries the display context (`session_name`, `description`, `input_questions`) needed to render the modal cold, since the task list is no longer available at bootstrap. `session_name` is a unified label: agent name for confirm/input, task name for permission.
 

package/src/commands/init.ts

@@ -3,6 +3,7 @@ import { loadConfig, saveConfig } from "../config.js";
 import { detectAgents } from "../agents/agent.js";
 import { getPlatform } from "../platform/index.js";
 import { pairCommand } from "./pair.js";
+import { detectDefaultInterface, getInterfaceIpv4 } from "../network.js";
 import { listTasks } from "../task.js";
 import type { HostConfig } from "../types.js";
 
@@ -41,6 +42,9 @@ export async function initCommand(): Promise<void> {
     const parsed = parseInt(portAnswer.trim(), 10);
     if (parsed > 0 && parsed < 65536) httpPort = parsed;
 
+    const defaultInterface = (await detectDefaultInterface()) ?? undefined;
+    const lanIp = defaultInterface ? getInterfaceIpv4(defaultInterface) : null;
+
     console.log(`\n${bold("Setup summary:")}\n`);
     console.log(`  ${dim("Task storage:")}   ${bold(process.cwd())}`);
     console.log(`                  All tasks and execution data will be stored here.\n`);
@@ -49,8 +53,14 @@ export async function initCommand(): Promise<void> {
     console.log(`  ${dim("Remote (web):")}   ${cyan("https://app.palmier.me")}`);
     console.log(`                  Pair a browser on any device. Traffic always goes through the relay.\n`);
     console.log(`  ${dim("Remote (app):")}   ${cyan("https://github.com/caihongxu/palmier-android/releases")}`);
-    console.log(`                  Download the Android APK. The app uses LAN for direct RPC`);
-    console.log(`                  when on the same network, otherwise the relay.\n`);
+    if (lanIp) {
+      console.log(`                  Download the Android APK. The app uses LAN for direct RPC`);
+      console.log(`                  on the same network (detected ${cyan(`http://${lanIp}:${httpPort}`)}),`);
+      console.log(`                  otherwise the relay.\n`);
+    } else {
+      console.log(`                  Download the Android APK. Traffic will go through the relay —`);
+      console.log(`                  ${red("could not detect a LAN interface")} for direct RPC.\n`);
+    }
     console.log(`  ${dim("Agents:")}         ${agents.map((a) => a.label).join(", ")}\n`);
 
     const existingTasks = listTasks(process.cwd());
@@ -101,6 +111,7 @@ export async function initCommand(): Promise<void> {
       natsNkeySeed: registerResponse.natsNkeySeed,
       agents,
       httpPort,
+      defaultInterface,
     };
 
     saveConfig(config);

package/src/commands/pair.ts

@@ -1,10 +1,9 @@
 import * as http from "node:http";
 import * as os from "node:os";
 import { StringCodec } from "nats";
-import { loadConfig, saveConfig } from "../config.js";
+import { loadConfig } from "../config.js";
 import { connectNats } from "../nats-client.js";
 import { addClient } from "../client-store.js";
-import { detectDefaultInterface } from "../network.js";
 import type { HostConfig } from "../types.js";
 
 const CODE_CHARS = "ABCDEFGHJKMNPQRSTUVWXYZ23456789"; // no O/0/I/1/L
@@ -18,13 +17,8 @@ export function generatePairingCode(): string {
   return Array.from(bytes, (b) => CODE_CHARS[b % CODE_CHARS.length]).join("");
 }
 
-async function buildPairResponse(config: HostConfig, label?: string) {
+function buildPairResponse(config: HostConfig, label?: string) {
   const client = addClient(label);
-  const iface = await detectDefaultInterface();
-  if (iface && iface !== config.defaultInterface) {
-    config.defaultInterface = iface;
-    saveConfig(config);
-  }
   return {
     hostId: config.hostId,
     clientToken: client.token,
@@ -108,7 +102,7 @@ export async function pairCommand(): Promise<void> {
         }
       } catch { /* empty body is fine */ }
 
-      const response = await buildPairResponse(config, label);
+      const response = buildPairResponse(config, label);
       if (msg.reply) {
         msg.respond(sc.encode(JSON.stringify(response)));
       }

package/src/linked-device.ts

@@ -0,0 +1,52 @@
+import * as fs from "fs";
+import * as path from "path";
+import { CONFIG_DIR } from "./config.js";
+
+const LINKED_DEVICE_FILE = path.join(CONFIG_DIR, "linked-device.json");
+
+export interface LinkedDevice {
+  clientToken: string;
+  fcmToken: string;
+}
+
+function read(): LinkedDevice | null {
+  try {
+    if (!fs.existsSync(LINKED_DEVICE_FILE)) return null;
+    const raw = fs.readFileSync(LINKED_DEVICE_FILE, "utf-8");
+    const parsed = JSON.parse(raw) as Partial<LinkedDevice>;
+    if (!parsed?.clientToken || !parsed?.fcmToken) return null;
+    return { clientToken: parsed.clientToken, fcmToken: parsed.fcmToken };
+  } catch {
+    return null;
+  }
+}
+
+function write(device: LinkedDevice | null): void {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  if (!device) {
+    if (fs.existsSync(LINKED_DEVICE_FILE)) fs.unlinkSync(LINKED_DEVICE_FILE);
+    return;
+  }
+  fs.writeFileSync(LINKED_DEVICE_FILE, JSON.stringify(device, null, 2), "utf-8");
+}
+
+export function getLinkedDevice(): LinkedDevice | null {
+  return read();
+}
+
+export function setLinkedDevice(clientToken: string, fcmToken: string): void {
+  write({ clientToken, fcmToken });
+}
+
+export function clearLinkedDevice(): void {
+  write(null);
+}
+
+export function clearLinkedDeviceIfMatches(clientToken: string): boolean {
+  const current = read();
+  if (current?.clientToken === clientToken) {
+    write(null);
+    return true;
+  }
+  return false;
+}

package/src/mcp-tools.ts

@@ -1,6 +1,6 @@
 import { StringCodec, type NatsConnection } from "nats";
 import { registerPending } from "./pending-requests.js";
-import { getCapabilityDevice } from "./device-capabilities.js";
+import { getLinkedDevice } from "./linked-device.js";
 import { getNotifications, onNotificationsChanged } from "./notification-store.js";
 import { getSmsMessages, onSmsChanged } from "./sms-store.js";
 import type { HostConfig } from "./types.js";
@@ -179,8 +179,8 @@ const deviceGeolocationTool: ToolDefinition = {
   async handler(_args, ctx) {
     if (!ctx.nc) throw new ToolError("Not connected to server (NATS unavailable)", 503);
 
-    const device = getCapabilityDevice("location");
-    if (!device) throw new ToolError("No device has location access enabled", 400);
+    const device = getLinkedDevice();
+    if (!device) throw new ToolError("No linked device configured", 400);
 
     const sc = StringCodec();
 
@@ -227,8 +227,8 @@ const readContactsTool: ToolDefinition = {
   async handler(_args, ctx) {
     if (!ctx.nc) throw new ToolError("Not connected to server (NATS unavailable)", 503);
 
-    const device = getCapabilityDevice("contacts");
-    if (!device) throw new ToolError("No device has contacts access enabled", 400);
+    const device = getLinkedDevice();
+    if (!device) throw new ToolError("No linked device configured", 400);
 
     const sc = StringCodec();
 
@@ -280,8 +280,8 @@ const createContactTool: ToolDefinition = {
   async handler(args, ctx) {
     if (!ctx.nc) throw new ToolError("Not connected to server (NATS unavailable)", 503);
 
-    const device = getCapabilityDevice("contacts");
-    if (!device) throw new ToolError("No device has contacts access enabled", 400);
+    const device = getLinkedDevice();
+    if (!device) throw new ToolError("No linked device configured", 400);
 
     const { name, phone, email } = args as { name: string; phone?: string; email?: string };
     if (!name) throw new ToolError("name is required", 400);
@@ -338,8 +338,8 @@ const readCalendarTool: ToolDefinition = {
   async handler(args, ctx) {
     if (!ctx.nc) throw new ToolError("Not connected to server (NATS unavailable)", 503);
 
-    const device = getCapabilityDevice("calendar");
-    if (!device) throw new ToolError("No device has calendar access enabled", 400);
+    const device = getLinkedDevice();
+    if (!device) throw new ToolError("No linked device configured", 400);
 
     const { startDate, endDate } = args as { startDate?: number; endDate?: number };
     const sc = StringCodec();
@@ -399,8 +399,8 @@ const createCalendarEventTool: ToolDefinition = {
   async handler(args, ctx) {
     if (!ctx.nc) throw new ToolError("Not connected to server (NATS unavailable)", 503);
 
-    const device = getCapabilityDevice("calendar");
-    if (!device) throw new ToolError("No device has calendar access enabled", 400);
+    const device = getLinkedDevice();
+    if (!device) throw new ToolError("No linked device configured", 400);
 
     const { title, startTime, endTime, location, description } = args as {
       title: string; startTime: number; endTime: number; location?: string; description?: string;
@@ -462,7 +462,7 @@ const sendSmsTool: ToolDefinition = {
   async handler(args, ctx) {
     if (!ctx.nc) throw new ToolError("Not connected to server (NATS unavailable)", 503);
 
-    const device = getCapabilityDevice("sms-send");
+    const device = getLinkedDevice();
     if (!device) throw new ToolError("No device has SMS Send enabled", 400);
 
     const { to, body } = args as { to: string; body: string };
@@ -521,8 +521,8 @@ const sendAlarmTool: ToolDefinition = {
   async handler(args, ctx) {
     if (!ctx.nc) throw new ToolError("Not connected to server (NATS unavailable)", 503);
 
-    const device = getCapabilityDevice("alarm");
-    if (!device) throw new ToolError("No device has alarm access enabled", 400);
+    const device = getLinkedDevice();
+    if (!device) throw new ToolError("No linked device configured", 400);
 
     const { title, description } = args as { title: string; description?: string };
     if (!title) throw new ToolError("title is required", 400);
@@ -578,8 +578,8 @@ const readBatteryTool: ToolDefinition = {
   async handler(_args, ctx) {
     if (!ctx.nc) throw new ToolError("Not connected to server (NATS unavailable)", 503);
 
-    const device = getCapabilityDevice("battery");
-    if (!device) throw new ToolError("No device has battery access enabled", 400);
+    const device = getLinkedDevice();
+    if (!device) throw new ToolError("No linked device configured", 400);
 
     const sc = StringCodec();
 
@@ -629,7 +629,7 @@ const setRingerModeTool: ToolDefinition = {
   async handler(args, ctx) {
     if (!ctx.nc) throw new ToolError("Not connected to server (NATS unavailable)", 503);
 
-    const device = getCapabilityDevice("dnd");
+    const device = getLinkedDevice();
     if (!device) throw new ToolError("No device has Do Not Disturb control enabled", 400);
 
     const { mode } = args as { mode: string };
@@ -687,8 +687,8 @@ const sendEmailTool: ToolDefinition = {
   async handler(args, ctx) {
     if (!ctx.nc) throw new ToolError("Not connected to server (NATS unavailable)", 503);
 
-    const device = getCapabilityDevice("send-email");
-    if (!device) throw new ToolError("No device has send-email access enabled", 400);
+    const device = getLinkedDevice();
+    if (!device) throw new ToolError("No linked device configured", 400);
 
     const { to, subject, body, cc, bcc } = args as { to: string; subject?: string; body?: string; cc?: string; bcc?: string };
     if (!to) throw new ToolError("to is required", 400);