From c23a51d53af9f7bd8e3980aa35a9a2ca53451ae6 Mon Sep 17 00:00:00 2001
From: St0rmz1 <astorms@replicated.com>
Date: Tue, 3 Mar 2026 13:42:37 -0800
Subject: [PATCH 1/4] feat(kiloclaw): Add user self-pinning UI and admin
 improvements (Phase 2.1) fix merge conflicts

---
 src/app/(app)/claw/components/SettingsTab.tsx |   5 +
 .../(app)/claw/components/VersionPinCard.tsx  | 216 ++++++++++++++
 .../KiloclawInstanceDetail.tsx                | 136 +++++----
 .../KiloclawVersions/KiloclawVersionsPage.tsx |  14 +-
 src/hooks/useKiloClaw.ts                      |  39 +++
 src/routers/admin-kiloclaw-versions-router.ts |  42 ++-
 src/routers/kiloclaw-router.ts                | 176 +++++++++++-
 .../kiloclaw-user-versions-router.test.ts     | 271 ++++++++++++++++++
 8 files changed, 820 insertions(+), 79 deletions(-)
 create mode 100644 src/app/(app)/claw/components/VersionPinCard.tsx
 create mode 100644 src/routers/kiloclaw-user-versions-router.test.ts

diff --git a/src/app/(app)/claw/components/SettingsTab.tsx b/src/app/(app)/claw/components/SettingsTab.tsx
index a5b58a19b..28c71f444 100644
--- a/src/app/(app)/claw/components/SettingsTab.tsx
+++ b/src/app/(app)/claw/components/SettingsTab.tsx
@@ -20,6 +20,7 @@ import { DetailTile } from './DetailTile';
 import { ChannelTokenInput } from './ChannelTokenInput';
 import { CHANNELS, CHANNEL_TYPES, type ChannelDefinition } from './channel-config';
 import { ConfirmActionDialog } from './ConfirmActionDialog';
+import { VersionPinCard } from './VersionPinCard';
 
 type ClawMutations = ReturnType<typeof useKiloClawMutations>;
 
