From fde263c0df42fceccc442dbb30e1ac682eaa4fec Mon Sep 17 00:00:00 2001
From: Remon Oldenbeuving <remon@kilocode.ai>
Date: Mon, 23 Mar 2026 14:12:08 +0100
Subject: [PATCH 01/14] feat(claw): add channel pairing step to onboarding for
 Telegram/Discord

After provisioning completes, users who selected Telegram or Discord are
shown an inline pairing step that polls for incoming pairing requests and
lets them approve with a button. Slack skips this step since it has no
dmPolicy/pairing mechanism.

- New ChannelPairingStep component with channel-specific instructions
- ClawDashboard captures selectedChannelId and routes to pairing step
- ProvisioningStep accepts dynamic totalSteps (4 or 5)
---
 .../claw/components/ChannelPairingStep.tsx    | 176 ++++++++++++++++++
 .../(app)/claw/components/ClawDashboard.tsx   |  19 +-
 .../claw/components/ProvisioningStep.tsx      |   8 +-
 3 files changed, 198 insertions(+), 5 deletions(-)
 create mode 100644 src/app/(app)/claw/components/ChannelPairingStep.tsx

diff --git a/src/app/(app)/claw/components/ChannelPairingStep.tsx b/src/app/(app)/claw/components/ChannelPairingStep.tsx
new file mode 100644
index 000000000..99c561a8b
--- /dev/null
+++ b/src/app/(app)/claw/components/ChannelPairingStep.tsx
@@ -0,0 +1,176 @@
+'use client';
+
+import { useEffect, useRef } from 'react';
+import { Check, Loader2, MessageSquare, ShieldCheck } from 'lucide-react';
+import { toast } from 'sonner';
+import { useKiloClawPairing, useRefreshPairing } from '@/hooks/useKiloClaw';
+import { Button } from '@/components/ui/button';
+import type { ClawMutations } from './claw.types';
+import { OnboardingStepView } from './OnboardingStepView';
+import { TelegramIcon } from './icons/TelegramIcon';
+import { DiscordIcon } from './icons/DiscordIcon';
+
+type ChannelPairingStepProps = {
+  channelId: 'telegram' | 'discord';
+  mutations: ClawMutations;
+  onComplete: () => void;
+  onSkip: () => void;
+};
+
+const CHANNEL_META: Record<
+  'telegram' | 'discord',
+  {
+    label: string;
+    icon: React.ComponentType<{ className?: string }>;
+    instruction: string;
+  }
+> = {
+  telegram: {
+    label: 'Telegram',
+    icon: TelegramIcon,
+    instruction: 'Open Telegram and send any message to your bot.',
+  },
+  discord: {
+    label: 'Discord',
+    icon: DiscordIcon,
+    instruction: 'Open Discord and send a DM to your bot.',
+  },
+};
+
+export function ChannelPairingStep({
+  channelId,
+  mutations,
+  onComplete,
+  onSkip,
+}: ChannelPairingStepProps) {
+  const meta = CHANNEL_META[channelId];
+  const Icon = meta.icon;
+
+  // Subscribe to the normal pairing query (shared cache with Settings tab)
+  const { data: pairingData, isLoading } = useKiloClawPairing(true);
+
+  // Bust the KV cache every 5 seconds so new requests appear quickly.
+  // useRefreshPairing returns a fresh closure each render, so pin it in a ref
+  // to keep the interval stable.
+  const refreshPairing = useRefreshPairing();
+  const refreshRef = useRef(refreshPairing);
+  refreshRef.current = refreshPairing;
+
+  useEffect(() => {
+    refreshRef.current().catch(() => {});
+    const id = setInterval(() => {
+      refreshRef.current().catch(() => {});
+    }, 5_000);
+    return () => clearInterval(id);
+  }, []);
+
+  // Find the first pairing request matching this channel
+  const matchingRequest = pairingData?.requests?.find(
+    (r: { channel: string; code: string; id: string }) => r.channel === channelId
+  );
+
+  const isApproving = mutations.approvePairingRequest.isPending;
+
+  function handleApprove(channel: string, code: string) {
+    mutations.approvePairingRequest.mutate(
+      { channel, code },
+      {
+        onSuccess: result => {
+          if (result.success) {
+            toast.success('Pairing approved');
+            onComplete();
+          } else {
+            toast.error(result.message || 'Approval failed');
+          }
+        },
+        onError: err => toast.error(`Failed to approve: ${err.message}`),
+      }
+    );
+  }
+
+  return (
+    <OnboardingStepView
+      currentStep={5}
+      totalSteps={5}
+      title="Pair your account"
+      description={`Before you can chat, ${meta.label} needs to verify it's really you.`}
+      contentClassName="gap-8"
+    >
+      {/* Instruction card */}
+      <div className="border-border flex items-start gap-4 rounded-lg border p-5">
+        <div className="bg-muted flex h-10 w-10 shrink-0 items-center justify-center rounded-lg">
+          <Icon className="h-5 w-5" />
+        </div>
+        <div className="flex flex-col gap-1">
+          <p className="text-foreground text-sm font-semibold">{meta.instruction}</p>
+          <p className="text-muted-foreground text-xs leading-relaxed">
+            Your bot will see the message and create a pairing request that appears below.
+          </p>
+        </div>
+      </div>
+
+      {/* Pairing request area */}
+      <div className="flex flex-col gap-3">
+        <div className="flex items-center gap-2">
+          <ShieldCheck className="text-muted-foreground h-4 w-4" />
+          <span className="text-foreground text-sm font-semibold">Pairing request</span>
+        </div>
+
+        {matchingRequest ? (
+          <div className="border-border flex items-center justify-between rounded-lg border p-4">
+            <div className="flex items-center gap-3">
+              <MessageSquare className="text-muted-foreground h-4 w-4 shrink-0" />
+              <div className="min-w-0">
+                <div className="flex items-center gap-2">
+                  <span className="bg-muted rounded px-1.5 py-0.5 font-mono text-xs">
+                    {matchingRequest.code}
+                  </span>
+                  <span className="text-muted-foreground text-xs capitalize">
+                    {matchingRequest.channel}
+                  </span>
+                </div>
+                <p className="text-muted-foreground mt-0.5 text-xs">User {matchingRequest.id}</p>
+              </div>
+            </div>
+            <Button
+              size="sm"
+              className="bg-emerald-600 text-white hover:bg-emerald-700"
+              onClick={() => handleApprove(matchingRequest.channel, matchingRequest.code)}
+              disabled={isApproving}
+            >
+              {isApproving ? (
+                <Loader2 className="h-3 w-3 animate-spin" />
+              ) : (
+                <Check className="h-3 w-3" />
+              )}
+              Approve
+            </Button>
+          </div>
+        ) : (
+          <div className="border-border flex items-center gap-3 rounded-lg border border-dashed p-4">
+            {isLoading ? (
+              <Loader2 className="text-muted-foreground h-4 w-4 animate-spin" />
+            ) : (
+              <span className="relative flex h-2 w-2 shrink-0">
+                <span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-blue-400 opacity-60" />
+                <span className="relative inline-flex h-2 w-2 rounded-full bg-blue-500" />
+              </span>
+            )}
+            <span className="text-muted-foreground text-sm">
+              Waiting for a message from {meta.label}...
+            </span>
+          </div>
+        )}
+      </div>
+
+      {/* Skip link */}
+      <button
+        type="button"
+        className="text-muted-foreground hover:text-foreground mx-auto text-sm transition-colors"
+        onClick={onSkip}
+      >
+        Skip — I&apos;ll pair later from Settings
+      </button>
+    </OnboardingStepView>
+  );
+}
diff --git a/src/app/(app)/claw/components/ClawDashboard.tsx b/src/app/(app)/claw/components/ClawDashboard.tsx
index 418a964d7..1599d5c5d 100644
--- a/src/app/(app)/claw/components/ClawDashboard.tsx
+++ b/src/app/(app)/claw/components/ClawDashboard.tsx
@@ -20,6 +20,7 @@ import { InstanceTab } from './InstanceTab';
 import { OpenClawButton } from './OpenClawButton';
 import { SettingsTab } from './SettingsTab';
 import { ChangelogTab } from './ChangelogTab';
+import { ChannelPairingStep } from './ChannelPairingStep';
 import { ChannelSelectionStepView } from './ChannelSelectionStep';
 import { PermissionStep } from './PermissionStep';
 import { ProvisioningStep } from './ProvisioningStep';
