Surface remote source-control version drift

apps/web/src/components/WorktreeSourceControl.logic.test.ts

@@ -1,6 +1,57 @@
 import { describe, expect, it } from "vite-plus/test";
 
-import { resolveWorktreeDiffSource } from "./WorktreeSourceControl.logic";
+import {
+  resolveWorktreeCompatibilityNotice,
+  resolveWorktreeDiffSource,
+} from "./WorktreeSourceControl.logic";
+
+describe("resolveWorktreeCompatibilityNotice", () => {
+  it("does not warn when the environment supports source-control mutations", () => {
+    expect(
+      resolveWorktreeCompatibilityNotice({
+        supportsMutations: true,
+        serverVersion: "1.2.3",
+        versionMismatch: {
+          clientVersion: "1.2.4",
+          serverVersion: "1.2.3",
+        },
+      }),
+    ).toBeNull();
+  });
+
+  it("identifies version drift when a mixed-version environment lacks the capability", () => {
+    expect(
+      resolveWorktreeCompatibilityNotice({
+        supportsMutations: false,
+        serverVersion: "1.2.3",
+        versionMismatch: {
+          clientVersion: "1.2.4",
+          serverVersion: "1.2.3",
+        },
+      }),
+    ).toEqual({
+      kind: "version-mismatch",
+      label: "Version mismatch",
+      detail:
+        "Client 1.2.4 · environment 1.2.3. Diffs remain available in read-only compatibility mode; update the environment to restore stage and discard actions.",
+    });
+  });
+
+  it("reports a missing capability even when version strings match", () => {
+    expect(
+      resolveWorktreeCompatibilityNotice({
+        supportsMutations: false,
+        serverVersion: "1.2.3",
+        versionMismatch: null,
+      }),
+    ).toEqual({
+      kind: "limited-capability",
+      label: "Limited compatibility",
+      detail:
+        "Environment 1.2.3 does not advertise source-control mutations. Update or restart it to restore stage and discard actions.",
+    });
+  });
+});
 
 describe("resolveWorktreeDiffSource", () => {
   it("uses the exact index-aware source when available", () => {

apps/web/src/components/WorktreeSourceControl.logic.ts

@@ -2,6 +2,37 @@ import type { ReviewDiffPreviewSourceKind } from "@t3tools/contracts";
 
 export type WorktreeChangeScope = "staged" | "unstaged";
 
+export interface WorktreeCompatibilityNotice {
+  readonly kind: "version-mismatch" | "limited-capability";
+  readonly label: string;
+  readonly detail: string;
+}
+
+export function resolveWorktreeCompatibilityNotice(input: {
+  readonly supportsMutations: boolean;
+  readonly serverVersion: string;
+  readonly versionMismatch: {
+    readonly clientVersion: string;
+    readonly serverVersion: string;
+  } | null;
+}): WorktreeCompatibilityNotice | null {
+  if (input.supportsMutations) return null;
+
+  if (input.versionMismatch) {
+    return {
+      kind: "version-mismatch",
+      label: "Version mismatch",
+      detail: `Client ${input.versionMismatch.clientVersion} · environment ${input.versionMismatch.serverVersion}. Diffs remain available in read-only compatibility mode; update the environment to restore stage and discard actions.`,
+    };
+  }
+
+  return {
+    kind: "limited-capability",
+    label: "Limited compatibility",
+    detail: `Environment ${input.serverVersion} does not advertise source-control mutations. Update or restart it to restore stage and discard actions.`,
+  };
+}
+
 /**
  * Older environments only return the combined `working-tree` review source.
  * Treat it as the unstaged source when no index-aware sources are present so

apps/web/src/components/WorktreeSourceControl.tsx

@@ -17,6 +17,7 @@ import {
   RotateCcwIcon,
   Rows3Icon,
   TextWrapIcon,
+  TriangleAlertIcon,
 } from "lucide-react";
 import { memo, useCallback, useMemo, useState } from "react";
 
@@ -35,6 +36,7 @@ import { useEnvironmentQuery } from "~/state/query";
 import { serverEnvironment } from "~/state/server";
 import { useAtomCommand } from "~/state/use-atom-command";
 import { vcsEnvironment } from "~/state/vcs";
+import { resolveServerConfigVersionMismatch } from "~/versionSkew";
 
 import { useClientSettings } from "../hooks/useSettings";
 import { useTheme } from "../hooks/useTheme";
@@ -45,7 +47,11 @@ import { DIFF_VIEW_UNSAFE_CSS } from "./diffs/diffViewStyles";
 import { Toggle, ToggleGroup } from "./ui/toggle-group";
 import { Tooltip, TooltipPopup, TooltipTrigger } from "./ui/tooltip";
 import { stackedThreadToast, toastManager } from "./ui/toast";
-import { resolveWorktreeDiffSource, type WorktreeChangeScope } from "./WorktreeSourceControl.logic";
+import {
+  resolveWorktreeCompatibilityNotice,
+  resolveWorktreeDiffSource,
+  type WorktreeChangeScope,
+} from "./WorktreeSourceControl.logic";
 
 export type { WorktreeChangeScope } from "./WorktreeSourceControl.logic";
 
@@ -318,6 +324,13 @@ export function WorktreeSourceControl({
   const stagedFiles = useMemo(() => files.filter(isStaged), [files]);
   const unstagedFiles = useMemo(() => files.filter(isUnstaged), [files]);
   const canMutate = serverConfig?.environment.capabilities.worktreeSourceControl === true;
+  const compatibilityNotice = serverConfig
+    ? resolveWorktreeCompatibilityNotice({
+        supportsMutations: canMutate,
+        serverVersion: serverConfig.environment.serverVersion,
+        versionMismatch: resolveServerConfigVersionMismatch(serverConfig),
+      })
+    : null;
   const selectedSource = resolveWorktreeDiffSource(preview.data?.sources ?? [], selectedScope);
   const renderablePatch = useMemo(
     () =>
@@ -472,6 +485,25 @@ export function WorktreeSourceControl({
           </div>
         </div>
         <div className="flex shrink-0 items-center gap-2 [-webkit-app-region:no-drag]">
+          {compatibilityNotice ? (
+            <Tooltip>
+              <TooltipTrigger
+                render={
+                  <span
+                    tabIndex={0}
+                    aria-label={`${compatibilityNotice.label}. ${compatibilityNotice.detail}`}
+                    className="inline-flex h-6 items-center gap-1 rounded border border-amber-500/20 bg-amber-500/8 px-1.5 text-[10px] font-medium text-amber-700 dark:text-amber-300/80"
+                  />
+                }
+              >
+                <TriangleAlertIcon aria-hidden="true" className="size-3" />
+                <span className="hidden sm:inline">{compatibilityNotice.label}</span>
+              </TooltipTrigger>
+              <TooltipPopup className="max-w-80" side="bottom">
+                {compatibilityNotice.detail}
+              </TooltipPopup>
+            </Tooltip>
+          ) : null}
           <span className="hidden font-mono text-[10px] tabular-nums text-muted-foreground/55 sm:inline">
             {stagedFiles.length} staged · {unstagedFiles.length} changed
           </span>
@@ -526,11 +558,16 @@ export function WorktreeSourceControl({
               </div>
             ) : (
               <>
-                {!canMutate ? (
-                  <p className="border-b border-border/50 bg-muted/20 px-3 py-2 text-[10px] text-muted-foreground/65">
-                    Read-only compatibility mode. Update this environment to stage or discard
-                    changes.
-                  </p>
+                {compatibilityNotice ? (
+                  <div
+                    role="status"
+                    className="border-b border-amber-500/15 bg-amber-500/6 px-3 py-2 text-[10px] text-amber-800 dark:text-amber-200/75"
+                  >
+                    <p className="font-medium">{compatibilityNotice.label}</p>
+                    <p className="mt-0.5 text-amber-700/80 dark:text-amber-300/65">
+                      {compatibilityNotice.detail}
+                    </p>
+                  </div>
                 ) : null}
                 <ChangeSection
                   title="Staged Changes"

docs/personal-fork-changes.md

@@ -66,7 +66,9 @@ Upstream PRs integrated into the fork are listed in
 - The viewer tolerates mixed-version and intermittently connected remote environments: it keeps
   rendering the last successful status/diff snapshot, falls back to the legacy combined worktree
   diff when index-aware sections are unavailable, and exposes stage/discard actions only when the
-  environment advertises `worktreeSourceControl` support.
+  environment advertises `worktreeSourceControl` support. When compatibility mode is active, the
+  viewer shows a persistent warning with the client and environment versions when they differ; a
+  missing capability is still called out when the version strings happen to match.
 
 ## Durable pull request status