@@ -337,6 +338,10 @@ export function SettingsTab({
 
       <Separator />
 
+      <VersionPinCard />
+
+      <Separator />
+
       <div className="rounded-lg border border-red-500/20 bg-red-500/5 p-5">
         <div className="flex items-start gap-3">
           <div className="mt-0.5 flex h-8 w-8 shrink-0 items-center justify-center rounded-md bg-red-500/10">
diff --git a/src/app/(app)/claw/components/VersionPinCard.tsx b/src/app/(app)/claw/components/VersionPinCard.tsx
new file mode 100644
index 000000000..f55d148d6
--- /dev/null
+++ b/src/app/(app)/claw/components/VersionPinCard.tsx
@@ -0,0 +1,216 @@
+'use client';
+
+import { useState } from 'react';
+import { Pin, PinOff, Info } from 'lucide-react';
+import { toast } from 'sonner';
+import { useKiloClawAvailableVersions, useKiloClawMyPin, useKiloClawMutations } from '@/hooks/useKiloClaw';
+import { Button } from '@/components/ui/button';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
+import { Label } from '@/components/ui/label';
+import { Textarea } from '@/components/ui/textarea';
+
+export function VersionPinCard() {
+  const { data: myPin, isLoading: pinLoading } = useKiloClawMyPin();
+  const { data: versions, isLoading: versionsLoading } = useKiloClawAvailableVersions(0, 50);
+  const mutations = useKiloClawMutations();
+
+  const [selectedImageTag, setSelectedImageTag] = useState<string>('');
+  const [reason, setReason] = useState('');
+
+  const isPinned = !!myPin;
+  const isLoading = pinLoading || versionsLoading;
+  const isPinning = mutations.setMyPin.isPending;
+  const isUnpinning = mutations.removeMyPin.isPending;
+
+  // Self-pin: pinned_by matches the pin's user_id (the user pinned themselves)
+  // Admin-pin: pinned_by differs from user_id (an admin pinned this user)
+  const pinnedBySelf = myPin && myPin.pinned_by === myPin.user_id;
+  const pinnedByLabel = pinnedBySelf ? 'You' : 'Kilo Admin';
+
+  const handlePin = async () => {
+    if (!selectedImageTag) {
+      toast.error('Please select a version to pin');
+      return;
+    }
+
+    try {
+      await mutations.setMyPin.mutateAsync({
+        imageTag: selectedImageTag,
+        reason: reason.trim() || undefined,
+      });
+      toast.success('Version pinned successfully. Use the "Redeploy or Upgrade" button to apply this version.');
+      setSelectedImageTag('');
+      setReason('');
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Failed to pin version';
+      toast.error(message);
+    }
+  };
+
+  const handleUnpin = async () => {
+    try {
+      await mutations.removeMyPin.mutateAsync();
+      toast.success('Version pin removed. Use the "Redeploy or Upgrade" button to return to the latest version.');
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Failed to remove pin';
+      toast.error(message);
+    }
+  };
+
+  if (isLoading) {
+    return (
+      <div>
+        <h3 className="text-foreground mb-1 text-sm font-medium flex items-center gap-2">
+          <Pin className="size-4" />
+          Version Pinning
+        </h3>
+        <p className="text-muted-foreground text-xs">Loading version information...</p>
+      </div>
+    );
+  }
+
+  const truncateTag = (tag: string) => {
+    if (tag.length <= 20) return tag;
+    return `${tag.slice(0, 8)}...${tag.slice(-8)}`;
+  };
+
+  return (
+    <div>
+        <h3 className="text-foreground mb-1 text-sm font-medium flex items-center gap-2">
+          <Pin className="size-4" />
+          Version Pinning
+        </h3>
+        {/* Description + Current Status */}
+        <div className="mb-6 grid grid-cols-2 items-start gap-6">
+          {/* Left: Description + Info */}
+          <div className="space-y-2">
+            <p className="text-sm text-muted-foreground">
+              Pin your instance to a specific OpenClaw version or follow the latest
+            </p>
+            <div className="flex items-start gap-1 text-xs text-muted-foreground">
+              <Info className="mt-0.5 h-3 w-3 shrink-0" />
+              <span>
+                Pinning locks your instance to a specific version. You won&apos;t receive automatic
+                updates until you unpin.
+              </span>
+            </div>
+          </div>
+
+          {/* Right: Current Status */}
+          <div>
+            <h3 className="mb-2 text-sm font-medium text-muted-foreground">Current Status</h3>
+            {isPinned ? (
+              <div className="space-y-1.5 text-sm">
+                <div>
+                  <span className="text-muted-foreground">Pinned to: </span>
+                  <code className="rounded bg-muted px-1.5 py-0.5 text-xs">
+                    {myPin.openclaw_version} / {myPin.variant}
+                  </code>
+                </div>
+                <div>
+                  <span className="text-muted-foreground">Image tag: </span>
+                  <code className="rounded bg-muted px-1.5 py-0.5 text-xs" title={myPin.image_tag}>
+                    {truncateTag(myPin.image_tag)}
+                  </code>
+                </div>
+                {myPin.reason && (
+                  <div>
+                    <span className="text-muted-foreground">Reason: </span>
+                    <span>{myPin.reason}</span>
+                  </div>
+                )}
+                <div>
+                  <span className="text-muted-foreground">Pinned by: </span>
+                  <span>{pinnedByLabel}</span>
+                </div>
+                <div className="pt-2 space-y-1.5">
+                  <Button
+                    onClick={handleUnpin}
+                    disabled={isUnpinning}
+                    variant="outline"
+                    size="sm"
+                  >
+                    <PinOff className="mr-2 size-4" />
+                    {isUnpinning ? 'Unpinning...' : 'Unpin'}
+                  </Button>
+                  <p className="flex items-start gap-1 text-xs text-muted-foreground">
+                    <Info className="mt-0.5 h-3 w-3 shrink-0" />
+                    <span>
+                      Unpinning returns to following latest. Use the Upgrade button to upgrade your instance.
+                    </span>
+                  </p>
+                </div>
+              </div>
+            ) : (
+              <div className="flex items-center gap-2">
+                <span className="rounded-full bg-green-100 px-2 py-0.5 text-xs font-medium text-green-800 dark:bg-green-900 dark:text-green-100">
+                  Following latest
+                </span>
+                <span className="text-xs text-muted-foreground">
+                  Automatically uses newest version
+                </span>
+              </div>
+            )}
+          </div>
+        </div>
+
+        {/* Row 3: Pin/Unpin Controls */}
+        {!isPinned ? (
+          <div className="grid grid-cols-2 items-start gap-6">
+            {/* Left Column: Version Selector + Reason */}
+            <div className="space-y-3">
+              <div className="space-y-2">
+                <Label htmlFor="version-select" className="text-sm">
+                  Select Version
+                </Label>
+                <Select value={selectedImageTag} onValueChange={setSelectedImageTag}>
+                  <SelectTrigger id="version-select">
+                    <SelectValue placeholder="Choose a version to pin..." />
+                  </SelectTrigger>
+                  <SelectContent>
+                    {versions?.items.map(version => (
+                      <SelectItem key={version.image_tag} value={version.image_tag}>
+                        <div className="flex flex-col">
+                          <span className="font-medium">
+                            {version.openclaw_version} / {version.variant}
+                          </span>
+                          <span className="text-xs text-muted-foreground" title={version.image_tag}>
+                            {truncateTag(version.image_tag)}
+                          </span>
+                        </div>
+                      </SelectItem>
+                    ))}
+                  </SelectContent>
+                </Select>
+              </div>
+              <div className="space-y-2">
+                <Label htmlFor="pin-reason" className="text-sm">
+                  Reason (optional)
+                </Label>
+                <Textarea
+                  id="pin-reason"
+                  placeholder="Why are you pinning to this version?"
+                  value={reason}
+                  onChange={e => setReason(e.target.value)}
+                  rows={3}
+                />
+              </div>
+            </div>
+
+            {/* Right Column: Pin Button */}
+            <div>
+              <Button onClick={handlePin} disabled={!selectedImageTag || isPinning} size="sm">
+                {isPinning ? 'Pinning...' : 'Pin to this version'}
+              </Button>
+            </div>
+          </div>
+        ) : null}
+    </div>
+  );
+}
diff --git a/src/app/admin/components/KiloclawInstances/KiloclawInstanceDetail.tsx b/src/app/admin/components/KiloclawInstances/KiloclawInstanceDetail.tsx
index c4c2e3042..19d9e4915 100644
--- a/src/app/admin/components/KiloclawInstances/KiloclawInstanceDetail.tsx
+++ b/src/app/admin/components/KiloclawInstances/KiloclawInstanceDetail.tsx
@@ -209,77 +209,89 @@ function VersionPinCard({ userId }: { userId: string }) {
               </DetailField>
               {pinData.reason && <DetailField label="Reason">{pinData.reason}</DetailField>}
             </div>
-            <div className="flex items-center gap-2 pt-2">
-              <Select value={selectedTag} onValueChange={setSelectedTag}>
-                <SelectTrigger className="w-[250px]">
-                  <SelectValue placeholder="Change image tag..." />
-                </SelectTrigger>
-                <SelectContent>
-                  {versionsData?.items.map(v => (
-                    <SelectItem key={v.image_tag} value={v.image_tag}>
-                      {v.image_tag} (OpenClaw {v.openclaw_version})
-                    </SelectItem>
-                  ))}
-                </SelectContent>
-              </Select>
-              <Input
-                placeholder="Reason (optional)"
-                value={reason}
-                onChange={e => setReason(e.target.value)}
-                className="w-[200px]"
-              />
-              {selectedTag && (
+            <div className="space-y-2 pt-2">
+              <div className="flex items-center gap-2">
+                <Select value={selectedTag} onValueChange={setSelectedTag}>
+                  <SelectTrigger className="w-[250px]">
+                    <SelectValue placeholder="Change image tag..." />
+                  </SelectTrigger>
+                  <SelectContent>
+                    {versionsData?.items.map(v => (
+                      <SelectItem key={v.image_tag} value={v.image_tag}>
+                        {v.image_tag} (OpenClaw {v.openclaw_version})
+                      </SelectItem>
+                    ))}
+                  </SelectContent>
+                </Select>
+                <Input
+                  placeholder="Reason (optional)"
+                  value={reason}
+                  onChange={e => setReason(e.target.value)}
+                  className="w-[200px]"
+                />
+                {selectedTag && (
+                  <Button
+                    size="sm"
+                    onClick={() =>
+                      void setPin({ userId, imageTag: selectedTag, reason: reason || undefined })
+                    }
+                    disabled={isPinning}
+                  >
+                    {isPinning ? 'Updating...' : 'Update Pin'}
+                  </Button>
+                )}
                 <Button
+                  variant="destructive"
                   size="sm"
-                  onClick={() =>
-                    void setPin({ userId, imageTag: selectedTag, reason: reason || undefined })
-                  }
-                  disabled={isPinning}
+                  onClick={() => void removePin({ userId })}
+                  disabled={isUnpinning}
                 >
-                  {isPinning ? 'Updating...' : 'Update Pin'}
+                  {isUnpinning ? 'Unpinning...' : 'Unpin'}
                 </Button>
-              )}
-              <Button
-                variant="destructive"
-                size="sm"
-                onClick={() => void removePin({ userId })}
-                disabled={isUnpinning}
-              >
-                {isUnpinning ? 'Unpinning...' : 'Unpin'}
-              </Button>
+              </div>
+              <p className="flex items-center gap-1 text-xs text-red-400">
+                <AlertTriangle className="h-3 w-3 shrink-0" />
+                Reason is visible to the end user.
+              </p>
             </div>
           </div>
         ) : (
           <div className="space-y-3">
             <p className="text-muted-foreground text-sm">Following latest available version</p>
-            <div className="flex items-center gap-2">
-              <Select value={selectedTag} onValueChange={setSelectedTag}>
-                <SelectTrigger className="w-[250px]">
-                  <SelectValue placeholder="Select image tag to pin..." />
-                </SelectTrigger>
-                <SelectContent>
-                  {versionsData?.items.map(v => (
-                    <SelectItem key={v.image_tag} value={v.image_tag}>
-                      {v.image_tag} (OpenClaw {v.openclaw_version})
-                    </SelectItem>
-                  ))}
-                </SelectContent>
-              </Select>
-              <Input
-                placeholder="Reason (optional)"
-                value={reason}
-                onChange={e => setReason(e.target.value)}
-                className="w-[200px]"
-              />
-              <Button
-                size="sm"
-                onClick={() =>
-                  void setPin({ userId, imageTag: selectedTag, reason: reason || undefined })
-                }
-                disabled={!selectedTag || isPinning}
-              >
-                {isPinning ? 'Pinning...' : 'Pin Version'}
-              </Button>
+            <div className="space-y-2">
+              <div className="flex items-center gap-2">
+                <Select value={selectedTag} onValueChange={setSelectedTag}>
+                  <SelectTrigger className="w-[250px]">
+                    <SelectValue placeholder="Select image tag to pin..." />
+                  </SelectTrigger>
+                  <SelectContent>
+                    {versionsData?.items.map(v => (
+                      <SelectItem key={v.image_tag} value={v.image_tag}>
+                        {v.image_tag} (OpenClaw {v.openclaw_version})
+                      </SelectItem>
+                    ))}
+                  </SelectContent>
+                </Select>
+                <Input
+                  placeholder="Reason (optional)"
+                  value={reason}
+                  onChange={e => setReason(e.target.value)}
+                  className="w-[200px]"
+                />
+                <Button
+                  size="sm"
+                  onClick={() =>
+                    void setPin({ userId, imageTag: selectedTag, reason: reason || undefined })
+                  }
+                  disabled={!selectedTag || isPinning}
+                >
+                  {isPinning ? 'Pinning...' : 'Pin Version'}
+                </Button>
+              </div>
+              <p className="flex items-center gap-1 text-xs text-red-400">
+                <AlertTriangle className="h-3 w-3 shrink-0" />
+                Reason is visible to the end user.
+              </p>
             </div>
           </div>
         )}
diff --git a/src/app/admin/components/KiloclawVersions/KiloclawVersionsPage.tsx b/src/app/admin/components/KiloclawVersions/KiloclawVersionsPage.tsx
index 3658f0969..a7d0d68e9 100644
--- a/src/app/admin/components/KiloclawVersions/KiloclawVersionsPage.tsx
+++ b/src/app/admin/components/KiloclawVersions/KiloclawVersionsPage.tsx
@@ -319,7 +319,7 @@ export function PinsTab() {
         </CardHeader>
         <CardContent>
           <div className="flex items-end gap-3">
-            <div className="flex-1">
+            <div className="w-[280px] shrink-0">
               <label className="text-muted-foreground mb-1 block text-xs">User</label>
               {selectedUserId ? (
                 <div className="flex items-center gap-2">
@@ -393,13 +393,13 @@ export function PinsTab() {
                 </Popover>
               )}
             </div>
-            <div className="w-[300px]">
+            <div className="w-[300px] shrink-0">
               <label className="text-muted-foreground mb-1 block text-xs">Image Tag</label>
               <Select value={pinImageTag} onValueChange={setPinImageTag}>
-                <SelectTrigger>
+                <SelectTrigger className="w-full">
                   <SelectValue placeholder="Select image tag..." />
                 </SelectTrigger>
-                <SelectContent>
+                <SelectContent className="min-w-[500px]">
                   {availableVersions?.items.map(v => (
                     <SelectItem key={v.image_tag} value={v.image_tag}>
                       {v.image_tag} (OpenClaw {v.openclaw_version})
@@ -408,7 +408,11 @@ export function PinsTab() {
                 </SelectContent>
               </Select>
             </div>
-            <div className="w-[200px]">
+            <div className="flex-1">
+              <p className="flex items-center gap-1 text-xs text-red-400 mb-1">
+                <AlertTriangle className="h-3 w-3 shrink-0" />
+                Reason is visible to the end user.
+              </p>
               <label className="text-muted-foreground mb-1 block text-xs">Reason</label>
               <Input
                 placeholder="Why pin this user?"
diff --git a/src/hooks/useKiloClaw.ts b/src/hooks/useKiloClaw.ts
index dea71d75a..cd72de1d6 100644
--- a/src/hooks/useKiloClaw.ts
+++ b/src/hooks/useKiloClaw.ts
@@ -169,6 +169,26 @@ export function useKiloClawMutations() {
         },
       })
     ),
+    setMyPin: useMutation(
+      trpc.kiloclaw.setMyPin.mutationOptions({
+        onSuccess: async () => {
+          await invalidateStatus();
+          await queryClient.invalidateQueries({
+            queryKey: trpc.kiloclaw.getMyPin.queryKey(),
+          });
+        },
+      })
+    ),
+    removeMyPin: useMutation(
+      trpc.kiloclaw.removeMyPin.mutationOptions({
+        onSuccess: async () => {
+          await invalidateStatus();
+          await queryClient.invalidateQueries({
+            queryKey: trpc.kiloclaw.getMyPin.queryKey(),
+          });
+        },
+      })
+    ),
   };
 }
 
@@ -182,3 +202,22 @@ export function useKiloClawServiceDegraded() {
     })
   );
 }