@@ -65,10 +66,12 @@ export function ClawDashboard({
   const configServiceNudgeVisible = !instanceStatus || instanceYoung;
 
   const [onboardingStep, setOnboardingStep] = useState<
-    'permissions' | 'channels' | 'provisioning' | 'done'
+    'permissions' | 'channels' | 'provisioning' | 'pairing' | 'done'
   >('permissions');
   const [selectedPreset, setSelectedPreset] = useState<ExecPreset | null>(null);
   const [channelTokens, setChannelTokens] = useState<Record<string, string> | null>(null);
+  const [selectedChannelId, setSelectedChannelId] = useState<string | null>(null);
+  const hasPairingStep = selectedChannelId === 'telegram' || selectedChannelId === 'discord';
 
   const [dirtySecrets, setDirtySecrets] = useState<Set<string>>(new Set());
 
@@ -160,11 +163,13 @@ export function ClawDashboard({
         ) : isNewSetup && onboardingStep === 'channels' ? (
           <ChannelSelectionStepView
             instanceRunning={isRunning && gatewayStatus?.state === 'running'}
-            onSelect={(_channelId, tokens) => {
+            onSelect={(channelId, tokens) => {
+              setSelectedChannelId(channelId);
               setChannelTokens(tokens);
               setOnboardingStep('provisioning');
             }}
             onSkip={() => {
+              setSelectedChannelId(null);
               setChannelTokens(null);
               setOnboardingStep('provisioning');
             }}
@@ -175,7 +180,17 @@ export function ClawDashboard({
             channelTokens={channelTokens}
             instanceRunning={isRunning && gatewayStatus?.state === 'running'}
             mutations={mutations}
+            totalSteps={hasPairingStep ? 5 : 4}
+            onComplete={() => setOnboardingStep(hasPairingStep ? 'pairing' : 'done')}
+          />
+        ) : isNewSetup &&
+          onboardingStep === 'pairing' &&
+          (selectedChannelId === 'telegram' || selectedChannelId === 'discord') ? (
+          <ChannelPairingStep
+            channelId={selectedChannelId}
+            mutations={mutations}
             onComplete={() => setOnboardingStep('done')}
+            onSkip={() => setOnboardingStep('done')}
           />
         ) : isNewSetup ? (
           <Card className="mt-6 overflow-hidden">
diff --git a/src/app/(app)/claw/components/ProvisioningStep.tsx b/src/app/(app)/claw/components/ProvisioningStep.tsx
index c89c1520e..9053f63c0 100644
--- a/src/app/(app)/claw/components/ProvisioningStep.tsx
+++ b/src/app/(app)/claw/components/ProvisioningStep.tsx
@@ -35,12 +35,14 @@ export function ProvisioningStep({
   channelTokens,
   instanceRunning,
   mutations,
+  totalSteps = 4,
   onComplete,
 }: {
   preset: ExecPreset;
   channelTokens: Record<string, string> | null;
   instanceRunning: boolean;
   mutations: ClawMutations;
+  totalSteps?: number;
   onComplete: () => void;
 }) {
   const completedRef = useRef(false);
@@ -110,7 +112,7 @@ export function ProvisioningStep({
     );
   }, [instanceRunning, preset]);
 
-  return <ProvisioningStepView />;
+  return <ProvisioningStepView totalSteps={totalSteps} />;
 }
 
 const PROVISIONING_MESSAGES = [
@@ -129,7 +131,7 @@ const PROVISIONING_MESSAGES = [
 ];
 
 /** Pure visual shell — extracted so Storybook can render it without wiring up mutations. */
-export function ProvisioningStepView() {
+export function ProvisioningStepView({ totalSteps = 4 }: { totalSteps?: number }) {
   const [messageIndex, setMessageIndex] = useState(0);
   const [visible, setVisible] = useState(true);
 
@@ -146,7 +148,7 @@ export function ProvisioningStepView() {
   return (
     <OnboardingStepView
       currentStep={4}
-      totalSteps={4}
+      totalSteps={totalSteps}
       stepLabel="Almost there..."
       contentClassName="items-center gap-8"
     >

From 2df6638e914b661f9488e2ab9525b190a2139f21 Mon Sep 17 00:00:00 2001
From: Remon Oldenbeuving <remon@kilocode.ai>
Date: Mon, 23 Mar 2026 14:25:47 +0100
Subject: [PATCH 02/14] feat(claw): add Storybook stories for
 ChannelPairingStep

Extract ChannelPairingStepView as a pure visual component (no hooks)
following the ProvisioningStep/ProvisioningStepView pattern. Stories
cover both channels, waiting/request/approving/loading states.
---
 .../claw/components/ChannelPairingStep.tsx    | 57 +++++++++++++----
 .../claw/ChannelPairingStep.stories.tsx       | 64 +++++++++++++++++++
 2 files changed, 109 insertions(+), 12 deletions(-)
 create mode 100644 storybook/stories/claw/ChannelPairingStep.stories.tsx

diff --git a/src/app/(app)/claw/components/ChannelPairingStep.tsx b/src/app/(app)/claw/components/ChannelPairingStep.tsx
index 99c561a8b..b839c9b5c 100644
--- a/src/app/(app)/claw/components/ChannelPairingStep.tsx
+++ b/src/app/(app)/claw/components/ChannelPairingStep.tsx
@@ -10,15 +10,10 @@ import { OnboardingStepView } from './OnboardingStepView';
 import { TelegramIcon } from './icons/TelegramIcon';
 import { DiscordIcon } from './icons/DiscordIcon';
 
-type ChannelPairingStepProps = {
-  channelId: 'telegram' | 'discord';
-  mutations: ClawMutations;
-  onComplete: () => void;
-  onSkip: () => void;
-};
+type PairingChannelId = 'telegram' | 'discord';
 
 const CHANNEL_META: Record<
-  'telegram' | 'discord',
+  PairingChannelId,
   {
     label: string;
     icon: React.ComponentType<{ className?: string }>;
@@ -37,15 +32,19 @@ const CHANNEL_META: Record<
   },
 };
 
+// ── Stateful wrapper (hooks + mutations) ────────────────────────────
+
 export function ChannelPairingStep({
   channelId,
   mutations,
   onComplete,
   onSkip,
-}: ChannelPairingStepProps) {
-  const meta = CHANNEL_META[channelId];
-  const Icon = meta.icon;
-
+}: {
+  channelId: PairingChannelId;
+  mutations: ClawMutations;
+  onComplete: () => void;
+  onSkip: () => void;
+}) {
   // Subscribe to the normal pairing query (shared cache with Settings tab)
   const { data: pairingData, isLoading } = useKiloClawPairing(true);
 
@@ -88,6 +87,40 @@ export function ChannelPairingStep({
     );
   }
 
+  return (
+    <ChannelPairingStepView
+      channelId={channelId}
+      matchingRequest={matchingRequest ?? null}
+      isLoading={isLoading}
+      isApproving={isApproving}
+      onApprove={handleApprove}
+      onSkip={onSkip}
+    />
+  );
+}
+
+// ── Pure visual component (no hooks — Storybook-friendly) ───────────
+
+type ChannelPairingStepViewProps = {
+  channelId: PairingChannelId;
+  matchingRequest: { code: string; channel: string; id: string } | null;
+  isLoading?: boolean;
+  isApproving?: boolean;
+  onApprove?: (channel: string, code: string) => void;
+  onSkip?: () => void;
+};
+
+export function ChannelPairingStepView({
+  channelId,
+  matchingRequest,
+  isLoading = false,
+  isApproving = false,
+  onApprove,
+  onSkip,
+}: ChannelPairingStepViewProps) {
+  const meta = CHANNEL_META[channelId];
+  const Icon = meta.icon;
+
   return (
     <OnboardingStepView
       currentStep={5}
@@ -135,7 +168,7 @@ export function ChannelPairingStep({
             <Button
               size="sm"
               className="bg-emerald-600 text-white hover:bg-emerald-700"
-              onClick={() => handleApprove(matchingRequest.channel, matchingRequest.code)}
+              onClick={() => onApprove?.(matchingRequest.channel, matchingRequest.code)}
               disabled={isApproving}
             >
               {isApproving ? (
diff --git a/storybook/stories/claw/ChannelPairingStep.stories.tsx b/storybook/stories/claw/ChannelPairingStep.stories.tsx
new file mode 100644
index 000000000..78bdf2882
--- /dev/null
+++ b/storybook/stories/claw/ChannelPairingStep.stories.tsx
@@ -0,0 +1,64 @@
+import type { Meta, StoryObj } from '@storybook/nextjs';
+import { ChannelPairingStepView } from '@/app/(app)/claw/components/ChannelPairingStep';
+
+const meta: Meta<typeof ChannelPairingStepView> = {
+  title: 'Claw/ChannelPairingStep',
+  component: ChannelPairingStepView,
+  parameters: {
+    layout: 'fullscreen',
+  },
+  decorators: [
+    Story => (
+      <div className="mx-auto flex w-full max-w-[1140px] flex-col gap-6 p-4 md:p-6">
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const TelegramWaiting: Story = {
+  args: {
+    channelId: 'telegram',
+    matchingRequest: null,
+  },
+};
+
+export const DiscordWaiting: Story = {
+  args: {
+    channelId: 'discord',
+    matchingRequest: null,
+  },
+};
+
+export const TelegramWithRequest: Story = {
+  args: {
+    channelId: 'telegram',
+    matchingRequest: { code: '3YPKLDPP', channel: 'telegram', id: '829104561' },
+  },
+};
+
+export const DiscordWithRequest: Story = {
+  args: {
+    channelId: 'discord',
+    matchingRequest: { code: 'K7WMRX2Q', channel: 'discord', id: '491028374165' },
+  },
+};
+
+export const Approving: Story = {
+  args: {
+    channelId: 'telegram',
+    matchingRequest: { code: '3YPKLDPP', channel: 'telegram', id: '829104561' },
+    isApproving: true,
+  },
+};
+
+export const Loading: Story = {
+  args: {
+    channelId: 'telegram',
+    matchingRequest: null,
+    isLoading: true,
+  },
+};

From 7dd50f07769454764d122369ab73bd429f233590 Mon Sep 17 00:00:00 2001
From: Remon Oldenbeuving <remon@kilocode.ai>
Date: Mon, 23 Mar 2026 14:51:22 +0100
Subject: [PATCH 03/14] refactor(claw): redesign pairing step waiting state to
 match mockup

Replace instruction card + dashed polling box with a centered spinner,
heading, and subtitle matching the provisioning step style. Title now
reads 'Pair your Telegram/Discord bot'. Skip button uses subdued
opacity. Step indicator stays left-aligned.
---
 .../claw/components/ChannelPairingStep.tsx    | 186 ++++++++++--------
 .../claw/ChannelPairingStep.stories.tsx       |   8 -
 2 files changed, 104 insertions(+), 90 deletions(-)

diff --git a/src/app/(app)/claw/components/ChannelPairingStep.tsx b/src/app/(app)/claw/components/ChannelPairingStep.tsx
index b839c9b5c..6029e063f 100644
--- a/src/app/(app)/claw/components/ChannelPairingStep.tsx
+++ b/src/app/(app)/claw/components/ChannelPairingStep.tsx
@@ -1,7 +1,7 @@
 'use client';
 
 import { useEffect, useRef } from 'react';
-import { Check, Loader2, MessageSquare, ShieldCheck } from 'lucide-react';
+import { Check, Loader2, MessageSquare } from 'lucide-react';
 import { toast } from 'sonner';
 import { useKiloClawPairing, useRefreshPairing } from '@/hooks/useKiloClaw';
 import { Button } from '@/components/ui/button';
@@ -23,12 +23,14 @@ const CHANNEL_META: Record<
   telegram: {
     label: 'Telegram',
     icon: TelegramIcon,
-    instruction: 'Open Telegram and send any message to your bot.',
+    instruction:
+      'Open Telegram and send any message to your bot. The bot will reply with a pairing request — we\u2019ll pick it up automatically.',
   },
   discord: {
     label: 'Discord',
     icon: DiscordIcon,
-    instruction: 'Open Discord and send a DM to your bot.',
+    instruction:
+      'Open Discord and send a DM to your bot. The bot will reply with a pairing request — we\u2019ll pick it up automatically.',
   },
 };
 
@@ -46,7 +48,7 @@ export function ChannelPairingStep({
   onSkip: () => void;
 }) {
   // Subscribe to the normal pairing query (shared cache with Settings tab)
-  const { data: pairingData, isLoading } = useKiloClawPairing(true);
+  const { data: pairingData } = useKiloClawPairing(true);
 
   // Bust the KV cache every 5 seconds so new requests appear quickly.
   // useRefreshPairing returns a fresh closure each render, so pin it in a ref
@@ -91,7 +93,6 @@ export function ChannelPairingStep({
     <ChannelPairingStepView
       channelId={channelId}
       matchingRequest={matchingRequest ?? null}
-      isLoading={isLoading}
       isApproving={isApproving}
       onApprove={handleApprove}
       onSkip={onSkip}
@@ -99,12 +100,9 @@ export function ChannelPairingStep({
   );
 }
 
-// ── Pure visual component (no hooks — Storybook-friendly) ───────────
-
 type ChannelPairingStepViewProps = {
   channelId: PairingChannelId;
   matchingRequest: { code: string; channel: string; id: string } | null;
-  isLoading?: boolean;
   isApproving?: boolean;
   onApprove?: (channel: string, code: string) => void;
   onSkip?: () => void;
@@ -113,97 +111,121 @@ type ChannelPairingStepViewProps = {
 export function ChannelPairingStepView({
   channelId,
   matchingRequest,
-  isLoading = false,
   isApproving = false,
   onApprove,
   onSkip,
 }: ChannelPairingStepViewProps) {
   const meta = CHANNEL_META[channelId];
-  const Icon = meta.icon;
+
+  if (matchingRequest) {
+    return (
+      <OnboardingStepView
+        currentStep={5}
+        totalSteps={5}
+        title={`Pair your ${meta.label} bot`}
+        description="A pairing request was detected — approve it to link your account."
+        contentClassName="gap-8"
+      >
+        <div className="border-border flex items-center justify-between rounded-lg border p-4">
+          <div className="flex items-center gap-3">
+            <MessageSquare className="text-muted-foreground h-4 w-4 shrink-0" />
+            <div className="min-w-0">
+              <div className="flex items-center gap-2">
+                <span className="bg-muted rounded px-1.5 py-0.5 font-mono text-xs">
+                  {matchingRequest.code}
+                </span>
+                <span className="text-muted-foreground text-xs capitalize">
+                  {matchingRequest.channel}
+                </span>
+              </div>
+              <p className="text-muted-foreground mt-0.5 text-xs">User {matchingRequest.id}</p>
+            </div>
+          </div>
+          <Button
+            size="sm"
+            className="bg-emerald-600 text-white hover:bg-emerald-700"
+            onClick={() => onApprove?.(matchingRequest.channel, matchingRequest.code)}
+            disabled={isApproving}
+          >
+            {isApproving ? (
+              <Loader2 className="h-3 w-3 animate-spin" />
+            ) : (
+              <Check className="h-3 w-3" />
+            )}
+            Approve
+          </Button>
+        </div>
+
+        <button
+          type="button"
+          className="text-muted-foreground/50 hover:text-muted-foreground mx-auto text-sm transition-colors"
+          onClick={onSkip}
+        >
+          Skip — I&apos;ll pair later from Settings
+        </button>
+      </OnboardingStepView>
+    );
+  }
 
   return (
     <OnboardingStepView
       currentStep={5}
       totalSteps={5}
-      title="Pair your account"
-      description={`Before you can chat, ${meta.label} needs to verify it's really you.`}
+      title={`Pair your ${meta.label} bot`}
+      description={meta.instruction}
       contentClassName="gap-8"
     >
-      {/* Instruction card */}
-      <div className="border-border flex items-start gap-4 rounded-lg border p-5">
-        <div className="bg-muted flex h-10 w-10 shrink-0 items-center justify-center rounded-lg">
-          <Icon className="h-5 w-5" />
+      <div className="flex flex-col items-center gap-8">
+        <div className="pairing-spinner relative h-24 w-24 my-6">
+          <svg className="h-full w-full" viewBox="0 0 96 96">
+            <circle
+              cx="48"
+              cy="48"
+              r="42"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="4"
+              className="text-muted/40"
+            />
+            <circle
+              cx="48"
+              cy="48"
+              r="42"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="4"
+              strokeLinecap="round"
+              strokeDasharray="132 264"
+              className="pairing-spinner-arc text-blue-500"
+            />
+          </svg>
+          <style>{`
+            .pairing-spinner svg {
+              animation: pairing-rotate 1.4s linear infinite;
+            }
+            @keyframes pairing-rotate {
+              to { transform: rotate(360deg); }
+            }
+          `}</style>
         </div>
-        <div className="flex flex-col gap-1">
-          <p className="text-foreground text-sm font-semibold">{meta.instruction}</p>
-          <p className="text-muted-foreground text-xs leading-relaxed">
-            Your bot will see the message and create a pairing request that appears below.
-          </p>
-        </div>
-      </div>
 
-      {/* Pairing request area */}
-      <div className="flex flex-col gap-3">
-        <div className="flex items-center gap-2">
-          <ShieldCheck className="text-muted-foreground h-4 w-4" />
-          <span className="text-foreground text-sm font-semibold">Pairing request</span>
+        <div className="flex flex-col items-center gap-2 text-center">
+          <h2 className="text-foreground text-lg font-semibold">
+            Waiting for you to message the bot...
+          </h2>
+          <p className="text-muted-foreground text-sm">
+            This page will update as soon as the bot responds
+          </p>
         </div>
 
-        {matchingRequest ? (
-          <div className="border-border flex items-center justify-between rounded-lg border p-4">
-            <div className="flex items-center gap-3">
-              <MessageSquare className="text-muted-foreground h-4 w-4 shrink-0" />
-              <div className="min-w-0">
-                <div className="flex items-center gap-2">
-                  <span className="bg-muted rounded px-1.5 py-0.5 font-mono text-xs">
-                    {matchingRequest.code}
-                  </span>
-                  <span className="text-muted-foreground text-xs capitalize">
-                    {matchingRequest.channel}
-                  </span>
-                </div>
-                <p className="text-muted-foreground mt-0.5 text-xs">User {matchingRequest.id}</p>
-              </div>
-            </div>
-            <Button
-              size="sm"
-              className="bg-emerald-600 text-white hover:bg-emerald-700"
-              onClick={() => onApprove?.(matchingRequest.channel, matchingRequest.code)}
-              disabled={isApproving}
-            >
-              {isApproving ? (
-                <Loader2 className="h-3 w-3 animate-spin" />
-              ) : (
-                <Check className="h-3 w-3" />
-              )}
-              Approve
-            </Button>
-          </div>
-        ) : (
-          <div className="border-border flex items-center gap-3 rounded-lg border border-dashed p-4">
-            {isLoading ? (
-              <Loader2 className="text-muted-foreground h-4 w-4 animate-spin" />
-            ) : (
-              <span className="relative flex h-2 w-2 shrink-0">
-                <span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-blue-400 opacity-60" />
-                <span className="relative inline-flex h-2 w-2 rounded-full bg-blue-500" />
-              </span>
-            )}
-            <span className="text-muted-foreground text-sm">
-              Waiting for a message from {meta.label}...
-            </span>
-          </div>
-        )}
+        <button
+          type="button"
+          className="text-muted-foreground/50 cursor-pointer hover:text-muted-foreground text-sm transition-colors my-6"
+          onClick={onSkip}
+        >
+          Skip — I&apos;ll pair later from Settings
+        </button>
       </div>
-
-      {/* Skip link */}
-      <button
-        type="button"
-        className="text-muted-foreground hover:text-foreground mx-auto text-sm transition-colors"
-        onClick={onSkip}
-      >
-        Skip — I&apos;ll pair later from Settings
-      </button>
     </OnboardingStepView>
   );
 }
diff --git a/storybook/stories/claw/ChannelPairingStep.stories.tsx b/storybook/stories/claw/ChannelPairingStep.stories.tsx
index 78bdf2882..3bff9eebd 100644
--- a/storybook/stories/claw/ChannelPairingStep.stories.tsx
+++ b/storybook/stories/claw/ChannelPairingStep.stories.tsx
@@ -54,11 +54,3 @@ export const Approving: Story = {
     isApproving: true,
   },
 };
-
-export const Loading: Story = {
-  args: {
-    channelId: 'telegram',
-    matchingRequest: null,
-    isLoading: true,
-  },
-};

From d26d85f19569c7d16b97c540758656860ff53fb9 Mon Sep 17 00:00:00 2001
From: Remon Oldenbeuving <remon@kilocode.ai>
Date: Mon, 23 Mar 2026 15:30:48 +0100
Subject: [PATCH 04/14] refactor(claw): redesign pairing request view to match
 mockup

Show pairing code prominently with user ID, full-width authorize
button, and decline link. Remove dead imports and JSX comments.
Add cursor-pointer to all interactive elements.
---
 .../claw/components/ChannelPairingStep.tsx    | 100 ++++++++----------
 1 file changed, 47 insertions(+), 53 deletions(-)

diff --git a/src/app/(app)/claw/components/ChannelPairingStep.tsx b/src/app/(app)/claw/components/ChannelPairingStep.tsx
index 6029e063f..63112fc8e 100644
--- a/src/app/(app)/claw/components/ChannelPairingStep.tsx
+++ b/src/app/(app)/claw/components/ChannelPairingStep.tsx
@@ -1,41 +1,28 @@
 'use client';
 
 import { useEffect, useRef } from 'react';
-import { Check, Loader2, MessageSquare } from 'lucide-react';
+import { CheckCircle2, Loader2, Send, XCircle } from 'lucide-react';
 import { toast } from 'sonner';
 import { useKiloClawPairing, useRefreshPairing } from '@/hooks/useKiloClaw';
 import { Button } from '@/components/ui/button';
 import type { ClawMutations } from './claw.types';
 import { OnboardingStepView } from './OnboardingStepView';
-import { TelegramIcon } from './icons/TelegramIcon';
-import { DiscordIcon } from './icons/DiscordIcon';
 
 type PairingChannelId = 'telegram' | 'discord';
 
-const CHANNEL_META: Record<
-  PairingChannelId,
-  {
-    label: string;
-    icon: React.ComponentType<{ className?: string }>;
-    instruction: string;
-  }
-> = {
+const CHANNEL_META: Record<PairingChannelId, { label: string; instruction: string }> = {
   telegram: {
     label: 'Telegram',
-    icon: TelegramIcon,
     instruction:
-      'Open Telegram and send any message to your bot. The bot will reply with a pairing request — we\u2019ll pick it up automatically.',
+      'Open Telegram and send any message to your bot. The bot will reply with a pairing request \u2014 we\u2019ll pick it up automatically.',
   },
   discord: {
     label: 'Discord',
-    icon: DiscordIcon,
     instruction:
-      'Open Discord and send a DM to your bot. The bot will reply with a pairing request — we\u2019ll pick it up automatically.',
+      'Open Discord and send a DM to your bot. The bot will reply with a pairing request \u2014 we\u2019ll pick it up automatically.',
   },
 };
 
-// ── Stateful wrapper (hooks + mutations) ────────────────────────────
-
 export function ChannelPairingStep({
   channelId,
   mutations,
@@ -47,12 +34,8 @@ export function ChannelPairingStep({
   onComplete: () => void;
   onSkip: () => void;
 }) {
-  // Subscribe to the normal pairing query (shared cache with Settings tab)
   const { data: pairingData } = useKiloClawPairing(true);
 
-  // Bust the KV cache every 5 seconds so new requests appear quickly.
-  // useRefreshPairing returns a fresh closure each render, so pin it in a ref
-  // to keep the interval stable.
   const refreshPairing = useRefreshPairing();
   const refreshRef = useRef(refreshPairing);
   refreshRef.current = refreshPairing;
@@ -65,7 +48,6 @@ export function ChannelPairingStep({
     return () => clearInterval(id);
   }, []);
 
-  // Find the first pairing request matching this channel
   const matchingRequest = pairingData?.requests?.find(
     (r: { channel: string; code: string; id: string }) => r.channel === channelId
   );
@@ -123,45 +105,57 @@ export function ChannelPairingStepView({
         currentStep={5}
         totalSteps={5}
         title={`Pair your ${meta.label} bot`}
-        description="A pairing request was detected — approve it to link your account."
-        contentClassName="gap-8"
+        description={meta.instruction}
+        contentClassName="gap-6"
       >
-        <div className="border-border flex items-center justify-between rounded-lg border p-4">
-          <div className="flex items-center gap-3">
-            <MessageSquare className="text-muted-foreground h-4 w-4 shrink-0" />
-            <div className="min-w-0">
-              <div className="flex items-center gap-2">
-                <span className="bg-muted rounded px-1.5 py-0.5 font-mono text-xs">
-                  {matchingRequest.code}
-                </span>
-                <span className="text-muted-foreground text-xs capitalize">
-                  {matchingRequest.channel}
-                </span>
-              </div>
-              <p className="text-muted-foreground mt-0.5 text-xs">User {matchingRequest.id}</p>
-            </div>
+        <div className="border-border bg-muted/30 flex flex-col rounded-lg border">
+          <div className="flex items-center gap-2 px-5 pt-5 pb-4">
+            <Send className="text-muted-foreground h-4 w-4" />
+            <span className="text-muted-foreground text-xs font-semibold uppercase tracking-wider">
+              Pairing request received
+            </span>
+          </div>
+
+          <div className="border-border mx-5 flex items-center justify-between border-b pb-4">
+            <span className="text-muted-foreground text-sm">{meta.label} user ID</span>
+            <span className="text-foreground font-mono text-sm">{matchingRequest.id}</span>
+          </div>
+
+          <div className="flex flex-col items-center gap-2 px-5 py-6">
+            <span className="text-muted-foreground text-xs font-semibold uppercase tracking-wider">
+              Pairing code
+            </span>
+            <span className="text-foreground font-mono text-3xl font-bold tracking-[0.25em]">
+              {matchingRequest.code}
+            </span>
           </div>
-          <Button
-            size="sm"
-            className="bg-emerald-600 text-white hover:bg-emerald-700"
-            onClick={() => onApprove?.(matchingRequest.channel, matchingRequest.code)}
-            disabled={isApproving}
-          >
-            {isApproving ? (
-              <Loader2 className="h-3 w-3 animate-spin" />
-            ) : (
-              <Check className="h-3 w-3" />
-            )}
-            Approve
-          </Button>
         </div>
 
+        <p className="text-muted-foreground/70 text-center text-sm">
+          A user on {meta.label} is requesting access to your bot. Only approve if you initiated
+          this.
+        </p>
+
+        <Button
+          className="w-full cursor-pointer bg-emerald-500 py-5 text-base font-semibold text-white hover:bg-emerald-600"
+          onClick={() => onApprove?.(matchingRequest.channel, matchingRequest.code)}
+          disabled={isApproving}
+        >
+          {isApproving ? (
+            <Loader2 className="h-4 w-4 animate-spin" />
+          ) : (
+            <CheckCircle2 className="h-4 w-4" />
+          )}
+          Authorize this request
+        </Button>
+
         <button
           type="button"
-          className="text-muted-foreground/50 hover:text-muted-foreground mx-auto text-sm transition-colors"
+          className="text-muted-foreground/50 hover:text-muted-foreground mx-auto flex cursor-pointer items-center gap-1.5 text-sm transition-colors"
           onClick={onSkip}
         >
-          Skip — I&apos;ll pair later from Settings
+          <XCircle className="h-3.5 w-3.5" />
+          Decline
         </button>
       </OnboardingStepView>
     );

From 932ebba5316fb85b4d3d13ba68e690ebfef1f82f Mon Sep 17 00:00:00 2001
From: Remon Oldenbeuving <remon@kilocode.ai>
Date: Tue, 24 Mar 2026 10:28:53 +0100
Subject: [PATCH 05/14] fix(claw): switch pairing poll from fixed interval to
 sequential fetch-then-wait

Replaces setInterval(5s) with a sequential loop that waits 1s after
each fetch completes, preventing request pileup on slow responses.
---
 .../claw/components/ChannelPairingStep.tsx     | 18 ++++++++++++------
 1 file changed, 12 insertions(+), 6 deletions(-)

diff --git a/src/app/(app)/claw/components/ChannelPairingStep.tsx b/src/app/(app)/claw/components/ChannelPairingStep.tsx
index 63112fc8e..c5b2a7ccd 100644
--- a/src/app/(app)/claw/components/ChannelPairingStep.tsx
+++ b/src/app/(app)/claw/components/ChannelPairingStep.tsx
@@ -41,11 +41,18 @@ export function ChannelPairingStep({
   refreshRef.current = refreshPairing;
 
   useEffect(() => {
-    refreshRef.current().catch(() => {});
-    const id = setInterval(() => {
-      refreshRef.current().catch(() => {});
-    }, 5_000);
-    return () => clearInterval(id);
+    let cancelled = false;
+    async function poll() {
+      while (!cancelled) {
+        await refreshRef.current().catch(() => {});
+        if (cancelled) break;
+        await new Promise(r => setTimeout(r, 1_000));
+      }
+    }
+    poll();
+    return () => {
+      cancelled = true;
+    };
   }, []);
 
   const matchingRequest = pairingData?.requests?.find(
@@ -211,7 +218,6 @@ export function ChannelPairingStepView({
             This page will update as soon as the bot responds
           </p>
         </div>
-
         <button
           type="button"
           className="text-muted-foreground/50 cursor-pointer hover:text-muted-foreground text-sm transition-colors my-6"

From 3d859b75e99c273efc7a18f89012c146a29258d2 Mon Sep 17 00:00:00 2001
From: Remon Oldenbeuving <remon@kilocode.ai>
Date: Tue, 24 Mar 2026 11:19:56 +0100
Subject: [PATCH 06/14] fix(claw): set staleTime: 0 on pairing refresh to
 bypass react-query cache

---
 src/hooks/useKiloClaw.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/hooks/useKiloClaw.ts b/src/hooks/useKiloClaw.ts
index 5bc76e3a0..cd65d71ed 100644
--- a/src/hooks/useKiloClaw.ts
+++ b/src/hooks/useKiloClaw.ts
@@ -34,7 +34,7 @@ export function useRefreshPairing() {
     // Fetch with refresh=true to bust KV cache, then write the result
     // into the normal (no-input) query so the component sees it immediately.
     const fresh = await queryClient.fetchQuery(
-      trpc.kiloclaw.listPairingRequests.queryOptions({ refresh: true })
+      trpc.kiloclaw.listPairingRequests.queryOptions({ refresh: true }, { staleTime: 0 })
     );
     queryClient.setQueryData(trpc.kiloclaw.listPairingRequests.queryKey(), fresh);
   };

From 49a6fb12124bf5a2d52b90f27d2aad9a0eb1c26d Mon Sep 17 00:00:00 2001
From: Remon Oldenbeuving <remon@kilocode.ai>
Date: Tue, 24 Mar 2026 11:47:02 +0100
Subject: [PATCH 07/14] fix(claw): move boot delay to provisioning step and fix
 approval flash

Move the 60-second boot delay from ChannelPairingStep into
ProvisioningStep so the user sees one continuous 'Setting up your
instance' spinner instead of two spinners in sequence. Config
mutations still fire immediately; onComplete is deferred until both
the config is applied and the timer elapses.

Fix the approval flash bug where the UI briefly reverted to the
'waiting for message' state after approving a pairing request. The
mutation's global onSuccess invalidates the pairing query (clearing
matchingRequest) before the call-site onSuccess fires onComplete.
pendingApproval preserves the request data across that refetch window.
---
 .../claw/components/ChannelPairingStep.tsx    | 28 +++++++++++++-----
 .../claw/components/ProvisioningStep.tsx      | 29 +++++++++++++++----
 2 files changed, 44 insertions(+), 13 deletions(-)

diff --git a/src/app/(app)/claw/components/ChannelPairingStep.tsx b/src/app/(app)/claw/components/ChannelPairingStep.tsx
index c5b2a7ccd..db19c1c18 100644
--- a/src/app/(app)/claw/components/ChannelPairingStep.tsx
+++ b/src/app/(app)/claw/components/ChannelPairingStep.tsx
@@ -1,6 +1,6 @@
 'use client';
 
-import { useEffect, useRef } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import { CheckCircle2, Loader2, Send, XCircle } from 'lucide-react';
 import { toast } from 'sonner';
 import { useKiloClawPairing, useRefreshPairing } from '@/hooks/useKiloClaw';
@@ -59,9 +59,21 @@ export function ChannelPairingStep({
     (r: { channel: string; code: string; id: string }) => r.channel === channelId
   );
 
-  const isApproving = mutations.approvePairingRequest.isPending;
+  // Preserve the request being approved so the approval card stays visible
+  // while the mutation's onSuccess invalidates the pairing query. Without
+  // this, matchingRequest goes null from the refetch before onComplete fires,
+  // causing a brief flash of the "waiting" state.
+  const [pendingApproval, setPendingApproval] = useState<{
+    code: string;
+    channel: string;
+    id: string;
+  } | null>(null);
+
+  const displayedRequest = matchingRequest ?? pendingApproval;
+  const isApproving = mutations.approvePairingRequest.isPending || pendingApproval !== null;
 
   function handleApprove(channel: string, code: string) {
+    if (matchingRequest) setPendingApproval(matchingRequest);
     mutations.approvePairingRequest.mutate(
       { channel, code },
       {
@@ -70,10 +82,14 @@ export function ChannelPairingStep({
             toast.success('Pairing approved');
             onComplete();
           } else {
+            setPendingApproval(null);
             toast.error(result.message || 'Approval failed');
           }
         },
-        onError: err => toast.error(`Failed to approve: ${err.message}`),
+        onError: err => {
+          setPendingApproval(null);
+          toast.error(`Failed to approve: ${err.message}`);
+        },
       }
     );
   }
@@ -81,7 +97,7 @@ export function ChannelPairingStep({
   return (
     <ChannelPairingStepView
       channelId={channelId}
-      matchingRequest={matchingRequest ?? null}
+      matchingRequest={displayedRequest ?? null}
       isApproving={isApproving}
       onApprove={handleApprove}
       onSkip={onSkip}
@@ -214,9 +230,7 @@ export function ChannelPairingStepView({
           <h2 className="text-foreground text-lg font-semibold">
             Waiting for you to message the bot...
           </h2>
-          <p className="text-muted-foreground text-sm">
-            This page will update as soon as the bot responds
-          </p>
+          <p className="text-muted-foreground text-sm">This page will update automatically.</p>
         </div>
         <button
           type="button"
diff --git a/src/app/(app)/claw/components/ProvisioningStep.tsx b/src/app/(app)/claw/components/ProvisioningStep.tsx
index 9053f63c0..42676e2a8 100644
--- a/src/app/(app)/claw/components/ProvisioningStep.tsx
+++ b/src/app/(app)/claw/components/ProvisioningStep.tsx
@@ -12,6 +12,11 @@ import {
 } from './claw.types';
 import { OnboardingStepView } from './OnboardingStepView';
 
+// Let the instance boot in peace before advancing to the pairing step.
+// Config mutations fire immediately, but we hold onComplete until this
+// timer elapses so the gateway has time to fully initialize.
+const BOOT_DELAY_MS = 60_000;
+
 /** Play a short chime via the Web Audio API. */
 function playChime() {
   try {
@@ -46,6 +51,8 @@ export function ProvisioningStep({
   onComplete: () => void;
 }) {
   const completedRef = useRef(false);
+  const [configReady, setConfigReady] = useState(false);
+  const [bootDelayElapsed, setBootDelayElapsed] = useState(false);
 
   // Keep stable references to callbacks so the effect only re-runs
   // when data values change, not when the parent re-renders or mutation
@@ -61,6 +68,11 @@ export function ProvisioningStep({
   const channelTokensRef = useRef(channelTokens);
   channelTokensRef.current = channelTokens;
 
+  useEffect(() => {
+    const timer = setTimeout(() => setBootDelayElapsed(true), BOOT_DELAY_MS);
+    return () => clearTimeout(timer);
+  }, []);
+
   useEffect(() => {
     if (!instanceRunning || completedRef.current) return;
     completedRef.current = true;
@@ -92,18 +104,14 @@ export function ProvisioningStep({
     }
 
     if (Object.keys(configPatch).length === 0) {
-      playChime();
-      onCompleteRef.current();
+      setConfigReady(true);
       return;
     }
 
     patchOpenclawConfigRef.current(
       { patch: configPatch },
       {
-        onSuccess: () => {
-          playChime();
-          onCompleteRef.current();
-        },
+        onSuccess: () => setConfigReady(true),
         onError: (err: { message: string }) => {
           completedRef.current = false;
           toast.error(err.message);
@@ -112,6 +120,15 @@ export function ProvisioningStep({
     );
   }, [instanceRunning, preset]);
 
+  // Advance to the next step only when both the config is applied
+  // and the boot delay has elapsed, giving the gateway time to start.
+  useEffect(() => {
+    if (configReady && bootDelayElapsed) {
+      playChime();
+      onCompleteRef.current();
+    }
+  }, [configReady, bootDelayElapsed]);
+
   return <ProvisioningStepView totalSteps={totalSteps} />;
 }
 

From d8339533e7c198b5eeef2fc896dba8a1cb8131a1 Mon Sep 17 00:00:00 2001
From: Remon Oldenbeuving <remon@kilocode.ai>
Date: Tue, 24 Mar 2026 13:00:03 +0100
Subject: [PATCH 08/14] feat(claw): wire controller health endpoint through to
 frontend
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Expose the controller's /_kilo/health endpoint (bootstrapping → starting
→ ready → degraded) through the full stack so the frontend can track
machine bootstrap progress. Both ProvisioningStep and ChannelPairingStep
poll every 1s and log the result to the browser console.
---
 .../gateway-controller-types.ts               | 14 ++++++++++++
 .../kiloclaw-instance/gateway.ts              | 22 +++++++++++++++++++
 .../kiloclaw-instance/index.ts                | 10 +++++++++
 kiloclaw/src/routes/platform.ts               | 20 +++++++++++++++++
 .../claw/components/ChannelPairingStep.tsx    |  9 +++++++-
 .../claw/components/ProvisioningStep.tsx      | 10 +++++++++
 src/hooks/useKiloClaw.ts                      | 10 +++++++++
 src/lib/kiloclaw/kiloclaw-internal-client.ts  |  9 ++++++++
 src/lib/kiloclaw/types.ts                     |  8 +++++++
 src/routers/kiloclaw-router.ts                | 18 +++++++++++++++
 10 files changed, 129 insertions(+), 1 deletion(-)

diff --git a/kiloclaw/src/durable-objects/gateway-controller-types.ts b/kiloclaw/src/durable-objects/gateway-controller-types.ts
index 24a8f5526..a9506638e 100644
--- a/kiloclaw/src/durable-objects/gateway-controller-types.ts
+++ b/kiloclaw/src/durable-objects/gateway-controller-types.ts
@@ -45,6 +45,20 @@ export const ControllerVersionResponseSchema = z.object({
   openclawCommit: z.string().nullable().optional(),
 });
 
+export type ControllerHealthResponse = {
+  status: 'ok';
+  state: 'bootstrapping' | 'starting' | 'ready' | 'degraded';
+  phase?: string;
+  error?: string;
+};
+
+export const ControllerHealthResponseSchema: ZodType<ControllerHealthResponse> = z.object({
+  status: z.literal('ok'),
+  state: z.enum(['bootstrapping', 'starting', 'ready', 'degraded']),
+  phase: z.string().optional(),
+  error: z.string().optional(),
+});
+
 export const EnvPatchResponseSchema = z.object({
   ok: z.boolean(),
   signaled: z.boolean(),
diff --git a/kiloclaw/src/durable-objects/kiloclaw-instance/gateway.ts b/kiloclaw/src/durable-objects/kiloclaw-instance/gateway.ts
index 010890485..f8ae31c02 100644
--- a/kiloclaw/src/durable-objects/kiloclaw-instance/gateway.ts
+++ b/kiloclaw/src/durable-objects/kiloclaw-instance/gateway.ts
@@ -3,10 +3,12 @@ import type { KiloClawEnv } from '../../types';
 import { deriveGatewayToken } from '../../auth/gateway-token';
 import {
   type GatewayProcessStatus,
+  type ControllerHealthResponse,
   GatewayProcessStatusSchema,
   GatewayCommandResponseSchema,
   ConfigRestoreResponseSchema,
   ControllerVersionResponseSchema,
+  ControllerHealthResponseSchema,
   EnvPatchResponseSchema,
   OpenclawConfigResponseSchema,
   GatewayControllerError,
@@ -239,6 +241,26 @@ export async function getControllerVersion(
   }
 }
 
+export async function getControllerHealth(
+  state: InstanceMutableState,
+  env: KiloClawEnv
+): Promise<ControllerHealthResponse | null> {
+  try {
+    return await callGatewayController(
+      state,
+      env,
+      '/_kilo/health',
+      'GET',
+      ControllerHealthResponseSchema
+    );
+  } catch (error) {
+    if (isErrorUnknownRoute(error)) {
+      return null;
+    }
+    throw error;
+  }
+}
+
 /** Returns null if the controller is too old to have the /_kilo/config/read endpoint. */
 export async function getOpenclawConfig(
   state: InstanceMutableState,
diff --git a/kiloclaw/src/durable-objects/kiloclaw-instance/index.ts b/kiloclaw/src/durable-objects/kiloclaw-instance/index.ts
index e631d0f18..ef404b7c2 100644
--- a/kiloclaw/src/durable-objects/kiloclaw-instance/index.ts
+++ b/kiloclaw/src/durable-objects/kiloclaw-instance/index.ts
@@ -1306,6 +1306,16 @@ export class KiloClawInstance extends DurableObject<KiloClawEnv> {
     return gateway.getControllerVersion(this.s, this.env);
   }
 
+  async getControllerHealth(): Promise<{
+    status: 'ok';
+    state: 'bootstrapping' | 'starting' | 'ready' | 'degraded';
+    phase?: string;
+    error?: string;
+  } | null> {
+    await this.loadState();
+    return gateway.getControllerHealth(this.s, this.env);
+  }
+
   async patchConfigOnMachine(patch: Record<string, unknown>): Promise<void> {
     await this.loadState();
     return gateway.patchConfigOnMachine(this.s, this.env, patch);
diff --git a/kiloclaw/src/routes/platform.ts b/kiloclaw/src/routes/platform.ts
index cbe66c375..3bbc6a6b0 100644
--- a/kiloclaw/src/routes/platform.ts
+++ b/kiloclaw/src/routes/platform.ts
@@ -620,6 +620,26 @@ platform.get('/gateway/status', async c => {
   }
 });
 
+// GET /api/platform/controller-health?userId=...
+platform.get('/controller-health', async c => {
+  const userId = setValidatedQueryUserId(c);
+  if (!userId) {
+    return c.json({ error: 'userId query parameter is required' }, 400);
+  }
+
+  try {
+    const result = await withDORetry(
+      instanceStubFactory(c.env, userId),
+      stub => stub.getControllerHealth(),
+      'getControllerHealth'
+    );
+    return c.json(result ?? { status: 'ok', state: 'starting' }, 200);
+  } catch (err) {
+    const { message, status } = sanitizeError(err, 'controller health');
+    return jsonError(message, status);
+  }
+});
+
 // GET /api/platform/controller-version?userId=...
 platform.get('/controller-version', async c => {
   const userId = setValidatedQueryUserId(c);
diff --git a/src/app/(app)/claw/components/ChannelPairingStep.tsx b/src/app/(app)/claw/components/ChannelPairingStep.tsx
index db19c1c18..44f57734a 100644
--- a/src/app/(app)/claw/components/ChannelPairingStep.tsx
+++ b/src/app/(app)/claw/components/ChannelPairingStep.tsx
@@ -3,7 +3,7 @@
 import { useEffect, useRef, useState } from 'react';
 import { CheckCircle2, Loader2, Send, XCircle } from 'lucide-react';
 import { toast } from 'sonner';
-import { useKiloClawPairing, useRefreshPairing } from '@/hooks/useKiloClaw';
+import { useKiloClawPairing, useRefreshPairing, useControllerHealth } from '@/hooks/useKiloClaw';
 import { Button } from '@/components/ui/button';
 import type { ClawMutations } from './claw.types';
 import { OnboardingStepView } from './OnboardingStepView';
@@ -35,6 +35,13 @@ export function ChannelPairingStep({
   onSkip: () => void;
 }) {
   const { data: pairingData } = useKiloClawPairing(true);
+  const { data: controllerHealth } = useControllerHealth(true);
+
+  useEffect(() => {
+    if (controllerHealth) {
+      console.log('[ChannelPairingStep] controller health:', controllerHealth);
+    }
+  }, [controllerHealth]);
 
   const refreshPairing = useRefreshPairing();
   const refreshRef = useRef(refreshPairing);
diff --git a/src/app/(app)/claw/components/ProvisioningStep.tsx b/src/app/(app)/claw/components/ProvisioningStep.tsx
index 42676e2a8..cfcbba524 100644
--- a/src/app/(app)/claw/components/ProvisioningStep.tsx
+++ b/src/app/(app)/claw/components/ProvisioningStep.tsx
@@ -4,6 +4,7 @@ import { useEffect, useRef, useState } from 'react';
 import { Volume2 } from 'lucide-react';
 import { toast } from 'sonner';
 import { Button } from '@/components/ui/button';
+import { useControllerHealth } from '@/hooks/useKiloClaw';
 import {
   type ExecPreset,
   type ClawMutations,
@@ -120,6 +121,15 @@ export function ProvisioningStep({
     );
   }, [instanceRunning, preset]);
 
+  // Poll the controller health endpoint to track bootstrap progress.
+  const { data: controllerHealth } = useControllerHealth(instanceRunning);
+
+  useEffect(() => {
+    if (controllerHealth) {
+      console.log('[ProvisioningStep] controller health:', controllerHealth);
+    }
+  }, [controllerHealth]);
+
   // Advance to the next step only when both the config is applied
   // and the boot delay has elapsed, giving the gateway time to start.
   useEffect(() => {
diff --git a/src/hooks/useKiloClaw.ts b/src/hooks/useKiloClaw.ts
index cd65d71ed..42433a963 100644
--- a/src/hooks/useKiloClaw.ts
+++ b/src/hooks/useKiloClaw.ts
@@ -71,6 +71,16 @@ export function useKiloClawGatewayStatus(enabled: boolean) {
   );
 }
 
+export function useControllerHealth(enabled: boolean) {
+  const trpc = useTRPC();
+  return useQuery(
+    trpc.kiloclaw.controllerHealth.queryOptions(undefined, {
+      enabled,
+      refetchInterval: enabled ? 1_000 : false,
+    })
+  );
+}
+
 export function useControllerVersion(enabled: boolean) {
   const trpc = useTRPC();
   return useQuery(
diff --git a/src/lib/kiloclaw/kiloclaw-internal-client.ts b/src/lib/kiloclaw/kiloclaw-internal-client.ts
index 22f723e14..7b43a4556 100644
--- a/src/lib/kiloclaw/kiloclaw-internal-client.ts
+++ b/src/lib/kiloclaw/kiloclaw-internal-client.ts
@@ -21,6 +21,7 @@ import type {
   GatewayProcessStatusResponse,
   GatewayProcessActionResponse,
   ConfigRestoreResponse,
+  ControllerHealthResponse,
   ControllerVersionResponse,
   OpenclawConfigResponse,
   GoogleCredentialsInput,
@@ -295,6 +296,14 @@ export class KiloClawInternalClient {
     );
   }
 
+  async getControllerHealth(userId: string): Promise<ControllerHealthResponse> {
+    return this.request(
+      `/api/platform/controller-health?userId=${encodeURIComponent(userId)}`,
+      undefined,
+      { userId }
+    );
+  }
+
   async getControllerVersion(userId: string): Promise<ControllerVersionResponse> {
     return this.request(
       `/api/platform/controller-version?userId=${encodeURIComponent(userId)}`,
diff --git a/src/lib/kiloclaw/types.ts b/src/lib/kiloclaw/types.ts
index 1f3e0ef7c..378572fac 100644
--- a/src/lib/kiloclaw/types.ts
+++ b/src/lib/kiloclaw/types.ts
@@ -219,6 +219,14 @@ export type ConfigRestoreResponse = {
   signaled: boolean;
 };
 
+/** Response from GET /api/platform/controller-health */
+export type ControllerHealthResponse = {
+  status: 'ok';
+  state: 'bootstrapping' | 'starting' | 'ready' | 'degraded';
+  phase?: string;
+  error?: string;
+};
+
 /** Response from GET /api/platform/controller-version. Null fields = old controller. */
 export type ControllerVersionResponse = {
   version: string | null;
diff --git a/src/routers/kiloclaw-router.ts b/src/routers/kiloclaw-router.ts
index d08516075..5957bfb23 100644
--- a/src/routers/kiloclaw-router.ts
+++ b/src/routers/kiloclaw-router.ts
@@ -659,6 +659,24 @@ export const kiloclawRouter = createTRPCRouter({
     }
   }),
 
+  controllerHealth: baseProcedure.query(async ({ ctx }) => {
+    try {
+      const client = new KiloClawInternalClient();
+      return await client.getControllerHealth(ctx.user.id);
+    } catch (err) {
+      if (err instanceof KiloClawApiError && (err.statusCode === 404 || err.statusCode === 409)) {
+        throw new TRPCError({
+          code: 'NOT_FOUND',
+          message: 'Controller health unavailable',
+        });
+      }
+      throw new TRPCError({
+        code: 'INTERNAL_SERVER_ERROR',
+        message: 'Failed to fetch controller health',
+      });
+    }
+  }),
+
   controllerVersion: baseProcedure.query(async ({ ctx }) => {
     const client = new KiloClawInternalClient();
     return client.getControllerVersion(ctx.user.id);

From 10062022948a6b30820f9bdd530ca0a87c513c8b Mon Sep 17 00:00:00 2001
From: Remon Oldenbeuving <remon@kilocode.ai>
Date: Tue, 24 Mar 2026 13:14:28 +0100
Subject: [PATCH 09/14] feat(claw): wire gateway /ready endpoint through to
 frontend

Add /_kilo/gateway/ready controller route that fetches /ready from the
OpenClaw gateway at 127.0.0.1:3001 and exposes it through the full
stack. Both ProvisioningStep and ChannelPairingStep now poll both
controller health (/_kilo/health) and gateway ready (/ready) every 1s,
logging both to the browser console for comparison during onboarding.
---
 kiloclaw/controller/src/routes/gateway.ts     | 20 ++++++++++++++++++
 .../gateway-controller-types.ts               |  2 ++
 .../kiloclaw-instance/gateway.ts              | 21 +++++++++++++++++++
 .../kiloclaw-instance/index.ts                |  5 +++++
 kiloclaw/src/routes/platform.ts               | 20 ++++++++++++++++++
 .../claw/components/ChannelPairingStep.tsx    | 14 ++++++++++++-
 .../claw/components/ProvisioningStep.tsx      |  9 +++++++-
 src/hooks/useKiloClaw.ts                      | 10 +++++++++
 src/lib/kiloclaw/kiloclaw-internal-client.ts  |  9 ++++++++
 src/lib/kiloclaw/types.ts                     |  3 +++
 src/routers/kiloclaw-router.ts                | 18 ++++++++++++++++
 11 files changed, 129 insertions(+), 2 deletions(-)

diff --git a/kiloclaw/controller/src/routes/gateway.ts b/kiloclaw/controller/src/routes/gateway.ts
index 7bb2f2e7d..c6b48584d 100644
--- a/kiloclaw/controller/src/routes/gateway.ts
+++ b/kiloclaw/controller/src/routes/gateway.ts
@@ -58,6 +58,26 @@ export function registerGatewayRoutes(
     }
   });
 
+  app.get('/_kilo/gateway/ready', async c => {
+    if (supervisor.getState() !== 'running') {
+      return c.json({ ready: false, error: 'Gateway not running' }, 503);
+    }
+    try {
+      const res = await fetch('http://127.0.0.1:3001/ready');
+      const body = await res.text();
+      let json: unknown;
+      try {
+        json = JSON.parse(body);
+      } catch {
+        json = { raw: body };
+      }
+      return c.json(json, res.ok ? 200 : 503);
+    } catch (error) {
+      console.error('[controller] /_kilo/gateway/ready failed:', error);
+      return c.json({ ready: false, error: 'Failed to reach gateway' }, 502);
+    }
+  });
+
   app.post('/_kilo/gateway/restart', async c => {
     try {
       const restarted = await supervisor.restart();
diff --git a/kiloclaw/src/durable-objects/gateway-controller-types.ts b/kiloclaw/src/durable-objects/gateway-controller-types.ts
index a9506638e..ac4c6d927 100644
--- a/kiloclaw/src/durable-objects/gateway-controller-types.ts
+++ b/kiloclaw/src/durable-objects/gateway-controller-types.ts
@@ -59,6 +59,8 @@ export const ControllerHealthResponseSchema: ZodType<ControllerHealthResponse> =
   error: z.string().optional(),
 });
 
+export const GatewayReadyResponseSchema = z.record(z.string(), z.unknown());
+
 export const EnvPatchResponseSchema = z.object({
   ok: z.boolean(),
   signaled: z.boolean(),
diff --git a/kiloclaw/src/durable-objects/kiloclaw-instance/gateway.ts b/kiloclaw/src/durable-objects/kiloclaw-instance/gateway.ts
index f8ae31c02..22702071b 100644
--- a/kiloclaw/src/durable-objects/kiloclaw-instance/gateway.ts
+++ b/kiloclaw/src/durable-objects/kiloclaw-instance/gateway.ts
@@ -9,6 +9,7 @@ import {
   ConfigRestoreResponseSchema,
   ControllerVersionResponseSchema,
   ControllerHealthResponseSchema,
+  GatewayReadyResponseSchema,
   EnvPatchResponseSchema,
   OpenclawConfigResponseSchema,
   GatewayControllerError,
@@ -261,6 +262,26 @@ export async function getControllerHealth(
   }
 }
 
+export async function getGatewayReady(
+  state: InstanceMutableState,
+  env: KiloClawEnv
+): Promise<Record<string, unknown> | null> {
+  try {
+    return await callGatewayController(
+      state,
+      env,
+      '/_kilo/gateway/ready',
+      'GET',
+      GatewayReadyResponseSchema
+    );
+  } catch (error) {
+    if (isErrorUnknownRoute(error)) {
+      return null;
+    }
+    throw error;
+  }
+}
+
 /** Returns null if the controller is too old to have the /_kilo/config/read endpoint. */
 export async function getOpenclawConfig(
   state: InstanceMutableState,
diff --git a/kiloclaw/src/durable-objects/kiloclaw-instance/index.ts b/kiloclaw/src/durable-objects/kiloclaw-instance/index.ts
index ef404b7c2..40037ecb4 100644
--- a/kiloclaw/src/durable-objects/kiloclaw-instance/index.ts
+++ b/kiloclaw/src/durable-objects/kiloclaw-instance/index.ts
@@ -1316,6 +1316,11 @@ export class KiloClawInstance extends DurableObject<KiloClawEnv> {
     return gateway.getControllerHealth(this.s, this.env);
   }
 
+  async getGatewayReady(): Promise<Record<string, unknown> | null> {
+    await this.loadState();
+    return gateway.getGatewayReady(this.s, this.env);
+  }
+
   async patchConfigOnMachine(patch: Record<string, unknown>): Promise<void> {
     await this.loadState();
     return gateway.patchConfigOnMachine(this.s, this.env, patch);
diff --git a/kiloclaw/src/routes/platform.ts b/kiloclaw/src/routes/platform.ts
index 3bbc6a6b0..a125178fa 100644
--- a/kiloclaw/src/routes/platform.ts
+++ b/kiloclaw/src/routes/platform.ts
@@ -620,6 +620,26 @@ platform.get('/gateway/status', async c => {
   }
 });
 
+// GET /api/platform/gateway/ready?userId=...
+platform.get('/gateway/ready', async c => {
+  const userId = setValidatedQueryUserId(c);
+  if (!userId) {
+    return c.json({ error: 'userId query parameter is required' }, 400);
+  }
+
+  try {
+    const result = await withDORetry(
+      instanceStubFactory(c.env, userId),
+      stub => stub.getGatewayReady(),
+      'getGatewayReady'
+    );
+    return c.json(result ?? { ready: false, error: 'controller too old' }, 200);
+  } catch (err) {
+    const { message, status } = sanitizeError(err, 'gateway ready');
+    return jsonError(message, status);
+  }
+});
+
 // GET /api/platform/controller-health?userId=...
 platform.get('/controller-health', async c => {
   const userId = setValidatedQueryUserId(c);
diff --git a/src/app/(app)/claw/components/ChannelPairingStep.tsx b/src/app/(app)/claw/components/ChannelPairingStep.tsx
index 44f57734a..e0286a826 100644
--- a/src/app/(app)/claw/components/ChannelPairingStep.tsx
+++ b/src/app/(app)/claw/components/ChannelPairingStep.tsx
@@ -3,7 +3,12 @@
 import { useEffect, useRef, useState } from 'react';
 import { CheckCircle2, Loader2, Send, XCircle } from 'lucide-react';
 import { toast } from 'sonner';
-import { useKiloClawPairing, useRefreshPairing, useControllerHealth } from '@/hooks/useKiloClaw';
+import {
+  useKiloClawPairing,
+  useRefreshPairing,
+  useControllerHealth,
+  useGatewayReady,
+} from '@/hooks/useKiloClaw';
 import { Button } from '@/components/ui/button';
 import type { ClawMutations } from './claw.types';
 import { OnboardingStepView } from './OnboardingStepView';
@@ -36,6 +41,7 @@ export function ChannelPairingStep({
 }) {
   const { data: pairingData } = useKiloClawPairing(true);
   const { data: controllerHealth } = useControllerHealth(true);
+  const { data: gatewayReady } = useGatewayReady(true);
 
   useEffect(() => {
     if (controllerHealth) {
@@ -43,6 +49,12 @@ export function ChannelPairingStep({
     }
   }, [controllerHealth]);
 
+  useEffect(() => {
+    if (gatewayReady) {
+      console.log('[ChannelPairingStep] gateway ready:', gatewayReady);
+    }
+  }, [gatewayReady]);
+
   const refreshPairing = useRefreshPairing();
   const refreshRef = useRef(refreshPairing);
   refreshRef.current = refreshPairing;
diff --git a/src/app/(app)/claw/components/ProvisioningStep.tsx b/src/app/(app)/claw/components/ProvisioningStep.tsx
index cfcbba524..88b9b21d8 100644
--- a/src/app/(app)/claw/components/ProvisioningStep.tsx
+++ b/src/app/(app)/claw/components/ProvisioningStep.tsx
@@ -4,7 +4,7 @@ import { useEffect, useRef, useState } from 'react';
 import { Volume2 } from 'lucide-react';
 import { toast } from 'sonner';
 import { Button } from '@/components/ui/button';
-import { useControllerHealth } from '@/hooks/useKiloClaw';
+import { useControllerHealth, useGatewayReady } from '@/hooks/useKiloClaw';
 import {
   type ExecPreset,
   type ClawMutations,
@@ -123,6 +123,7 @@ export function ProvisioningStep({
 
   // Poll the controller health endpoint to track bootstrap progress.
   const { data: controllerHealth } = useControllerHealth(instanceRunning);
+  const { data: gatewayReady } = useGatewayReady(instanceRunning);
 
   useEffect(() => {
     if (controllerHealth) {
@@ -130,6 +131,12 @@ export function ProvisioningStep({
     }
   }, [controllerHealth]);
 
+  useEffect(() => {
+    if (gatewayReady) {
+      console.log('[ProvisioningStep] gateway ready:', gatewayReady);
+    }
+  }, [gatewayReady]);
+
   // Advance to the next step only when both the config is applied
   // and the boot delay has elapsed, giving the gateway time to start.
   useEffect(() => {
diff --git a/src/hooks/useKiloClaw.ts b/src/hooks/useKiloClaw.ts
index 42433a963..65cc9e89c 100644
--- a/src/hooks/useKiloClaw.ts
+++ b/src/hooks/useKiloClaw.ts
@@ -71,6 +71,16 @@ export function useKiloClawGatewayStatus(enabled: boolean) {
   );
 }
 
+export function useGatewayReady(enabled: boolean) {
+  const trpc = useTRPC();
+  return useQuery(
+    trpc.kiloclaw.gatewayReady.queryOptions(undefined, {
+      enabled,
+      refetchInterval: enabled ? 1_000 : false,
+    })
+  );
+}
+
 export function useControllerHealth(enabled: boolean) {
   const trpc = useTRPC();
   return useQuery(
diff --git a/src/lib/kiloclaw/kiloclaw-internal-client.ts b/src/lib/kiloclaw/kiloclaw-internal-client.ts
index 7b43a4556..f352da812 100644
--- a/src/lib/kiloclaw/kiloclaw-internal-client.ts
+++ b/src/lib/kiloclaw/kiloclaw-internal-client.ts
@@ -21,6 +21,7 @@ import type {
   GatewayProcessStatusResponse,
   GatewayProcessActionResponse,
   ConfigRestoreResponse,
+  GatewayReadyResponse,
   ControllerHealthResponse,
   ControllerVersionResponse,
   OpenclawConfigResponse,
@@ -296,6 +297,14 @@ export class KiloClawInternalClient {
     );
   }
 
+  async getGatewayReady(userId: string): Promise<GatewayReadyResponse> {
+    return this.request(
+      `/api/platform/gateway/ready?userId=${encodeURIComponent(userId)}`,
+      undefined,
+      { userId }
+    );
+  }
+
   async getControllerHealth(userId: string): Promise<ControllerHealthResponse> {
     return this.request(
       `/api/platform/controller-health?userId=${encodeURIComponent(userId)}`,
diff --git a/src/lib/kiloclaw/types.ts b/src/lib/kiloclaw/types.ts
index 378572fac..cff77c8eb 100644
--- a/src/lib/kiloclaw/types.ts
+++ b/src/lib/kiloclaw/types.ts
@@ -219,6 +219,9 @@ export type ConfigRestoreResponse = {
   signaled: boolean;
 };
 
+/** Response from GET /api/platform/gateway/ready (opaque — shape depends on OpenClaw version) */
+export type GatewayReadyResponse = Record<string, unknown>;
+
 /** Response from GET /api/platform/controller-health */
 export type ControllerHealthResponse = {
   status: 'ok';
diff --git a/src/routers/kiloclaw-router.ts b/src/routers/kiloclaw-router.ts
index 5957bfb23..878e6f066 100644
--- a/src/routers/kiloclaw-router.ts
+++ b/src/routers/kiloclaw-router.ts
@@ -659,6 +659,24 @@ export const kiloclawRouter = createTRPCRouter({
     }
   }),
 
+  gatewayReady: baseProcedure.query(async ({ ctx }) => {
+    try {
+      const client = new KiloClawInternalClient();
+      return await client.getGatewayReady(ctx.user.id);
+    } catch (err) {
+      if (err instanceof KiloClawApiError && (err.statusCode === 404 || err.statusCode === 409)) {
+        throw new TRPCError({
+          code: 'NOT_FOUND',
+          message: 'Gateway ready check unavailable',
+        });
+      }
+      throw new TRPCError({
+        code: 'INTERNAL_SERVER_ERROR',
+        message: 'Failed to fetch gateway ready state',
+      });
+    }
+  }),
+
   controllerHealth: baseProcedure.query(async ({ ctx }) => {
     try {
       const client = new KiloClawInternalClient();

From a5b77de1149e3437fbdbc934e04faffa1064cd90 Mon Sep 17 00:00:00 2001
From: Remon Oldenbeuving <remon@kilocode.ai>
Date: Tue, 24 Mar 2026 13:39:43 +0100
Subject: [PATCH 10/14] fix(claw): make health/ready polling endpoints
 non-fatal during startup

Return 200 with error details in the body instead of 500 when the
gateway isn't reachable yet. Prevents a wall of errors in the console
and tRPC cache during the bootstrap window.
---
 .../src/durable-objects/kiloclaw-instance/gateway.ts |  6 ++++++
 kiloclaw/src/routes/platform.ts                      | 12 ++++++++----
 src/routers/kiloclaw-router.ts                       |  2 ++
 3 files changed, 16 insertions(+), 4 deletions(-)

diff --git a/kiloclaw/src/durable-objects/kiloclaw-instance/gateway.ts b/kiloclaw/src/durable-objects/kiloclaw-instance/gateway.ts
index 22702071b..48722a18a 100644
--- a/kiloclaw/src/durable-objects/kiloclaw-instance/gateway.ts
+++ b/kiloclaw/src/durable-objects/kiloclaw-instance/gateway.ts
@@ -278,6 +278,12 @@ export async function getGatewayReady(
     if (isErrorUnknownRoute(error)) {
       return null;
     }
+    // During startup the gateway process may not be running yet, producing
+    // a 503 from the controller. Return a descriptive object instead of
+    // throwing so the frontend poll doesn't see a wall of 500s.
+    if (error instanceof GatewayControllerError) {
+      return { ready: false, error: error.message, status: error.status };
+    }
     throw error;
   }
 }
diff --git a/kiloclaw/src/routes/platform.ts b/kiloclaw/src/routes/platform.ts
index a125178fa..db47ffaac 100644
--- a/kiloclaw/src/routes/platform.ts
+++ b/kiloclaw/src/routes/platform.ts
@@ -621,6 +621,8 @@ platform.get('/gateway/status', async c => {
 });
 
 // GET /api/platform/gateway/ready?userId=...
+// Non-fatal polling endpoint — always returns 200 so the frontend poll
+// doesn't generate a wall of errors during startup.
 platform.get('/gateway/ready', async c => {
   const userId = setValidatedQueryUserId(c);
   if (!userId) {
@@ -635,12 +637,14 @@ platform.get('/gateway/ready', async c => {
     );
     return c.json(result ?? { ready: false, error: 'controller too old' }, 200);
   } catch (err) {
-    const { message, status } = sanitizeError(err, 'gateway ready');
-    return jsonError(message, status);
+    const raw = err instanceof Error ? err.message : String(err);
+    return c.json({ ready: false, error: raw }, 200);
   }
 });
 
 // GET /api/platform/controller-health?userId=...
+// Non-fatal polling endpoint — always returns 200 so the frontend poll
+// doesn't generate a wall of errors during startup.
 platform.get('/controller-health', async c => {
   const userId = setValidatedQueryUserId(c);
   if (!userId) {
@@ -655,8 +659,8 @@ platform.get('/controller-health', async c => {
     );
     return c.json(result ?? { status: 'ok', state: 'starting' }, 200);
   } catch (err) {
-    const { message, status } = sanitizeError(err, 'controller health');
-    return jsonError(message, status);
+    const raw = err instanceof Error ? err.message : String(err);
+    return c.json({ status: 'ok', state: 'starting', error: raw }, 200);
   }
 });
 
diff --git a/src/routers/kiloclaw-router.ts b/src/routers/kiloclaw-router.ts
index 878e6f066..b5b2cc914 100644
--- a/src/routers/kiloclaw-router.ts
+++ b/src/routers/kiloclaw-router.ts
@@ -664,6 +664,7 @@ export const kiloclawRouter = createTRPCRouter({
       const client = new KiloClawInternalClient();
       return await client.getGatewayReady(ctx.user.id);
     } catch (err) {
+      console.error('[gatewayReady] error for user:', ctx.user.id, err);
       if (err instanceof KiloClawApiError && (err.statusCode === 404 || err.statusCode === 409)) {
         throw new TRPCError({
           code: 'NOT_FOUND',
@@ -682,6 +683,7 @@ export const kiloclawRouter = createTRPCRouter({
       const client = new KiloClawInternalClient();
       return await client.getControllerHealth(ctx.user.id);
     } catch (err) {
+      console.error('[controllerHealth] error for user:', ctx.user.id, err);
       if (err instanceof KiloClawApiError && (err.statusCode === 404 || err.statusCode === 409)) {
         throw new TRPCError({
           code: 'NOT_FOUND',

From 663ab75c48869e63953b30de1bb6e312bc550da8 Mon Sep 17 00:00:00 2001
From: Remon Oldenbeuving <remon@kilocode.ai>
Date: Tue, 24 Mar 2026 14:08:24 +0100
Subject: [PATCH 11/14] refactor(claw): replace 60s boot delay with gateway
 /ready polling

Wait for the gateway to report ready: true instead of an arbitrary 60s
timeout. Remove console logging from both onboarding steps.
---
 .../claw/components/ChannelPairingStep.tsx    | 21 +----------
 .../claw/components/ProvisioningStep.tsx      | 36 ++++---------------
 2 files changed, 7 insertions(+), 50 deletions(-)

diff --git a/src/app/(app)/claw/components/ChannelPairingStep.tsx b/src/app/(app)/claw/components/ChannelPairingStep.tsx
index e0286a826..db19c1c18 100644
--- a/src/app/(app)/claw/components/ChannelPairingStep.tsx
+++ b/src/app/(app)/claw/components/ChannelPairingStep.tsx
@@ -3,12 +3,7 @@
 import { useEffect, useRef, useState } from 'react';
 import { CheckCircle2, Loader2, Send, XCircle } from 'lucide-react';
 import { toast } from 'sonner';
-import {
-  useKiloClawPairing,
-  useRefreshPairing,
-  useControllerHealth,
-  useGatewayReady,
-} from '@/hooks/useKiloClaw';
+import { useKiloClawPairing, useRefreshPairing } from '@/hooks/useKiloClaw';
 import { Button } from '@/components/ui/button';
 import type { ClawMutations } from './claw.types';
 import { OnboardingStepView } from './OnboardingStepView';
@@ -40,20 +35,6 @@ export function ChannelPairingStep({
   onSkip: () => void;
 }) {
   const { data: pairingData } = useKiloClawPairing(true);
-  const { data: controllerHealth } = useControllerHealth(true);
-  const { data: gatewayReady } = useGatewayReady(true);
-
-  useEffect(() => {
-    if (controllerHealth) {
-      console.log('[ChannelPairingStep] controller health:', controllerHealth);
-    }
-  }, [controllerHealth]);
-
-  useEffect(() => {
-    if (gatewayReady) {
-      console.log('[ChannelPairingStep] gateway ready:', gatewayReady);
-    }
-  }, [gatewayReady]);
 
   const refreshPairing = useRefreshPairing();
   const refreshRef = useRef(refreshPairing);
diff --git a/src/app/(app)/claw/components/ProvisioningStep.tsx b/src/app/(app)/claw/components/ProvisioningStep.tsx
index 88b9b21d8..a23540859 100644
--- a/src/app/(app)/claw/components/ProvisioningStep.tsx
+++ b/src/app/(app)/claw/components/ProvisioningStep.tsx
@@ -4,7 +4,7 @@ import { useEffect, useRef, useState } from 'react';
 import { Volume2 } from 'lucide-react';
 import { toast } from 'sonner';
 import { Button } from '@/components/ui/button';
-import { useControllerHealth, useGatewayReady } from '@/hooks/useKiloClaw';
+import { useGatewayReady } from '@/hooks/useKiloClaw';
 import {
   type ExecPreset,
   type ClawMutations,
@@ -13,11 +13,6 @@ import {
 } from './claw.types';
 import { OnboardingStepView } from './OnboardingStepView';
 
-// Let the instance boot in peace before advancing to the pairing step.
-// Config mutations fire immediately, but we hold onComplete until this
-// timer elapses so the gateway has time to fully initialize.
-const BOOT_DELAY_MS = 60_000;
-
 /** Play a short chime via the Web Audio API. */
 function playChime() {
   try {
@@ -53,7 +48,6 @@ export function ProvisioningStep({
 }) {
   const completedRef = useRef(false);
   const [configReady, setConfigReady] = useState(false);
-  const [bootDelayElapsed, setBootDelayElapsed] = useState(false);
 
   // Keep stable references to callbacks so the effect only re-runs
   // when data values change, not when the parent re-renders or mutation
@@ -69,11 +63,6 @@ export function ProvisioningStep({
   const channelTokensRef = useRef(channelTokens);
   channelTokensRef.current = channelTokens;
 
-  useEffect(() => {
-    const timer = setTimeout(() => setBootDelayElapsed(true), BOOT_DELAY_MS);
-    return () => clearTimeout(timer);
-  }, []);
-
   useEffect(() => {
     if (!instanceRunning || completedRef.current) return;
     completedRef.current = true;
@@ -121,30 +110,17 @@ export function ProvisioningStep({
     );
   }, [instanceRunning, preset]);
 
-  // Poll the controller health endpoint to track bootstrap progress.
-  const { data: controllerHealth } = useControllerHealth(instanceRunning);
+  // Poll the gateway /ready endpoint to know when channels are fully set up.
   const { data: gatewayReady } = useGatewayReady(instanceRunning);
+  const isGatewayReady = gatewayReady?.ready === true;
 
+  // Advance to the next step when both config is applied and gateway reports ready.
   useEffect(() => {
-    if (controllerHealth) {
-      console.log('[ProvisioningStep] controller health:', controllerHealth);
-    }
-  }, [controllerHealth]);
-
-  useEffect(() => {
-    if (gatewayReady) {
-      console.log('[ProvisioningStep] gateway ready:', gatewayReady);
-    }
-  }, [gatewayReady]);
-
-  // Advance to the next step only when both the config is applied
-  // and the boot delay has elapsed, giving the gateway time to start.
-  useEffect(() => {
-    if (configReady && bootDelayElapsed) {
+    if (configReady && isGatewayReady) {
       playChime();
       onCompleteRef.current();
     }
-  }, [configReady, bootDelayElapsed]);
+  }, [configReady, isGatewayReady]);
 
   return <ProvisioningStepView totalSteps={totalSteps} />;
 }

From bd7f4197df5275b3338098dbbf50c367722afd36 Mon Sep 17 00:00:00 2001
From: Remon Oldenbeuving <remon@kilocode.ai>
Date: Tue, 24 Mar 2026 14:12:37 +0100
Subject: [PATCH 12/14] chore(claw): remove unused controllerHealth endpoint
 chain

The controller health polling was only needed for debugging. The
gateway /ready endpoint is the one used for the provisioning gate.
---
 .../kiloclaw-instance/gateway.ts              | 22 -------------------
 .../kiloclaw-instance/index.ts                | 10 ---------
 kiloclaw/src/routes/platform.ts               | 22 -------------------
 .../claw/components/ChannelPairingStep.tsx    |  2 +-
 src/hooks/useKiloClaw.ts                      | 12 +---------
 src/lib/kiloclaw/kiloclaw-internal-client.ts  |  9 --------
 src/lib/kiloclaw/types.ts                     |  8 -------
 src/routers/kiloclaw-router.ts                | 19 ----------------
 8 files changed, 2 insertions(+), 102 deletions(-)

diff --git a/kiloclaw/src/durable-objects/kiloclaw-instance/gateway.ts b/kiloclaw/src/durable-objects/kiloclaw-instance/gateway.ts
index 48722a18a..9a4208ae7 100644
--- a/kiloclaw/src/durable-objects/kiloclaw-instance/gateway.ts
+++ b/kiloclaw/src/durable-objects/kiloclaw-instance/gateway.ts
@@ -3,12 +3,10 @@ import type { KiloClawEnv } from '../../types';
 import { deriveGatewayToken } from '../../auth/gateway-token';
 import {
   type GatewayProcessStatus,
-  type ControllerHealthResponse,
   GatewayProcessStatusSchema,
   GatewayCommandResponseSchema,
   ConfigRestoreResponseSchema,
   ControllerVersionResponseSchema,
-  ControllerHealthResponseSchema,
   GatewayReadyResponseSchema,
   EnvPatchResponseSchema,
   OpenclawConfigResponseSchema,
@@ -242,26 +240,6 @@ export async function getControllerVersion(
   }
 }
 
-export async function getControllerHealth(
-  state: InstanceMutableState,
-  env: KiloClawEnv
-): Promise<ControllerHealthResponse | null> {
-  try {
-    return await callGatewayController(
-      state,
-      env,
-      '/_kilo/health',
-      'GET',
-      ControllerHealthResponseSchema
-    );
-  } catch (error) {
-    if (isErrorUnknownRoute(error)) {
-      return null;
-    }
-    throw error;
-  }
-}
-
 export async function getGatewayReady(
   state: InstanceMutableState,
   env: KiloClawEnv
diff --git a/kiloclaw/src/durable-objects/kiloclaw-instance/index.ts b/kiloclaw/src/durable-objects/kiloclaw-instance/index.ts
index 40037ecb4..ad753f449 100644
--- a/kiloclaw/src/durable-objects/kiloclaw-instance/index.ts
+++ b/kiloclaw/src/durable-objects/kiloclaw-instance/index.ts
@@ -1306,16 +1306,6 @@ export class KiloClawInstance extends DurableObject<KiloClawEnv> {
     return gateway.getControllerVersion(this.s, this.env);
   }
 
-  async getControllerHealth(): Promise<{
-    status: 'ok';
-    state: 'bootstrapping' | 'starting' | 'ready' | 'degraded';
-    phase?: string;
-    error?: string;
-  } | null> {
-    await this.loadState();
-    return gateway.getControllerHealth(this.s, this.env);
-  }
-
   async getGatewayReady(): Promise<Record<string, unknown> | null> {
     await this.loadState();
     return gateway.getGatewayReady(this.s, this.env);
diff --git a/kiloclaw/src/routes/platform.ts b/kiloclaw/src/routes/platform.ts
index db47ffaac..644c57763 100644
--- a/kiloclaw/src/routes/platform.ts
+++ b/kiloclaw/src/routes/platform.ts
@@ -642,28 +642,6 @@ platform.get('/gateway/ready', async c => {
   }
 });
 
-// GET /api/platform/controller-health?userId=...
-// Non-fatal polling endpoint — always returns 200 so the frontend poll
-// doesn't generate a wall of errors during startup.
-platform.get('/controller-health', async c => {
-  const userId = setValidatedQueryUserId(c);
-  if (!userId) {
-    return c.json({ error: 'userId query parameter is required' }, 400);
-  }
-
-  try {
-    const result = await withDORetry(
-      instanceStubFactory(c.env, userId),
-      stub => stub.getControllerHealth(),
-      'getControllerHealth'
-    );
-    return c.json(result ?? { status: 'ok', state: 'starting' }, 200);
-  } catch (err) {
-    const raw = err instanceof Error ? err.message : String(err);
-    return c.json({ status: 'ok', state: 'starting', error: raw }, 200);
-  }
-});
-
 // GET /api/platform/controller-version?userId=...
 platform.get('/controller-version', async c => {
   const userId = setValidatedQueryUserId(c);
diff --git a/src/app/(app)/claw/components/ChannelPairingStep.tsx b/src/app/(app)/claw/components/ChannelPairingStep.tsx
index db19c1c18..686ca13aa 100644
--- a/src/app/(app)/claw/components/ChannelPairingStep.tsx
+++ b/src/app/(app)/claw/components/ChannelPairingStep.tsx
@@ -49,7 +49,7 @@ export function ChannelPairingStep({
         await new Promise(r => setTimeout(r, 1_000));
       }
     }
-    poll();
+    void poll();
     return () => {
       cancelled = true;
     };
diff --git a/src/hooks/useKiloClaw.ts b/src/hooks/useKiloClaw.ts
index 65cc9e89c..e1d2d2ce5 100644
--- a/src/hooks/useKiloClaw.ts
+++ b/src/hooks/useKiloClaw.ts
@@ -76,17 +76,7 @@ export function useGatewayReady(enabled: boolean) {
   return useQuery(
     trpc.kiloclaw.gatewayReady.queryOptions(undefined, {
       enabled,
-      refetchInterval: enabled ? 1_000 : false,
-    })
-  );
-}
-
-export function useControllerHealth(enabled: boolean) {
-  const trpc = useTRPC();
-  return useQuery(
-    trpc.kiloclaw.controllerHealth.queryOptions(undefined, {
-      enabled,
-      refetchInterval: enabled ? 1_000 : false,
+      refetchInterval: enabled ? 5_000 : false,
     })
   );
 }
diff --git a/src/lib/kiloclaw/kiloclaw-internal-client.ts b/src/lib/kiloclaw/kiloclaw-internal-client.ts
index f352da812..983e1e169 100644
--- a/src/lib/kiloclaw/kiloclaw-internal-client.ts
+++ b/src/lib/kiloclaw/kiloclaw-internal-client.ts
@@ -22,7 +22,6 @@ import type {
   GatewayProcessActionResponse,
   ConfigRestoreResponse,
   GatewayReadyResponse,
-  ControllerHealthResponse,
   ControllerVersionResponse,
   OpenclawConfigResponse,
   GoogleCredentialsInput,
@@ -305,14 +304,6 @@ export class KiloClawInternalClient {
     );
   }
 
-  async getControllerHealth(userId: string): Promise<ControllerHealthResponse> {
-    return this.request(
-      `/api/platform/controller-health?userId=${encodeURIComponent(userId)}`,
-      undefined,
-      { userId }
-    );
-  }
-
   async getControllerVersion(userId: string): Promise<ControllerVersionResponse> {
     return this.request(
       `/api/platform/controller-version?userId=${encodeURIComponent(userId)}`,
diff --git a/src/lib/kiloclaw/types.ts b/src/lib/kiloclaw/types.ts
index cff77c8eb..751cca509 100644
--- a/src/lib/kiloclaw/types.ts
+++ b/src/lib/kiloclaw/types.ts
@@ -222,14 +222,6 @@ export type ConfigRestoreResponse = {
 /** Response from GET /api/platform/gateway/ready (opaque — shape depends on OpenClaw version) */
 export type GatewayReadyResponse = Record<string, unknown>;
 
-/** Response from GET /api/platform/controller-health */
-export type ControllerHealthResponse = {
-  status: 'ok';
-  state: 'bootstrapping' | 'starting' | 'ready' | 'degraded';
-  phase?: string;
-  error?: string;
-};
-
 /** Response from GET /api/platform/controller-version. Null fields = old controller. */
 export type ControllerVersionResponse = {
   version: string | null;
diff --git a/src/routers/kiloclaw-router.ts b/src/routers/kiloclaw-router.ts
index b5b2cc914..5157bca10 100644
--- a/src/routers/kiloclaw-router.ts
+++ b/src/routers/kiloclaw-router.ts
@@ -678,25 +678,6 @@ export const kiloclawRouter = createTRPCRouter({
     }
   }),
 
-  controllerHealth: baseProcedure.query(async ({ ctx }) => {
-    try {
-      const client = new KiloClawInternalClient();
-      return await client.getControllerHealth(ctx.user.id);
-    } catch (err) {
-      console.error('[controllerHealth] error for user:', ctx.user.id, err);
-      if (err instanceof KiloClawApiError && (err.statusCode === 404 || err.statusCode === 409)) {
-        throw new TRPCError({
-          code: 'NOT_FOUND',
-          message: 'Controller health unavailable',
-        });
-      }
-      throw new TRPCError({
-        code: 'INTERNAL_SERVER_ERROR',
-        message: 'Failed to fetch controller health',
-      });
-    }
-  }),
-
   controllerVersion: baseProcedure.query(async ({ ctx }) => {
     const client = new KiloClawInternalClient();
     return client.getControllerVersion(ctx.user.id);

From 890118314bc1605e3c37ed81c644d0c677556dd2 Mon Sep 17 00:00:00 2001
From: Remon Oldenbeuving <remon@kilocode.ai>
Date: Tue, 24 Mar 2026 16:51:10 +0100
Subject: [PATCH 13/14] feat(claw): gate provisioning on CPU load settling
 after boot

The /ready endpoint reports readiness before boot CPU pressure subsides.
When the user sends a message immediately after ready: true, the combined
load triggers throttling on the shared-cpu-2x instance.

Add os.loadavg() and a 'settled' boolean to the controller's /ready
response (threshold: 0.1 for ~6% shared CPU allocation), and gate
ProvisioningStep on settled === true so the frontend waits for the
system to actually be idle before advancing.
---
 kiloclaw/controller/src/routes/gateway.ts     | 22 ++++++++++++++++---
 .../claw/components/ProvisioningStep.tsx      | 12 +++++-----
 2 files changed, 26 insertions(+), 8 deletions(-)

diff --git a/kiloclaw/controller/src/routes/gateway.ts b/kiloclaw/controller/src/routes/gateway.ts
index c6b48584d..c0e8954f8 100644
--- a/kiloclaw/controller/src/routes/gateway.ts
+++ b/kiloclaw/controller/src/routes/gateway.ts
@@ -1,7 +1,19 @@
+import os from 'node:os';
 import type { Hono } from 'hono';
 import { timingSafeTokenEqual } from '../auth';
 import type { Supervisor } from '../supervisor';
 
+// shared-cpu-2x gives ~6% of 2 physical cores, so even modest load
+// averages represent heavy pressure. After boot completes, an idle
+// system sits near 0. A threshold of 0.1 ensures boot CPU work has
+// fully subsided before we tell the frontend it's safe to proceed.
+const LOAD_SETTLED_THRESHOLD = 0.1;
+
+function loadFields(): { loadAverage: number[]; settled: boolean } {
+  const loadAverage = os.loadavg();
+  return { loadAverage, settled: loadAverage[0] < LOAD_SETTLED_THRESHOLD };
+}
+
 export function getBearerToken(header: string | undefined): string | null {
   if (!header) return null;
   const [scheme, token] = header.split(/\s+/, 2);
@@ -60,7 +72,7 @@ export function registerGatewayRoutes(
 
   app.get('/_kilo/gateway/ready', async c => {
     if (supervisor.getState() !== 'running') {
-      return c.json({ ready: false, error: 'Gateway not running' }, 503);
+      return c.json({ ready: false, error: 'Gateway not running', ...loadFields() }, 503);
     }
     try {
       const res = await fetch('http://127.0.0.1:3001/ready');
@@ -71,10 +83,14 @@ export function registerGatewayRoutes(
       } catch {
         json = { raw: body };
       }
-      return c.json(json, res.ok ? 200 : 503);
+      const envelope =
+        typeof json === 'object' && json !== null
+          ? { ...json, ...loadFields() }
+          : { raw: json, ...loadFields() };
+      return c.json(envelope, res.ok ? 200 : 503);
     } catch (error) {
       console.error('[controller] /_kilo/gateway/ready failed:', error);
-      return c.json({ ready: false, error: 'Failed to reach gateway' }, 502);
+      return c.json({ ready: false, error: 'Failed to reach gateway', ...loadFields() }, 502);
     }
   });
 
diff --git a/src/app/(app)/claw/components/ProvisioningStep.tsx b/src/app/(app)/claw/components/ProvisioningStep.tsx
index a23540859..3411b4dc0 100644
--- a/src/app/(app)/claw/components/ProvisioningStep.tsx
+++ b/src/app/(app)/claw/components/ProvisioningStep.tsx
@@ -110,17 +110,19 @@ export function ProvisioningStep({
     );
   }, [instanceRunning, preset]);
 
-  // Poll the gateway /ready endpoint to know when channels are fully set up.
+  // Poll the gateway /ready endpoint to know when channels are fully set up
+  // and the system's CPU load has settled after boot.
   const { data: gatewayReady } = useGatewayReady(instanceRunning);
-  const isGatewayReady = gatewayReady?.ready === true;
+  const isGatewaySettled = gatewayReady?.ready === true && gatewayReady?.settled === true;
 
-  // Advance to the next step when both config is applied and gateway reports ready.
+  // Advance to the next step when config is applied, gateway reports ready,
+  // and boot CPU pressure has subsided (settled === true).
   useEffect(() => {
-    if (configReady && isGatewayReady) {
+    if (configReady && isGatewaySettled) {
       playChime();
       onCompleteRef.current();
     }
-  }, [configReady, isGatewayReady]);
+  }, [configReady, isGatewaySettled]);
 
   return <ProvisioningStepView totalSteps={totalSteps} />;
 }

From 923fbedb8956ebfbe6e32e9463f5940cc9ed3c71 Mon Sep 17 00:00:00 2001
From: Remon Oldenbeuving <remon@kilocode.ai>
Date: Wed, 25 Mar 2026 08:25:57 +0100
Subject: [PATCH 14/14] fix(claw): sanitize error in gateway/ready polling
 endpoint

---
 kiloclaw/src/routes/platform.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/kiloclaw/src/routes/platform.ts b/kiloclaw/src/routes/platform.ts
index f305cd1b3..6c0096c48 100644
--- a/kiloclaw/src/routes/platform.ts
+++ b/kiloclaw/src/routes/platform.ts
@@ -637,8 +637,8 @@ platform.get('/gateway/ready', async c => {
     );
     return c.json(result ?? { ready: false, error: 'controller too old' }, 200);
   } catch (err) {
-    const raw = err instanceof Error ? err.message : String(err);
-    return c.json({ ready: false, error: raw }, 200);
+    const { message } = sanitizeError(err, 'gateway ready');
+    return c.json({ ready: false, error: message }, 200);
   }
 });