@yunazgr/pi-companion 0.2.1 → 0.2.3

package/README.md

@@ -13,6 +13,8 @@ The UI is a static SvelteKit application. There is no Node runtime in production
   <img src="docs/mobile.webp" alt="Session detail on a phone" width="28%" />
 </p>
 
+Screenshots use demo sessions, not private conversation data. See the [session menu](docs/session-menu.webp), [desktop session rows](docs/session-list-desktop.webp) and [mobile session list](docs/session-list.webp), plus [attachment previews](docs/attachments.webp), [file-grouped changes](docs/changes.webp) and [connection recovery](docs/connection-error.webp).
+
 ## Install
 
     pi install npm:@yunazgr/pi-companion
@@ -21,7 +23,11 @@ or straight from git:
 
     pi install git:github.com/ygrip/pi-companion
 
-Then start pi as usual and run /companion in each session you want to follow from the dashboard or your phone. It starts the daemon if needed, prints the dashboard address and shares that session with paired devices (`/companion off` stops sharing). Nothing else to configure: the extension finds or starts the daemon on its own, downloading the matching sha256-verified daemon binary from GitHub Releases on first use (see Daemon).
+Then start Pi as usual. Installing the Pi extension is enough for normal use: the extension does not probe, connect to, download, or start a daemon until you run `/companion` in that session. On first use it downloads the matching sha256-verified daemon binary from GitHub Releases, caches it under `~/.pi/agent/pi-companion/bin/<version>/`, and reuses the same daemon across Pi sessions.
+
+Use `/companion` in each session you want to share with paired devices. It enables remote access for that session and prints the local dashboard address. `/companion off` stops sharing that session.
+
+You do **not** need to run `pi-companion-server` manually for a normal npm install. Manual daemon startup is mainly for local development, debugging, or when `PI_COMPANION_AUTOSTART=0` is set.
 
 ## Architecture
 
@@ -56,7 +62,32 @@ Then start pi as usual and run /companion in each session you want to follow fro
 
 The local administration surface and paired-device surface are separate listeners. If you expose Pi Companion through a tunnel, target only port 43722. Never expose port 43721.
 
-## Daemon
+## Install the web app on your phone
+
+Open the daemon’s **HTTPS device URL** and pair the phone first. On Android/Chromium, choose **Install app** (or **Add to Home screen**) in the browser menu. On iPhone/iPad, open Safari and choose **Share → Add to Home Screen**; enable **Open as Web App** if offered. Installation does not grant additional session permissions.
+
+Service workers require HTTPS; `http://localhost` is permitted for desktop development, but ordinary LAN HTTP addresses are not. An insecure-origin banner explains this in the UI. Install prompts vary by browser and may not appear inside in-app browsers.
+
+After an online visit, the public app shell and visited immutable assets are cached. This is not an offline agent: sending, live activity, pairing, uploads and changes require the daemon connection. No credentials, API responses or session files are stored in the service-worker cache. Reopen online after an update to load the new build.
+
+## How the daemon runs
+
+For a normal install:
+
+    pi install npm:@yunazgr/pi-companion
+
+That is enough. Start Pi normally, then run `/companion` in the session you want to share. Only then does the extension connect or start the daemon on demand and keep its daemon version aligned with the installed extension. Updating the Pi package is therefore enough to update both pieces. You do not need a separate terminal, launch agent, system service, or manual `pi-companion-server` process.
+
+The lifecycle is:
+
+1. A Pi session loads the extension without daemon network or startup work.
+2. You run `/companion` in that session; the extension probes `http://127.0.0.1:43721`.
+3. If the daemon is already running, this opted-in session connects to it.
+4. If not, the extension resolves the daemon binary, downloading the matching GitHub Release on first use if necessary.
+5. It starts the daemon detached in the background.
+6. Other Pi sessions reuse the same daemon only after their own `/companion` command. New sessions start disconnected, even when another session has enabled Companion.
+7. On extension upgrades, the extension compares its package version with the running daemon. If they differ, it stops the old local daemon, resolves/downloads the matching release, and starts the new daemon automatically.
+8. The daemon keeps running independently until it is stopped or the machine restarts.
 
 There is exactly one daemon per machine, shared by every Pi session. The extension manages it with no configuration:
 
@@ -109,7 +140,7 @@ Inside any Pi session:
     /companion off      # stop sharing this session
     /remote-control     # toggle sharing on/off
 