+
+// User version pinning hooks
+export function useKiloClawAvailableVersions(offset = 0, limit = 25) {
+  const trpc = useTRPC();
+  return useQuery(
+    trpc.kiloclaw.listAvailableVersions.queryOptions({ offset, limit }, {
+      staleTime: 5 * 60_000, // versions don't change frequently
+    })
+  );
+}
+
+export function useKiloClawMyPin() {
+  const trpc = useTRPC();
+  return useQuery(
+    trpc.kiloclaw.getMyPin.queryOptions(undefined, {
+      staleTime: 60_000, // pins don't change frequently
+    })
+  );
+}
diff --git a/src/routers/admin-kiloclaw-versions-router.ts b/src/routers/admin-kiloclaw-versions-router.ts
index 74d32fa5c..7bde4788e 100644
--- a/src/routers/admin-kiloclaw-versions-router.ts
+++ b/src/routers/admin-kiloclaw-versions-router.ts
@@ -74,18 +74,51 @@ export const adminKiloclawVersionsRouter = createTRPCRouter({
     .input(UpdateVersionStatusSchema)
     .mutation(async ({ input, ctx }) => {
       // Prevent disabling the :latest version — it would break all unpinned users.
-      // Note: TOCTOU race exists between fetching latest from KV and the DB update below.
-      // Acceptable because this is an admin-only operation with low concurrent usage.
       if (input.status === 'disabled') {
         const client = new KiloClawInternalClient();
         try {
-          const latestTag = (await client.getLatestVersion())?.imageTag;
-          if (latestTag === input.imageTag) {
+          const latestTagBefore = (await client.getLatestVersion())?.imageTag;
+          if (latestTagBefore === input.imageTag) {
             throw new TRPCError({
               code: 'PRECONDITION_FAILED',
               message: 'Cannot disable the current :latest version. Push a new image first.',
             });
           }
+
+          const [updated] = await db
+            .update(kiloclaw_image_catalog)
+            .set({
+              status: input.status,
+              updated_by: ctx.user.id,
+              updated_at: new Date().toISOString(),
+            })
+            .where(eq(kiloclaw_image_catalog.image_tag, input.imageTag))
+            .returning();
+
+          if (!updated) {
+            throw new TRPCError({ code: 'NOT_FOUND', message: 'Version not found' });
+          }
+
+          // Re-verify after update to catch race condition where :latest changed
+          const latestTagAfter = (await client.getLatestVersion())?.imageTag;
+          if (latestTagAfter === input.imageTag) {
+            // Rollback the disable - this version became :latest during the operation
+            await db
+              .update(kiloclaw_image_catalog)
+              .set({
+                status: 'available',
+                updated_by: ctx.user.id,
+                updated_at: new Date().toISOString(),
+              })
+              .where(eq(kiloclaw_image_catalog.image_tag, input.imageTag));
+
+            throw new TRPCError({
+              code: 'PRECONDITION_FAILED',
+              message: 'This version became :latest during the operation. Cannot disable.',
+            });
+          }
+
+          return updated;
         } catch (err) {
           // If it's already a TRPCError, re-throw it
           if (err instanceof TRPCError) {
@@ -100,6 +133,7 @@ export const adminKiloclawVersionsRouter = createTRPCRouter({
         }
       }
 
+      // For non-disable status changes, no :latest check needed
       const [updated] = await db
         .update(kiloclaw_image_catalog)
         .set({
diff --git a/src/routers/kiloclaw-router.ts b/src/routers/kiloclaw-router.ts
index 52f270d61..f535d3208 100644
--- a/src/routers/kiloclaw-router.ts
+++ b/src/routers/kiloclaw-router.ts
@@ -12,6 +12,10 @@ import {
   STRIPE_KILOCLAW_EARLYBIRD_PRICE_ID,
   STRIPE_KILOCLAW_EARLYBIRD_COUPON_ID,
 } from '@/lib/config.server';
+import { db } from '@/lib/drizzle';
+import { kiloclaw_version_pins, kiloclaw_image_catalog, kilocode_users } from '@kilocode/db/schema';
+import { eq, desc, sql } from 'drizzle-orm';
+import { alias } from 'drizzle-orm/pg-core';
 import { sentryLogger } from '@/lib/utils.server';
 import type { KiloClawDashboardStatus, KiloCodeConfigResponse } from '@/lib/kiloclaw/types';
 import {
@@ -52,7 +56,7 @@ const provisionSchema = z.object({
   envVars: z.record(z.string(), z.string()).optional(),
   secrets: z.record(z.string(), z.string()).optional(),
   channels: channelsSchema,
-  kilocodeDefaultModel: kilocodeDefaultModelSchema,
+  kilocodeDefaultModel: kilocodeDefaultModelSchema.nullable().optional(),
 });
 
 const updateKiloCodeConfigSchema = z.object({
@@ -134,12 +138,15 @@ async function provisionInstance(
   });
   const kilocodeApiKeyExpiresAt = new Date(Date.now() + expiresInSeconds * 1000).toISOString();
 
-  // Check if the user has a version pin
-  const [pin] = await db
-    .select({ image_tag: kiloclaw_version_pins.image_tag })
-    .from(kiloclaw_version_pins)
-    .where(eq(kiloclaw_version_pins.user_id, user.id))
-    .limit(1);
+  // Check if the user has a version pin within a transaction to prevent race conditions
+  const pinnedImageTag = await db.transaction(async (tx) => {
+    const [pin] = await tx
+      .select({ image_tag: kiloclaw_version_pins.image_tag })
+      .from(kiloclaw_version_pins)
+      .where(eq(kiloclaw_version_pins.user_id, user.id))
+      .limit(1);
+    return pin?.image_tag;
+  });
 
   const client = new KiloClawInternalClient();
   return client.provision(user.id, {
@@ -149,7 +156,7 @@ async function provisionInstance(
     kilocodeApiKey,
     kilocodeApiKeyExpiresAt,
     kilocodeDefaultModel: input.kilocodeDefaultModel ?? undefined,
-    pinnedImageTag: pin?.image_tag,
+    pinnedImageTag,
   });
 }
 
@@ -377,6 +384,7 @@ export const kiloclawRouter = createTRPCRouter({
     return client.restoreConfig(ctx.user.id);
   }),
 
+<<<<<<< HEAD
   getEarlybirdStatus: baseProcedure
     .output(z.object({ purchased: z.boolean() }))
     .query(async ({ ctx }) => {
@@ -451,4 +459,156 @@ export const kiloclawRouter = createTRPCRouter({
 
       return { url: typeof session.url === 'string' ? session.url : null };
     }),
+
+  // User version pinning endpoints
+  listAvailableVersions: baseProcedure
+    .input(
+      z.object({
+        offset: z.number().min(0).default(0),
+        limit: z.number().min(1).max(100).default(25),
+      })
+    )
+    .query(async ({ input }) => {
+      const { offset, limit } = input;
+
+      const [items, countResult] = await Promise.all([
+        db
+          .select({
+            openclaw_version: kiloclaw_image_catalog.openclaw_version,
+            variant: kiloclaw_image_catalog.variant,
+            image_tag: kiloclaw_image_catalog.image_tag,
+            description: kiloclaw_image_catalog.description,
+            published_at: kiloclaw_image_catalog.published_at,
+          })
+          .from(kiloclaw_image_catalog)
+          .where(eq(kiloclaw_image_catalog.status, 'available'))
+          .orderBy(desc(kiloclaw_image_catalog.published_at))
+          .offset(offset)
+          .limit(limit),
+        db
+          .select({ count: sql<number>`COUNT(*)::int` })
+          .from(kiloclaw_image_catalog)
+          .where(eq(kiloclaw_image_catalog.status, 'available')),
+      ]);
+
+      const totalCount = countResult[0]?.count ?? 0;
+
+      return {
+        items,
+        pagination: {
+          offset,
+          limit,
+          totalCount,
+          totalPages: Math.ceil(totalCount / limit),
+        },
+      };
+    }),
+
+  getMyPin: baseProcedure.query(async ({ ctx }) => {
+    const pinnedByUser = alias(kilocode_users, 'pinned_by_user');
+    const [result] = await db
+      .select({
+        pin: kiloclaw_version_pins,
+        openclaw_version: kiloclaw_image_catalog.openclaw_version,
+        variant: kiloclaw_image_catalog.variant,
+        pinned_by_email: pinnedByUser.google_user_email,
+      })
+      .from(kiloclaw_version_pins)
+      .leftJoin(
+        kiloclaw_image_catalog,
+        eq(kiloclaw_version_pins.image_tag, kiloclaw_image_catalog.image_tag)
+      )
+      .leftJoin(pinnedByUser, eq(kiloclaw_version_pins.pinned_by, pinnedByUser.id))
+      .where(eq(kiloclaw_version_pins.user_id, ctx.user.id))
+      .limit(1);
+
+    if (!result) return null;
+
+    return {
+      ...result.pin,
+      openclaw_version: result.openclaw_version,
+      variant: result.variant,
+      pinned_by_email: result.pinned_by_email,
+    };
+  }),
+
+  setMyPin: baseProcedure
+    .input(
+      z.object({
+        imageTag: z.string().min(1),
+        reason: z.string().optional(),
+      })
+    )
+    .mutation(async ({ input, ctx }) => {
+      // Verify the version exists and is available
+      const [version] = await db
+        .select()
+        .from(kiloclaw_image_catalog)
+        .where(eq(kiloclaw_image_catalog.image_tag, input.imageTag))
+        .limit(1);
+
+      if (!version) {
+        throw new TRPCError({
+          code: 'NOT_FOUND',
+          message: `Image tag '${input.imageTag}' not found in catalog`,
+        });
+      }
+
+      if (version.status !== 'available') {
+        throw new TRPCError({
+          code: 'BAD_REQUEST',
+          message: `Cannot pin to version with status '${version.status}'. Only 'available' versions can be pinned.`,
+        });
+      }
+
+      let result;
+      try {
+        [result] = await db
+          .insert(kiloclaw_version_pins)
+          .values({
+            user_id: ctx.user.id,
+            image_tag: input.imageTag,
+            pinned_by: ctx.user.id, // User is pinning themselves
+            reason: input.reason ?? null,
+          })
+          .onConflictDoUpdate({
+            target: kiloclaw_version_pins.user_id,
+            set: {
+              image_tag: input.imageTag,
+              pinned_by: ctx.user.id,
+              reason: input.reason ?? null,
+              updated_at: new Date().toISOString(),
+            },
+          })
+          .returning();
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : '';
+        if (msg.includes('foreign key')) {
+          throw new TRPCError({
+            code: 'BAD_REQUEST',
+            message: `Image tag '${input.imageTag}' not found in catalog`,
+          });
+        }
+        throw err;
+      }
+
+      if (!result) {
+        throw new TRPCError({ code: 'INTERNAL_SERVER_ERROR', message: 'Failed to create pin' });
+      }
+
+      return result;
+    }),
+
+  removeMyPin: baseProcedure.mutation(async ({ ctx }) => {
+    const [deleted] = await db
+      .delete(kiloclaw_version_pins)
+      .where(eq(kiloclaw_version_pins.user_id, ctx.user.id))
+      .returning();
+
+    if (!deleted) {
+      throw new TRPCError({ code: 'NOT_FOUND', message: 'No pin found for your account' });
+    }
+
+    return { success: true };
+  }),
 });
diff --git a/src/routers/kiloclaw-user-versions-router.test.ts b/src/routers/kiloclaw-user-versions-router.test.ts
new file mode 100644
index 000000000..053eccf81
--- /dev/null
+++ b/src/routers/kiloclaw-user-versions-router.test.ts
@@ -0,0 +1,271 @@
+/* eslint-disable drizzle/enforce-delete-with-where */
+import { createCallerForUser } from '@/routers/test-utils';
+import { insertTestUser } from '@/tests/helpers/user.helper';
+import type { User } from '@kilocode/db/schema';
+import { db } from '@/lib/drizzle';
+import { kiloclaw_image_catalog, kiloclaw_version_pins } from '@kilocode/db/schema';
+import { eq } from 'drizzle-orm';
+
+let userA: User;
+let userB: User;
+
+const availableVersion = {
+  openclaw_version: '2026.2.9',
+  variant: 'default',
+  image_tag: 'registry.fly.io/kiloclaw:test-available',
+  image_digest: 'sha256:abc123',
+  status: 'available' as const,
+  published_at: new Date().toISOString(),
+};
+
+const disabledVersion = {
+  openclaw_version: '2026.2.8',
+  variant: 'default',
+  image_tag: 'registry.fly.io/kiloclaw:test-disabled',
+  image_digest: 'sha256:def456',
+  status: 'disabled' as const,
+  published_at: new Date(Date.now() - 86400000).toISOString(), // 1 day ago
+};
+
+beforeAll(async () => {
+  userA = await insertTestUser({
+    google_user_email: 'user-a-kiloclaw-pin@example.com',
+    is_admin: false,
+  });
+  userB = await insertTestUser({
+    google_user_email: 'user-b-kiloclaw-pin@example.com',
+    is_admin: false,
+  });
+
+  await db.insert(kiloclaw_image_catalog).values([availableVersion, disabledVersion]);
+});
+
+afterAll(async () => {
+  try {
+    await db.delete(kiloclaw_version_pins);
+    await db
+      .delete(kiloclaw_image_catalog)
+      .where(eq(kiloclaw_image_catalog.image_tag, availableVersion.image_tag));
+    await db
+      .delete(kiloclaw_image_catalog)
+      .where(eq(kiloclaw_image_catalog.image_tag, disabledVersion.image_tag));
+  } catch {
+    // Test DB may already be torn down by framework
+  }
+});
+
+describe('kiloclaw.listAvailableVersions', () => {
+  it('returns only available versions', async () => {
+    const caller = await createCallerForUser(userA.id);
+    const result = await caller.kiloclaw.listAvailableVersions({});
+
+    expect(result.items.length).toBeGreaterThanOrEqual(1);
+    for (const item of result.items) {
+      // Disabled versions should not be in the list
+      expect(item.image_tag).not.toBe(disabledVersion.image_tag);
+    }
+
+    // Available version should be in the list
+    const hasAvailable = result.items.some(
+      item => item.image_tag === availableVersion.image_tag
+    );
+    expect(hasAvailable).toBe(true);
+  });
+
+  it('returns pagination metadata', async () => {
+    const caller = await createCallerForUser(userA.id);
+    const result = await caller.kiloclaw.listAvailableVersions({ limit: 10 });
+
+    expect(result.pagination).toHaveProperty('offset');
+    expect(result.pagination).toHaveProperty('limit');
+    expect(result.pagination).toHaveProperty('totalCount');
+    expect(result.pagination).toHaveProperty('totalPages');
+  });
+});
+
+describe('kiloclaw.getMyPin', () => {
+  it('returns null when user has no pin', async () => {
+    const caller = await createCallerForUser(userA.id);
+    const result = await caller.kiloclaw.getMyPin();
+
+    expect(result).toBeNull();
+  });
+
+  it('returns pin details when user has a pin', async () => {
+    // Create a pin for userB
+    await db.insert(kiloclaw_version_pins).values({
+      user_id: userB.id,
+      image_tag: availableVersion.image_tag,
+      pinned_by: userB.id,
+      reason: 'Testing',
+    });
+
+    const caller = await createCallerForUser(userB.id);
+    const result = await caller.kiloclaw.getMyPin();
+
+    expect(result).not.toBeNull();
+    expect(result?.image_tag).toBe(availableVersion.image_tag);
+    expect(result?.reason).toBe('Testing');
+    expect(result?.openclaw_version).toBe(availableVersion.openclaw_version);
+    expect(result?.variant).toBe(availableVersion.variant);
+
+    // Cleanup
+    await db.delete(kiloclaw_version_pins).where(eq(kiloclaw_version_pins.user_id, userB.id));
+  });
+});
+
+describe('kiloclaw.setMyPin', () => {
+  afterEach(async () => {
+    // Cleanup pins after each test
+    await db.delete(kiloclaw_version_pins).where(eq(kiloclaw_version_pins.user_id, userA.id));
+  });
+
+  it('creates a new pin for the user', async () => {
+    const caller = await createCallerForUser(userA.id);
+    const result = await caller.kiloclaw.setMyPin({
+      imageTag: availableVersion.image_tag,
+      reason: 'Testing new pin',
+    });
+
+    expect(result.user_id).toBe(userA.id);
+    expect(result.image_tag).toBe(availableVersion.image_tag);
+    expect(result.pinned_by).toBe(userA.id); // User pins themselves
+    expect(result.reason).toBe('Testing new pin');
+  });
+
+  it('updates existing pin when called again', async () => {
+    const caller = await createCallerForUser(userA.id);
+
+    // Create initial pin
+    await caller.kiloclaw.setMyPin({
+      imageTag: availableVersion.image_tag,
+      reason: 'Initial reason',
+    });
+
+    // Update pin (this should be an upsert)
+    const result = await caller.kiloclaw.setMyPin({
+      imageTag: availableVersion.image_tag,
+      reason: 'Updated reason',
+    });
+
+    expect(result.reason).toBe('Updated reason');
+
+    // Verify only one pin exists
+    const pins = await db
+      .select()
+      .from(kiloclaw_version_pins)
+      .where(eq(kiloclaw_version_pins.user_id, userA.id));
+    expect(pins.length).toBe(1);
+  });
+
+  it('throws error when pinning to non-existent version', async () => {
+    const caller = await createCallerForUser(userA.id);
+
+    await expect(
+      caller.kiloclaw.setMyPin({
+        imageTag: 'registry.fly.io/kiloclaw:non-existent',
+      })
+    ).rejects.toThrow('not found in catalog');
+  });
+
+  it('throws error when pinning to disabled version', async () => {
+    const caller = await createCallerForUser(userA.id);
+
+    await expect(
+      caller.kiloclaw.setMyPin({
+        imageTag: disabledVersion.image_tag,
+      })
+    ).rejects.toThrow("Cannot pin to version with status 'disabled'");
+  });
+
+  it('allows pinning without a reason', async () => {
+    const caller = await createCallerForUser(userA.id);
+    const result = await caller.kiloclaw.setMyPin({
+      imageTag: availableVersion.image_tag,
+    });
+
+    expect(result.reason).toBeNull();
+  });
+});
+
+describe('kiloclaw.removeMyPin', () => {
+  it('removes the user pin', async () => {
+    // Create a pin first
+    await db.insert(kiloclaw_version_pins).values({
+      user_id: userA.id,
+      image_tag: availableVersion.image_tag,
+      pinned_by: userA.id,
+    });
+
+    const caller = await createCallerForUser(userA.id);
+    const result = await caller.kiloclaw.removeMyPin();
+
+    expect(result.success).toBe(true);
+
+    // Verify pin is deleted
+    const pins = await db
+      .select()
+      .from(kiloclaw_version_pins)
+      .where(eq(kiloclaw_version_pins.user_id, userA.id));
+    expect(pins.length).toBe(0);
+  });
+
+  it('throws error when no pin exists', async () => {
+    const caller = await createCallerForUser(userA.id);
+
+    await expect(caller.kiloclaw.removeMyPin()).rejects.toThrow('No pin found for your account');
+  });
+});
+
+describe('Authorization', () => {
+  beforeEach(async () => {
+    // Create pins for both users
+    await db.insert(kiloclaw_version_pins).values([
+      {
+        user_id: userA.id,
+        image_tag: availableVersion.image_tag,
+        pinned_by: userA.id,
+      },
+      {
+        user_id: userB.id,
+        image_tag: availableVersion.image_tag,
+        pinned_by: userB.id,
+      },
+    ]);
+  });
+
+  afterEach(async () => {
+    await db.delete(kiloclaw_version_pins);
+  });
+
+  it('getMyPin only returns the current user pin', async () => {
+    const callerA = await createCallerForUser(userA.id);
+    const resultA = await callerA.kiloclaw.getMyPin();
+
+    expect(resultA?.user_id).toBe(userA.id);
+
+    const callerB = await createCallerForUser(userB.id);
+    const resultB = await callerB.kiloclaw.getMyPin();
+
+    expect(resultB?.user_id).toBe(userB.id);
+  });
+
+  it('removeMyPin only removes the current user pin', async () => {
+    const callerA = await createCallerForUser(userA.id);
+    await callerA.kiloclaw.removeMyPin();
+
+    // UserA's pin should be deleted
+    const pinsA = await db
+      .select()
+      .from(kiloclaw_version_pins)
+      .where(eq(kiloclaw_version_pins.user_id, userA.id));
+    expect(pinsA.length).toBe(0);
+
+    // UserB's pin should still exist
+    const pinsB = await db
+      .select()
+      .from(kiloclaw_version_pins)
+      .where(eq(kiloclaw_version_pins.user_id, userB.id));
+    expect(pinsB.length).toBe(1);
+  });
+});

From 31db04a76fa7bec51d409027c44d63acf7f6d12f Mon Sep 17 00:00:00 2001
From: St0rmz1 <astorms@replicated.com>
Date: Tue, 3 Mar 2026 14:03:13 -0800
Subject: [PATCH 2/4] fix: address kilo-bot review findings

---
 .../(app)/claw/components/VersionPinCard.tsx  |  2 +-
 src/routers/admin-kiloclaw-versions-router.ts | 24 +++++++++++------
 src/routers/kiloclaw-router.ts                | 27 +++++++++----------
 3 files changed, 29 insertions(+), 24 deletions(-)

diff --git a/src/app/(app)/claw/components/VersionPinCard.tsx b/src/app/(app)/claw/components/VersionPinCard.tsx
index f55d148d6..13d3743cb 100644
--- a/src/app/(app)/claw/components/VersionPinCard.tsx
+++ b/src/app/(app)/claw/components/VersionPinCard.tsx
@@ -110,7 +110,7 @@ export function VersionPinCard() {
                 <div>
                   <span className="text-muted-foreground">Pinned to: </span>
                   <code className="rounded bg-muted px-1.5 py-0.5 text-xs">
-                    {myPin.openclaw_version} / {myPin.variant}
+                    {myPin.openclaw_version ?? 'Unknown'} / {myPin.variant ?? 'Unknown'}
                   </code>
                 </div>
                 <div>
diff --git a/src/routers/admin-kiloclaw-versions-router.ts b/src/routers/admin-kiloclaw-versions-router.ts
index 7bde4788e..731e46d8b 100644
--- a/src/routers/admin-kiloclaw-versions-router.ts
+++ b/src/routers/admin-kiloclaw-versions-router.ts
@@ -103,14 +103,22 @@ export const adminKiloclawVersionsRouter = createTRPCRouter({
           const latestTagAfter = (await client.getLatestVersion())?.imageTag;
           if (latestTagAfter === input.imageTag) {
             // Rollback the disable - this version became :latest during the operation
-            await db
-              .update(kiloclaw_image_catalog)
-              .set({
-                status: 'available',
-                updated_by: ctx.user.id,
-                updated_at: new Date().toISOString(),
-              })
-              .where(eq(kiloclaw_image_catalog.image_tag, input.imageTag));
+            try {
+              await db
+                .update(kiloclaw_image_catalog)
+                .set({
+                  status: 'available',
+                  updated_by: ctx.user.id,
+                  updated_at: new Date().toISOString(),
+                })
+                .where(eq(kiloclaw_image_catalog.image_tag, input.imageTag));
+            } catch (rollbackErr) {
+              console.error(
+                `Failed to rollback disable for ${input.imageTag}:`,
+                rollbackErr instanceof Error ? rollbackErr.message : rollbackErr
+              );
+              // Still throw the precondition error so the caller knows the operation failed
+            }
 
             throw new TRPCError({
               code: 'PRECONDITION_FAILED',
diff --git a/src/routers/kiloclaw-router.ts b/src/routers/kiloclaw-router.ts
index f535d3208..913670cce 100644
--- a/src/routers/kiloclaw-router.ts
+++ b/src/routers/kiloclaw-router.ts
@@ -13,7 +13,7 @@ import {
   STRIPE_KILOCLAW_EARLYBIRD_COUPON_ID,
 } from '@/lib/config.server';
 import { db } from '@/lib/drizzle';
-import { kiloclaw_version_pins, kiloclaw_image_catalog, kilocode_users } from '@kilocode/db/schema';
+import { kiloclaw_version_pins, kiloclaw_image_catalog, kilocode_users, kiloclaw_earlybird_purchases } from '@kilocode/db/schema';
 import { eq, desc, sql } from 'drizzle-orm';
 import { alias } from 'drizzle-orm/pg-core';
 import { sentryLogger } from '@/lib/utils.server';
@@ -25,9 +25,6 @@ import {
 } from '@/lib/kiloclaw/instance-registry';
 import { client as stripe } from '@/lib/stripe-client';
 import { APP_URL } from '@/lib/constants';
-import { db } from '@/lib/drizzle';
-import { kiloclaw_earlybird_purchases, kiloclaw_version_pins } from '@kilocode/db/schema';
-import { eq } from 'drizzle-orm';
 
 const kilocodeDefaultModelSchema = z
   .string()
@@ -138,15 +135,13 @@ async function provisionInstance(
   });
   const kilocodeApiKeyExpiresAt = new Date(Date.now() + expiresInSeconds * 1000).toISOString();
 
-  // Check if the user has a version pin within a transaction to prevent race conditions
-  const pinnedImageTag = await db.transaction(async (tx) => {
-    const [pin] = await tx
-      .select({ image_tag: kiloclaw_version_pins.image_tag })
-      .from(kiloclaw_version_pins)
-      .where(eq(kiloclaw_version_pins.user_id, user.id))
-      .limit(1);
-    return pin?.image_tag;
-  });
+  // Check if the user has a version pin
+  const [pin] = await db
+    .select({ image_tag: kiloclaw_version_pins.image_tag })
+    .from(kiloclaw_version_pins)
+    .where(eq(kiloclaw_version_pins.user_id, user.id))
+    .limit(1);
+  const pinnedImageTag = pin?.image_tag;
 
   const client = new KiloClawInternalClient();
   return client.provision(user.id, {
@@ -384,7 +379,6 @@ export const kiloclawRouter = createTRPCRouter({
     return client.restoreConfig(ctx.user.id);
   }),
 
-<<<<<<< HEAD
   getEarlybirdStatus: baseProcedure
     .output(z.object({ purchased: z.boolean() }))
     .query(async ({ ctx }) => {
@@ -536,11 +530,14 @@ export const kiloclawRouter = createTRPCRouter({
     .input(
       z.object({
         imageTag: z.string().min(1),
-        reason: z.string().optional(),
+        reason: z.string().max(500).optional(),
       })
     )
     .mutation(async ({ input, ctx }) => {
       // Verify the version exists and is available
+      // Note: There is a small TOCTOU window between this check and the insert below.
+      // Worst case: a user pins to a version disabled milliseconds before. The FK constraint
+      // on image_tag ensures referential integrity, and the status check is best-effort.
       const [version] = await db
         .select()
         .from(kiloclaw_image_catalog)

From c7a04f5f212f0eaedef1d743eb5ba086f967c227 Mon Sep 17 00:00:00 2001
From: St0rmz1 <astorms@replicated.com>
Date: Tue, 3 Mar 2026 14:14:18 -0800
Subject: [PATCH 3/4] fix: address kilo-bot review findings

---
 .../(app)/claw/components/VersionPinCard.tsx  | 259 ++++++++++--------
 .../KiloclawVersions/KiloclawVersionsPage.tsx |   2 +-
 src/hooks/useKiloClaw.ts                      |   9 +-
 src/routers/kiloclaw-router.ts                |  41 ++-
 .../kiloclaw-user-versions-router.test.ts     |   4 +-
 5 files changed, 183 insertions(+), 132 deletions(-)

diff --git a/src/app/(app)/claw/components/VersionPinCard.tsx b/src/app/(app)/claw/components/VersionPinCard.tsx
index 13d3743cb..f0f8b832e 100644
--- a/src/app/(app)/claw/components/VersionPinCard.tsx
+++ b/src/app/(app)/claw/components/VersionPinCard.tsx
@@ -3,7 +3,11 @@
 import { useState } from 'react';
 import { Pin, PinOff, Info } from 'lucide-react';
 import { toast } from 'sonner';
-import { useKiloClawAvailableVersions, useKiloClawMyPin, useKiloClawMutations } from '@/hooks/useKiloClaw';
+import {
+  useKiloClawAvailableVersions,
+  useKiloClawMyPin,
+  useKiloClawMutations,
+} from '@/hooks/useKiloClaw';
 import { Button } from '@/components/ui/button';
 import {
   Select,
@@ -44,7 +48,9 @@ export function VersionPinCard() {
         imageTag: selectedImageTag,
         reason: reason.trim() || undefined,
       });
-      toast.success('Version pinned successfully. Use the "Redeploy or Upgrade" button to apply this version.');
+      toast.success(
+        'Version pinned successfully. Use the "Redeploy or Upgrade" button to apply this version.'
+      );
       setSelectedImageTag('');
       setReason('');
     } catch (error) {
@@ -56,7 +62,9 @@ export function VersionPinCard() {
   const handleUnpin = async () => {
     try {
       await mutations.removeMyPin.mutateAsync();
-      toast.success('Version pin removed. Use the "Redeploy or Upgrade" button to return to the latest version.');
+      toast.success(
+        'Version pin removed. Use the "Redeploy or Upgrade" button to return to the latest version.'
+      );
     } catch (error) {
       const message = error instanceof Error ? error.message : 'Failed to remove pin';
       toast.error(message);
@@ -66,7 +74,7 @@ export function VersionPinCard() {
   if (isLoading) {
     return (
       <div>
-        <h3 className="text-foreground mb-1 text-sm font-medium flex items-center gap-2">
+        <h3 className="text-foreground mb-1 flex items-center gap-2 text-sm font-medium">
           <Pin className="size-4" />
           Version Pinning
         </h3>
@@ -82,135 +90,148 @@ export function VersionPinCard() {
 
   return (
     <div>
-        <h3 className="text-foreground mb-1 text-sm font-medium flex items-center gap-2">
-          <Pin className="size-4" />
-          Version Pinning
-        </h3>
-        {/* Description + Current Status */}
-        <div className="mb-6 grid grid-cols-2 items-start gap-6">
-          {/* Left: Description + Info */}
-          <div className="space-y-2">
-            <p className="text-sm text-muted-foreground">
-              Pin your instance to a specific OpenClaw version or follow the latest
-            </p>
-            <div className="flex items-start gap-1 text-xs text-muted-foreground">
-              <Info className="mt-0.5 h-3 w-3 shrink-0" />
-              <span>
-                Pinning locks your instance to a specific version. You won&apos;t receive automatic
-                updates until you unpin.
-              </span>
-            </div>
+      <h3 className="text-foreground mb-1 flex items-center gap-2 text-sm font-medium">
+        <Pin className="size-4" />
+        Version Pinning
+      </h3>
+      {/* Description + Current Status */}
+      <div className="mb-6 grid grid-cols-2 items-start gap-6">
+        {/* Left: Description + Info */}
+        <div className="space-y-2">
+          <p className="text-muted-foreground text-sm">
+            Pin your instance to a specific OpenClaw version or follow the latest
+          </p>
+          <div className="text-muted-foreground flex items-start gap-1 text-xs">
+            <Info className="mt-0.5 h-3 w-3 shrink-0" />
+            <span>
+              Pinning locks your instance to a specific version. You won&apos;t receive automatic
+              updates until you unpin.
+            </span>
           </div>
+        </div>
 
-          {/* Right: Current Status */}
-          <div>
-            <h3 className="mb-2 text-sm font-medium text-muted-foreground">Current Status</h3>
-            {isPinned ? (
-              <div className="space-y-1.5 text-sm">
-                <div>
-                  <span className="text-muted-foreground">Pinned to: </span>
-                  <code className="rounded bg-muted px-1.5 py-0.5 text-xs">
-                    {myPin.openclaw_version ?? 'Unknown'} / {myPin.variant ?? 'Unknown'}
-                  </code>
-                </div>
-                <div>
-                  <span className="text-muted-foreground">Image tag: </span>
-                  <code className="rounded bg-muted px-1.5 py-0.5 text-xs" title={myPin.image_tag}>
-                    {truncateTag(myPin.image_tag)}
-                  </code>
-                </div>
-                {myPin.reason && (
-                  <div>
-                    <span className="text-muted-foreground">Reason: </span>
-                    <span>{myPin.reason}</span>
-                  </div>
-                )}
+        {/* Right: Current Status */}
+        <div>
+          <h3 className="text-muted-foreground mb-2 text-sm font-medium">Current Status</h3>
+          {isPinned ? (
+            <div className="space-y-1.5 text-sm">
+              <div>
+                <span className="text-muted-foreground">Pinned to: </span>
+                <code className="bg-muted rounded px-1.5 py-0.5 text-xs">
+                  {myPin.openclaw_version ?? 'Unknown'} / {myPin.variant ?? 'Unknown'}
+                </code>
+              </div>
+              <div>
+                <span className="text-muted-foreground">Image tag: </span>
+                <code className="bg-muted rounded px-1.5 py-0.5 text-xs" title={myPin.image_tag}>
+                  {truncateTag(myPin.image_tag)}
+                </code>
+              </div>
+              {myPin.reason && (
                 <div>
-                  <span className="text-muted-foreground">Pinned by: </span>
-                  <span>{pinnedByLabel}</span>
+                  <span className="text-muted-foreground">Reason: </span>
+                  <span>{myPin.reason}</span>
                 </div>
-                <div className="pt-2 space-y-1.5">
-                  <Button
-                    onClick={handleUnpin}
-                    disabled={isUnpinning}
-                    variant="outline"
-                    size="sm"
-                  >
-                    <PinOff className="mr-2 size-4" />
-                    {isUnpinning ? 'Unpinning...' : 'Unpin'}
-                  </Button>
-                  <p className="flex items-start gap-1 text-xs text-muted-foreground">
+              )}
+              <div>
+                <span className="text-muted-foreground">Pinned by: </span>
+                <span>{pinnedByLabel}</span>
+              </div>
+              <div className="space-y-1.5 pt-2">
+                {pinnedBySelf ? (
+                  <>
+                    <Button
+                      onClick={handleUnpin}
+                      disabled={isUnpinning}
+                      variant="outline"
+                      size="sm"
+                    >
+                      <PinOff className="mr-2 size-4" />
+                      {isUnpinning ? 'Unpinning...' : 'Unpin'}
+                    </Button>
+                    <p className="text-muted-foreground flex items-start gap-1 text-xs">
+                      <Info className="mt-0.5 h-3 w-3 shrink-0" />
+                      <span>
+                        Unpinning returns to following latest. Use the Upgrade button to upgrade
+                        your instance.
+                      </span>
+                    </p>
+                  </>
+                ) : (
+                  <p className="text-muted-foreground flex items-start gap-1 text-xs">
                     <Info className="mt-0.5 h-3 w-3 shrink-0" />
                     <span>
-                      Unpinning returns to following latest. Use the Upgrade button to upgrade your instance.
+                      This pin was set by a Kilo admin. Contact your admin to change or remove it.
                     </span>
                   </p>
-                </div>
-              </div>
-            ) : (
-              <div className="flex items-center gap-2">
-                <span className="rounded-full bg-green-100 px-2 py-0.5 text-xs font-medium text-green-800 dark:bg-green-900 dark:text-green-100">
-                  Following latest
-                </span>
-                <span className="text-xs text-muted-foreground">
-                  Automatically uses newest version
-                </span>
+                )}
               </div>
-            )}
-          </div>
+            </div>
+          ) : (
+            <div className="flex items-center gap-2">
+              <span className="rounded-full bg-green-100 px-2 py-0.5 text-xs font-medium text-green-800 dark:bg-green-900 dark:text-green-100">
+                Following latest
+              </span>
+              <span className="text-muted-foreground text-xs">
+                Automatically uses newest version
+              </span>
+            </div>
+          )}
         </div>
+      </div>
 
-        {/* Row 3: Pin/Unpin Controls */}
-        {!isPinned ? (
-          <div className="grid grid-cols-2 items-start gap-6">
-            {/* Left Column: Version Selector + Reason */}
-            <div className="space-y-3">
-              <div className="space-y-2">
-                <Label htmlFor="version-select" className="text-sm">
-                  Select Version
-                </Label>
-                <Select value={selectedImageTag} onValueChange={setSelectedImageTag}>
-                  <SelectTrigger id="version-select">
-                    <SelectValue placeholder="Choose a version to pin..." />
-                  </SelectTrigger>
-                  <SelectContent>
-                    {versions?.items.map(version => (
-                      <SelectItem key={version.image_tag} value={version.image_tag}>
-                        <div className="flex flex-col">
-                          <span className="font-medium">
-                            {version.openclaw_version} / {version.variant}
-                          </span>
-                          <span className="text-xs text-muted-foreground" title={version.image_tag}>
-                            {truncateTag(version.image_tag)}
-                          </span>
-                        </div>
-                      </SelectItem>
-                    ))}
-                  </SelectContent>
-                </Select>
-              </div>
-              <div className="space-y-2">
-                <Label htmlFor="pin-reason" className="text-sm">
-                  Reason (optional)
-                </Label>
-                <Textarea
-                  id="pin-reason"
-                  placeholder="Why are you pinning to this version?"
-                  value={reason}
-                  onChange={e => setReason(e.target.value)}
-                  rows={3}
-                />
-              </div>
+      {/* Row 3: Pin/Unpin Controls */}
+      {!isPinned ? (
+        <div className="grid grid-cols-2 items-start gap-6">
+          {/* Left Column: Version Selector + Reason */}
+          <div className="space-y-3">
+            <div className="space-y-2">
+              <Label htmlFor="version-select" className="text-sm">
+                Select Version
+              </Label>
+              <Select value={selectedImageTag} onValueChange={setSelectedImageTag}>
+                <SelectTrigger id="version-select">
+                  <SelectValue placeholder="Choose a version to pin..." />
+                </SelectTrigger>
+                <SelectContent>
+                  {versions?.items.map(version => (
+                    <SelectItem key={version.image_tag} value={version.image_tag}>
+                      <div className="flex flex-col">
+                        <span className="font-medium">
+                          {version.openclaw_version} / {version.variant}
+                        </span>
+                        <span className="text-muted-foreground text-xs" title={version.image_tag}>
+                          {truncateTag(version.image_tag)}
+                        </span>
+                      </div>
+                    </SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
             </div>
-
-            {/* Right Column: Pin Button */}
-            <div>
-              <Button onClick={handlePin} disabled={!selectedImageTag || isPinning} size="sm">
-                {isPinning ? 'Pinning...' : 'Pin to this version'}
-              </Button>
+            <div className="space-y-2">
+              <Label htmlFor="pin-reason" className="text-sm">
+                Reason (optional)
+              </Label>
+              <Textarea
+                id="pin-reason"
+                placeholder="Why are you pinning to this version?"
+                value={reason}
+                onChange={e => setReason(e.target.value)}
+                rows={3}
+                maxLength={500}
+              />
             </div>
           </div>
-        ) : null}
+
+          {/* Right Column: Pin Button */}
+          <div>
+            <Button onClick={handlePin} disabled={!selectedImageTag || isPinning} size="sm">
+              {isPinning ? 'Pinning...' : 'Pin to this version'}
+            </Button>
+          </div>
+        </div>
+      ) : null}
     </div>
   );
 }
diff --git a/src/app/admin/components/KiloclawVersions/KiloclawVersionsPage.tsx b/src/app/admin/components/KiloclawVersions/KiloclawVersionsPage.tsx
index a7d0d68e9..f975cd9a6 100644
--- a/src/app/admin/components/KiloclawVersions/KiloclawVersionsPage.tsx
+++ b/src/app/admin/components/KiloclawVersions/KiloclawVersionsPage.tsx
@@ -409,7 +409,7 @@ export function PinsTab() {
               </Select>
             </div>
             <div className="flex-1">
-              <p className="flex items-center gap-1 text-xs text-red-400 mb-1">
+              <p className="mb-1 flex items-center gap-1 text-xs text-red-400">
                 <AlertTriangle className="h-3 w-3 shrink-0" />
                 Reason is visible to the end user.
               </p>
diff --git a/src/hooks/useKiloClaw.ts b/src/hooks/useKiloClaw.ts
index cd72de1d6..0099aad29 100644
--- a/src/hooks/useKiloClaw.ts
+++ b/src/hooks/useKiloClaw.ts
@@ -207,9 +207,12 @@ export function useKiloClawServiceDegraded() {
 export function useKiloClawAvailableVersions(offset = 0, limit = 25) {
   const trpc = useTRPC();
   return useQuery(
-    trpc.kiloclaw.listAvailableVersions.queryOptions({ offset, limit }, {
-      staleTime: 5 * 60_000, // versions don't change frequently
-    })
+    trpc.kiloclaw.listAvailableVersions.queryOptions(
+      { offset, limit },
+      {
+        staleTime: 5 * 60_000, // versions don't change frequently
+      }
+    )
   );
 }
 
diff --git a/src/routers/kiloclaw-router.ts b/src/routers/kiloclaw-router.ts
index 913670cce..51e1a92c2 100644
--- a/src/routers/kiloclaw-router.ts
+++ b/src/routers/kiloclaw-router.ts
@@ -13,9 +13,12 @@ import {
   STRIPE_KILOCLAW_EARLYBIRD_COUPON_ID,
 } from '@/lib/config.server';
 import { db } from '@/lib/drizzle';
-import { kiloclaw_version_pins, kiloclaw_image_catalog, kilocode_users, kiloclaw_earlybird_purchases } from '@kilocode/db/schema';
+import {
+  kiloclaw_version_pins,
+  kiloclaw_image_catalog,
+  kiloclaw_earlybird_purchases,
+} from '@kilocode/db/schema';
 import { eq, desc, sql } from 'drizzle-orm';
-import { alias } from 'drizzle-orm/pg-core';
 import { sentryLogger } from '@/lib/utils.server';
 import type { KiloClawDashboardStatus, KiloCodeConfigResponse } from '@/lib/kiloclaw/types';
 import {
@@ -499,20 +502,18 @@ export const kiloclawRouter = createTRPCRouter({
     }),
 
   getMyPin: baseProcedure.query(async ({ ctx }) => {
-    const pinnedByUser = alias(kilocode_users, 'pinned_by_user');
     const [result] = await db
       .select({
         pin: kiloclaw_version_pins,
         openclaw_version: kiloclaw_image_catalog.openclaw_version,
         variant: kiloclaw_image_catalog.variant,
-        pinned_by_email: pinnedByUser.google_user_email,
       })
       .from(kiloclaw_version_pins)
       .leftJoin(
         kiloclaw_image_catalog,
         eq(kiloclaw_version_pins.image_tag, kiloclaw_image_catalog.image_tag)
       )
-      .leftJoin(pinnedByUser, eq(kiloclaw_version_pins.pinned_by, pinnedByUser.id))
+      // Intentionally not joining pinned_by user — avoid leaking admin email to end users
       .where(eq(kiloclaw_version_pins.user_id, ctx.user.id))
       .limit(1);
 
@@ -522,7 +523,6 @@ export const kiloclawRouter = createTRPCRouter({
       ...result.pin,
       openclaw_version: result.openclaw_version,
       variant: result.variant,
-      pinned_by_email: result.pinned_by_email,
     };
   }),
 
@@ -558,6 +558,21 @@ export const kiloclawRouter = createTRPCRouter({
         });
       }
 
+      // Prevent users from overwriting admin-set pins
+      const [existingPin] = await db
+        .select({ pinned_by: kiloclaw_version_pins.pinned_by })
+        .from(kiloclaw_version_pins)
+        .where(eq(kiloclaw_version_pins.user_id, ctx.user.id))
+        .limit(1);
+
+      if (existingPin && existingPin.pinned_by !== ctx.user.id) {
+        throw new TRPCError({
+          code: 'FORBIDDEN',
+          message:
+            'Your version is pinned by an admin. Contact your Kilo admin to change or remove the pin.',
+        });
+      }
+
       let result;
       try {
         [result] = await db
@@ -597,6 +612,20 @@ export const kiloclawRouter = createTRPCRouter({
     }),
 
   removeMyPin: baseProcedure.mutation(async ({ ctx }) => {
+    // Check if the pin was set by an admin — users cannot remove admin-set pins
+    const [existingPin] = await db
+      .select({ pinned_by: kiloclaw_version_pins.pinned_by })
+      .from(kiloclaw_version_pins)
+      .where(eq(kiloclaw_version_pins.user_id, ctx.user.id))
+      .limit(1);
+
+    if (existingPin && existingPin.pinned_by !== ctx.user.id) {
+      throw new TRPCError({
+        code: 'FORBIDDEN',
+        message: 'Your version is pinned by an admin. Contact your Kilo admin to remove the pin.',
+      });
+    }
+
     const [deleted] = await db
       .delete(kiloclaw_version_pins)
       .where(eq(kiloclaw_version_pins.user_id, ctx.user.id))
diff --git a/src/routers/kiloclaw-user-versions-router.test.ts b/src/routers/kiloclaw-user-versions-router.test.ts
index 053eccf81..8d681a39b 100644
--- a/src/routers/kiloclaw-user-versions-router.test.ts
+++ b/src/routers/kiloclaw-user-versions-router.test.ts
@@ -66,9 +66,7 @@ describe('kiloclaw.listAvailableVersions', () => {
     }
 
     // Available version should be in the list
-    const hasAvailable = result.items.some(
-      item => item.image_tag === availableVersion.image_tag
-    );
+    const hasAvailable = result.items.some(item => item.image_tag === availableVersion.image_tag);
     expect(hasAvailable).toBe(true);
   });
 

From dc234fd48c785e8ae32db36853640711d4faba8e Mon Sep 17 00:00:00 2001
From: St0rmz1 <astorms@replicated.com>
Date: Tue, 3 Mar 2026 14:23:15 -0800
Subject: [PATCH 4/4] fix more kilo bot

---
 src/routers/kiloclaw-router.ts                | 39 ++++++-----
 .../kiloclaw-user-versions-router.test.ts     | 69 ++++++++++++++++++-
 2 files changed, 91 insertions(+), 17 deletions(-)

diff --git a/src/routers/kiloclaw-router.ts b/src/routers/kiloclaw-router.ts
index 51e1a92c2..1acc6ec8e 100644
--- a/src/routers/kiloclaw-router.ts
+++ b/src/routers/kiloclaw-router.ts
@@ -18,7 +18,7 @@ import {
   kiloclaw_image_catalog,
   kiloclaw_earlybird_purchases,
 } from '@kilocode/db/schema';
-import { eq, desc, sql } from 'drizzle-orm';
+import { and, eq, desc, sql } from 'drizzle-orm';
 import { sentryLogger } from '@/lib/utils.server';
 import type { KiloClawDashboardStatus, KiloCodeConfigResponse } from '@/lib/kiloclaw/types';
 import {
@@ -612,26 +612,33 @@ export const kiloclawRouter = createTRPCRouter({
     }),
 
   removeMyPin: baseProcedure.mutation(async ({ ctx }) => {
-    // Check if the pin was set by an admin — users cannot remove admin-set pins
-    const [existingPin] = await db
-      .select({ pinned_by: kiloclaw_version_pins.pinned_by })
-      .from(kiloclaw_version_pins)
-      .where(eq(kiloclaw_version_pins.user_id, ctx.user.id))
-      .limit(1);
-
-    if (existingPin && existingPin.pinned_by !== ctx.user.id) {
-      throw new TRPCError({
-        code: 'FORBIDDEN',
-        message: 'Your version is pinned by an admin. Contact your Kilo admin to remove the pin.',
-      });
-    }
-
+    // Atomically delete only self-set pins — the WHERE clause enforces the admin-pin guard
+    // so there's no TOCTOU race between checking pinned_by and deleting.
     const [deleted] = await db
       .delete(kiloclaw_version_pins)
-      .where(eq(kiloclaw_version_pins.user_id, ctx.user.id))
+      .where(
+        and(
+          eq(kiloclaw_version_pins.user_id, ctx.user.id),
+          eq(kiloclaw_version_pins.pinned_by, ctx.user.id)
+        )
+      )
       .returning();
 
     if (!deleted) {
+      // Check if a pin exists at all — if so, it's admin-set
+      const [existingPin] = await db
+        .select({ pinned_by: kiloclaw_version_pins.pinned_by })
+        .from(kiloclaw_version_pins)
+        .where(eq(kiloclaw_version_pins.user_id, ctx.user.id))
+        .limit(1);
+
+      if (existingPin) {
+        throw new TRPCError({
+          code: 'FORBIDDEN',
+          message: 'Your version is pinned by an admin. Contact your Kilo admin to remove the pin.',
+        });
+      }
+
       throw new TRPCError({ code: 'NOT_FOUND', message: 'No pin found for your account' });
     }
 
diff --git a/src/routers/kiloclaw-user-versions-router.test.ts b/src/routers/kiloclaw-user-versions-router.test.ts
index 8d681a39b..fe2bf348e 100644
--- a/src/routers/kiloclaw-user-versions-router.test.ts
+++ b/src/routers/kiloclaw-user-versions-router.test.ts
@@ -8,6 +8,7 @@ import { eq } from 'drizzle-orm';
 
 let userA: User;
 let userB: User;
+let adminUser: User;
 
 const availableVersion = {
   openclaw_version: '2026.2.9',
@@ -36,6 +37,10 @@ beforeAll(async () => {
     google_user_email: 'user-b-kiloclaw-pin@example.com',
     is_admin: false,
   });
+  adminUser = await insertTestUser({
+    google_user_email: 'admin-kiloclaw-pin@example.com',
+    is_admin: true,
+  });
 
   await db.insert(kiloclaw_image_catalog).values([availableVersion, disabledVersion]);
 });
@@ -248,7 +253,7 @@ describe('Authorization', () => {
     expect(resultB?.user_id).toBe(userB.id);
   });
 
-  it('removeMyPin only removes the current user pin', async () => {
+  it('removeMyPin only removes the current user pin (self-set)', async () => {
     const callerA = await createCallerForUser(userA.id);
     await callerA.kiloclaw.removeMyPin();
 
@@ -267,3 +272,65 @@ describe('Authorization', () => {
     expect(pinsB.length).toBe(1);
   });
 });
+
+describe('Admin-pin guard', () => {
+  afterEach(async () => {
+    await db.delete(kiloclaw_version_pins).where(eq(kiloclaw_version_pins.user_id, userA.id));
+  });
+
+  it('setMyPin throws FORBIDDEN when an admin has pinned the user', async () => {
+    // Admin pins userA
+    await db.insert(kiloclaw_version_pins).values({
+      user_id: userA.id,
+      image_tag: availableVersion.image_tag,
+      pinned_by: adminUser.id,
+      reason: 'Admin override',
+    });
+
+    const caller = await createCallerForUser(userA.id);
+    await expect(
+      caller.kiloclaw.setMyPin({
+        imageTag: availableVersion.image_tag,
+        reason: 'User trying to override',
+      })
+    ).rejects.toThrow('pinned by an admin');
+  });
+
+  it('removeMyPin throws FORBIDDEN when an admin has pinned the user', async () => {
+    // Admin pins userA
+    await db.insert(kiloclaw_version_pins).values({
+      user_id: userA.id,
+      image_tag: availableVersion.image_tag,
+      pinned_by: adminUser.id,
+    });
+
+    const caller = await createCallerForUser(userA.id);
+    await expect(caller.kiloclaw.removeMyPin()).rejects.toThrow('pinned by an admin');
+
+    // Verify pin is still there
+    const pins = await db
+      .select()
+      .from(kiloclaw_version_pins)
+      .where(eq(kiloclaw_version_pins.user_id, userA.id));
+    expect(pins.length).toBe(1);
+    expect(pins[0].pinned_by).toBe(adminUser.id);
+  });
+
+  it('setMyPin succeeds when user has self-set pin', async () => {
+    // User pins themselves first
+    await db.insert(kiloclaw_version_pins).values({
+      user_id: userA.id,
+      image_tag: availableVersion.image_tag,
+      pinned_by: userA.id,
+    });
+
+    const caller = await createCallerForUser(userA.id);
+    const result = await caller.kiloclaw.setMyPin({
+      imageTag: availableVersion.image_tag,
+      reason: 'Updated by user',
+    });
+
+    expect(result.reason).toBe('Updated by user');
+    expect(result.pinned_by).toBe(userA.id);
+  });
+});