protocol: symmetric compat check + name the outdated side on version mismatch

- isProtocolCompatible: replace npm caret (asymmetric — rejected a remote
  with a lower patch on the same line) with symmetric same-breaking-line
  comparison, the faithful implementation of the bump policy (0.x: same
  minor; >=1.0: same major; prerelease: exact match)
- new outdatedSide(remote) helper: semver-lower side is the outdated one;
  null on equal/garbage input
- error frame: optional protocolVersion field, set by the daemon on
  version-mismatch rejections (deliberately absent on the
  frame-before-hello misuse rejection where direction is meaningless)
- app: IncompatibleProtocolError gains outdatedSide ("app" | "daemon" |
  "unknown") and direction-specific copy — "update the Mac app" vs
  "update this app" vs the neutral both-sides fallback
- protocol 0.0.0 -> 0.0.1 (additive field)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: yyq1025

packages/app/src/lib/daemon-client-context.tsx

@@ -303,9 +303,10 @@ export function DaemonClientProvider({ children }: { children: ReactNode }) {
             if (!shouldReconnectRef.current) return;
             // Protocol mismatch is TERMINAL — retrying can't change a
             // version check. Stop the auto-reconnect loop and surface a
-            // terminal `error` (red, "update both"); the user re-attempts
-            // via reset() after updating. KEEP `paired` so the update
-            // screen can still show host context, like the offline path.
+            // terminal `error` (the message names which side is outdated
+            // via `err.outdatedSide`); the user re-attempts via reset()
+            // after updating. KEEP `paired` so the update screen can
+            // still show host context, like the offline path.
             if (err instanceof IncompatibleProtocolError) {
               shouldReconnectRef.current = false;
               setState({ status: "error", error: err });

packages/app/src/lib/daemon-client.ts

@@ -11,6 +11,7 @@ import {
   type ImageAttachment,
   isChunkEnvelope,
   isProtocolCompatible,
+  outdatedSide,
   PAIR_OFFER_VERSION,
   PROTOCOL_VERSION,
   type SessionState,
@@ -26,26 +27,40 @@ import { WebRTCPeer } from "./webrtc-peer";
 
 /**
  * Thrown by the connect handshake when the daemon and app speak
- * wire-incompatible protocol versions (either side too old — the caret
- * compat gate is symmetric, so we can't tell which from here, and it
- * doesn't matter: "update both to latest" is always-correct guidance).
+ * wire-incompatible protocol versions. The daemon's rejection frame (and
+ * `server_info`) carry its PROTOCOL_VERSION, so `outdatedSide` names the
+ * side that needs updating — the semver-lower side — and the message is
+ * tailored to it. `"unknown"` (→ direction-neutral "update both" copy)
+ * only happens when the version is missing or unparseable, e.g. the
+ * frame-before-hello misuse rejection which deliberately omits it.
  *
  * Unlike a transient unreachable-daemon failure, this is TERMINAL: no
  * amount of retrying changes the version check. `DaemonClientProvider`
  * routes it to a terminal `error` state and stops the auto-reconnect loop
- * (the user re-attempts via `reset()` after updating). `daemonProtocolVersion`
- * is best-effort for diagnostics — null when the daemon rejected our `hello`
- * before we could read its version; the user-facing copy never names a side.
+ * (the user re-attempts via `reset()` after updating).
  */
 export class IncompatibleProtocolError extends Error {
   readonly appProtocolVersion = PROTOCOL_VERSION;
   readonly daemonProtocolVersion: string | null;
+  /** Which side is too old. `"daemon"` → update the Mac app, `"app"` →
+   *  update this app, `"unknown"` → no usable daemon version, update both. */
+  readonly outdatedSide: "app" | "daemon" | "unknown";
   constructor(daemonProtocolVersion: string | null = null) {
+    const side =
+      daemonProtocolVersion === null
+        ? null
+        : outdatedSide(daemonProtocolVersion);
     super(
-      "Sidecode is out of date. Update both the iPhone app and the Mac app to the latest version, then try again.",
+      side === "remote"
+        ? "The Mac app is out of date. Update Sidecode on your Mac, then try again."
+        : side === "local"
+          ? "This app is out of date. Update Sidecode from the App Store, then try again."
+          : "Sidecode is out of date. Update both the iPhone app and the Mac app to the latest version, then try again.",
     );
     this.name = "IncompatibleProtocolError";
     this.daemonProtocolVersion = daemonProtocolVersion;
+    this.outdatedSide =
+      side === "remote" ? "daemon" : side === "local" ? "app" : "unknown";
   }
 }
 
@@ -416,9 +431,10 @@ export class Transport {
                   `daemon reported incompatible_protocol: ${frame.message}`,
                 );
               }
-              // Daemon's error frame carries no structured version (only the
-              // freetext message above), so direction is unknown — fine, the
-              // copy never names a side.
+              // Version-mismatch rejections carry the daemon's structured
+              // protocolVersion → the error names which side is outdated.
+              // The frame-before-hello misuse rejection omits it → falls
+              // back to the direction-neutral "update both" copy.
               fail(
                 new IncompatibleProtocolError(frame.protocolVersion ?? null),
               );

packages/daemon/src/webrtc-peer.ts

@@ -522,6 +522,9 @@ export class WebRTCPeerServer {
           type: "error",
           code: "incompatible_protocol",
           message: `client protocol ${frame.protocolVersion} is not compatible with daemon ${PROTOCOL_VERSION}`,
+          // Structured copy of our version so iOS can tell WHICH side is
+          // outdated (`outdatedSide`) and name it in the error copy.
+          protocolVersion: PROTOCOL_VERSION,
         });
         this.closePeer(slot, "incompatible wire protocol");
         return;

packages/protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sidecodeapp/protocol",
-  "version": "0.0.0",
+  "version": "0.0.1",
   "private": true,
   "description": "Wire protocol shared between sidecode daemon and clients",
   "type": "module",

packages/protocol/src/index.test.ts

@@ -16,6 +16,7 @@ import {
   interruptCommand,
   interruptResponse,
   isProtocolCompatible,
+  outdatedSide,
   PAIR_OFFER_VERSION,
   PROTOCOL_VERSION,
   pairOfferFrame,
@@ -48,28 +49,21 @@ describe("isProtocolCompatible", () => {
     expect(isProtocolCompatible(PROTOCOL_VERSION)).toBe(true);
   });
 
-  it("npm caret semantics for 0.0.x: exact-match only (every change is breaking)", () => {
-    // npm convention: ^0.0.0 → >=0.0.0 <0.0.1. No upgrades allowed
-    // because at 0.0.x every change is potentially breaking. We surface
-    // this through `^PROTOCOL_VERSION`. If PROTOCOL_VERSION is in this
-    // range, anything other than exact-match is rejected.
-    if (PROTOCOL_VERSION.startsWith("0.0.")) {
-      const [, , patch] = PROTOCOL_VERSION.split(".").map(Number);
-      expect(isProtocolCompatible(`0.0.${patch + 1}`)).toBe(false);
-      expect(isProtocolCompatible(`0.1.0`)).toBe(false);
-      expect(isProtocolCompatible(`1.0.0`)).toBe(false);
-    }
-  });
-
-  it("npm caret semantics for 0.x.y (x≥1): same minor + patch ≥ local", () => {
-    // ^0.5.3 → >=0.5.3 <0.6.0. Patch upgrades OK, minor bump breaking.
-    if (
-      PROTOCOL_VERSION.startsWith("0.") &&
-      !PROTOCOL_VERSION.startsWith("0.0.")
-    ) {
+  it("same breaking line during 0.x: patch differences compatible BOTH directions", () => {
+    // Bump policy: patch = additive only, old peers harmlessly ignore.
+    // The check is symmetric same-`0.minor`-line — deliberately NOT npm
+    // caret (which rejects a remote with a LOWER patch than ours).
+    if (PROTOCOL_VERSION.startsWith("0.")) {
       const [, minor, patch] = PROTOCOL_VERSION.split(".").map(Number);
       expect(isProtocolCompatible(`0.${minor}.${patch + 5}`)).toBe(true);
+      if (patch > 0) {
+        expect(isProtocolCompatible(`0.${minor}.${patch - 1}`)).toBe(true);
+      }
       expect(isProtocolCompatible(`0.${minor + 1}.0`)).toBe(false);
+      if (minor > 0) {
+        expect(isProtocolCompatible(`0.${minor - 1}.0`)).toBe(false);
+      }
+      expect(isProtocolCompatible(`1.0.0`)).toBe(false);
     }
   });
 
@@ -89,6 +83,33 @@ describe("isProtocolCompatible", () => {
   });
 });
 
+describe("outdatedSide", () => {
+  it("semver-lower remote → remote is the outdated side", () => {
+    const [major, minor, patch] = PROTOCOL_VERSION.split(".").map(Number);
+    expect(outdatedSide(`${major}.${minor}.${patch + 1}`)).toBe("local");
+    expect(outdatedSide(`${major}.${minor + 1}.0`)).toBe("local");
+    expect(outdatedSide(`${major + 1}.0.0`)).toBe("local");
+    if (patch > 0) {
+      expect(outdatedSide(`${major}.${minor}.${patch - 1}`)).toBe("remote");
+    }
+    if (minor > 0) {
+      expect(outdatedSide(`${major}.${minor - 1}.0`)).toBe("remote");
+    }
+    if (major > 0) {
+      expect(outdatedSide(`${major - 1}.0.0`)).toBe("remote");
+    }
+  });
+
+  it("equal version → null (a peer rejecting us at OUR version is misbehaving, not outdated)", () => {
+    expect(outdatedSide(PROTOCOL_VERSION)).toBe(null);
+  });
+
+  it("garbage input → null (caller falls back to direction-neutral copy)", () => {
+    expect(outdatedSide("not-a-version")).toBe(null);
+    expect(outdatedSide("")).toBe(null);
+  });
+});
+
 describe("pair offer", () => {
   it("PAIR_OFFER_VERSION is 2", () => {
     // Bumping forces an old iOS app to fail-decode an incompatible QR
@@ -443,6 +464,20 @@ describe("error frame", () => {
       }).code,
     ).toBe("incompatible_protocol");
   });
+
+  it("preserves the sender's protocolVersion on incompatible_protocol", () => {
+    // The field must be in the schema — z.object strips unknown keys, so
+    // a zod-parsed path would silently drop it and iOS couldn't tell
+    // which side is outdated.
+    expect(
+      errorFrame.parse({
+        type: "error",
+        code: "incompatible_protocol",
+        message: "client protocol 0.1.0 is not compatible with daemon 0.2.0",
+        protocolVersion: "0.2.0",
+      }).protocolVersion,
+    ).toBe("0.2.0");
+  });
 });
 
 describe("clientFrame union (commands only — no application-layer handshake)", () => {

packages/protocol/src/index.ts

@@ -70,30 +70,54 @@ export const PROTOCOL_VERSION: string = pkg.version;
 /**
  * True iff a remote peer reporting `remote` speaks a wire-compatible
  * schema set with this build's PROTOCOL_VERSION. Compatible means
- * `remote` satisfies a caret range over PROTOCOL_VERSION:
+ * "same breaking line", per the bump policy above:
  *
- *   - `^0.5.7` → compatible with `0.5.x` (any patch), not `0.6.0`
- *   - `^1.2.3` → compatible with `1.x.y` (any minor or patch ≥ 1.2.3)
+ *   - during 0.x the minor is the breaking axis → same `0.minor` line
+ *     (`0.5.1` ↔ `0.5.9` compatible in both directions, `0.6.0` not)
+ *   - ≥1.0 the major is the breaking axis → same major
+ *   - pre-release on either side → exact match only (mid-development
+ *     schemas churn; two builds are only known-compatible if identical)
  *
- * This is npm's standard caret semantics — same rule npm uses to decide
- * which versions satisfy a `^x.y.z` dependency. The semver package
- * handles pre-release tags / build metadata / edge cases correctly,
- * which a hand-rolled major-comparison would miss.
+ * Deliberately NOT npm caret semantics. `satisfies(remote, ^local)` is
+ * asymmetric — it rejects a remote with a LOWER patch on the same
+ * breaking line, but the bump policy says patch bumps are additive and
+ * old peers harmlessly ignore them. Symmetric same-line comparison is
+ * the faithful implementation, and it guarantees the daemon (which
+ * checks `hello` first) always rejects before iOS gets a chance to —
+ * iOS's `server_info` re-check is pure drift defense.
  *
  * Returns `false` on unparseable input (defensive — we'd rather refuse
  * than blunder on with an unknown version that might or might not be
  * compatible).
  */
 export function isProtocolCompatible(remote: string): boolean {
-  if (!semver.valid(remote) || !semver.valid(PROTOCOL_VERSION)) return false;
-  return semver.satisfies(remote, `^${PROTOCOL_VERSION}`, {
-    // includePrerelease: false — pre-release versions don't satisfy
-    // a caret range over a stable version. This is npm's default and
-    // it's the right call: a 1.2.0-beta.1 daemon shouldn't be
-    // considered compatible with a 1.0.0 client (the beta may have
-    // incompatible schemas mid-development).
-    includePrerelease: false,
-  });
+  const r = semver.parse(remote);
+  const local = semver.parse(PROTOCOL_VERSION);
+  if (!r || !local) return false;
+  if (r.prerelease.length > 0 || local.prerelease.length > 0) {
+    return semver.eq(r, local);
+  }
+  if (r.major !== local.major) return false;
+  return local.major === 0 ? r.minor === local.minor : true;
+}
+
+/**
+ * Which side is outdated, given the version an INCOMPATIBLE remote
+ * reported. Only meaningful after `isProtocolCompatible(remote)`
+ * returned false — incompatible versions are never equal, so the
+ * semver-lower side is the one that needs updating.
+ *
+ * Returns from the caller's perspective: `"remote"` → the peer is
+ * older (iOS calling this → tell the user to update the Mac app),
+ * `"local"` → this build is older. Returns `null` when the input is
+ * unparseable or equal to ours (a peer that rejected us while
+ * reporting our own version is misbehaving, not outdated) — callers
+ * fall back to direction-neutral "update both" copy.
+ */
+export function outdatedSide(remote: string): "local" | "remote" | null {
+  if (!semver.valid(remote) || !semver.valid(PROTOCOL_VERSION)) return null;
+  if (semver.eq(remote, PROTOCOL_VERSION)) return null;
+  return semver.lt(remote, PROTOCOL_VERSION) ? "remote" : "local";
 }
 
 // ─── Pair offer ────────────────────────────────────────────────────────────
@@ -1320,15 +1344,23 @@ export const errorFrame = z.object({
     "not_a_directory",
   ]),
   message: z.string(),
+  /** Sender's PROTOCOL_VERSION. Set on `incompatible_protocol` VERSION-
+   *  mismatch rejections so the receiver can run `outdatedSide()` and
+   *  name the side that needs updating. Deliberately absent on the
+   *  other `incompatible_protocol` use (frame-before-hello, a protocol-
+   *  misuse rejection where versions may well be EQUAL and direction is
+   *  meaningless) and on all other codes. */
+  protocolVersion: z.string().optional(),
 });
 
 // ─── Hello / server_info (wire-version handshake on DataChannel open) ─────
 //
 // iOS sends `hello` immediately after DC.open carrying its PROTOCOL_VERSION.
 // Daemon checks compatibility via `isProtocolCompatible` and responds with
-// its own `server_info` (or with `error{code:"incompatible_protocol"}` +
-// DC close on mismatch). iOS treats `server_info` as the "ready" signal —
-// application commands may only flow after it arrives.
+// its own `server_info` (or with `error{code:"incompatible_protocol",
+// protocolVersion}` + DC close on mismatch — the version lets iOS name
+// which side is outdated via `outdatedSide`). iOS treats `server_info` as
+// the "ready" signal — application commands may only flow after it arrives.
 //
 // Single field exchanged each way. There's no separate "app release
 // version" / "daemon release version" — the protocol package owns the