palmier 0.8.11 → 0.9.2

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

@@ -10,6 +10,7 @@ import HostMenu from "../components/HostMenu";
 import ConnectionStatusIcon from "../components/ConnectionStatusIcon";
 import SessionsView from "../components/SessionsView";
 import RunDetailView from "../components/RunDetailView";
+import { loadEnabledCapabilities } from "../components/CapabilityToggles";
 import { usePushSubscription } from "../hooks/usePushSubscription";
 import { useMediaQuery } from "../hooks/useMediaQuery";
 import { setAgentLabels } from "../agentLabels";
@@ -45,14 +46,16 @@ interface PermissionPrompt { permissions: RequiredPermission[]; sessionName?: st
 interface InputPrompt { questions: string[]; description?: string; sessionName?: string }
 
 export default function Dashboard() {
-  const { pairedHosts, activeHostId, removePairedHost, setHostLanUrl } = useHostStore();
-  const { connected, request, subscribeEvents, unauthorized } = useHostConnection();
+  const { removePairedHost, setHostLanUrl } = useHostStore();
+  const { connected, request, subscribeEvents, unauthorized, activeHost } = useHostConnection();
+  const hostId = activeHost.hostId;
+  const activeClientToken = activeHost.clientToken || null;
   const navigate = useNavigate();
   const location = useLocation();
   const params = useParams<{ taskId?: string; runId?: string }>();
   const isDesktop = useMediaQuery("(min-width: 768px)");
 
-  const isTasksTab = location.pathname.startsWith("/tasks");
+  const isTasksTab = location.pathname.endsWith("/tasks");
   const runsFilterTaskId = params.runId ? undefined : params.taskId;
 
   // "latest" is passed through to RunDetailView, which does its own resolution
@@ -63,10 +66,13 @@ export default function Dashboard() {
   const [updating, setUpdating] = useState(false);
   const [updateError, setUpdateError] = useState<string | null>(null);
   const [daemonVersion, setDaemonVersion] = useState<string | null>(null);
-  const [capabilityTokens, setCapabilityTokens] = useState<Record<string, string | null>>({});
+  const [linkedClientToken, setLinkedClientToken] = useState<string | null>(null);
+  const [enabledCapabilities, setEnabledCapabilities] = useState<Set<string>>(new Set());
   const [agents, setAgents] = useState<AgentInfo[]>([]);
   const [hostPlatform, setHostPlatform] = useState<string | undefined>();
 
+  const isLinkedDevice = !!activeClientToken && linkedClientToken === activeClientToken;
+
   // Pending prompt state — owned by Dashboard because these modals must show
   // regardless of which tab (Sessions/Tasks/RunDetail) is currently rendered.
   const [pendingConfirms, setPendingConfirms] = useState<Map<string, ConfirmPrompt>>(new Map());
@@ -78,7 +84,13 @@ export default function Dashboard() {
 
   useEffect(() => {
     window.scrollTo(0, 0);
-  }, [activeHostId]);
+  }, [hostId]);
+
+  useEffect(() => {
+    let cancelled = false;
+    loadEnabledCapabilities().then((caps) => { if (!cancelled) setEnabledCapabilities(caps); });
+    return () => { cancelled = true; };
+  }, []);
 
   // host.info bootstrap: agents/version/platform + any prompts that were already
   // pending when this PWA connected. Runs once per (host, connection).
@@ -88,21 +100,19 @@ export default function Dashboard() {
       agents?: AgentInfo[];
       version?: string | null;
       host_platform?: string;
-      capability_tokens?: Record<string, string | null>;
+      linked_client_token?: string | null;
       pending_prompts?: PendingPrompt[];
       lan_url?: string | null;
     }>("host.info")
       .then((result) => {
         setAgents(result.agents ?? []);
         setHostPlatform(result.host_platform);
-        setCapabilityTokens(result.capability_tokens ?? {});
+        setLinkedClientToken(result.linked_client_token ?? null);
         setAgentLabels(result.agents ?? []);
         const version = result.version ?? null;
         setDaemonVersion(version);
         setUpdateRequired(!!version && isOlderThan(version, MIN_HOST_VERSION));
-        if (activeHostId) {
-          setHostLanUrl(activeHostId, result.lan_url ?? undefined);
-        }
+        setHostLanUrl(hostId, result.lan_url ?? undefined);
 
         // Seed modal state from already-pending prompts.
         const confirms = new Map<string, ConfirmPrompt>();
@@ -136,13 +146,13 @@ export default function Dashboard() {
         setInputValues(inputVals);
       })
       .catch(() => { /* silent — update-required prompt guards the broken case */ });
-  }, [connected, activeHostId, request, setHostLanUrl]);
+  }, [connected, hostId, request, setHostLanUrl]);
 
   // Always-on event subscription for modal lifecycle. Independent of which tab
   // is active. Task-card status updates happen inside TasksView while mounted.
   useEffect(() => {
-    if (!connected || !activeHostId) return;
-    const unsubscribe = subscribeEvents(activeHostId, (msg) => {
+    if (!connected) return;
+    const unsubscribe = subscribeEvents(hostId, (msg) => {
       const tokens = msg.subject.split(".");
       if (tokens.length < 3) return;
       const taskId = tokens.slice(2).join(".");
@@ -239,7 +249,7 @@ export default function Dashboard() {
       }
     });
     return unsubscribe;
-  }, [connected, activeHostId, subscribeEvents]);
+  }, [connected, hostId, subscribeEvents]);
 
   async function respondToConfirm(sessionId: string, response: "confirmed" | "aborted") {
     try {
@@ -267,11 +277,8 @@ export default function Dashboard() {
 
   function handleViewRun(taskId: string, runId?: string) {
     if (!confirmLeaveDraft()) return;
-    if (runId) {
-      navigate(`/runs/${encodeURIComponent(taskId)}/${encodeURIComponent(runId)}`);
-    } else {
-      navigate(`/runs/${encodeURIComponent(taskId)}`);
-    }
+    const base = `/hosts/${encodeURIComponent(hostId)}/runs/${encodeURIComponent(taskId)}`;
+    navigate(runId ? `${base}/${encodeURIComponent(runId)}` : base);
   }
 
   async function handleUpdate() {
@@ -290,18 +297,16 @@ export default function Dashboard() {
     setTimeout(() => window.location.reload(), 15000);
   }
 
-  const hasHosts = pairedHosts.length > 0;
-  const showTaskContent = hasHosts && connected && activeHostId && !unauthorized;
-  const activeClientToken = pairedHosts.find((h) => h.hostId === activeHostId)?.clientToken ?? null;
+  const showTaskContent = connected && !unauthorized;
 
   return (
     <div className="dashboard">
-      {isDesktop && <HostMenu daemonVersion={daemonVersion} capabilityTokens={capabilityTokens} activeClientToken={activeClientToken} request={request} onCapabilityTokensChange={setCapabilityTokens} />}
+      {isDesktop && <HostMenu daemonVersion={daemonVersion} linkedClientToken={linkedClientToken} request={request} onEnabledCapabilitiesChange={setEnabledCapabilities} onLinkedClientTokenChange={setLinkedClientToken} />}
 
       <div className="dashboard-content">
         <header className="app-header">
           <div className="app-title-bar">
-            {!isDesktop && <HostMenu daemonVersion={daemonVersion} capabilityTokens={capabilityTokens} activeClientToken={activeClientToken} request={request} onCapabilityTokensChange={setCapabilityTokens} />}
+            {!isDesktop && <HostMenu daemonVersion={daemonVersion} linkedClientToken={linkedClientToken} request={request} onEnabledCapabilitiesChange={setEnabledCapabilities} onLinkedClientTokenChange={setLinkedClientToken} />}
             <h1 className="app-title">Palmier</h1>
             <ConnectionStatusIcon />
           </div>
@@ -336,9 +341,7 @@ export default function Dashboard() {
               </button>
               <button
                 className="btn btn-secondary"
-                onClick={() => {
-                  if (activeHostId) removePairedHost(activeHostId);
-                }}
+                onClick={() => { removePairedHost(hostId); navigate("/", { replace: true }); }}
               >
                 Remove Host
               </button>
@@ -349,19 +352,19 @@ export default function Dashboard() {
             {isTasksTab && !isRunDetail && (
               <TasksView
                 connected={connected}
-                hostId={activeHostId}
+                hostId={hostId}
                 request={request}
                 subscribeEvents={subscribeEvents}
                 agents={agents}
                 hostPlatform={hostPlatform}
-                isNotificationListener={!!activeClientToken && capabilityTokens["notifications"] === activeClientToken}
+                isNotificationListener={isLinkedDevice && enabledCapabilities.has("notifications")}
                 onViewRun={handleViewRun}
               />
             )}
             {isRunDetail ? (
               <RunDetailView
                 connected={connected}
-                hostId={activeHostId}
+                hostId={hostId}
                 request={request}
                 subscribeEvents={subscribeEvents}
                 taskId={params.taskId!}
@@ -370,27 +373,19 @@ export default function Dashboard() {
             ) : !isTasksTab ? (
               <SessionsView
                 connected={connected}
-                hostId={activeHostId}
+                hostId={hostId}
                 request={request}
                 subscribeEvents={subscribeEvents}
                 agents={agents}
                 hostPlatform={hostPlatform}
                 filterTaskId={runsFilterTaskId}
-                onClearFilter={() => { if (confirmLeaveDraft()) navigate("/"); }}
+                onClearFilter={() => { if (confirmLeaveDraft()) navigate(`/hosts/${encodeURIComponent(hostId)}`); }}
               />
             ) : null}
           </>
         ) : (
           <div className="empty-state">
-            <p>{hasHosts ? "Connecting to host..." : "No host computer paired yet."}</p>
-            {!hasHosts && (
-              <button
-                className="btn btn-primary"
-                onClick={() => navigate("/pair")}
-              >
-                Pair Host
-              </button>
-            )}
+            <p>Connecting to host...</p>
           </div>
         )}
         </main>

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

@@ -18,8 +18,11 @@ interface PairResponse {
 const isLoopback = !!(window as any).__PALMIER_SERVE__
   && (window.location.hostname === "localhost" || window.location.hostname === "127.0.0.1");
 
+const isNative = Capacitor.isNativePlatform();
+
 export default function PairHost() {
   const [code, setCode] = useState("");
+  const [makeLinked, setMakeLinked] = useState(true);
   const [pairing, setPairing] = useState(false);
   const [error, setError] = useState<string | null>(null);
   const { addPairedHost } = useHostStore();
@@ -106,7 +109,8 @@ export default function PairHost() {
         }
       }
 
-      navigate(Capacitor.isNativePlatform() ? "/pair/setup" : "/");
+      const base = `/hosts/${encodeURIComponent(response.hostId)}`;
+      navigate(isNative && makeLinked ? `${base}/pair/setup` : base);
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       if (message.includes("timeout") || message.includes("TIMEOUT") || message.includes("503") || message.toLowerCase().includes("no responders")) {
@@ -176,6 +180,21 @@ export default function PairHost() {
             />
           </label>
 
+          {isNative && (
+            <label className="pair-checkbox">
+              <input
+                type="checkbox"
+                checked={makeLinked}
+                onChange={(e) => setMakeLinked(e.target.checked)}
+                disabled={pairing}
+              />
+              <span className="pair-checkbox-text">
+                <span className="pair-checkbox-title">Link this device</span>
+                <span className="pair-checkbox-hint">The host will use this device for SMS, contacts, calendar, location, and alarms. Only one device can be linked at a time.</span>
+              </span>
+            </label>
+          )}
+
           {error && <p className="pair-error">{error}</p>}
 
           <button

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.
 
@@ -140,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.
@@ -152,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. |
@@ -294,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.
 
@@ -320,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.
 
@@ -330,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/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;
+}