-A paired device cannot access sessions that have not explicitly enabled remote control.
+A paired device cannot access sessions that have not explicitly enabled remote control. Turning `/remote-control` off or running `/companion off` closes this session’s daemon channel: it disappears from paired devices and becomes **Ended** on the local dashboard. Pi continues locally; local Pi history is untouched. Sharing does not reconnect itself while disabled. After the initial opt-in, `/remote-control` can enable sharing again; `/companion` can also resume it. Temporary uploads follow the usual disconnected-session cleanup below.
 
 ## Questions from Pi
 
@@ -122,7 +153,7 @@ Dialogs from other extensions (`ctx.ui.select`, `ctx.ui.confirm`, `ctx.ui.input`
 Pairing is daemon-wide rather than session-specific. Everything lives on the **Devices** page of the local console (port 43721):
 
 1. Choose **Pair a device**. The daemon creates a single-use invitation (5 minutes by default, configurable in Settings) and shows it as a QR code, a copyable link and a short code (`XXXX-XXXX`).
-2. On the phone, open the paired-device address. An unpaired device gets a connect screen: scan the QR code with the in-app camera (needs HTTPS; otherwise use the phone's camera app, which opens the invitation link) or type the short code, then give the device a name.
+2. On the phone, open the paired-device address. An unpaired device gets a connect screen: scan the QR code with the in-app camera (HTTPS required), use the phone's camera app to open the invitation link, or type the short code shown beside the QR, then give the device a name. Pi Companion explains why camera access is needed before triggering the browser permission prompt.
 3. The daemon issues a long random credential and stores only its SHA-256 hash.
 
 Typed codes are short, so wrong ones are counted: after ten misses within ten minutes every open invitation is withdrawn and code entry is refused (HTTP 429) until the window passes.
@@ -158,7 +189,7 @@ Each session has an isolated temporary directory beneath the operating system te
 
 On Unix the daemon attempts to set the Pi Companion and session directories to mode 0700.
 
-The browser can upload a file from the Files tab. Current constraints:
+The browser can upload a file using the composer’s attachment button, or from **Shared files** in the session menu. Composer attachments show previews, file names, sizes and upload status; validation and upload failures appear beside the file. Image thumbnails are limited to safe raster image types. Removing a preview removes that attachment from the draft; deleting a shared upload remains an explicit action. The current daemon upload policy is checked before selection is uploaded, and the daemon remains authoritative. Current constraints:
 
 - 25 MiB maximum per upload by default (Settings); a rejected or interrupted upload leaves no partial file
 - optional MIME allowlist: the type guessed from the file name and any specific declared Content-Type must both be allowed
@@ -182,6 +213,18 @@ which destroys one temporary file by opaque id.
 
 This means the agent can consume uploaded artifacts using its normal file capabilities while Pi Companion retains ownership of upload placement and cleanup.
 
+## Workspace and tunnel connection errors
+
+If a tunnel closes, the workspace stops, or your device loses its network, Companion shows an actionable **Workspace connection interrupted** notice with **Retry now** and reconnect instructions. On initial connection failure, it shows **Workspace unavailable**, not a misleading empty session list or “session not found.” Gateway errors (including HTTP 502/503/504 and tunnel-provider errors) are translated into readable messages rather than raw HTML or JSON parse errors. A browser cannot always distinguish a closed tunnel from a daemon, DNS or network failure, so these messages describe possible causes rather than claiming certainty.
+
+- Ordinary API requests and live-connection handshakes time out after 10 seconds; uploads allow 60 seconds.
+- Reconnection uses bounded backoff and retries when the device returns online. **Retry now** is available immediately.
+- Previously loaded activity may be stale. Failed sends keep your draft; messages and uploads are never automatically resent.
+- Network/tunnel errors preserve pairing. Explicit computer disconnects still require manual reconnect; revoked credentials still require pairing again.
+- Restart the tunnel, keep the workspace running, and run `/companion` in Pi if the daemon is not running. If the tunnel URL changed, open the new HTTPS device URL; a different hostname/origin may require pairing again in that browser.
+
+A previously cached PWA shell can also explain gateway failures on reload. If the app has never loaded successfully on that device and no shell is cached, the browser/tunnel provider owns the initial error page; Companion cannot display its own UI until its assets are reachable.
+
 ## Session identity
 
 Every registered Pi session publishes a compact display model to the daemon:
@@ -194,7 +237,7 @@ Every registered Pi session publishes a compact display model to the daemon:
 - working directory and process id
 - remote-control state
 
-Stopped sessions remain visible in the daemon registry so the dashboard does not lose context when a Pi process exits. Their controls are disabled and their temporary sandbox is cleaned after the reconnect grace period.
+Stopped sessions remain visible in the daemon registry so the dashboard does not lose context when a Pi process exits. Their controls are disabled and their temporary sandbox is cleaned after the reconnect grace period. Use **Archive session** on the list or in the session menu to remove a disconnected/stopped entry. The daemon rejects removal of active, idle, waiting, or otherwise connected sessions. Archiving removes only the daemon entry; it never deletes Pi history, project files or other files on disk. Temporary uploads still follow the existing disconnect cleanup lifecycle. Reopening the Pi session and running `/companion` can register it again.
 
 ## UI
 
@@ -202,15 +245,15 @@ A single-page SvelteKit app, embedded in the daemon binary:
 
 | Page | Who sees it | What it is for |
 |---|---|---|
-| Overview | everyone | Dot-field hero, live counts, sessions that need your answer, live sessions, Help entry |
-| Sessions | everyone | Searchable, filterable list (Working / Waiting / Ended). Paired devices only see shared sessions |
-| Session detail | everyone | Shell-style transcript that follows the theme: Markdown replies with highlight.js code and Mermaid diagrams, collapsible tool output and thinking. Question sheet, files, git changes, /plan; the composer (message / steer) appears on Activity only. Session details are collapsed under the title |
+| Overview | everyone | Dot-field hero, live counts, sessions that need your answer, a labeled live-session table, and a spaced onboarding/help panel with Claymorphism actions |
+| Sessions | everyone | Searchable, filterable full-width session rows (Working / Waiting / Ended), with short titles, workspace/model metadata, View details and safe Archive actions. Paired devices only see shared sessions |
+| Session detail | everyone | Activity-first transcript with Markdown, highlighted code, Mermaid diagrams, collapsible tool output/thinking and question sheets. Compact header and navigation leave more space for the shell. The expanding composer includes Auto/Plan selection, attachment previews and a full-width labeled Send/Steer action; Plan uses the existing `/plan` command, not an agent permission setting. The top-right session menu opens Shared files, Changes and Archive session. The session header shows a status dot; clicking its title reveals status and session metadata. Changes are grouped by file with clear separators and a filename filter |
 | Devices, Settings | local console only | Pairing, connection status, disconnect and revoke; daemon settings with a save bar that appears only for unsaved edits |
 | Help, Privacy, Terms | everyone | Setup stepper, commands, tools, troubleshooting; data handling; terms of use. Help is opened from the Overview |
 
 The Live indicator in the header and sidebar opens the connection sheet (status, version and, on this computer, the console and device addresses and data folders).
 
-Git problems on the Changes tab (for example a folder that is not a git repository) show as a toast, never in the transcript.
+Git problems in the Changes panel (for example a folder that is not a git repository) show as a toast, never in the transcript.
 
 Design notes:
 
@@ -218,11 +261,13 @@ Design notes:
 - claymorphism: solid surfaces with an outer drop shadow plus inset highlight and shade (no blur or glass); small icons are Lucide line icons on raised clay wells, feature art is 3D clay renders from [3dicons](https://3dicons.co) (CC0)
 - warm amber on graphite or paper, matching the logo; system fonts only, so nothing loads from the network. highlight.js and Mermaid load only when a reply contains code or a diagram
 - the window never scrolls. The sidebar, page content, activity feed, file list, diff, chips and tabs each scroll inside their own container, and the composer and mobile tab bar stay put
+- the shell gently breathes while the displayed session is working, with a slower [thinking animation](docs/thinking.webp) and a soft progress sweep on the mobile header; it stops when idle or disconnected and respects reduced-motion preferences
 - the activity feed follows new output and stops following when you scroll up ("Jump to latest" brings you back)
+- installable PWA: scoped manifest with explicit 192×192 and 512×512 PNG icons plus a maskable icon, standalone display mode, Apple home-screen metadata, and a service worker that caches only the public shell and static assets; API/session traffic and uploads are never cached
 - mobile: bottom tab bar, safe-area insets, 44px touch targets, 16px inputs (no iOS zoom), Enter inserts a newline on touch keyboards
-- accessibility: skip link, visible focus rings, arrow-key tabs, labelled controls, live regions for the feed and questions, reduced-motion support
+- accessibility: skip link, visible focus rings, labeled controls and table metadata, accessible session menus, live regions for the feed and questions, reduced-motion support
 - the dot field is Raksara's component, loaded when the browser is idle, paused when hidden, and static under reduced motion
-- dropping a file anywhere outside the Files drop zone is ignored. Without this, the browser tries to open the file itself (Firefox reports this as "may not load or link to file:///")
+- dropping a file anywhere outside the Shared files drop zone is ignored. Without this, the browser tries to open the file itself (Firefox reports this as "may not load or link to file:///")
 
 ### Caching and updates
 
@@ -254,16 +299,20 @@ The initial slice supports:
 
 There is deliberately no arbitrary shell, arbitrary tool invocation, or arbitrary filesystem API.
 
-## Development
+## Running locally from source
+
+Use this only when developing Pi Companion itself. A published install does not require these steps.
 
 Requirements: Node 22.17+ and stable Rust.
 
+Clone the repository, then:
+
     npm install
     npm run serve
 
-This builds the UI, starts the daemon and prints where it is listening:
+`npm run serve` builds the embedded Svelte UI and starts the Rust daemon in the foreground. It prints:
 
-      Pi Companion v0.2.1
+      Pi Companion v0.2.2
 
       Console          http://127.0.0.1:43721
       Paired devices   http://127.0.0.1:43722
@@ -276,7 +325,7 @@ Type checks cover the extension (`tsc`) and the UI (`svelte-check`, warnings fai
 
     npm run check
 
-Tests cover the question relay (`node --test`) and the daemon's wire protocol, pairing expiry and code throttling, origin policy, bridge and device reconnects, path traversal, upload limits, MIME allowlist, state-file permissions and multi-session isolation (`cargo test`):
+Tests cover the question relay, deferred per-session startup and remote-off/re-enable behavior (including an executable extension/bridge harness), attachment validation and path references, changed-file grouping/filtering, workspace error classification and actual connection-store recovery, install icon dimensions and service-worker cache isolation (`node --test`), plus the daemon's wire protocol, safe session archiving, pairing expiry and code throttling, origin policy, bridge and device reconnects, path traversal, upload limits, MIME allowlist, state-file permissions and multi-session isolation (`cargo test`):
 
     npm test
 
@@ -286,13 +335,21 @@ Then, in another shell, start Pi with the extension from this checkout:
 
     pi -e ./src/index.ts
 
+After you run `/companion`, the extension detects the development daemon already listening on port 43721 and does not launch another daemon.
+
 For hot-reloading UI work, keep the daemon running and use:
 
     npm run ui:dev
 
 which proxies /api and /ws to the daemon on 43721.
 
-Running the daemon manually with npm run serve and the extension side by side just works: the extension sees the running daemon and connects to it. If you don't run it, the extension launches your local cargo build automatically.
+If you start Pi from the checkout without running `npm run serve`, running `/companion` can still auto-start a local daemon build if one exists under `server/target/debug` or `server/target/release`. For predictable UI work, prefer `npm run serve` in one terminal and `pi -e ./src/index.ts` in another.
+
+To test the same behavior as a published install, stop any development daemon first and install the package normally:
+
+    pi install npm:@yunazgr/pi-companion
+
+Then start Pi and run `/companion`. The extension downloads and starts the released daemon on demand; merely starting Pi does neither.
 
 ## Releases
 
@@ -306,7 +363,7 @@ Before publishing, the workflow requires X.Y.Z to match both package.json and se
 
 Only after the GitHub Release exists, the same tag publishes @yunazgr/pi-companion to npm with provenance through npm Trusted Publishing (GitHub OIDC). No long-lived NPM_TOKEN is required. The trusted publisher should point to GitHub owner ygrip, repository pi-companion, workflow release.yml. Git installs need no npm credential.
 
-On first use the extension downloads `pi-companion-server-<os>-<arch>` for its own package version (`releases/download/v<version>/`), verifies it against `SHA256SUMS`, and caches it under `~/.pi/agent/pi-companion/bin/<version>/`. A git install from a branch that is ahead of the newest tag falls back to the latest release.
+On first use the extension downloads `pi-companion-server-<os>-<arch>` for its own package version (`releases/download/v<version>/`), verifies it against `SHA256SUMS`, and caches it under `~/.pi/agent/pi-companion/bin/<version>/`. On later extension upgrades it detects a running daemon with a different version, stops it locally, and starts the matching daemon automatically. A git install from a branch that is ahead of the newest tag falls back to the latest release.
 
 ## Security boundary
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yunazgr/pi-companion",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Local-first remote control for Pi sessions: live activity feed, steering, git diff, file drop and phone pairing from a single Rust daemon.",
   "keywords": [
     "pi-package",

package/src/ask.ts

@@ -28,6 +28,7 @@ export function relayDialogs(ui: ExtensionUIContext, channel: AskChannel, tools:
   const confirm = ui.confirm.bind(ui);
   const input = ui.input.bind(ui);
   const custom = ui.custom.bind(ui);
+  const originals = { select: ui.select, confirm: ui.confirm, input: ui.input, custom: ui.custom };
 
   ui.custom = (factory, options) => {
     const complete = tools.claim();
@@ -73,6 +74,11 @@ export function relayDialogs(ui: ExtensionUIContext, channel: AskChannel, tools:
       undefined,
       opts?.signal
     );
+
+  return () => {
+    Object.assign(ui, originals);
+    delete target[RELAYED];
+  };
 }
 
 async function race<T>(

package/src/bridge.ts

@@ -17,6 +17,8 @@ export class CompanionBridge implements AskChannel {
   private ctx?: ExtensionContext;
   private reconnect?: NodeJS.Timeout;
   private closed = false;
+  private activated = false;
+  private restoreDialogs?: () => void;
   private connecting = false;
   private everConnected = false;
   private downSince = 0;
@@ -40,11 +42,13 @@ export class CompanionBridge implements AskChannel {
 
   setContext(ctx: ExtensionContext) {
     this.ctx = ctx;
-    if (ctx.hasUI) relayDialogs(ctx.ui, this, this.toolDialogs);
+    if (this.activated && this.snapshot.remoteEnabled && ctx.hasUI && !this.restoreDialogs) this.restoreDialogs = relayDialogs(ctx.ui, this, this.toolDialogs);
+    const name = this.pi.getSessionName() ?? this.snapshot.name;
     this.snapshot = {
       ...this.snapshot,
+      name,
       cwd: ctx.cwd,
-      shortTitle: this.snapshot.name?.trim() || ctx.cwd.split(/[\\/]/).filter(Boolean).pop() || "Pi",
+      shortTitle: name?.trim() || ctx.cwd.split(/[\\/]/).filter(Boolean).pop() || "Pi",
       mainModel: ctx.model?.id,
       effort: ctx.thinkingLevel,
       status: ctx.isIdle() ? "idle" : "active"
@@ -53,12 +57,32 @@ export class CompanionBridge implements AskChannel {
 
   setName(name?: string) {
     this.snapshot.name = name;
-    this.send({ type: "session.update", session: { name } });
+    this.snapshot.shortTitle = name?.trim() || this.snapshot.cwd.split(/[\\/]/).filter(Boolean).pop() || "Pi";
+    this.send({ type: "session.update", session: { name, shortTitle: this.snapshot.shortTitle } });
   }
 
   setRemoteEnabled(remoteEnabled: boolean) {
     this.snapshot.remoteEnabled = remoteEnabled;
-    this.send({ type: "session.update", session: { remoteEnabled } });
+    this.snapshot.status = remoteEnabled ? (this.ctx?.isIdle() === false ? "active" : "idle") : "stopped";
+    this.send({ type: "session.update", session: { remoteEnabled, status: this.snapshot.status } });
+    if (remoteEnabled) {
+      if (this.isActivated()) { this.activate(); void this.connect(); }
+      return;
+    }
+    // End only Companion sharing: Pi itself and its local history keep running.
+    this.restoreDialogs?.();
+    this.restoreDialogs = undefined;
+    for (const entry of [...this.asks.values()]) entry.settle(null);
+    for (const pending of this.pendingDeletes.values()) {
+      clearTimeout(pending.timer);
+      pending.resolve({ ok: false, error: "Session sharing ended." });
+    }
+    this.pendingDeletes.clear();
+    if (this.reconnect) clearTimeout(this.reconnect);
+    this.reconnect = undefined;
+    const ws = this.ws;
+    this.ws = undefined;
+    ws?.close();
   }
 
   isRemoteEnabled() {
@@ -69,9 +93,19 @@ export class CompanionBridge implements AskChannel {
     return [...this.tempFiles];
   }
 
-  /** Connect to the shared daemon, launching it only when nothing is listening. */
+  /** Only an explicit /companion command may activate this session's bridge. */
+  activate() {
+    this.activated = true;
+    if (this.snapshot.remoteEnabled && this.ctx?.hasUI && !this.restoreDialogs) this.restoreDialogs = relayDialogs(this.ctx.ui, this, this.toolDialogs);
+  }
+
+  isActivated() {
+    return this.activated && !this.closed;
+  }
+
+  /** Connect to the shared daemon only after this session opted in. */
   async connect() {
-    if (this.closed || this.connecting) return;
+    if (!this.activated || !this.snapshot.remoteEnabled || this.closed || this.connecting) return;
     if (this.ws && this.ws.readyState <= WebSocket.OPEN) return; // connecting or already live
     this.connecting = true;
     try {
@@ -79,7 +113,7 @@ export class CompanionBridge implements AskChannel {
       // period to come back before launching a replacement.
       const allowSpawn = !this.everConnected || (this.downSince > 0 && Date.now() - this.downSince > 20_000);
       if (allowSpawn) await ensureDaemon((message, level = "info") => this.log(message, level));
-      if (this.closed) return;
+      if (this.closed || !this.snapshot.remoteEnabled) return;
       this.open();
     } finally {
       this.connecting = false;
@@ -91,12 +125,14 @@ export class CompanionBridge implements AskChannel {
     const ws = new WebSocket(base.replace(/\/$/, "") + "/ws/bridge/" + this.sessionId);
     this.ws = ws;
     ws.on("open", () => {
+      if (this.ws !== ws || this.closed || !this.snapshot.remoteEnabled) { ws.close(); return; }
       this.everConnected = true;
       this.downSince = 0;
       this.retryDelay = 1000;
       this.send({ type: "register", session: this.snapshot });
     });
     ws.on("message", raw => {
+      if (this.ws !== ws || this.closed || !this.snapshot.remoteEnabled) return;
       try { void this.handle(JSON.parse(raw.toString()) as ServerMessage); }
       catch (error) { this.send({ type: "error", message: "Invalid server message: " + String(error) }); }
     });
@@ -116,6 +152,9 @@ export class CompanionBridge implements AskChannel {
 
   close() {
     this.closed = true;
+    this.restoreDialogs?.();
+    this.restoreDialogs = undefined;
+    for (const entry of [...this.asks.values()]) entry.settle(null);
     if (this.reconnect) clearTimeout(this.reconnect);
     this.ws?.close();
   }
@@ -136,7 +175,7 @@ export class CompanionBridge implements AskChannel {
   ask(input: AskInput, signal?: AbortSignal) {
     const request: AskRequest = { ...input, requestId: randomUUID(), createdAt: new Date().toISOString() };
     return new Promise<AskAnswers | null>(resolve => {
-      if (signal?.aborted) return resolve(null);
+      if (!this.isActivated() || !this.snapshot.remoteEnabled || signal?.aborted) return resolve(null);
       const onAbort = () => settle(null);
       const settle = (answers: AskAnswers | null) => {
         if (!this.asks.delete(request.requestId)) return;
@@ -157,6 +196,7 @@ export class CompanionBridge implements AskChannel {
   }
 
   async deleteTempFile(fileId: string) {
+    if (!this.isActivated()) return { ok: false, error: "Run /companion first to enable this session." };
     const requestId = randomUUID();
     this.send({ type: "file.delete", requestId, fileId });
     return await new Promise<{ ok: boolean; error?: string }>(resolve => {
@@ -174,7 +214,7 @@ export class CompanionBridge implements AskChannel {
 
   private scheduleReconnect() {
     if (this.reconnect) clearTimeout(this.reconnect);
-    if (this.closed) return;
+    if (!this.activated || !this.snapshot.remoteEnabled || this.closed) return;
     this.reconnect = setTimeout(() => void this.connect(), this.retryDelay);
     this.retryDelay = Math.min(this.retryDelay * 2, 10_000);
   }

package/src/daemon.ts

@@ -40,15 +40,22 @@ function isLocalTarget() {
   }
 }
 
-export async function isDaemonUp(timeoutMs = 800) {
+type DaemonContext = { version?: string; pid?: number };
+
+async function daemonContext(timeoutMs = 800): Promise<DaemonContext | null> {
   try {
     const response = await fetch(adminHttpUrl() + "/api/context", { signal: AbortSignal.timeout(timeoutMs) });
-    return response.ok;
+    if (!response.ok) return null;
+    return await response.json() as DaemonContext;
   } catch {
-    return false;
+    return null;
   }
 }
 
+export async function isDaemonUp(timeoutMs = 800) {
+  return Boolean(await daemonContext(timeoutMs));
+}
+
 function packageVersion() {
   try {
     return JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8")).version as string;
@@ -182,35 +189,84 @@ async function acquireLock() {
   }
 }
 
-async function waitForDaemon(ms: number) {
+async function waitForDaemon(ms: number, expectedVersion?: string) {
   const deadline = Date.now() + ms;
   while (Date.now() < deadline) {
-    if (await isDaemonUp(500)) return true;
+    const context = await daemonContext(500);
+    if (context && (!expectedVersion || context.version === expectedVersion)) return true;
     await new Promise(resolve => setTimeout(resolve, 300));
   }
   return false;
 }
 
+async function waitForDaemonDown(ms: number) {
+  const deadline = Date.now() + ms;
+  while (Date.now() < deadline) {
+    if (!(await isDaemonUp(300))) return true;
+    await new Promise(resolve => setTimeout(resolve, 200));
+  }
+  return false;
+}
+
+async function stopDaemonForUpgrade(context: DaemonContext, log: DaemonLog) {
+  try {
+    const response = await fetch(adminHttpUrl() + "/api/shutdown", {
+      method: "POST",
+      signal: AbortSignal.timeout(2_000)
+    });
+    if (response.ok && await waitForDaemonDown(5_000)) return true;
+  } catch {
+    // Older daemons do not have /api/shutdown. Fall through to a local process stop.
+  }
+
+  try {
+    if (typeof context.pid === "number" && Number.isInteger(context.pid) && context.pid > 1) {
+      process.kill(context.pid, "SIGTERM");
+    } else if (process.platform === "win32") {
+      await execFileAsync("taskkill", ["/IM", "pi-companion-server.exe", "/F"]);
+    } else {
+      await execFileAsync("pkill", ["-f", "pi-companion-server"]);
+    }
+  } catch {
+    // The process may already have exited between the probe and the stop attempt.
+  }
+
+  const stopped = await waitForDaemonDown(5_000);
+  if (!stopped) log("Could not stop the older Pi Companion daemon automatically.", "warning");
+  return stopped;
+}
+
 /**
  * Make sure a daemon is reachable. Returns true when one answers.
  * Never spawns when a daemon (manual `cargo run`, another session's daemon, …) is already up.
  */
 export async function ensureDaemon(log: DaemonLog) {
-  if (await isDaemonUp()) return true;
-  if (process.env.PI_COMPANION_AUTOSTART === "0" || !isLocalTarget()) return false;
+  const expectedVersion = packageVersion();
+  const running = await daemonContext();
+  if (running?.version === expectedVersion) return true;
+  if (process.env.PI_COMPANION_AUTOSTART === "0" || !isLocalTarget()) return Boolean(running);
 
   const release = await acquireLock();
-  if (!release) return await waitForDaemon(10_000); // another Pi session is starting it
+  if (!release) return await waitForDaemon(10_000, expectedVersion); // another Pi session is starting/upgrading it
   try {
-    if (await isDaemonUp()) return true; // started while we were taking the lock
+    const current = await daemonContext();
+    if (current?.version === expectedVersion) return true;
+
+    if (current) {
+      log(
+        "Updating Pi Companion daemon from v" + (current.version ?? "unknown") + " to v" + expectedVersion + "…"
+      );
+      if (!(await stopDaemonForUpgrade(current, log))) return false;
+    }
+
     const binary = await resolveDaemonBinary(log);
     await new Promise<void>((resolve, reject) => {
       const child = spawn(binary, [], { detached: true, stdio: "ignore", windowsHide: true });
       child.once("error", reject);
       child.once("spawn", () => { child.unref(); resolve(); });
     });
-    const up = await waitForDaemon(10_000);
-    if (!up) log("Pi Companion daemon did not become ready (" + binary + ")", "warning");
+    const up = await waitForDaemon(10_000, expectedVersion);
+    if (!up) log("Pi Companion daemon v" + expectedVersion + " did not become ready (" + binary + ")", "warning");
     return up;
   } catch (error) {
     log("Could not start Pi Companion daemon: " + (error instanceof Error ? error.message : String(error)), "warning");

package/src/index.ts

@@ -68,11 +68,15 @@ function resultText(result: unknown) {
 }
 
 export default function companionExtension(pi: ExtensionAPI) {
-  const bridge = new CompanionBridge(pi);
+  let bridge = new CompanionBridge(pi);
+  let sharingGeneration = 0;
 
   pi.on("session_start", (_event, ctx) => {
+    // Switching or starting a Pi session must not inherit the previous opt-in.
+    sharingGeneration += 1;
+    bridge.close();
+    bridge = new CompanionBridge(pi);
     bridge.setContext(ctx);
-    void bridge.connect();
     bridge.emit("session.start", { cwd: ctx.cwd });
   });
   pi.on("session_info_changed", (event, ctx) => {
@@ -118,6 +122,7 @@ export default function companionExtension(pi: ExtensionAPI) {
     });
   });
   pi.on("session_shutdown", event => {
+    sharingGeneration += 1;
     bridge.updateStatus("stopped");
     bridge.emit("session.shutdown", event);
     bridge.close();
@@ -131,6 +136,12 @@ export default function companionExtension(pi: ExtensionAPI) {
     parameters: AskParams,
     executionMode: "sequential",
     async execute(_toolCallId, params, signal) {
+      if (!bridge.isActivated()) {
+        return {
+          content: [{ type: "text", text: "Pi Companion is not enabled for this session. Run /companion before asking through the dashboard." }],
+          details: { questions: [], answers: null }
+        };
+      }
       const items = params.questions?.length
         ? params.questions
         : params.question
@@ -196,18 +207,28 @@ export default function companionExtension(pi: ExtensionAPI) {
   pi.registerCommand("companion", {
     description: "Enable Pi Companion for this session and show the dashboard address (`/companion off` to stop sharing)",
     handler: async (args, ctx) => {
+      const generation = ++sharingGeneration;
+      bridge.setContext(ctx);
+      if (args.trim().toLowerCase() === "off") {
+        bridge.setRemoteEnabled(false);
+        ctx.ui.notify("Pi Companion sharing ended for this session. Pi continues locally.", "info");
+        return;
+      }
+      const currentBridge = bridge;
       const up = await ensureDaemon((message, level = "info") => ctx.ui.notify(message, level));
+      if (bridge !== currentBridge || generation !== sharingGeneration) return;
       if (!up) {
         ctx.ui.notify("Pi Companion daemon is not reachable at " + adminHttpUrl(), "warning");
         return;
       }
+      bridge.activate();
       void bridge.connect();
-      const enabled = args.trim().toLowerCase() !== "off";
+      const enabled = true;
       bridge.setRemoteEnabled(enabled);
       ctx.ui.notify(
         enabled
           ? "Pi Companion enabled for this session: " + adminHttpUrl() + " (paired devices can now see it)"
-          : "Pi Companion: this session is no longer shared with paired devices.",
+          : "Pi Companion sharing ended for this session. Pi continues locally.",
         "info"
       );
     }
@@ -216,12 +237,17 @@ export default function companionExtension(pi: ExtensionAPI) {
   pi.registerCommand("remote-control", {
     description: "Toggle remote control for this Pi session",
     handler: async (_args, ctx) => {
+      sharingGeneration += 1;
+      if (!bridge.isActivated()) {
+        ctx.ui.notify("Run /companion first to enable this session's daemon connection.", "warning");
+        return;
+      }
       const enabled = !bridge.isRemoteEnabled();
       bridge.setRemoteEnabled(enabled);
       ctx.ui.notify(
         enabled
           ? "Remote control enabled for this session. Pair a device from Pi Companion."
-          : "Remote control disabled for this session.",
+          : "Remote control disabled; this Companion session has ended. Pi continues locally.",
         enabled ? "info" : "warning"
       );
     }