From bb8a36f7970d7a925a08ee341ccb1d6e3b739c4b Mon Sep 17 00:00:00 2001
From: syn <syn@neonronin.sh>
Date: Mon, 4 May 2026 09:30:35 -0500
Subject: [PATCH 1/9] refactor(kiloclaw): consolidate catch-all proxy blocks
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

All four catch-all paths (/i/:instanceId/*, host-based, cookie-routed,
default personal) now share a single `proxyThroughTarget` helper.
Previously the host branch used the helper while the other three
inlined the same ~130-line HTTP + WebSocket relay; this commit
collapses them onto the helper.

The helper gains optional `unreachableHint` / `startingUpHint`
parameters so the default-personal branch can keep its user-facing
hint strings (these are test-asserted). All other behavior is
preserved — same status codes, same JSON shapes, identical
WebSocket relay semantics.

One pre-existing inconsistency is unified rather than preserved: the
cookie branch used to return `{ error: 'WebSocket upgrade failed' }`
with status 502 when the upstream returned no webSocket. The helper
(and the /i and default branches) return the raw containerResponse in
that case, which is strictly more informative. No test asserted the
cookie-branch-specific response.

src/index.ts: +48 / -393 (net -345).
---
 services/kiloclaw/src/index.ts | 441 ++++-----------------------------
 1 file changed, 48 insertions(+), 393 deletions(-)

diff --git a/services/kiloclaw/src/index.ts b/services/kiloclaw/src/index.ts
index 1b4382462..f26d879cc 100644
--- a/services/kiloclaw/src/index.ts
+++ b/services/kiloclaw/src/index.ts
@@ -159,39 +159,49 @@ function routingTargetUrl(target: ProviderRoutingTarget, pathname: string, searc
 /**
  * Forward an HTTP or WebSocket request through to a provider-routed target.
  *
- * Shared by the host-based branch of the catch-all proxy. The existing
- * cookie-based branch and the `/i/:instanceId/*` route predate this helper
- * and inline the same logic — they can be consolidated in a follow-up.
+ * Shared by all four catch-all proxy branches (`/i/:instanceId/*`, host-based,
+ * cookie-routed, and default personal). `logTag` is prepended to console logs
+ * so failing requests can be traced back to their originating branch.
  *
- * `logTag` is prepended to console logs so failing requests can be traced
- * back to their originating branch.
+ * Optional `unreachableHint` / `startingUpHint` are attached to the 503 JSON
+ * bodies the helper emits when the upstream fetch fails or the container is
+ * still booting. Only the default-personal branch surfaces hints today (tests
+ * assert the specific strings); branches that prefer the bare error
+ * (`{ "error": "Instance not reachable" }`) just omit them.
  */
 async function proxyThroughTarget(opts: {
   request: Request;
   targetUrl: string;
   forwardHeaders: Headers;
   logTag: string;
+  unreachableHint?: string;
+  startingUpHint?: string;
 }): Promise<Response> {
-  const { request, targetUrl, forwardHeaders, logTag } = opts;
+  const { request, targetUrl, forwardHeaders, logTag, unreachableHint, startingUpHint } = opts;
   const isWebSocketRequest = request.headers.get('Upgrade')?.toLowerCase() === 'websocket';
 
+  const unreachableBody: Record<string, string> = { error: 'Instance not reachable' };
+  if (unreachableHint) unreachableBody.hint = unreachableHint;
+  const startingUpBody: Record<string, string> = { error: 'Instance is starting up' };
+  if (startingUpHint) startingUpBody.hint = startingUpHint;
+
   if (isWebSocketRequest) {
     let containerResponse: Response;
     try {
       containerResponse = await fetch(targetUrl, { headers: forwardHeaders });
     } catch (err) {
       console.error(`${logTag} WS fetch failed:`, err);
-      return Response.json(
-        { error: 'Instance not reachable' },
-        { status: 503, headers: { 'Retry-After': '5' } }
-      );
+      return Response.json(unreachableBody, {
+        status: 503,
+        headers: { 'Retry-After': '5' },
+      });
     }
 
     if (containerResponse.status === 502) {
-      return Response.json(
-        { error: 'Instance is starting up' },
-        { status: 503, headers: { 'Retry-After': '5' } }
-      );
+      return Response.json(startingUpBody, {
+        status: 503,
+        headers: { 'Retry-After': '5' },
+      });
     }
 
     const containerWs = containerResponse.webSocket;
@@ -279,10 +289,10 @@ async function proxyThroughTarget(opts: {
     return httpResponse;
   } catch (err) {
     console.error(`${logTag} HTTP fetch failed:`, err);
-    return Response.json(
-      { error: 'Instance not reachable' },
-      { status: 503, headers: { 'Retry-After': '5' } }
-    );
+    return Response.json(unreachableBody, {
+      status: 503,
+      headers: { 'Retry-After': '5' },
+    });
   }
 }
 
@@ -507,117 +517,12 @@ app.all('/i/:instanceId/*', async c => {
     status.runtimeId
   );
 
-  const isWebSocketRequest = c.req.raw.headers.get('Upgrade')?.toLowerCase() === 'websocket';
-
-  if (isWebSocketRequest) {
-    let containerResponse: Response;
-    try {
-      containerResponse = await fetch(targetUrl, { headers: forwardHeaders });
-    } catch (err) {
-      console.error('[PROXY /i] Fly Proxy fetch failed:', err);
-      return c.json(
-        { error: 'Instance not reachable' },
-        { status: 503, headers: { 'Retry-After': '5' } }
-      );
-    }
-
-    if (containerResponse.status === 502) {
-      return c.json(
-        { error: 'Instance is starting up' },
-        { status: 503, headers: { 'Retry-After': '5' } }
-      );
-    }
-
-    const containerWs = containerResponse.webSocket;
-    if (!containerWs) {
-      return containerResponse;
-    }
-
-    const [clientWs, serverWs] = Object.values(new WebSocketPair());
-    serverWs.accept();
-    containerWs.accept();
-
-    let droppedToContainer = 0;
-    let droppedToClient = 0;
-
-    serverWs.addEventListener('message', event => {
-      if (containerWs.readyState === WebSocket.OPEN) {
-        containerWs.send(event.data as string | ArrayBuffer);
-      } else {
-        droppedToContainer++;
-        if (droppedToContainer === 1) {
-          console.warn(
-            '[WS /i] First dropped client->container message (readyState:',
-            containerWs.readyState,
-            ')'
-          );
-        }
-      }
-    });
-    containerWs.addEventListener('message', event => {
-      const data = transformWsMessage(event.data as string | ArrayBuffer);
-      if (serverWs.readyState === WebSocket.OPEN) {
-        serverWs.send(data);
-      } else {
-        droppedToClient++;
-        if (droppedToClient === 1) {
-          console.warn(
-            '[WS /i] First dropped container->client message (readyState:',
-            serverWs.readyState,
-            ')'
-          );
-        }
-      }
-    });
-
-    const logDropSummary = () => {
-      const totalDropped = droppedToClient + droppedToContainer;
-      if (totalDropped > 0) {
-        console.warn(
-          '[WS /i] Connection closed with',
-          totalDropped,
-          'dropped messages (toClient:',
-          droppedToClient,
-          'toContainer:',
-          droppedToContainer,
-          ')'
-        );
-      }
-    };
-
-    serverWs.addEventListener('close', event => {
-      logDropSummary();
-      safeClose(containerWs, event.code, event.reason);
-    });
-    containerWs.addEventListener('close', event => {
-      logDropSummary();
-      safeClose(serverWs, event.code, sanitizeCloseReason(event.reason));
-    });
-    serverWs.addEventListener('error', () => safeClose(containerWs, 1011, 'Client error'));
-    containerWs.addEventListener('error', () => safeClose(serverWs, 1011, 'Container error'));
-
-    return new Response(null, { status: 101, webSocket: clientWs });
-  }
-
-  // HTTP proxy
-  const requestBody = c.req.raw.body ? await c.req.raw.arrayBuffer() : null;
-  try {
-    const httpResponse = await fetch(targetUrl, {
-      method: c.req.raw.method,
-      headers: forwardHeaders,
-      body: requestBody,
-    });
-    if (httpResponse.status === 502) {
-      return startingUpPage();
-    }
-    return httpResponse;
-  } catch (err) {
-    console.error('[PROXY /i] HTTP fetch failed:', err);
-    return c.json(
-      { error: 'Instance not reachable' },
-      { status: 503, headers: { 'Retry-After': '5' } }
-    );
-  }
+  return proxyThroughTarget({
+    request: c.req.raw,
+    targetUrl,
+    forwardHeaders,
+    logTag: '[PROXY /i]',
+  });
 });
 
 // =============================================================================
@@ -977,117 +882,12 @@ app.all('*', async c => {
             providerHeaders: routingTarget.headers,
           });
 
-          const isWebSocketRequest = request.headers.get('Upgrade')?.toLowerCase() === 'websocket';
-
-          if (isWebSocketRequest) {
-            let containerResponse: Response;
-            try {
-              containerResponse = await fetch(targetUrl, { headers: forwardHeaders });
-            } catch (err) {
-              console.error('[PROXY] Cookie-routed WS fetch failed:', err);
-              return c.json(
-                { error: 'Instance not reachable' },
-                { status: 503, headers: { 'Retry-After': '5' } }
-              );
-            }
-
-            if (containerResponse.status === 502) {
-              return c.json(
-                { error: 'Instance is starting up' },
-                { status: 503, headers: { 'Retry-After': '5' } }
-              );
-            }
-
-            const containerWs = containerResponse.webSocket;
-            if (!containerWs) {
-              return c.json({ error: 'WebSocket upgrade failed' }, 502);
-            }
-            containerWs.accept();
-            const [clientWs, serverWs] = Object.values(new WebSocketPair());
-            serverWs.accept();
-
-            let cookieDroppedToContainer = 0;
-            let cookieDroppedToClient = 0;
-
-            serverWs.addEventListener('message', event => {
-              if (containerWs.readyState === WebSocket.OPEN) {
-                containerWs.send(event.data as string | ArrayBuffer);
-              } else {
-                cookieDroppedToContainer++;
-                if (cookieDroppedToContainer === 1) {
-                  console.warn(
-                    '[WS cookie] First dropped client->container message (readyState:',
-                    containerWs.readyState,
-                    ')'
-                  );
-                }
-              }
-            });
-            containerWs.addEventListener('message', event => {
-              const data = transformWsMessage(event.data as string | ArrayBuffer);
-              if (serverWs.readyState === WebSocket.OPEN) {
-                serverWs.send(data);
-              } else {
-                cookieDroppedToClient++;
-                if (cookieDroppedToClient === 1) {
-                  console.warn(
-                    '[WS cookie] First dropped container->client message (readyState:',
-                    serverWs.readyState,
-                    ')'
-                  );
-                }
-              }
-            });
-
-            const logCookieDropSummary = () => {
-              const totalDropped = cookieDroppedToClient + cookieDroppedToContainer;
-              if (totalDropped > 0) {
-                console.warn(
-                  '[WS cookie] Connection closed with',
-                  totalDropped,
-                  'dropped messages (toClient:',
-                  cookieDroppedToClient,
-                  'toContainer:',
-                  cookieDroppedToContainer,
-                  ')'
-                );
-              }
-            };
-
-            serverWs.addEventListener('close', event => {
-              logCookieDropSummary();
-              safeClose(containerWs, event.code, event.reason);
-            });
-            containerWs.addEventListener('close', event => {
-              logCookieDropSummary();
-              safeClose(serverWs, event.code, sanitizeCloseReason(event.reason));
-            });
-            serverWs.addEventListener('error', () => safeClose(containerWs, 1011, 'Client error'));
-            containerWs.addEventListener('error', () =>
-              safeClose(serverWs, 1011, 'Container error')
-            );
-            return new Response(null, { status: 101, webSocket: clientWs });
-          }
-
-          // HTTP proxy
-          const requestBody = request.body ? await request.arrayBuffer() : null;
-          try {
-            const httpResponse = await fetch(targetUrl, {
-              method: request.method,
-              headers: forwardHeaders,
-              body: requestBody,
-            });
-            if (httpResponse.status === 502) {
-              return startingUpPage();
-            }
-            return httpResponse;
-          } catch (err) {
-            console.error('[PROXY] Cookie-routed HTTP fetch failed:', err);
-            return c.json(
-              { error: 'Instance not reachable' },
-              { status: 503, headers: { 'Retry-After': '5' } }
-            );
-          }
+          return proxyThroughTarget({
+            request,
+            targetUrl,
+            forwardHeaders,
+            logTag: '[PROXY cookie]',
+          });
         }
       }
     }
@@ -1155,8 +955,6 @@ app.all('*', async c => {
 
   console.log('[PROXY] Handling request:', url.pathname, 'runtime:', runtimeId);
 
-  const isWebSocketRequest = request.headers.get('Upgrade')?.toLowerCase() === 'websocket';
-
   if (!c.env.GATEWAY_TOKEN_SECRET) {
     console.error('[CONFIG] Missing required environment variables: GATEWAY_TOKEN_SECRET');
     return c.json(
@@ -1176,157 +974,14 @@ app.all('*', async c => {
     providerHeaders: routingTarget.headers,
   });
 
-  // WebSocket proxy
-  if (isWebSocketRequest) {
-    console.log('[WS] Proxying WebSocket connection to OpenClaw via Fly Proxy');
-
-    let containerResponse: Response;
-    try {
-      containerResponse = await fetch(targetUrl, {
-        headers: forwardHeaders,
-      });
-    } catch (err) {
-      console.error('[WS] Fly Proxy fetch failed:', err);
-      return c.json(
-        {
-          error: 'Instance not reachable',
-          hint: 'Your instance may not be running. Start it from the dashboard.',
-        },
-        { status: 503, headers: { 'Retry-After': '5' } }
-      );
-    }
-    console.log('[WS] Fly Proxy response status:', containerResponse.status);
-
-    // Gateway not ready yet — return a clear JSON error for WebSocket clients
-    if (containerResponse.status === 502) {
-      return c.json(
-        {
-          error: 'Instance is starting up',
-          hint: 'The gateway process is still initializing. Please retry shortly.',
-        },
-        { status: 503, headers: { 'Retry-After': '5' } }
-      );
-    }
-
-    const containerWs = containerResponse.webSocket;
-    if (!containerWs) {
-      console.error('[WS] No WebSocket in response - returning direct response');
-      return containerResponse;
-    }
-
-    const [clientWs, serverWs] = Object.values(new WebSocketPair());
-
-    serverWs.accept();
-    containerWs.accept();
-
-    let catchAllDroppedToContainer = 0;
-    let catchAllDroppedToClient = 0;
-
-    // Client -> Container relay
-    serverWs.addEventListener('message', event => {
-      if (containerWs.readyState === WebSocket.OPEN) {
-        containerWs.send(event.data as string | ArrayBuffer);
-      } else {
-        catchAllDroppedToContainer++;
-        if (catchAllDroppedToContainer === 1) {
-          console.warn(
-            '[WS] First dropped client->container message (readyState:',
-            containerWs.readyState,
-            ')'
-          );
-        }
-      }
-    });
-
-    // Container -> Client relay with error transformation
-    containerWs.addEventListener('message', event => {
-      const data = transformWsMessage(event.data as string | ArrayBuffer);
-      if (serverWs.readyState === WebSocket.OPEN) {
-        serverWs.send(data);
-      } else {
-        catchAllDroppedToClient++;
-        if (catchAllDroppedToClient === 1) {
-          console.warn(
-            '[WS] First dropped container->client message (readyState:',
-            serverWs.readyState,
-            ')'
-          );
-        }
-      }
-    });
-
-    const logCatchAllDropSummary = () => {
-      const totalDropped = catchAllDroppedToClient + catchAllDroppedToContainer;
-      if (totalDropped > 0) {
-        console.warn(
-          '[WS] Connection closed with',
-          totalDropped,
-          'dropped messages (toClient:',
-          catchAllDroppedToClient,
-          'toContainer:',
-          catchAllDroppedToContainer,
-          ')'
-        );
-      }
-    };
-
-    // Close relay
-    serverWs.addEventListener('close', event => {
-      logCatchAllDropSummary();
-      safeClose(containerWs, event.code, event.reason);
-    });
-
-    containerWs.addEventListener('close', event => {
-      logCatchAllDropSummary();
-      safeClose(serverWs, event.code, sanitizeCloseReason(event.reason));
-    });
-
-    // Error relay
-    serverWs.addEventListener('error', event => {
-      console.error('[WS] Client error:', event);
-      safeClose(containerWs, 1011, 'Client error');
-    });
-
-    containerWs.addEventListener('error', event => {
-      console.error('[WS] Container error:', event);
-      safeClose(serverWs, 1011, 'Container error');
-    });
-
-    return new Response(null, {
-      status: 101,
-      webSocket: clientWs,
-    });
-  }
-
-  // HTTP proxy
-  // Buffer body upfront so it can be replayed on crash-recovery retry (streams are one-shot).
-  const requestBody = request.body ? await request.arrayBuffer() : null;
-  console.log('[HTTP] Proxying:', url.pathname + url.search);
-  let httpResponse: Response;
-  try {
-    httpResponse = await fetch(targetUrl, {
-      method: request.method,
-      headers: forwardHeaders,
-      body: requestBody,
-    });
-  } catch (err) {
-    console.error('[HTTP] Fly Proxy fetch failed:', err);
-    return c.json(
-      {
-        error: 'Instance not reachable',
-        hint: 'Your instance may not be running. Start it from the dashboard.',
-      },
-      { status: 503, headers: { 'Retry-After': '5' } }
-    );
-  }
-  console.log('[HTTP] Response status:', httpResponse.status);
-
-  // Gateway not ready yet — show friendly "starting up" page instead of raw 502
-  if (httpResponse.status === 502) {
-    return startingUpPage();
-  }
-
-  return httpResponse;
+  return proxyThroughTarget({
+    request,
+    targetUrl,
+    forwardHeaders,
+    logTag: '[PROXY default]',
+    unreachableHint: 'Your instance may not be running. Start it from the dashboard.',
+    startingUpHint: 'The gateway process is still initializing. Please retry shortly.',
+  });
 });
 
 export default class extends WorkerEntrypoint<KiloClawEnv> {

From 410191e84c9e79776e5b18077b1a0d8a87e86773 Mon Sep 17 00:00:00 2001
From: syn <syn@neonronin.sh>
Date: Mon, 4 May 2026 09:55:20 -0500
Subject: [PATCH 2/9] refactor(worker-utils): host label + sandbox-id helpers
 for cross-package reuse

Move the pure sandboxId <-> hostname-label logic (plus sandboxId <-> userId
encoding) from `services/kiloclaw/src/auth/` into
`@kilocode/worker-utils` so `apps/web` can use it to mint per-instance
URLs in PR3 without duplicating the base64url / base32hex encoding.

- New subpath exports: `@kilocode/worker-utils/hostname-label` and
  `@kilocode/worker-utils/sandbox-id`.
- The existing `services/kiloclaw/src/auth/hostname-label.ts` and
  `sandbox-id.ts` become thin re-export shims so the many existing
  `./auth/hostname-label` / `./auth/sandbox-id` imports inside the
  worker don't have to migrate all at once.
- Tests move with the implementation.

No behaviour change.
---
 packages/worker-utils/package.json            |   2 +
 .../worker-utils/src}/hostname-label.test.ts  |   6 +-
 packages/worker-utils/src/hostname-label.ts   | 240 +++++++++++++++++
 packages/worker-utils/src/sandbox-id.ts       |  50 ++++
 services/kiloclaw/src/auth/hostname-label.ts  | 251 ++----------------
 services/kiloclaw/src/auth/sandbox-id.ts      |  58 +---
 6 files changed, 322 insertions(+), 285 deletions(-)
 rename {services/kiloclaw/src/auth => packages/worker-utils/src}/hostname-label.test.ts (98%)
 create mode 100644 packages/worker-utils/src/hostname-label.ts
 create mode 100644 packages/worker-utils/src/sandbox-id.ts

diff --git a/packages/worker-utils/package.json b/packages/worker-utils/package.json
index 5a9540a46..8523d8263 100644
--- a/packages/worker-utils/package.json
+++ b/packages/worker-utils/package.json
@@ -6,6 +6,8 @@
   "exports": {
     ".": "./src/index.ts",
     "./instance-id": "./src/instance-id.ts",
+    "./sandbox-id": "./src/sandbox-id.ts",
+    "./hostname-label": "./src/hostname-label.ts",
     "./redact-headers": "./src/redact-headers.ts",
     "./kiloclaw-billing-observability": "./src/kiloclaw-billing-observability.ts"
   },
diff --git a/services/kiloclaw/src/auth/hostname-label.test.ts b/packages/worker-utils/src/hostname-label.test.ts
similarity index 98%
rename from services/kiloclaw/src/auth/hostname-label.test.ts
rename to packages/worker-utils/src/hostname-label.test.ts
index 961347151..fb36408f7 100644
--- a/services/kiloclaw/src/auth/hostname-label.test.ts
+++ b/packages/worker-utils/src/hostname-label.test.ts
@@ -1,13 +1,13 @@
 import { describe, it, expect } from 'vitest';
-import { sandboxIdFromUserId } from './sandbox-id';
-import { sandboxIdFromInstanceId } from '@kilocode/worker-utils/instance-id';
+import { sandboxIdFromUserId } from './sandbox-id.js';
+import { sandboxIdFromInstanceId } from './instance-id.js';
 import {
   hostnameLabelFromSandboxId,
   sandboxIdFromHostnameLabel,
   instanceUrl,
   parseInstanceHost,
   MAX_HOSTNAME_LABEL_LENGTH,
-} from './hostname-label';
+} from './hostname-label.js';
 
 describe('hostnameLabelFromSandboxId', () => {
   it('maps an instance-keyed sandboxId to `i-{32hex}`', () => {
diff --git a/packages/worker-utils/src/hostname-label.ts b/packages/worker-utils/src/hostname-label.ts
new file mode 100644
index 000000000..5957fb78d
--- /dev/null
+++ b/packages/worker-utils/src/hostname-label.ts
@@ -0,0 +1,240 @@
+/**
+ * Hostname label <-> sandboxId translation for per-instance virtual hosting
+ * on `*.kiloclaw.ai` (or a configured dev-suffix).
+ *
+ * Two instance shapes map to two label prefixes:
+ *
+ *   instance-keyed sandboxId  "ki_{32hex}"       <->  "i-{32hex}"
+ *   legacy sandboxId          base64url(userId)   <->  "u-{base32hex(userId)}"
+ *
+ * Prefix disambiguates the two cases without a database lookup.
+ *
+ * The per-instance URL used to inject per-instance origins into
+ * `OPENCLAW_ALLOWED_ORIGINS` and (post-PR2) to route incoming requests by
+ * `Host` is built from two env-configurable pieces:
+ *
+ *   KILOCLAW_INSTANCE_HOST_SUFFIX  default ".kiloclaw.ai"
+ *   KILOCLAW_INSTANCE_URL_SCHEME   default "https"
+ *
+ * Dev parity: set the suffix to `.kiloclaw.localhost:8795` and the scheme to
+ * `http` and the worker will both inject `http://<label>.kiloclaw.localhost:8795`
+ * into the container's origin allowlist and route requests matching that
+ * host to the owning DO. `.kiloclaw.localhost` auto-resolves to 127.0.0.1 on
+ * modern OSes + browsers per RFC 6761, so no `/etc/hosts` edit is required.
+ */
+
+import { isInstanceKeyedSandboxId } from './instance-id.js';
+
+/** RFC 1035 max label length. */
+export const MAX_HOSTNAME_LABEL_LENGTH = 63;
+
+/** Narrow view of the env bindings consumed by `instanceUrl` / `parseInstanceHost`. */
+export type HostSuffixEnv = {
+  KILOCLAW_INSTANCE_HOST_SUFFIX?: string;
+  KILOCLAW_INSTANCE_URL_SCHEME?: string;
+};
+
+/**
+ * No silent fallback: a misconfigured worker should fail loudly rather than
+ * inject `.kiloclaw.ai` / `https` into machine origins that were supposed to
+ * use a preview-specific or dev suffix. The canonical production values live
+ * in `services/kiloclaw/wrangler.jsonc` under `vars`, so this only throws
+ * when the var was explicitly cleared (unit test fixtures, malformed
+ * preview config, etc.). `validateRequiredEnv` on the catch-all middleware
+ * chain rejects requests with a 503 before this path is reached in a
+ * normal request flow.
+ */
+function requireEnv(env: HostSuffixEnv, key: keyof HostSuffixEnv): string {
+  const value = env[key];
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`${key} is not set; refuse to fall back to a default host suffix/scheme`);
+  }
+  return value;
+}
+
+function hostSuffix(env: HostSuffixEnv): string {
+  return requireEnv(env, 'KILOCLAW_INSTANCE_HOST_SUFFIX');
+}
+
+function urlScheme(env: HostSuffixEnv): string {
+  return requireEnv(env, 'KILOCLAW_INSTANCE_URL_SCHEME');
+}
+
+const BASE32_HEX_ALPHABET = '0123456789abcdefghijklmnopqrstuv';
+const INSTANCE_KEYED_BODY_RE = /^[0-9a-f]{32}$/;
+
+const INSTANCE_LABEL_RE = /^i-([0-9a-f]{32})$/;
+const USER_LABEL_RE = /^u-([0-9a-v]+)$/;
+
+function bytesToBase64url(bytes: Uint8Array): string {
+  const binString = Array.from(bytes, b => String.fromCodePoint(b)).join('');
+  return btoa(binString).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+function base64urlToBytes(encoded: string): Uint8Array | null {
+  try {
+    let b64 = encoded.replace(/-/g, '+').replace(/_/g, '/');
+    while (b64.length % 4 !== 0) {
+      b64 += '=';
+    }
+    const binString = atob(b64);
+    const bytes = Uint8Array.from(binString, c => c.codePointAt(0) ?? 0);
+    return bytesToBase64url(bytes) === encoded ? bytes : null;
+  } catch {
+    return null;
+  }
+}
+
+function bytesToBase32Hex(bytes: Uint8Array): string {
+  let output = '';
+  let buffer = 0;
+  let bits = 0;
+
+  for (const byte of bytes) {
+    buffer = (buffer << 8) | byte;
+    bits += 8;
+
+    while (bits >= 5) {
+      bits -= 5;
+      output += BASE32_HEX_ALPHABET[(buffer >> bits) & 31];
+    }
+  }
+
+  if (bits > 0) {
+    output += BASE32_HEX_ALPHABET[(buffer << (5 - bits)) & 31];
+  }
+
+  return output;
+}
+
+function base32HexToBytes(encoded: string): Uint8Array | null {
+  const bytes: number[] = [];
+  let buffer = 0;
+  let bits = 0;
+
+  for (const char of encoded) {
+    const value = BASE32_HEX_ALPHABET.indexOf(char);
+    if (value === -1) return null;
+
+    buffer = (buffer << 5) | value;
+    bits += 5;
+
+    while (bits >= 8) {
+      bits -= 8;
+      bytes.push((buffer >> bits) & 255);
+    }
+  }
+
+  const decoded = Uint8Array.from(bytes);
+  return bytesToBase32Hex(decoded) === encoded ? decoded : null;
+}
+
+/**
+ * Produce a DNS-safe hostname label for `<label>.kiloclaw.ai` from a
+ * sandboxId, or `null` if the sandboxId can't be represented as a safe
+ * label (e.g. pathological Unicode userId whose base64url encoding
+ * contains non-alnum chars, or a label that would exceed 63 chars).
+ *
+ * Callers should treat `null` as "no per-instance origin available for
+ * this sandbox" and fall back to the shared origin list.
+ */
+export function hostnameLabelFromSandboxId(sandboxId: string): string | null {
+  if (isInstanceKeyedSandboxId(sandboxId)) {
+    const body = sandboxId.slice(3);
+    if (!INSTANCE_KEYED_BODY_RE.test(body)) return null;
+    const label = `i-${body}`;
+    if (label.length > MAX_HOSTNAME_LABEL_LENGTH) return null;
+    return label;
+  }
+
+  const legacyUserIdBytes = base64urlToBytes(sandboxId);
+  if (!legacyUserIdBytes || legacyUserIdBytes.length === 0) return null;
+
+  const label = `u-${bytesToBase32Hex(legacyUserIdBytes)}`;
+  if (label.length > MAX_HOSTNAME_LABEL_LENGTH) return null;
+  return label;
+}
+
+/**
+ * Reverse of `hostnameLabelFromSandboxId`: parse a hostname label back
+ * into its sandboxId, returning `null` if the label doesn't match either
+ * scheme.
+ *
+ * Used by the host-based router in a follow-up PR to resolve
+ * `<label>.kiloclaw.ai` to the owning Instance DO.
+ */
+export function sandboxIdFromHostnameLabel(label: string): string | null {
+  const normalized = label.toLowerCase();
+  const instanceMatch = INSTANCE_LABEL_RE.exec(normalized);
+  if (instanceMatch) return `ki_${instanceMatch[1]}`;
+
+  const userMatch = USER_LABEL_RE.exec(normalized);
+  if (userMatch) {
+    const body = userMatch[1];
+    if (body.length + 2 > MAX_HOSTNAME_LABEL_LENGTH) return null;
+    const bytes = base32HexToBytes(body);
+    if (!bytes) return null;
+    return bytesToBase64url(bytes);
+  }
+
+  return null;
+}
+
+/**
+ * Build the per-instance URL (no path, no query) for the given label.
+ *
+ *   instanceUrl('i-abc', { KILOCLAW_INSTANCE_HOST_SUFFIX: '.kiloclaw.ai' })
+ *     => 'https://i-abc.kiloclaw.ai'
+ *   instanceUrl('i-abc', {
+ *     KILOCLAW_INSTANCE_HOST_SUFFIX: '.kiloclaw.localhost:8795',
+ *     KILOCLAW_INSTANCE_URL_SCHEME: 'http',
+ *   })
+ *     => 'http://i-abc.kiloclaw.localhost:8795'
+ *
+ * Used by the per-instance origin injector in `gateway/env.ts` and by any
+ * code that needs to mint the canonical user-facing host for an instance.
+ */
+export function instanceUrl(label: string, env: HostSuffixEnv): string {
+  return `${urlScheme(env)}://${label}${hostSuffix(env)}`;
+}
+
+/**
+ * Does the given host fall within the per-instance virtual-host space?
+ * True for anything ending in the configured suffix, including malformed
+ * cases (bare suffix, multi-label, unparseable label). Callers use this
+ * to decide whether the request should be handled by the host-based
+ * branch (which may still return 404) or fall through to cookie-based
+ * routing. Case-insensitive.
+ */
+export function hostMatchesInstanceSuffix(host: string, env: HostSuffixEnv): boolean {
+  return host.toLowerCase().endsWith(hostSuffix(env).toLowerCase());
+}
+
+/**
+ * Extract the hostname label from an incoming `Host` header if the host
+ * matches the configured instance-host suffix. Returns `null` if:
+ *
+ *   - the host doesn't end with the configured suffix
+ *   - the portion preceding the suffix is empty (e.g. ".kiloclaw.ai")
+ *   - the portion preceding the suffix contains a dot, i.e. multi-label
+ *     subdomain like `foo.bar.kiloclaw.ai`
+ *
+ * The suffix can legitimately contain a port in dev (`.kiloclaw.localhost:8795`),
+ * so we use raw suffix comparison rather than DNS-only parsing. The input
+ * host should be the full value of the `Host` header / `URL.host`, including
+ * any `:port` component.
+ *
+ * Case-insensitive: DNS is case-insensitive and CDNs/proxies may rewrite
+ * case. The returned label is lowercased so callers can run it through
+ * `sandboxIdFromHostnameLabel` (which also lowercases, but doing it here
+ * makes the behaviour explicit).
+ */
+export function parseInstanceHost(host: string, env: HostSuffixEnv): string | null {
+  const suffix = hostSuffix(env).toLowerCase();
+  const normalized = host.toLowerCase();
+  if (!normalized.endsWith(suffix)) return null;
+  const label = normalized.slice(0, -suffix.length);
+  if (label.length === 0) return null;
+  if (label.includes('.')) return null;
+  return label;
+}
diff --git a/packages/worker-utils/src/sandbox-id.ts b/packages/worker-utils/src/sandbox-id.ts
new file mode 100644
index 000000000..8f6beebf6
--- /dev/null
+++ b/packages/worker-utils/src/sandbox-id.ts
@@ -0,0 +1,50 @@
+/**
+ * Reversible base64url encoding of userId into sandboxId.
+ *
+ * NOT the cloud-agent-next SHA-256 pattern -- we need to recover userId
+ * from sandboxId in lifecycle hooks without a DB lookup.
+ *
+ * Uses TextEncoder/TextDecoder so non-Latin1 userIds (e.g. Unicode from
+ * some IdPs) don't throw at runtime. ASCII userIds encode identically
+ * to the old btoa() approach.
+ *
+ * No prefix -- the full 63-char sandboxId limit is available.
+ */
+
+const MAX_SANDBOX_ID_LENGTH = 63;
+
+function bytesToBase64url(bytes: Uint8Array): string {
+  const binString = Array.from(bytes, b => String.fromCodePoint(b)).join('');
+  return btoa(binString).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+function base64urlToBytes(encoded: string): Uint8Array {
+  let b64 = encoded.replace(/-/g, '+').replace(/_/g, '/');
+  while (b64.length % 4 !== 0) {
+    b64 += '=';
+  }
+  const binString = atob(b64);
+  return Uint8Array.from(binString, c => c.codePointAt(0) ?? 0);
+}
+
+export function sandboxIdFromUserId(userId: string): string {
+  const bytes = new TextEncoder().encode(userId);
+  const encoded = bytesToBase64url(bytes);
+  if (encoded.length > MAX_SANDBOX_ID_LENGTH) {
+    throw new Error(
+      `userId too long: encoded sandboxId would be ${encoded.length} chars (max ${MAX_SANDBOX_ID_LENGTH})`
+    );
+  }
+  return encoded;
+}
+
+export function userIdFromSandboxId(sandboxId: string): string {
+  const bytes = base64urlToBytes(sandboxId);
+  return new TextDecoder('utf-8', { fatal: false, ignoreBOM: true }).decode(bytes);
+}
+
+// ─── Instance-scoped identity ───────────────────────────────────────
+// Canonical implementation lives in ./instance-id; re-exported here for
+// convenience so callers get both shapes from one module.
+
+export { isValidInstanceId, sandboxIdFromInstanceId } from './instance-id.js';
diff --git a/services/kiloclaw/src/auth/hostname-label.ts b/services/kiloclaw/src/auth/hostname-label.ts
index e6750bb95..7fd445a4c 100644
--- a/services/kiloclaw/src/auth/hostname-label.ts
+++ b/services/kiloclaw/src/auth/hostname-label.ts
@@ -1,240 +1,19 @@
 /**
- * Hostname label <-> sandboxId translation for per-instance virtual hosting
- * on `*.kiloclaw.ai` (or a configured dev-suffix).
+ * Hostname label helpers.
  *
- * Two instance shapes map to two label prefixes:
- *
- *   instance-keyed sandboxId  "ki_{32hex}"       <->  "i-{32hex}"
- *   legacy sandboxId          base64url(userId)   <->  "u-{base32hex(userId)}"
- *
- * Prefix disambiguates the two cases without a database lookup.
- *
- * The per-instance URL used to inject per-instance origins into
- * `OPENCLAW_ALLOWED_ORIGINS` and (post-PR2) to route incoming requests by
- * `Host` is built from two env-configurable pieces:
- *
- *   KILOCLAW_INSTANCE_HOST_SUFFIX  default ".kiloclaw.ai"
- *   KILOCLAW_INSTANCE_URL_SCHEME   default "https"
- *
- * Dev parity: set the suffix to `.kiloclaw.localhost:8795` and the scheme to
- * `http` and the worker will both inject `http://<label>.kiloclaw.localhost:8795`
- * into the container's origin allowlist and route requests matching that
- * host to the owning DO. `.kiloclaw.localhost` auto-resolves to 127.0.0.1 on
- * modern OSes + browsers per RFC 6761, so no `/etc/hosts` edit is required.
- */
-
-import { isInstanceKeyedSandboxId } from '@kilocode/worker-utils/instance-id';
-
-/** RFC 1035 max label length. */
-export const MAX_HOSTNAME_LABEL_LENGTH = 63;
-
-/** Narrow view of the env bindings consumed by `instanceUrl` / `parseInstanceHost`. */
-export type HostSuffixEnv = {
-  KILOCLAW_INSTANCE_HOST_SUFFIX?: string;
-  KILOCLAW_INSTANCE_URL_SCHEME?: string;
-};
-
-/**
- * No silent fallback: a misconfigured worker should fail loudly rather than
- * inject `.kiloclaw.ai` / `https` into machine origins that were supposed to
- * use a preview-specific or dev suffix. The canonical production values live
- * in `services/kiloclaw/wrangler.jsonc` under `vars`, so this only throws
- * when the var was explicitly cleared (unit test fixtures, malformed
- * preview config, etc.). `validateRequiredEnv` on the catch-all middleware
- * chain rejects requests with a 503 before this path is reached in a
- * normal request flow.
- */
-function requireEnv(env: HostSuffixEnv, key: keyof HostSuffixEnv): string {
-  const value = env[key];
-  if (typeof value !== 'string' || value.length === 0) {
-    throw new Error(`${key} is not set; refuse to fall back to a default host suffix/scheme`);
-  }
-  return value;
-}
-
-function hostSuffix(env: HostSuffixEnv): string {
-  return requireEnv(env, 'KILOCLAW_INSTANCE_HOST_SUFFIX');
-}
-
-function urlScheme(env: HostSuffixEnv): string {
-  return requireEnv(env, 'KILOCLAW_INSTANCE_URL_SCHEME');
-}
-
-const BASE32_HEX_ALPHABET = '0123456789abcdefghijklmnopqrstuv';
-const INSTANCE_KEYED_BODY_RE = /^[0-9a-f]{32}$/;
-
-const INSTANCE_LABEL_RE = /^i-([0-9a-f]{32})$/;
-const USER_LABEL_RE = /^u-([0-9a-v]+)$/;
-
-function bytesToBase64url(bytes: Uint8Array): string {
-  const binString = Array.from(bytes, b => String.fromCodePoint(b)).join('');
-  return btoa(binString).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
-}
-
-function base64urlToBytes(encoded: string): Uint8Array | null {
-  try {
-    let b64 = encoded.replace(/-/g, '+').replace(/_/g, '/');
-    while (b64.length % 4 !== 0) {
-      b64 += '=';
-    }
-    const binString = atob(b64);
-    const bytes = Uint8Array.from(binString, c => c.codePointAt(0) ?? 0);
-    return bytesToBase64url(bytes) === encoded ? bytes : null;
-  } catch {
-    return null;
-  }
-}
-
-function bytesToBase32Hex(bytes: Uint8Array): string {
-  let output = '';
-  let buffer = 0;
-  let bits = 0;
-
-  for (const byte of bytes) {
-    buffer = (buffer << 8) | byte;
-    bits += 8;
-
-    while (bits >= 5) {
-      bits -= 5;
-      output += BASE32_HEX_ALPHABET[(buffer >> bits) & 31];
-    }
-  }
-
-  if (bits > 0) {
-    output += BASE32_HEX_ALPHABET[(buffer << (5 - bits)) & 31];
-  }
-
-  return output;
-}
-
-function base32HexToBytes(encoded: string): Uint8Array | null {
-  const bytes: number[] = [];
-  let buffer = 0;
-  let bits = 0;
-
-  for (const char of encoded) {
-    const value = BASE32_HEX_ALPHABET.indexOf(char);
-    if (value === -1) return null;
-
-    buffer = (buffer << 5) | value;
-    bits += 5;
-
-    while (bits >= 8) {
-      bits -= 8;
-      bytes.push((buffer >> bits) & 255);
-    }
-  }
-
-  const decoded = Uint8Array.from(bytes);
-  return bytesToBase32Hex(decoded) === encoded ? decoded : null;
-}
-
-/**
- * Produce a DNS-safe hostname label for `<label>.kiloclaw.ai` from a
- * sandboxId, or `null` if the sandboxId can't be represented as a safe
- * label (e.g. pathological Unicode userId whose base64url encoding
- * contains non-alnum chars, or a label that would exceed 63 chars).
- *
- * Callers should treat `null` as "no per-instance origin available for
- * this sandbox" and fall back to the shared origin list.
- */
-export function hostnameLabelFromSandboxId(sandboxId: string): string | null {
-  if (isInstanceKeyedSandboxId(sandboxId)) {
-    const body = sandboxId.slice(3);
-    if (!INSTANCE_KEYED_BODY_RE.test(body)) return null;
-    const label = `i-${body}`;
-    if (label.length > MAX_HOSTNAME_LABEL_LENGTH) return null;
-    return label;
-  }
-
-  const legacyUserIdBytes = base64urlToBytes(sandboxId);
-  if (!legacyUserIdBytes || legacyUserIdBytes.length === 0) return null;
-
-  const label = `u-${bytesToBase32Hex(legacyUserIdBytes)}`;
-  if (label.length > MAX_HOSTNAME_LABEL_LENGTH) return null;
-  return label;
-}
-
-/**
- * Reverse of `hostnameLabelFromSandboxId`: parse a hostname label back
- * into its sandboxId, returning `null` if the label doesn't match either
- * scheme.
- *
- * Used by the host-based router in a follow-up PR to resolve
- * `<label>.kiloclaw.ai` to the owning Instance DO.
- */
-export function sandboxIdFromHostnameLabel(label: string): string | null {
-  const normalized = label.toLowerCase();
-  const instanceMatch = INSTANCE_LABEL_RE.exec(normalized);
-  if (instanceMatch) return `ki_${instanceMatch[1]}`;
-
-  const userMatch = USER_LABEL_RE.exec(normalized);
-  if (userMatch) {
-    const body = userMatch[1];
-    if (body.length + 2 > MAX_HOSTNAME_LABEL_LENGTH) return null;
-    const bytes = base32HexToBytes(body);
-    if (!bytes) return null;
-    return bytesToBase64url(bytes);
-  }
-
-  return null;
-}
-
-/**
- * Build the per-instance URL (no path, no query) for the given label.
- *
- *   instanceUrl('i-abc', { KILOCLAW_INSTANCE_HOST_SUFFIX: '.kiloclaw.ai' })
- *     => 'https://i-abc.kiloclaw.ai'
- *   instanceUrl('i-abc', {
- *     KILOCLAW_INSTANCE_HOST_SUFFIX: '.kiloclaw.localhost:8795',
- *     KILOCLAW_INSTANCE_URL_SCHEME: 'http',
- *   })
- *     => 'http://i-abc.kiloclaw.localhost:8795'
- *
- * Used by the per-instance origin injector in `gateway/env.ts` and by any
- * code that needs to mint the canonical user-facing host for an instance.
+ * Canonical implementation lives in `@kilocode/worker-utils/hostname-label`
+ * so it can be shared with `apps/web` (per-instance URL minting) without
+ * duplicating the label encoding. This module is a thin re-export shim
+ * kept in place so the many existing `./auth/hostname-label` imports in
+ * the worker don't have to migrate all at once.
  */
-export function instanceUrl(label: string, env: HostSuffixEnv): string {
-  return `${urlScheme(env)}://${label}${hostSuffix(env)}`;
-}
 
-/**
- * Does the given host fall within the per-instance virtual-host space?
- * True for anything ending in the configured suffix, including malformed
- * cases (bare suffix, multi-label, unparseable label). Callers use this
- * to decide whether the request should be handled by the host-based
- * branch (which may still return 404) or fall through to cookie-based
- * routing. Case-insensitive.
- */
-export function hostMatchesInstanceSuffix(host: string, env: HostSuffixEnv): boolean {
-  return host.toLowerCase().endsWith(hostSuffix(env).toLowerCase());
-}
-
-/**
- * Extract the hostname label from an incoming `Host` header if the host
- * matches the configured instance-host suffix. Returns `null` if:
- *
- *   - the host doesn't end with the configured suffix
- *   - the portion preceding the suffix is empty (e.g. ".kiloclaw.ai")
- *   - the portion preceding the suffix contains a dot, i.e. multi-label
- *     subdomain like `foo.bar.kiloclaw.ai`
- *
- * The suffix can legitimately contain a port in dev (`.kiloclaw.localhost:8795`),
- * so we use raw suffix comparison rather than DNS-only parsing. The input
- * host should be the full value of the `Host` header / `URL.host`, including
- * any `:port` component.
- *
- * Case-insensitive: DNS is case-insensitive and CDNs/proxies may rewrite
- * case. The returned label is lowercased so callers can run it through
- * `sandboxIdFromHostnameLabel` (which also lowercases, but doing it here
- * makes the behaviour explicit).
- */
-export function parseInstanceHost(host: string, env: HostSuffixEnv): string | null {
-  const suffix = hostSuffix(env).toLowerCase();
-  const normalized = host.toLowerCase();
-  if (!normalized.endsWith(suffix)) return null;
-  const label = normalized.slice(0, -suffix.length);
-  if (label.length === 0) return null;
-  if (label.includes('.')) return null;
-  return label;
-}
+export {
+  MAX_HOSTNAME_LABEL_LENGTH,
+  hostnameLabelFromSandboxId,
+  sandboxIdFromHostnameLabel,
+  instanceUrl,
+  hostMatchesInstanceSuffix,
+  parseInstanceHost,
+} from '@kilocode/worker-utils/hostname-label';
+export type { HostSuffixEnv } from '@kilocode/worker-utils/hostname-label';
diff --git a/services/kiloclaw/src/auth/sandbox-id.ts b/services/kiloclaw/src/auth/sandbox-id.ts
index 434c8c665..511362596 100644
--- a/services/kiloclaw/src/auth/sandbox-id.ts
+++ b/services/kiloclaw/src/auth/sandbox-id.ts
@@ -1,50 +1,16 @@
 /**
- * Reversible base64url encoding of userId into sandboxId.
+ * SandboxId encoding helpers.
  *
- * NOT the cloud-agent-next SHA-256 pattern -- we need to recover userId
- * from sandboxId in lifecycle hooks without a DB lookup.
- *
- * Uses TextEncoder/TextDecoder so non-Latin1 userIds (e.g. Unicode from
- * some IdPs) don't throw at runtime. ASCII userIds encode identically
- * to the old btoa() approach.
- *
- * No prefix -- the full 63-char sandboxId limit is available.
+ * Canonical implementation lives in `@kilocode/worker-utils/sandbox-id`
+ * so it can be shared with `apps/web` (per-instance URL minting) without
+ * duplicating the base64url encoding. This module is a thin re-export
+ * shim kept in place so the many existing `./auth/sandbox-id` imports in
+ * the worker don't have to migrate all at once.
  */
 
-const MAX_SANDBOX_ID_LENGTH = 63;
-
-function bytesToBase64url(bytes: Uint8Array): string {
-  const binString = Array.from(bytes, b => String.fromCodePoint(b)).join('');
-  return btoa(binString).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
-}
-
-function base64urlToBytes(encoded: string): Uint8Array {
-  let b64 = encoded.replace(/-/g, '+').replace(/_/g, '/');
-  while (b64.length % 4 !== 0) {
-    b64 += '=';
-  }
-  const binString = atob(b64);
-  return Uint8Array.from(binString, c => c.codePointAt(0) ?? 0);
-}
-
-export function sandboxIdFromUserId(userId: string): string {
-  const bytes = new TextEncoder().encode(userId);
-  const encoded = bytesToBase64url(bytes);
-  if (encoded.length > MAX_SANDBOX_ID_LENGTH) {
-    throw new Error(
-      `userId too long: encoded sandboxId would be ${encoded.length} chars (max ${MAX_SANDBOX_ID_LENGTH})`
-    );
-  }
-  return encoded;
-}
-
-export function userIdFromSandboxId(sandboxId: string): string {
-  const bytes = base64urlToBytes(sandboxId);
-  return new TextDecoder('utf-8', { fatal: false, ignoreBOM: true }).decode(bytes);
-}
-
-// ─── Instance-scoped identity ───────────────────────────────────────
-// Canonical implementation lives in @kilocode/worker-utils/instance-id;
-// re-exported here so existing imports within the worker package continue to work.
-
-export { isValidInstanceId, sandboxIdFromInstanceId } from '@kilocode/worker-utils/instance-id';
+export {
+  sandboxIdFromUserId,
+  userIdFromSandboxId,
+  isValidInstanceId,
+  sandboxIdFromInstanceId,
+} from '@kilocode/worker-utils/sandbox-id';

From d1b29ec1ad4358f3755eb477ee0ade4629cca4b5 Mon Sep 17 00:00:00 2001
From: syn <syn@neonronin.sh>
Date: Mon, 4 May 2026 09:55:35 -0500
Subject: [PATCH 3/9] feat(kiloclaw): route users to per-instance
 `<label>.kiloclaw.ai` URLs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Wires the dashboard to emit per-instance hostnames as `workerUrl` so
users of v2+ instances open their instance directly on its virtual host
instead of the single shared `claw.kilo.ai` / `claw.kilosessions.ai`
endpoint. Completes the PR3 step of the name-based routing rollout;
PR1 built the host space, PR2 taught the worker to route by Host.

- New env var `KILOCLAW_INSTANCE_URL_TEMPLATE` (e.g.
  `https://{label}.kiloclaw.ai`). Unset → legacy single-host behaviour
  (dev default, no change).
- `workerUrlForInstance` helper expands the template only when the
  instance is on `controllerCapabilitiesVersion >= 2`. Pre-v2 instances
  don't have their per-instance origin in
  `OPENCLAW_ALLOWED_ORIGINS`, so WebSocket upgrades from the new host
  would fail openclaw's exact-match origin check; keep them on the
  legacy host until they restart onto v2.
- `getStatus` tRPC procedures (personal + org) thread the new field
  through and compute `workerUrl` via the helper. No-instance sentinel
  stays on the legacy URL (no sandboxId yet to label).
- `PlatformStatusResponse` type gains `controllerCapabilitiesVersion`;
  worker DO was already emitting it, this just exposes it to callers.
- Worker `KILOCLAW_CHECKIN_URL` flipped from
  `claw.kilosessions.ai` to `claw.kiloclaw.ai`. Only affects
  newly-provisioned / restarted machines; running machines continue
  hitting the legacy URL (still live via the existing custom domain).
- Test fixtures (state tests, walkthrough) updated for the new field.
- New helper covered by 9 unit tests in `instance-url.test.ts`.
---
 .../ClawOnboardingFakeWalkthrough.tsx         |   1 +
 .../ClawOnboardingFlow.state.test.ts          |   1 +
 .../withStatusQueryBoundary.test.ts           |   1 +
 .../claw/new/ClawNewClient.state.test.ts      |   1 +
 apps/web/src/lib/config.server.ts             |  13 ++
 .../web/src/lib/kiloclaw/instance-url.test.ts | 122 ++++++++++++++++++
 apps/web/src/lib/kiloclaw/instance-url.ts     |  50 +++++++
 apps/web/src/lib/kiloclaw/types.ts            |  18 ++-
 apps/web/src/routers/kiloclaw-router.ts       |  18 ++-
 .../organization-kiloclaw-router.ts           |  15 ++-
 services/kiloclaw/wrangler.jsonc              |  10 +-
 11 files changed, 242 insertions(+), 8 deletions(-)
 create mode 100644 apps/web/src/lib/kiloclaw/instance-url.test.ts
 create mode 100644 apps/web/src/lib/kiloclaw/instance-url.ts

diff --git a/apps/web/src/app/(app)/claw/components/ClawOnboardingFakeWalkthrough.tsx b/apps/web/src/app/(app)/claw/components/ClawOnboardingFakeWalkthrough.tsx
index 1cdd0c5e0..3354912b0 100644
--- a/apps/web/src/app/(app)/claw/components/ClawOnboardingFakeWalkthrough.tsx
+++ b/apps/web/src/app/(app)/claw/components/ClawOnboardingFakeWalkthrough.tsx
@@ -67,6 +67,7 @@ const fakeStatus = {
   botVibe: 'Focused, capable, effective',
   botEmoji: '🤖',
   workerUrl: 'https://claw.kilo.ai',
+  controllerCapabilitiesVersion: null,
   name: 'Fake KiloClaw',
   instanceId: 'fake-instance',
   inboundEmailAddress: null,
diff --git a/apps/web/src/app/(app)/claw/components/ClawOnboardingFlow.state.test.ts b/apps/web/src/app/(app)/claw/components/ClawOnboardingFlow.state.test.ts
index f2f729fe2..dc5d7f180 100644
--- a/apps/web/src/app/(app)/claw/components/ClawOnboardingFlow.state.test.ts
+++ b/apps/web/src/app/(app)/claw/components/ClawOnboardingFlow.state.test.ts
@@ -48,6 +48,7 @@ function createStatus(status: KiloClawDashboardStatus['status']): KiloClawDashbo
     botVibe: null,
     botEmoji: null,
     workerUrl: 'https://claw.kilo.ai',
+    controllerCapabilitiesVersion: null,
     instanceId: null,
     inboundEmailAddress: null,
     inboundEmailEnabled: false,
diff --git a/apps/web/src/app/(app)/claw/components/withStatusQueryBoundary.test.ts b/apps/web/src/app/(app)/claw/components/withStatusQueryBoundary.test.ts
index 9c478097f..ebc7df324 100644
--- a/apps/web/src/app/(app)/claw/components/withStatusQueryBoundary.test.ts
+++ b/apps/web/src/app/(app)/claw/components/withStatusQueryBoundary.test.ts
@@ -41,6 +41,7 @@ const baseStatus: KiloClawDashboardStatus = {
   botVibe: null,
   botEmoji: null,
   workerUrl: 'https://claw.kilo.ai',
+  controllerCapabilitiesVersion: null,
   instanceId: null,
   inboundEmailAddress: 'amber-river-quiet-maple@kiloclaw.ai',
   inboundEmailEnabled: true,
diff --git a/apps/web/src/app/(app)/claw/new/ClawNewClient.state.test.ts b/apps/web/src/app/(app)/claw/new/ClawNewClient.state.test.ts
index e64aaa12d..7d7316a41 100644
--- a/apps/web/src/app/(app)/claw/new/ClawNewClient.state.test.ts
+++ b/apps/web/src/app/(app)/claw/new/ClawNewClient.state.test.ts
@@ -39,6 +39,7 @@ const baseStatus: KiloClawDashboardStatus = {
   botVibe: null,
   botEmoji: null,
   workerUrl: 'https://claw.kilo.ai',
+  controllerCapabilitiesVersion: null,
   instanceId: 'instance-1',
   inboundEmailAddress: 'amber-river-quiet-maple@kiloclaw.ai',
   inboundEmailEnabled: true,
diff --git a/apps/web/src/lib/config.server.ts b/apps/web/src/lib/config.server.ts
index f3bb4df35..209c8eee1 100644
--- a/apps/web/src/lib/config.server.ts
+++ b/apps/web/src/lib/config.server.ts
@@ -209,6 +209,19 @@ export const KILOCLAW_INTERNAL_API_SECRET = getEnvVariable('KILOCLAW_INTERNAL_AP
 export const KILOCLAW_INBOUND_EMAIL_DOMAIN =
   getEnvVariable('KILOCLAW_INBOUND_EMAIL_DOMAIN') || 'kiloclaw.ai';
 
+/**
+ * Per-instance worker URL template. When set to e.g.
+ * `https://{label}.kiloclaw.ai`, `getStatus` emits a `workerUrl` pointing
+ * at the instance's own virtual host (derived from its sandboxId) for
+ * instances whose `controllerCapabilitiesVersion >= 2`. Pre-v2 instances
+ * keep falling back to `KILOCLAW_API_URL`.
+ *
+ * Leave unset to keep the path-based / legacy behaviour everywhere —
+ * dev defaults to localhost and doesn't need the template.
+ */
+export const KILOCLAW_INSTANCE_URL_TEMPLATE =
+  getEnvVariable('KILOCLAW_INSTANCE_URL_TEMPLATE') || '';
+
 // KiloClaw Early Bird Checkout
 export const STRIPE_KILOCLAW_EARLYBIRD_PRICE_ID = getEnvVariable(
   'STRIPE_KILOCLAW_EARLYBIRD_PRICE_ID'
diff --git a/apps/web/src/lib/kiloclaw/instance-url.test.ts b/apps/web/src/lib/kiloclaw/instance-url.test.ts
new file mode 100644
index 000000000..e9a3f3347
--- /dev/null
+++ b/apps/web/src/lib/kiloclaw/instance-url.test.ts
@@ -0,0 +1,122 @@
+import { describe, it, expect } from '@jest/globals';
+import { workerUrlForInstance } from './instance-url';
+import { sandboxIdFromUserId, sandboxIdFromInstanceId } from '@kilocode/worker-utils/sandbox-id';
+
+const LEGACY = 'https://claw.kilo.ai';
+const TEMPLATE = 'https://{label}.kiloclaw.ai';
+
+describe('workerUrlForInstance', () => {
+  it('falls back to the legacy URL when the template is unset', () => {
+    const sandboxId = sandboxIdFromInstanceId('550e8400-e29b-41d4-a716-446655440000');
+    expect(
+      workerUrlForInstance({
+        sandboxId,
+        controllerCapabilitiesVersion: 2,
+        template: '',
+        fallback: LEGACY,
+      })
+    ).toBe(LEGACY);
+  });
+
+  it('falls back to the legacy URL when the template has no {label} placeholder', () => {
+    const sandboxId = sandboxIdFromInstanceId('550e8400-e29b-41d4-a716-446655440000');
+    expect(
+      workerUrlForInstance({
+        sandboxId,
+        controllerCapabilitiesVersion: 2,
+        template: 'https://claw.kiloclaw.ai',
+        fallback: LEGACY,
+      })
+    ).toBe(LEGACY);
+  });
+
+  it('falls back to the legacy URL for pre-v2 instances', () => {
+    const sandboxId = sandboxIdFromInstanceId('550e8400-e29b-41d4-a716-446655440000');
+    expect(
+      workerUrlForInstance({
+        sandboxId,
+        controllerCapabilitiesVersion: null,
+        template: TEMPLATE,
+        fallback: LEGACY,
+      })
+    ).toBe(LEGACY);
+    expect(
+      workerUrlForInstance({
+        sandboxId,
+        controllerCapabilitiesVersion: 1,
+        template: TEMPLATE,
+        fallback: LEGACY,
+      })
+    ).toBe(LEGACY);
+  });
+
+  it('falls back to the legacy URL when sandboxId is null (no-instance sentinel)', () => {
+    expect(
+      workerUrlForInstance({
+        sandboxId: null,
+        controllerCapabilitiesVersion: 2,
+        template: TEMPLATE,
+        fallback: LEGACY,
+      })
+    ).toBe(LEGACY);
+  });
+
+  it('expands the template for instance-keyed sandboxIds on v2+', () => {
+    const sandboxId = sandboxIdFromInstanceId('550e8400-e29b-41d4-a716-446655440000');
+    expect(
+      workerUrlForInstance({
+        sandboxId,
+        controllerCapabilitiesVersion: 2,
+        template: TEMPLATE,
+        fallback: LEGACY,
+      })
+    ).toBe('https://i-550e8400e29b41d4a716446655440000.kiloclaw.ai');
+  });
+
+  it('expands the template for legacy userId sandboxes on v2+', () => {
+    const sandboxId = sandboxIdFromUserId('oauth/google:118234567890');
+    expect(
+      workerUrlForInstance({
+        sandboxId,
+        controllerCapabilitiesVersion: 2,
+        template: TEMPLATE,
+        fallback: LEGACY,
+      })
+    ).toMatch(/^https:\/\/u-[0-9a-v]+\.kiloclaw\.ai$/);
+  });
+
+  it('falls back to the legacy URL when the sandboxId cannot be safely labelled', () => {
+    const overlongSandboxId = sandboxIdFromUserId('a'.repeat(39));
+    expect(
+      workerUrlForInstance({
+        sandboxId: overlongSandboxId,
+        controllerCapabilitiesVersion: 2,
+        template: TEMPLATE,
+        fallback: LEGACY,
+      })
+    ).toBe(LEGACY);
+  });
+
+  it('uses the hardcoded default when fallback is empty', () => {
+    expect(
+      workerUrlForInstance({
+        sandboxId: null,
+        controllerCapabilitiesVersion: 2,
+        template: '',
+        fallback: '',
+      })
+    ).toBe('https://claw.kilo.ai');
+  });
+
+  it('works with dev-parity templates (http + port)', () => {
+    const sandboxId = sandboxIdFromInstanceId('550e8400-e29b-41d4-a716-446655440000');
+    expect(
+      workerUrlForInstance({
+        sandboxId,
+        controllerCapabilitiesVersion: 2,
+        template: 'http://{label}.kiloclaw.localhost:8795',
+        fallback: 'http://localhost:8795',
+      })
+    ).toBe('http://i-550e8400e29b41d4a716446655440000.kiloclaw.localhost:8795');
+  });
+});
diff --git a/apps/web/src/lib/kiloclaw/instance-url.ts b/apps/web/src/lib/kiloclaw/instance-url.ts
new file mode 100644
index 000000000..df3e45243
--- /dev/null
+++ b/apps/web/src/lib/kiloclaw/instance-url.ts
@@ -0,0 +1,50 @@
+/**
+ * Per-instance worker URL minting.
+ *
+ * Returns the dashboard-facing URL the browser should use to talk to a
+ * specific KiloClaw instance.
+ *
+ * When `KILOCLAW_INSTANCE_URL_TEMPLATE` is set (e.g.
+ * `https://{label}.kiloclaw.ai`) AND the instance is on the post-PR1
+ * controller contract (`controllerCapabilitiesVersion >= 2`), the
+ * template is expanded with the sandboxId's hostname label. Otherwise
+ * falls back to the legacy single-host `KILOCLAW_API_URL`.
+ *
+ * The capability gate matters: v1 machines don't have the per-instance
+ * origin in their OpenClaw allowlist, so WebSocket upgrades from the
+ * per-instance host would fail openclaw's exact-match origin check.
+ * Keeping v1 instances on the legacy host until they restart onto v2
+ * avoids a user-visible regression.
+ *
+ * Inputs:
+ *   - `sandboxId`: DO's authoritative sandboxId (null for no-instance sentinel)
+ *   - `controllerCapabilitiesVersion`: from the worker's `getStatus`
+ *     (null → treat as pre-v1, legacy host)
+ *   - `template`: `KILOCLAW_INSTANCE_URL_TEMPLATE` (empty → legacy host)
+ *   - `fallback`: `KILOCLAW_API_URL` (empty → "https://claw.kilo.ai")
+ */
+
+import { hostnameLabelFromSandboxId } from '@kilocode/worker-utils/hostname-label';
+
+const MIN_CAPABILITY_VERSION_FOR_PER_INSTANCE_URL = 2;
+
+const DEFAULT_LEGACY_URL = 'https://claw.kilo.ai';
+
+export function workerUrlForInstance(params: {
+  sandboxId: string | null;
+  controllerCapabilitiesVersion: number | null;
+  template: string;
+  fallback: string;
+}): string {
+  const { sandboxId, controllerCapabilitiesVersion, template, fallback } = params;
+  const legacyUrl = fallback || DEFAULT_LEGACY_URL;
+
+  if (!template || !template.includes('{label}')) return legacyUrl;
+  if (!sandboxId) return legacyUrl;
+  if ((controllerCapabilitiesVersion ?? 0) < MIN_CAPABILITY_VERSION_FOR_PER_INSTANCE_URL) {
+    return legacyUrl;
+  }
+  const label = hostnameLabelFromSandboxId(sandboxId);
+  if (!label) return legacyUrl;
+  return template.replace('{label}', label);
+}
diff --git a/apps/web/src/lib/kiloclaw/types.ts b/apps/web/src/lib/kiloclaw/types.ts
index fe0a6fb34..8006ba0cf 100644
--- a/apps/web/src/lib/kiloclaw/types.ts
+++ b/apps/web/src/lib/kiloclaw/types.ts
@@ -225,6 +225,15 @@ export type PlatformStatusResponse = {
   botNature: string | null;
   botVibe: string | null;
   botEmoji: string | null;
+  /**
+   * Version of the controller-configuration contract the running machine
+   * was started with. Bumped by the worker whenever the set of env vars /
+   * config it writes into a machine changes in a way callers care about.
+   * `null` means the instance has never been started under a versioned
+   * contract (treat as pre-v1 / legacy). See
+   * `services/kiloclaw/src/config.ts` (`WORKER_CONTROLLER_CAPABILITIES_VERSION`).
+   */
+  controllerCapabilitiesVersion: number | null;
 };
 
 /** A single registry DO's entries + migration status. */
@@ -594,7 +603,14 @@ export type ChatCredentials = {
 
 /** Combined status returned by tRPC getStatus */
 export type KiloClawDashboardStatus = PlatformStatusResponse & {
-  /** Worker base URL for constructing the "Open" link. Falls back to claw.kilo.ai. */
+  /**
+   * Worker base URL for constructing the "Open" link.
+   *
+   * When `KILOCLAW_INSTANCE_URL_TEMPLATE` is configured and the instance
+   * is on `controllerCapabilitiesVersion >= 2`, this is the per-instance
+   * virtual host (e.g. `https://i-<hex>.kiloclaw.ai`). Otherwise it falls
+   * back to `KILOCLAW_API_URL` (production: `https://claw.kilo.ai`).
+   */
   workerUrl: string;
   name: string | null;
   /** Postgres row ID. Used to construct /i/{instanceId} proxy paths for instance-keyed instances. */
diff --git a/apps/web/src/routers/kiloclaw-router.ts b/apps/web/src/routers/kiloclaw-router.ts
index c5dc52f5a..a9276d951 100644
--- a/apps/web/src/routers/kiloclaw-router.ts
+++ b/apps/web/src/routers/kiloclaw-router.ts
@@ -17,7 +17,8 @@ import {
   isValidCustomSecretKey,
   isValidConfigPath,
 } from '@kilocode/kiloclaw-secret-catalog';
-import { KILOCLAW_API_URL } from '@/lib/config.server';
+import { KILOCLAW_API_URL, KILOCLAW_INSTANCE_URL_TEMPLATE } from '@/lib/config.server';
+import { workerUrlForInstance } from '@/lib/kiloclaw/instance-url';
 import { db, type DrizzleTransaction } from '@/lib/drizzle';
 import { insertKiloClawSubscriptionChangeLog } from '@kilocode/db';
 import {
@@ -914,6 +915,7 @@ function createNoInstanceStatus(userId: string, workerUrl: string): KiloClawDash
     botVibe: null,
     botEmoji: null,
     workerUrl,
+    controllerCapabilitiesVersion: null,
     name: null,
     instanceId: null,
     inboundEmailAddress: null,
@@ -2345,10 +2347,13 @@ export const kiloclawRouter = createTRPCRouter({
 
   getStatus: baseProcedure.query(async ({ ctx }) => {
     const instance = await getActiveInstance(ctx.user.id);
-    const workerUrl = KILOCLAW_API_URL || 'https://claw.kilo.ai';
+    const legacyWorkerUrl = KILOCLAW_API_URL || 'https://claw.kilo.ai';
 
     if (!instance) {
-      return createNoInstanceStatus(ctx.user.id, workerUrl);
+      // No instance yet → no sandboxId yet → per-instance URL can't be
+      // minted. Serve the legacy host; the real host kicks in once the
+      // dashboard provisions and re-fetches status.
+      return createNoInstanceStatus(ctx.user.id, legacyWorkerUrl);
     }
 
     const client = new KiloClawInternalClient();
@@ -2357,6 +2362,13 @@ export const kiloclawRouter = createTRPCRouter({
       getInboundEmailAddressForInstance(instance.id),
     ]);
 
+    const workerUrl = workerUrlForInstance({
+      sandboxId: status.sandboxId,
+      controllerCapabilitiesVersion: status.controllerCapabilitiesVersion,
+      template: KILOCLAW_INSTANCE_URL_TEMPLATE,
+      fallback: legacyWorkerUrl,
+    });
+
     return {
       ...status,
       name: instance.name ?? null,
diff --git a/apps/web/src/routers/organizations/organization-kiloclaw-router.ts b/apps/web/src/routers/organizations/organization-kiloclaw-router.ts
index 2f42d9567..f30e970ac 100644
--- a/apps/web/src/routers/organizations/organization-kiloclaw-router.ts
+++ b/apps/web/src/routers/organizations/organization-kiloclaw-router.ts
@@ -17,7 +17,8 @@ import {
   isValidCustomSecretKey,
   isValidConfigPath,
 } from '@kilocode/kiloclaw-secret-catalog';
-import { KILOCLAW_API_URL } from '@/lib/config.server';
+import { KILOCLAW_API_URL, KILOCLAW_INSTANCE_URL_TEMPLATE } from '@/lib/config.server';
+import { workerUrlForInstance } from '@/lib/kiloclaw/instance-url';
 import { sentryLogger } from '@/lib/utils.server';
 import { db } from '@/lib/drizzle';
 import {
@@ -309,7 +310,7 @@ export const organizationKiloclawRouter = createTRPCRouter({
 
   getStatus: organizationMemberProcedure.query(async ({ ctx, input }) => {
     const instance = await getActiveOrgInstance(ctx.user.id, input.organizationId);
-    const workerUrl = KILOCLAW_API_URL || 'https://claw.kilo.ai';
+    const legacyWorkerUrl = KILOCLAW_API_URL || 'https://claw.kilo.ai';
 
     // No org instance → return a "no instance" sentinel so the frontend
     // renders setup entry points. Without this guard, workerInstanceId(null)
@@ -351,7 +352,8 @@ export const organizationKiloclawRouter = createTRPCRouter({
         botNature: null,
         botVibe: null,
         botEmoji: null,
-        workerUrl,
+        workerUrl: legacyWorkerUrl,
+        controllerCapabilitiesVersion: null,
         name: null,
         instanceId: null,
         inboundEmailAddress: null,
@@ -365,6 +367,13 @@ export const organizationKiloclawRouter = createTRPCRouter({
       getInboundEmailAddressForInstance(instance.id),
     ]);
 
+    const workerUrl = workerUrlForInstance({
+      sandboxId: status.sandboxId,
+      controllerCapabilitiesVersion: status.controllerCapabilitiesVersion,
+      template: KILOCLAW_INSTANCE_URL_TEMPLATE,
+      fallback: legacyWorkerUrl,
+    });
+
     return {
       ...status,
       name: instance.name ?? null,
diff --git a/services/kiloclaw/wrangler.jsonc b/services/kiloclaw/wrangler.jsonc
index fa388cb85..e0c85970e 100644
--- a/services/kiloclaw/wrangler.jsonc
+++ b/services/kiloclaw/wrangler.jsonc
@@ -142,7 +142,15 @@
     // `buildEnvVars` in src/gateway/env.ts appends
     // `https://<instanceId>.kiloclaw.ai` per-instance at machine build time.
     "OPENCLAW_ALLOWED_ORIGINS": "https://claw.kilosessions.ai,https://kilo.ai,https://www.kilo.ai",
-    "KILOCLAW_CHECKIN_URL": "https://claw.kilosessions.ai/api/controller/checkin",
+    // Controller check-in URL baked into newly-provisioned / restarted
+    // machines. Points at a single canonical hostname under
+    // `kiloclaw.ai` so the legacy `claw.kilosessions.ai` custom domain
+    // can be retired once the fleet rolls over. Both hostnames resolve
+    // to the same worker, so in-flight machines on the old URL keep
+    // working through the transition. Apex is not routed, so we use a
+    // dedicated `claw` subdomain (covered by the `*.kiloclaw.ai/*`
+    // wildcard route).
+    "KILOCLAW_CHECKIN_URL": "https://claw.kiloclaw.ai/api/controller/checkin",
     // Per-instance virtual hosting. Three call sites share this suffix:
     //   1. `parseInstanceHost` (catch-all proxy, PR2) routes `<label>.kiloclaw.ai`
     //      requests by `Host` header.

From a550665f5b31cf6ecf422965960ae635f44ba46f Mon Sep 17 00:00:00 2001
From: syn <syn@neonronin.sh>
Date: Mon, 4 May 2026 10:32:16 -0500
Subject: [PATCH 4/9] =?UTF-8?q?fix(kiloclaw):=20address=20PR=20review=20?=
 =?UTF-8?q?=E2=80=94=20normalize=20WS=20no-upgrade,=20reserve=20'claw'=20l?=
 =?UTF-8?q?abel,=20warn=20on=20misconfigured=20URL=20template?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three PR review findings on the PR2/PR3 routing work.

1. proxyThroughTarget: on a WebSocket request where the upstream returns
   a non-upgrade response, return a normalized 502 JSON
   `{ error: 'WebSocket upgrade failed' }` instead of the raw upstream
   response. The previous helper passed `containerResponse` straight
   through (matching the pre-refactor /i/ and default branches but
   changing the cookie-routed branch's contract, which was 502 JSON).
   Raw upstream bodies on this edge path can leak provider/controller
   error detail to the Control UI; normalize to a minimal error body
   and log the upstream status for operators. Unified across all four
   call sites.

2. Host-based routing: add an explicit `claw` reserved-label guard.
   With PR3 flipping KILOCLAW_CHECKIN_URL to `claw.kiloclaw.ai`, that
   hostname now enters the `*.kiloclaw.ai/*` wildcard route. The
   controller check-in path is registered before the catch-all so it
   works, but any other path on that host was hitting
   handleHostBasedRoute → `claw` fails label parsing → 404 "Instance
   not found" — a confusing error for a reserved operational hostname.
   Short-circuit the host branch for reserved labels so requests fall
   through to cookie/default routing and produce the normal catch-all
   responses instead. Introduces RESERVED_INSTANCE_HOST_LABELS as an
   explicit set so future reserved hostnames (`api`, `www`, etc.) are
   trivial to add.

3. workerUrlForInstance: log a one-time `console.warn` when
   KILOCLAW_INSTANCE_URL_TEMPLATE is set but missing the `{label}`
   placeholder. Silently falling back to the legacy URL hides the
   misconfiguration. Guarded by a module-level flag so the warning
   doesn't spam logs on every getStatus call.
---
 .../web/src/lib/kiloclaw/instance-url.test.ts | 24 +++++++---
 apps/web/src/lib/kiloclaw/instance-url.ts     | 22 +++++++++-
 services/kiloclaw/src/index.test.ts           | 44 +++++++++++++++++++
 services/kiloclaw/src/index.ts                | 32 +++++++++++++-
 4 files changed, 115 insertions(+), 7 deletions(-)

diff --git a/apps/web/src/lib/kiloclaw/instance-url.test.ts b/apps/web/src/lib/kiloclaw/instance-url.test.ts
index e9a3f3347..3cc97697f 100644
--- a/apps/web/src/lib/kiloclaw/instance-url.test.ts
+++ b/apps/web/src/lib/kiloclaw/instance-url.test.ts
@@ -1,4 +1,4 @@
-import { describe, it, expect } from '@jest/globals';
+import { describe, it, expect, jest } from '@jest/globals';
 import { workerUrlForInstance } from './instance-url';
 import { sandboxIdFromUserId, sandboxIdFromInstanceId } from '@kilocode/worker-utils/sandbox-id';
 
@@ -18,16 +18,30 @@ describe('workerUrlForInstance', () => {
     ).toBe(LEGACY);
   });
 
-  it('falls back to the legacy URL when the template has no {label} placeholder', () => {
+  it('falls back to the legacy URL and warns once when the template has no {label} placeholder', () => {
     const sandboxId = sandboxIdFromInstanceId('550e8400-e29b-41d4-a716-446655440000');
-    expect(
+    const warn = jest.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      expect(
+        workerUrlForInstance({
+          sandboxId,
+          controllerCapabilitiesVersion: 2,
+          template: 'https://claw.kiloclaw.ai',
+          fallback: LEGACY,
+        })
+      ).toBe(LEGACY);
+      // Subsequent calls with the same misconfiguration must not spam logs.
       workerUrlForInstance({
         sandboxId,
         controllerCapabilitiesVersion: 2,
         template: 'https://claw.kiloclaw.ai',
         fallback: LEGACY,
-      })
-    ).toBe(LEGACY);
+      });
+      expect(warn).toHaveBeenCalledTimes(1);
+      expect(warn.mock.calls[0][0]).toMatch(/missing the \{label\} placeholder/);
+    } finally {
+      warn.mockRestore();
+    }
   });
 
   it('falls back to the legacy URL for pre-v2 instances', () => {
diff --git a/apps/web/src/lib/kiloclaw/instance-url.ts b/apps/web/src/lib/kiloclaw/instance-url.ts
index df3e45243..8cd01e302 100644
--- a/apps/web/src/lib/kiloclaw/instance-url.ts
+++ b/apps/web/src/lib/kiloclaw/instance-url.ts
@@ -30,6 +30,14 @@ const MIN_CAPABILITY_VERSION_FOR_PER_INSTANCE_URL = 2;
 
 const DEFAULT_LEGACY_URL = 'https://claw.kilo.ai';
 
+/**
+ * Process-local guard so the "misconfigured template" warning fires
+ * once per worker/Node process instead of on every getStatus call.
+ * Resets on cold start, which is the right granularity for operator
+ * feedback after a config change.
+ */
+let warnedAboutMissingLabelPlaceholder = false;
+
 export function workerUrlForInstance(params: {
   sandboxId: string | null;
   controllerCapabilitiesVersion: number | null;
@@ -39,7 +47,19 @@ export function workerUrlForInstance(params: {
   const { sandboxId, controllerCapabilitiesVersion, template, fallback } = params;
   const legacyUrl = fallback || DEFAULT_LEGACY_URL;
 
-  if (!template || !template.includes('{label}')) return legacyUrl;
+  if (!template) return legacyUrl;
+  if (!template.includes('{label}')) {
+    // Operator set a template but forgot the placeholder. Silently
+    // falling back to the legacy URL hides the misconfiguration; emit
+    // a one-time warning so it shows up in logs.
+    if (!warnedAboutMissingLabelPlaceholder) {
+      warnedAboutMissingLabelPlaceholder = true;
+      console.warn(
+        '[workerUrlForInstance] KILOCLAW_INSTANCE_URL_TEMPLATE is set but missing the {label} placeholder; falling back to legacy URL'
+      );
+    }
+    return legacyUrl;
+  }
   if (!sandboxId) return legacyUrl;
   if ((controllerCapabilitiesVersion ?? 0) < MIN_CAPABILITY_VERSION_FOR_PER_INSTANCE_URL) {
     return legacyUrl;
diff --git a/services/kiloclaw/src/index.test.ts b/services/kiloclaw/src/index.test.ts
index d8655c046..734e8a790 100644
--- a/services/kiloclaw/src/index.test.ts
+++ b/services/kiloclaw/src/index.test.ts
@@ -826,6 +826,50 @@ describe('host-based routing', () => {
     expect(response.status).toBe(404);
   });
 
+  it('skips host-based routing for reserved labels (e.g. claw) and falls through', async () => {
+    // `claw` is reserved for controller check-in + platform traffic that's
+    // registered before the catch-all. A request hitting the catch-all on
+    // `claw.kiloclaw.ai` means no earlier route matched — we want to fall
+    // through to cookie/default routing rather than 404 with "Instance not
+    // found" (the host-branch's response for unparseable labels), which
+    // would be a misleading error for a reserved operational hostname.
+    const instanceStub = {
+      getStatus: vi.fn(),
+    };
+    const registryStub = {
+      // Empty registry → default-personal path resolves no instance,
+      // responds with "Instance not provisioned". Distinct from the
+      // host-branch's "Instance not found".
+      listInstances: vi.fn().mockResolvedValue([]),
+    };
+    const response = await app.fetch(
+      new Request('https://claw.kiloclaw.ai/some-unhandled-path'),
+      {
+        ...baseEnv(),
+        KILOCLAW_INSTANCE: {
+          idFromName: vi.fn().mockReturnValue('instance-id'),
+          get: vi.fn().mockReturnValue(instanceStub),
+        },
+        KILOCLAW_REGISTRY: {
+          idFromName: vi.fn().mockReturnValue('registry-id'),
+          get: vi.fn().mockReturnValue(registryStub),
+        },
+      } as never,
+      { waitUntil: vi.fn() } as never
+    );
+
+    expect(response.status).toBe(404);
+    // Host branch would have replied `{ error: 'Instance not found' }`;
+    // the default branch replies `{ error: 'Instance not provisioned', ... }`.
+    // The latter body proves the reserved-label short-circuit kicked in.
+    await expect(response.json()).resolves.toMatchObject({
+      error: 'Instance not provisioned',
+    });
+    // Host branch would have called the Instance DO's getStatus for the
+    // `claw` label. It must not.
+    expect(instanceStub.getStatus).not.toHaveBeenCalled();
+  });
+
   it('returns 404 when the DO has no userId (instance never provisioned)', async () => {
     const instanceStub = {
       getStatus: vi.fn().mockResolvedValue({
diff --git a/services/kiloclaw/src/index.ts b/services/kiloclaw/src/index.ts
index f26d879cc..8e80bbaa9 100644
--- a/services/kiloclaw/src/index.ts
+++ b/services/kiloclaw/src/index.ts
@@ -206,7 +206,14 @@ async function proxyThroughTarget(opts: {
 
     const containerWs = containerResponse.webSocket;
     if (!containerWs) {
-      return containerResponse;
+      // Upstream returned a non-upgrade response to a WebSocket request.
+      // Normalize to 502 JSON rather than leaking the raw upstream body —
+      // this path is only hit when the container is in a bad state
+      // (gateway crash, proxy misconfig) and the raw response may contain
+      // provider/controller error details we don't want to surface to
+      // the Control UI.
+      console.warn(`${logTag} upstream did not upgrade (status ${containerResponse.status})`);
+      return Response.json({ error: 'WebSocket upgrade failed' }, { status: 502 });
     }
 
     const [clientWs, serverWs] = Object.values(new WebSocketPair());
@@ -617,6 +624,20 @@ async function resolveInstance(c: Context<AppEnv>): Promise<{
   };
 }
 
+/**
+ * Reserved hostname labels under the instance-host suffix that are NOT
+ * per-instance virtual hosts. Requests to these land on the worker via
+ * the `*.kiloclaw.ai/*` wildcard route but must be served by
+ * earlier-registered routes (controller check-in, future platform
+ * endpoints) rather than the host-based proxy branch.
+ *
+ * Keeping this set small and explicit prevents accidental routing: a
+ * request to `claw.kiloclaw.ai/someuserpath` will fall through the
+ * host-based branch to cookie/default routing instead of 404ing with an
+ * "instance not found" that's actually a configuration misunderstanding.
+ */
+const RESERVED_INSTANCE_HOST_LABELS = new Set<string>(['claw']);
+
 /**
  * Resolve the DO key that a host-routed request should proxy to.
  *
@@ -666,6 +687,15 @@ async function handleHostBasedRoute(c: Context<AppEnv>): Promise<Response | null
     return c.json({ error: 'Instance not found' }, 404);
   }
 
+  // Reserved labels (e.g. `claw` for controller check-in, platform health
+  // probes) are served by earlier-registered routes. If we've reached the
+  // catch-all on a reserved label the path wasn't a controller/platform
+  // route — return null so the cookie/default branches handle it rather
+  // than 404ing with a misleading "instance not found".
+  if (RESERVED_INSTANCE_HOST_LABELS.has(label)) {
+    return null;
+  }
+
   const userId = c.get('userId');
   if (!userId) {
     return c.json({ error: 'Authentication required' }, 401);

From e0d8699ab0881f5c8e44bb2d1c4b3357ecb3a981 Mon Sep 17 00:00:00 2001
From: syn <syn@neonronin.sh>
Date: Mon, 4 May 2026 12:23:17 -0500
Subject: [PATCH 5/9] fix(worker-utils): drop .js extensions from sibling
 imports for Turbopack
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Next.js / Turbopack can't resolve `./instance-id.js` when apps/web
imports @kilocode/worker-utils/hostname-label through the subpath
export — the .js rewrite convention only works in resolvers that do
the TS→JS extension mapping (Vitest, tsgo). Turbopack treats the
literal .js filename and fails.

Drop the .js suffix on the three sibling imports that crossed the
package boundary. worker-utils uses `moduleResolution: bundler`, which
accepts extensionless imports, so the typecheck and Vitest runs stay
green.
---
 packages/worker-utils/src/hostname-label.test.ts | 6 +++---
 packages/worker-utils/src/hostname-label.ts      | 2 +-
 packages/worker-utils/src/sandbox-id.ts          | 2 +-
 3 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/packages/worker-utils/src/hostname-label.test.ts b/packages/worker-utils/src/hostname-label.test.ts
index fb36408f7..3197f9061 100644
--- a/packages/worker-utils/src/hostname-label.test.ts
+++ b/packages/worker-utils/src/hostname-label.test.ts
@@ -1,13 +1,13 @@
 import { describe, it, expect } from 'vitest';
-import { sandboxIdFromUserId } from './sandbox-id.js';
-import { sandboxIdFromInstanceId } from './instance-id.js';
+import { sandboxIdFromUserId } from './sandbox-id';
+import { sandboxIdFromInstanceId } from './instance-id';
 import {
   hostnameLabelFromSandboxId,
   sandboxIdFromHostnameLabel,
   instanceUrl,
   parseInstanceHost,
   MAX_HOSTNAME_LABEL_LENGTH,
-} from './hostname-label.js';
+} from './hostname-label';
 
 describe('hostnameLabelFromSandboxId', () => {
   it('maps an instance-keyed sandboxId to `i-{32hex}`', () => {
diff --git a/packages/worker-utils/src/hostname-label.ts b/packages/worker-utils/src/hostname-label.ts
index 5957fb78d..4f5a59d72 100644
--- a/packages/worker-utils/src/hostname-label.ts
+++ b/packages/worker-utils/src/hostname-label.ts
@@ -23,7 +23,7 @@
  * modern OSes + browsers per RFC 6761, so no `/etc/hosts` edit is required.
  */
 
-import { isInstanceKeyedSandboxId } from './instance-id.js';
+import { isInstanceKeyedSandboxId } from './instance-id';
 
 /** RFC 1035 max label length. */
 export const MAX_HOSTNAME_LABEL_LENGTH = 63;
diff --git a/packages/worker-utils/src/sandbox-id.ts b/packages/worker-utils/src/sandbox-id.ts
index 8f6beebf6..83986162d 100644
--- a/packages/worker-utils/src/sandbox-id.ts
+++ b/packages/worker-utils/src/sandbox-id.ts
@@ -47,4 +47,4 @@ export function userIdFromSandboxId(sandboxId: string): string {
 // Canonical implementation lives in ./instance-id; re-exported here for
 // convenience so callers get both shapes from one module.
 
-export { isValidInstanceId, sandboxIdFromInstanceId } from './instance-id.js';
+export { isValidInstanceId, sandboxIdFromInstanceId } from './instance-id';

From fa6ee8d854ca0b8f148a748d0e0af2bfd232020d Mon Sep 17 00:00:00 2001
From: syn <syn@neonronin.sh>
Date: Mon, 4 May 2026 12:42:57 -0500
Subject: [PATCH 6/9] feat(web): default KILOCLAW_INSTANCE_URL_TEMPLATE to prod
 on NODE_ENV=production

So the per-instance URL rollout goes live automatically on merge, without
needing a Vercel env var edit.

- New `resolveInstanceUrlTemplate(envVar, nodeEnv)` pure function with
  three-level resolution: explicit override wins (including empty string
  as a kill switch), then NODE_ENV=production defaults to the canonical
  `https://{label}.kiloclaw.ai` template, otherwise empty (dev/test).
- Operators can roll back without a code deploy by setting
  `KILOCLAW_INSTANCE_URL_TEMPLATE=` (empty) in Vercel.
- Dev/test stay on legacy localhost unless a dev opts in by setting the
  dev-parity template (`http://{label}.kiloclaw.localhost:8795`)
  explicitly.
- Factored out of the config-module scope so it's testable without
  forcing a re-import of config.server.ts, which runs production-only
  validation on unrelated secrets at module load time.
---
 apps/web/src/lib/config.server.test.ts | 32 ++++++++++++++++++++
 apps/web/src/lib/config.server.ts      | 42 ++++++++++++++++++++------
 2 files changed, 65 insertions(+), 9 deletions(-)
 create mode 100644 apps/web/src/lib/config.server.test.ts

diff --git a/apps/web/src/lib/config.server.test.ts b/apps/web/src/lib/config.server.test.ts
new file mode 100644
index 000000000..1a6064f73
--- /dev/null
+++ b/apps/web/src/lib/config.server.test.ts
@@ -0,0 +1,32 @@
+import { describe, it, expect } from '@jest/globals';
+import { resolveInstanceUrlTemplate } from './config.server';
+
+describe('resolveInstanceUrlTemplate', () => {
+  it('defaults to the canonical prod template when running in production with no override', () => {
+    expect(resolveInstanceUrlTemplate(undefined, 'production')).toBe('https://{label}.kiloclaw.ai');
+  });
+
+  it('returns empty in dev/test when no override is set', () => {
+    expect(resolveInstanceUrlTemplate(undefined, 'development')).toBe('');
+    expect(resolveInstanceUrlTemplate(undefined, 'test')).toBe('');
+    expect(resolveInstanceUrlTemplate(undefined, undefined)).toBe('');
+  });
+
+  it('honors an explicit override in production', () => {
+    expect(resolveInstanceUrlTemplate('https://{label}.preview.kiloclaw.ai', 'production')).toBe(
+      'https://{label}.preview.kiloclaw.ai'
+    );
+  });
+
+  it('treats an explicit empty string as a kill switch in production', () => {
+    // Operators can roll back without a code deploy by setting
+    // KILOCLAW_INSTANCE_URL_TEMPLATE= (empty) in Vercel.
+    expect(resolveInstanceUrlTemplate('', 'production')).toBe('');
+  });
+
+  it('honors a dev-parity override in development', () => {
+    expect(
+      resolveInstanceUrlTemplate('http://{label}.kiloclaw.localhost:8795', 'development')
+    ).toBe('http://{label}.kiloclaw.localhost:8795');
+  });
+});
diff --git a/apps/web/src/lib/config.server.ts b/apps/web/src/lib/config.server.ts
index 209c8eee1..657b368d0 100644
--- a/apps/web/src/lib/config.server.ts
+++ b/apps/web/src/lib/config.server.ts
@@ -210,17 +210,41 @@ export const KILOCLAW_INBOUND_EMAIL_DOMAIN =
   getEnvVariable('KILOCLAW_INBOUND_EMAIL_DOMAIN') || 'kiloclaw.ai';
 
 /**
- * Per-instance worker URL template. When set to e.g.
- * `https://{label}.kiloclaw.ai`, `getStatus` emits a `workerUrl` pointing
- * at the instance's own virtual host (derived from its sandboxId) for
- * instances whose `controllerCapabilitiesVersion >= 2`. Pre-v2 instances
- * keep falling back to `KILOCLAW_API_URL`.
+ * Per-instance worker URL template.
  *
- * Leave unset to keep the path-based / legacy behaviour everywhere —
- * dev defaults to localhost and doesn't need the template.
+ * Resolution rules:
+ *   1. If `KILOCLAW_INSTANCE_URL_TEMPLATE` is set (to anything, including
+ *      empty string), use that value. Explicit empty = kill switch for
+ *      rolling back the per-instance URL without redeploying code.
+ *   2. Otherwise in `NODE_ENV=production`, default to the canonical
+ *      `https://{label}.kiloclaw.ai` template so merging this feature
+ *      flips per-instance URLs on without a Vercel env var edit.
+ *   3. Otherwise (dev/test) return empty → legacy path-based behaviour.
+ *      Devs opt into dev-parity by setting
+ *      `http://{label}.kiloclaw.localhost:8795` explicitly.
+ *
+ * When the template ends up set and contains `{label}`,
+ * `getStatus` emits a `workerUrl` pointing at the instance's own virtual
+ * host (derived from its sandboxId) for instances whose
+ * `controllerCapabilitiesVersion >= 2`. Pre-v2 instances keep falling
+ * back to `KILOCLAW_API_URL`.
+ *
+ * Exported as a plain function so it's testable without forcing a
+ * re-import of this entire module (which triggers production-only
+ * validation of unrelated secrets).
  */
-export const KILOCLAW_INSTANCE_URL_TEMPLATE =
-  getEnvVariable('KILOCLAW_INSTANCE_URL_TEMPLATE') || '';
+export function resolveInstanceUrlTemplate(
+  envVar: string | undefined,
+  nodeEnv: string | undefined
+): string {
+  if (envVar !== undefined) return envVar;
+  return nodeEnv === 'production' ? 'https://{label}.kiloclaw.ai' : '';
+}
+
+export const KILOCLAW_INSTANCE_URL_TEMPLATE = resolveInstanceUrlTemplate(
+  process.env.KILOCLAW_INSTANCE_URL_TEMPLATE,
+  process.env.NODE_ENV
+);
 
 // KiloClaw Early Bird Checkout
 export const STRIPE_KILOCLAW_EARLYBIRD_PRICE_ID = getEnvVariable(

From 858742a926eea989647272b68099c64673ae14a3 Mon Sep 17 00:00:00 2001
From: syn <syn@neonronin.sh>
Date: Mon, 4 May 2026 12:48:03 -0500
Subject: [PATCH 7/9] feat(web): default per-instance URLs on in dev too,
 derived from KILOCLAW_API_URL
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Previously `resolveInstanceUrlTemplate` only defaulted on in
production; dev/test returned empty so the dashboard kept emitting the
legacy `KILOCLAW_API_URL` (usually `http://localhost:8795`) as
`workerUrl` until a developer manually added
`KILOCLAW_INSTANCE_URL_TEMPLATE` to `apps/web/.env.local`. That hoop
defeats the point of merging the feature — local repro of the
per-instance flow is exactly what devs need to verify changes.

Make the new pattern default in dev too, derived from
`KILOCLAW_API_URL`:

- `http://localhost:8795` -> `http://{label}.kiloclaw.localhost:8795`
- `http://127.0.0.1:9000` -> `http://{label}.kiloclaw.localhost:9000`
- Non-loopback / missing / unparsable `KILOCLAW_API_URL` falls back to
  `http://{label}.kiloclaw.localhost:8795` (the wrangler dev default).

Scheme and port are preserved from `KILOCLAW_API_URL` so a dev
running wrangler on a non-default port still gets a working template.

Opt-out is unchanged: `KILOCLAW_INSTANCE_URL_TEMPLATE=` (empty) in
env returns empty and falls back to legacy routing. Tests exercise
prod default, dev defaults across loopback/non-loopback URLs, explicit
overrides, and the kill-switch opt-out.
---
 apps/web/src/lib/config.server.test.ts | 108 ++++++++++++++++++++-----
 apps/web/src/lib/config.server.ts      |  59 +++++++++++---
 2 files changed, 133 insertions(+), 34 deletions(-)

diff --git a/apps/web/src/lib/config.server.test.ts b/apps/web/src/lib/config.server.test.ts
index 1a6064f73..0e44de882 100644
--- a/apps/web/src/lib/config.server.test.ts
+++ b/apps/web/src/lib/config.server.test.ts
@@ -2,31 +2,97 @@ import { describe, it, expect } from '@jest/globals';
 import { resolveInstanceUrlTemplate } from './config.server';
 
 describe('resolveInstanceUrlTemplate', () => {
-  it('defaults to the canonical prod template when running in production with no override', () => {
-    expect(resolveInstanceUrlTemplate(undefined, 'production')).toBe('https://{label}.kiloclaw.ai');
-  });
+  describe('production', () => {
+    it('defaults to the canonical prod template when no override is set', () => {
+      expect(resolveInstanceUrlTemplate(undefined, 'production', 'https://claw.kilo.ai')).toBe(
+        'https://{label}.kiloclaw.ai'
+      );
+    });
 
-  it('returns empty in dev/test when no override is set', () => {
-    expect(resolveInstanceUrlTemplate(undefined, 'development')).toBe('');
-    expect(resolveInstanceUrlTemplate(undefined, 'test')).toBe('');
-    expect(resolveInstanceUrlTemplate(undefined, undefined)).toBe('');
-  });
+    it('honors an explicit override in production', () => {
+      expect(
+        resolveInstanceUrlTemplate(
+          'https://{label}.preview.kiloclaw.ai',
+          'production',
+          'https://claw.kilo.ai'
+        )
+      ).toBe('https://{label}.preview.kiloclaw.ai');
+    });
 
-  it('honors an explicit override in production', () => {
-    expect(resolveInstanceUrlTemplate('https://{label}.preview.kiloclaw.ai', 'production')).toBe(
-      'https://{label}.preview.kiloclaw.ai'
-    );
+    it('treats an explicit empty string as a kill switch in production', () => {
+      // Operators can roll back without a code deploy by setting
+      // KILOCLAW_INSTANCE_URL_TEMPLATE= (empty) in Vercel.
+      expect(resolveInstanceUrlTemplate('', 'production', 'https://claw.kilo.ai')).toBe('');
+    });
   });
 
-  it('treats an explicit empty string as a kill switch in production', () => {
-    // Operators can roll back without a code deploy by setting
-    // KILOCLAW_INSTANCE_URL_TEMPLATE= (empty) in Vercel.
-    expect(resolveInstanceUrlTemplate('', 'production')).toBe('');
-  });
+  describe('development / test defaults', () => {
+    it('derives a loopback-parity template from a localhost KILOCLAW_API_URL', () => {
+      expect(resolveInstanceUrlTemplate(undefined, 'development', 'http://localhost:8795')).toBe(
+        'http://{label}.kiloclaw.localhost:8795'
+      );
+    });
+
+    it('derives a loopback-parity template from a 127.0.0.1 KILOCLAW_API_URL', () => {
+      expect(resolveInstanceUrlTemplate(undefined, 'development', 'http://127.0.0.1:8795')).toBe(
+        'http://{label}.kiloclaw.localhost:8795'
+      );
+    });
+
+    it('preserves the port from KILOCLAW_API_URL when non-default', () => {
+      expect(resolveInstanceUrlTemplate(undefined, 'development', 'http://localhost:9999')).toBe(
+        'http://{label}.kiloclaw.localhost:9999'
+      );
+    });
+
+    it('preserves the scheme from KILOCLAW_API_URL', () => {
+      expect(resolveInstanceUrlTemplate(undefined, 'development', 'https://localhost:8795')).toBe(
+        'https://{label}.kiloclaw.localhost:8795'
+      );
+    });
+
+    it('falls back to the wrangler dev port when KILOCLAW_API_URL is missing', () => {
+      expect(resolveInstanceUrlTemplate(undefined, 'development', undefined)).toBe(
+        'http://{label}.kiloclaw.localhost:8795'
+      );
+    });
+
+    it('falls back when KILOCLAW_API_URL is unparsable', () => {
+      expect(resolveInstanceUrlTemplate(undefined, 'development', 'not a url')).toBe(
+        'http://{label}.kiloclaw.localhost:8795'
+      );
+    });
+
+    it('uses the fallback template when KILOCLAW_API_URL points at a non-loopback host', () => {
+      // Remote staging — dev mode with a non-local worker. We don't try
+      // to derive a wildcard host for it; fall back to the loopback
+      // template. Operators who want a real per-instance URL on remote
+      // staging set KILOCLAW_INSTANCE_URL_TEMPLATE explicitly.
+      expect(resolveInstanceUrlTemplate(undefined, 'development', 'https://staging.kilo.ai')).toBe(
+        'http://{label}.kiloclaw.localhost:8795'
+      );
+    });
+
+    it('defaults loopback-parity in test mode too', () => {
+      expect(resolveInstanceUrlTemplate(undefined, 'test', 'http://localhost:8795')).toBe(
+        'http://{label}.kiloclaw.localhost:8795'
+      );
+    });
+
+    it('honors a dev-parity override', () => {
+      expect(
+        resolveInstanceUrlTemplate(
+          'http://{label}.kiloclaw.localhost:8795',
+          'development',
+          'http://localhost:8795'
+        )
+      ).toBe('http://{label}.kiloclaw.localhost:8795');
+    });
 
-  it('honors a dev-parity override in development', () => {
-    expect(
-      resolveInstanceUrlTemplate('http://{label}.kiloclaw.localhost:8795', 'development')
-    ).toBe('http://{label}.kiloclaw.localhost:8795');
+    it('treats an explicit empty string as an opt-out in dev', () => {
+      // Devs who want the legacy path-based flow can set
+      // KILOCLAW_INSTANCE_URL_TEMPLATE= (empty) in .env.local.
+      expect(resolveInstanceUrlTemplate('', 'development', 'http://localhost:8795')).toBe('');
+    });
   });
 });
diff --git a/apps/web/src/lib/config.server.ts b/apps/web/src/lib/config.server.ts
index 657b368d0..dd62bb0b0 100644
--- a/apps/web/src/lib/config.server.ts
+++ b/apps/web/src/lib/config.server.ts
@@ -212,20 +212,30 @@ export const KILOCLAW_INBOUND_EMAIL_DOMAIN =
 /**
  * Per-instance worker URL template.
  *
+ * Per-instance URLs are the default in BOTH production and dev/test so a
+ * merge of the name-based routing feature flips them on automatically,
+ * without forcing anyone to edit env files.
+ *
  * Resolution rules:
  *   1. If `KILOCLAW_INSTANCE_URL_TEMPLATE` is set (to anything, including
- *      empty string), use that value. Explicit empty = kill switch for
- *      rolling back the per-instance URL without redeploying code.
+ *      empty string), use that value verbatim. Explicit empty = kill
+ *      switch / opt-out — operators can roll back without a code deploy,
+ *      devs can disable the per-instance flow locally, and tests can
+ *      force the legacy path.
  *   2. Otherwise in `NODE_ENV=production`, default to the canonical
- *      `https://{label}.kiloclaw.ai` template so merging this feature
- *      flips per-instance URLs on without a Vercel env var edit.
- *   3. Otherwise (dev/test) return empty → legacy path-based behaviour.
- *      Devs opt into dev-parity by setting
- *      `http://{label}.kiloclaw.localhost:8795` explicitly.
+ *      `https://{label}.kiloclaw.ai` template.
+ *   3. Otherwise (dev/test) derive a template from `KILOCLAW_API_URL`:
+ *      if `KILOCLAW_API_URL` looks like a loopback URL (`http://localhost:<port>`
+ *      / `http://127.0.0.1:<port>`), emit
+ *      `http://{label}.kiloclaw.localhost:<port>` so the browser
+ *      auto-resolves `*.kiloclaw.localhost` to `127.0.0.1` per RFC 6761.
+ *      If `KILOCLAW_API_URL` is missing or unparsable, fall back to the
+ *      same template with the wrangler dev port (`8795`) — matches
+ *      `.dev.vars.example`.
  *
- * When the template ends up set and contains `{label}`,
- * `getStatus` emits a `workerUrl` pointing at the instance's own virtual
- * host (derived from its sandboxId) for instances whose
+ * When the template ends up set and contains `{label}`, `getStatus`
+ * emits a `workerUrl` pointing at the instance's own virtual host
+ * (derived from its sandboxId) for instances whose
  * `controllerCapabilitiesVersion >= 2`. Pre-v2 instances keep falling
  * back to `KILOCLAW_API_URL`.
  *
@@ -233,17 +243,40 @@ export const KILOCLAW_INBOUND_EMAIL_DOMAIN =
  * re-import of this entire module (which triggers production-only
  * validation of unrelated secrets).
  */
+const DEFAULT_DEV_WRANGLER_PORT = '8795';
+
+function deriveDevTemplateFromWorkerUrl(workerUrl: string | undefined): string {
+  const fallback = `http://{label}.kiloclaw.localhost:${DEFAULT_DEV_WRANGLER_PORT}`;
+  if (!workerUrl) return fallback;
+  try {
+    const parsed = new URL(workerUrl);
+    // Only derive when we're pointed at a loopback dev worker. Anything
+    // else (remote staging, preview domains, etc.) uses the same
+    // fallback — operators can still override explicitly.
+    if (parsed.hostname !== 'localhost' && parsed.hostname !== '127.0.0.1') {
+      return fallback;
+    }
+    const port = parsed.port || DEFAULT_DEV_WRANGLER_PORT;
+    return `${parsed.protocol}//{label}.kiloclaw.localhost:${port}`;
+  } catch {
+    return fallback;
+  }
+}
+
 export function resolveInstanceUrlTemplate(
   envVar: string | undefined,
-  nodeEnv: string | undefined
+  nodeEnv: string | undefined,
+  workerUrl: string | undefined
 ): string {
   if (envVar !== undefined) return envVar;
-  return nodeEnv === 'production' ? 'https://{label}.kiloclaw.ai' : '';
+  if (nodeEnv === 'production') return 'https://{label}.kiloclaw.ai';
+  return deriveDevTemplateFromWorkerUrl(workerUrl);
 }
 
 export const KILOCLAW_INSTANCE_URL_TEMPLATE = resolveInstanceUrlTemplate(
   process.env.KILOCLAW_INSTANCE_URL_TEMPLATE,
-  process.env.NODE_ENV
+  process.env.NODE_ENV,
+  KILOCLAW_API_URL
 );
 
 // KiloClaw Early Bird Checkout

From 7772d4c19aae7025c5e7300790b25694834c7972 Mon Sep 17 00:00:00 2001
From: syn <syn@neonronin.sh>
Date: Mon, 4 May 2026 13:47:20 -0500
Subject: [PATCH 8/9] feat(kiloclaw): 301 redirect www.kiloclaw.ai -> apex

The `*.kiloclaw.ai/*` wildcard route catches `www.kiloclaw.ai`; without
an explicit handler it would surface as "Instance not found" 404 because
`www` fails hostname-label parsing. Add a canonical-redirect set
(currently just `www`) that 301s to the apex host derived from
`KILOCLAW_INSTANCE_HOST_SUFFIX` + `KILOCLAW_INSTANCE_URL_SCHEME`, so
dev parity works automatically (`www.kiloclaw.localhost:8795` ->
`kiloclaw.localhost:8795`) without hardcoding the apex.

Redirect target is built via URL setters (pathname/search), not string
concatenation, to sidestep the scheme-relative `//` open-redirect class
PR2 had to patch out of the capability-gate path.

Two new tests cover the prod and dev-parity cases.

DNS side: the existing proxied wildcard `AAAA * -> 100::` record on
`kiloclaw.ai` already covers `www`, and the wildcard cert SAN matches
one-label subdomains. No extra DNS / cert work needed.
---
 services/kiloclaw/src/index.test.ts | 26 +++++++++++++++++++++
 services/kiloclaw/src/index.ts      | 35 +++++++++++++++++++++++++++++
 2 files changed, 61 insertions(+)

diff --git a/services/kiloclaw/src/index.test.ts b/services/kiloclaw/src/index.test.ts
index 734e8a790..1eddb5a1f 100644
--- a/services/kiloclaw/src/index.test.ts
+++ b/services/kiloclaw/src/index.test.ts
@@ -826,6 +826,32 @@ describe('host-based routing', () => {
     expect(response.status).toBe(404);
   });
 
+  it('permanently redirects www.kiloclaw.ai to the apex preserving path and query', async () => {
+    const response = await app.fetch(
+      new Request('https://www.kiloclaw.ai/foo/bar?x=1&y=2', { redirect: 'manual' }),
+      baseEnv(),
+      { waitUntil: vi.fn() } as never
+    );
+
+    expect(response.status).toBe(301);
+    expect(response.headers.get('Location')).toBe('https://kiloclaw.ai/foo/bar?x=1&y=2');
+  });
+
+  it('preserves scheme + port from the suffix when redirecting www in dev parity', async () => {
+    const response = await app.fetch(
+      new Request('http://www.kiloclaw.localhost:8795/', { redirect: 'manual' }),
+      {
+        ...baseEnv(),
+        KILOCLAW_INSTANCE_HOST_SUFFIX: '.kiloclaw.localhost:8795',
+        KILOCLAW_INSTANCE_URL_SCHEME: 'http',
+      } as never,
+      { waitUntil: vi.fn() } as never
+    );
+
+    expect(response.status).toBe(301);
+    expect(response.headers.get('Location')).toBe('http://kiloclaw.localhost:8795/');
+  });
+
   it('skips host-based routing for reserved labels (e.g. claw) and falls through', async () => {
     // `claw` is reserved for controller check-in + platform traffic that's
     // registered before the catch-all. A request hitting the catch-all on
diff --git a/services/kiloclaw/src/index.ts b/services/kiloclaw/src/index.ts
index 8e80bbaa9..6772c7e76 100644
--- a/services/kiloclaw/src/index.ts
+++ b/services/kiloclaw/src/index.ts
@@ -638,6 +638,34 @@ async function resolveInstance(c: Context<AppEnv>): Promise<{
  */
 const RESERVED_INSTANCE_HOST_LABELS = new Set<string>(['claw']);
 
+/**
+ * Labels that should permanently 301 to the apex host (suffix with the
+ * leading dot stripped). The wildcard route on `*.kiloclaw.ai/*` catches
+ * these before they can surface as "instance not found" 404s, and the
+ * redirect target inherits the configured scheme + suffix so dev parity
+ * works without hardcoding `kiloclaw.ai`.
+ *
+ * Example (prod): `www.kiloclaw.ai/foo?q=1` → `https://kiloclaw.ai/foo?q=1`
+ */
+const CANONICAL_APEX_REDIRECT_LABELS = new Set<string>(['www']);
+
+/**
+ * Build the apex redirect target for a canonical-redirect label.
+ * Strips the leading dot from the suffix and pairs it with the configured
+ * scheme. Preserves path + search verbatim via the URL setters (not via
+ * string construction) to avoid scheme-relative (`//`) open-redirect
+ * footguns.
+ */
+function buildApexRedirectUrl(requestUrl: URL, env: KiloClawEnv): string {
+  const suffix = env.KILOCLAW_INSTANCE_HOST_SUFFIX ?? '';
+  const apexHost = suffix.startsWith('.') ? suffix.slice(1) : suffix;
+  const scheme = env.KILOCLAW_INSTANCE_URL_SCHEME ?? 'https';
+  const target = new URL(`${scheme}://${apexHost}`);
+  target.pathname = requestUrl.pathname;
+  target.search = requestUrl.search;
+  return target.toString();
+}
+
 /**
  * Resolve the DO key that a host-routed request should proxy to.
  *
@@ -687,6 +715,13 @@ async function handleHostBasedRoute(c: Context<AppEnv>): Promise<Response | null
     return c.json({ error: 'Instance not found' }, 404);
   }
 
+  // Canonical-host redirects (e.g. `www.kiloclaw.ai` → `kiloclaw.ai`).
+  // 301 happens before auth / ownership checks so the redirect target
+  // doesn't depend on request state.
+  if (CANONICAL_APEX_REDIRECT_LABELS.has(label)) {
+    return c.redirect(buildApexRedirectUrl(url, c.env), 301);
+  }
+
   // Reserved labels (e.g. `claw` for controller check-in, platform health
   // probes) are served by earlier-registered routes. If we've reached the
   // catch-all on a reserved label the path wasn't a controller/platform

From 787b9d268dbdadd7e1eed31f517158133b6f5008 Mon Sep 17 00:00:00 2001
From: syn <syn@neonronin.sh>
Date: Mon, 4 May 2026 14:09:00 -0500
Subject: [PATCH 9/9] =?UTF-8?q?fix(kiloclaw,web):=20address=20PR=20review?=
 =?UTF-8?q?=20=E2=80=94=20drop=20www=20redirect,=20harden=20kill=20switch?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two review findings on the latest PR3 commits.

1. **www redirect removed.** `CANONICAL_APEX_REDIRECT_LABELS` and
   `buildApexRedirectUrl` lived inside `handleHostBasedRoute`, which
   runs from the catch-all route. The catch-all is behind the global
   `authGuard` middleware, so unauthenticated `www.kiloclaw.ai`
   requests would 401 before the redirect could fire — exactly the
   traffic the redirect was meant to serve. Tests passed because the
   auth middleware is mocked to always succeed in the worker test
   harness. Rather than rearrange the middleware chain to make it
   work, drop the worker-side redirect entirely: the `www` → apex
   redirect is handled by Cloudflare DNS/edge routes, which is the
   right layer for this anyway (no worker invocation cost, runs
   before any auth, always correct).

2. **Kill switch now uses an explicit `legacy` sentinel.** The
   previous `KILOCLAW_INSTANCE_URL_TEMPLATE=` (empty string) rollback
   was brittle: Vercel / Node env pipelines frequently coerce empty
   entries into "unset", making an empty-string rollback
   indistinguishable from the default-on path (fails open). Switch to
   a non-empty word sentinel: `KILOCLAW_INSTANCE_URL_TEMPLATE=legacy`
   (case-insensitive) disables per-instance URLs. Empty string now
   falls through to the production/dev defaults, matching "unset"
   semantics across all env pipelines.

Tests updated to cover the new sentinel behavior and to assert that
empty string no longer disables the feature.
---
 apps/web/src/lib/config.server.test.ts | 40 +++++++++++++++++---------
 apps/web/src/lib/config.server.ts      | 38 ++++++++++++++++++------
 services/kiloclaw/src/index.test.ts    | 26 -----------------
 services/kiloclaw/src/index.ts         | 35 ----------------------
 4 files changed, 56 insertions(+), 83 deletions(-)

diff --git a/apps/web/src/lib/config.server.test.ts b/apps/web/src/lib/config.server.test.ts
index 0e44de882..cf53dd347 100644
--- a/apps/web/src/lib/config.server.test.ts
+++ b/apps/web/src/lib/config.server.test.ts
@@ -2,7 +2,33 @@ import { describe, it, expect } from '@jest/globals';
 import { resolveInstanceUrlTemplate } from './config.server';
 
 describe('resolveInstanceUrlTemplate', () => {
-  describe('production', () => {
+  describe('kill switch (KILOCLAW_INSTANCE_URL_TEMPLATE=legacy)', () => {
+    it('returns empty (legacy routing) when set to the kill-switch sentinel in production', () => {
+      expect(resolveInstanceUrlTemplate('legacy', 'production', 'https://claw.kilo.ai')).toBe('');
+    });
+
+    it('matches the sentinel case-insensitively', () => {
+      expect(resolveInstanceUrlTemplate('Legacy', 'production', 'https://claw.kilo.ai')).toBe('');
+      expect(resolveInstanceUrlTemplate('LEGACY', 'production', 'https://claw.kilo.ai')).toBe('');
+    });
+
+    it('also disables per-instance URLs in dev when set', () => {
+      expect(resolveInstanceUrlTemplate('legacy', 'development', 'http://localhost:8795')).toBe('');
+    });
+
+    it('treats an explicit empty string as "unset" (falls through to defaults), not as a kill switch', () => {
+      // Platform env pipelines often coerce empty values to "unset", so
+      // empty string must not be the rollback signal.
+      expect(resolveInstanceUrlTemplate('', 'production', 'https://claw.kilo.ai')).toBe(
+        'https://{label}.kiloclaw.ai'
+      );
+      expect(resolveInstanceUrlTemplate('', 'development', 'http://localhost:8795')).toBe(
+        'http://{label}.kiloclaw.localhost:8795'
+      );
+    });
+  });
+
+  describe('production defaults', () => {
     it('defaults to the canonical prod template when no override is set', () => {
       expect(resolveInstanceUrlTemplate(undefined, 'production', 'https://claw.kilo.ai')).toBe(
         'https://{label}.kiloclaw.ai'
@@ -18,12 +44,6 @@ describe('resolveInstanceUrlTemplate', () => {
         )
       ).toBe('https://{label}.preview.kiloclaw.ai');
     });
-
-    it('treats an explicit empty string as a kill switch in production', () => {
-      // Operators can roll back without a code deploy by setting
-      // KILOCLAW_INSTANCE_URL_TEMPLATE= (empty) in Vercel.
-      expect(resolveInstanceUrlTemplate('', 'production', 'https://claw.kilo.ai')).toBe('');
-    });
   });
 
   describe('development / test defaults', () => {
@@ -88,11 +108,5 @@ describe('resolveInstanceUrlTemplate', () => {
         )
       ).toBe('http://{label}.kiloclaw.localhost:8795');
     });
-
-    it('treats an explicit empty string as an opt-out in dev', () => {
-      // Devs who want the legacy path-based flow can set
-      // KILOCLAW_INSTANCE_URL_TEMPLATE= (empty) in .env.local.
-      expect(resolveInstanceUrlTemplate('', 'development', 'http://localhost:8795')).toBe('');
-    });
   });
 });
diff --git a/apps/web/src/lib/config.server.ts b/apps/web/src/lib/config.server.ts
index dd62bb0b0..a7ccad9d6 100644
--- a/apps/web/src/lib/config.server.ts
+++ b/apps/web/src/lib/config.server.ts
@@ -216,15 +216,20 @@ export const KILOCLAW_INBOUND_EMAIL_DOMAIN =
  * merge of the name-based routing feature flips them on automatically,
  * without forcing anyone to edit env files.
  *
- * Resolution rules:
- *   1. If `KILOCLAW_INSTANCE_URL_TEMPLATE` is set (to anything, including
- *      empty string), use that value verbatim. Explicit empty = kill
- *      switch / opt-out — operators can roll back without a code deploy,
- *      devs can disable the per-instance flow locally, and tests can
- *      force the legacy path.
- *   2. Otherwise in `NODE_ENV=production`, default to the canonical
+ * Resolution rules (checked in order):
+ *   1. `KILOCLAW_INSTANCE_URL_TEMPLATE=legacy` (case-insensitive) is the
+ *      explicit **kill switch** — disables per-instance URLs entirely and
+ *      falls back to the single-host `KILOCLAW_API_URL`. Operators can
+ *      roll prod back without a code deploy; devs can disable locally.
+ *      A non-empty sentinel is used (rather than empty string) because
+ *      Vercel / Node env pipelines often coerce empty env entries into
+ *      "unset", making an empty-string rollback unreliable.
+ *   2. A non-empty `KILOCLAW_INSTANCE_URL_TEMPLATE` is used verbatim.
+ *      Must contain `{label}`; missing placeholder is a misconfiguration
+ *      warned about at render time (see `workerUrlForInstance`).
+ *   3. Otherwise in `NODE_ENV=production`, default to the canonical
  *      `https://{label}.kiloclaw.ai` template.
- *   3. Otherwise (dev/test) derive a template from `KILOCLAW_API_URL`:
+ *   4. Otherwise (dev/test) derive a template from `KILOCLAW_API_URL`:
  *      if `KILOCLAW_API_URL` looks like a loopback URL (`http://localhost:<port>`
  *      / `http://127.0.0.1:<port>`), emit
  *      `http://{label}.kiloclaw.localhost:<port>` so the browser
@@ -245,6 +250,15 @@ export const KILOCLAW_INBOUND_EMAIL_DOMAIN =
  */
 const DEFAULT_DEV_WRANGLER_PORT = '8795';
 
+/**
+ * Sentinel value for `KILOCLAW_INSTANCE_URL_TEMPLATE` that disables the
+ * per-instance URL pattern entirely. Case-insensitive match. Picked as
+ * a non-empty word because empty env values are unreliable across
+ * Vercel / Node / dotenv pipelines (often dropped or indistinguishable
+ * from "unset"), which would mean the kill switch silently fails open.
+ */
+const KILL_SWITCH_SENTINEL = 'legacy';
+
 function deriveDevTemplateFromWorkerUrl(workerUrl: string | undefined): string {
   const fallback = `http://{label}.kiloclaw.localhost:${DEFAULT_DEV_WRANGLER_PORT}`;
   if (!workerUrl) return fallback;
@@ -268,7 +282,13 @@ export function resolveInstanceUrlTemplate(
   nodeEnv: string | undefined,
   workerUrl: string | undefined
 ): string {
-  if (envVar !== undefined) return envVar;
+  // Explicit kill switch. Empty string falls through to the production
+  // / dev defaults — operators must set `legacy` to disable, not "".
+  if (envVar !== undefined && envVar.toLowerCase() === KILL_SWITCH_SENTINEL) {
+    return '';
+  }
+  // Non-empty explicit override wins.
+  if (envVar !== undefined && envVar !== '') return envVar;
   if (nodeEnv === 'production') return 'https://{label}.kiloclaw.ai';
   return deriveDevTemplateFromWorkerUrl(workerUrl);
 }
diff --git a/services/kiloclaw/src/index.test.ts b/services/kiloclaw/src/index.test.ts
index 1eddb5a1f..734e8a790 100644
--- a/services/kiloclaw/src/index.test.ts
+++ b/services/kiloclaw/src/index.test.ts
@@ -826,32 +826,6 @@ describe('host-based routing', () => {
     expect(response.status).toBe(404);
   });
 
-  it('permanently redirects www.kiloclaw.ai to the apex preserving path and query', async () => {
-    const response = await app.fetch(
-      new Request('https://www.kiloclaw.ai/foo/bar?x=1&y=2', { redirect: 'manual' }),
-      baseEnv(),
-      { waitUntil: vi.fn() } as never
-    );
-
-    expect(response.status).toBe(301);
-    expect(response.headers.get('Location')).toBe('https://kiloclaw.ai/foo/bar?x=1&y=2');
-  });
-
-  it('preserves scheme + port from the suffix when redirecting www in dev parity', async () => {
-    const response = await app.fetch(
-      new Request('http://www.kiloclaw.localhost:8795/', { redirect: 'manual' }),
-      {
-        ...baseEnv(),
-        KILOCLAW_INSTANCE_HOST_SUFFIX: '.kiloclaw.localhost:8795',
-        KILOCLAW_INSTANCE_URL_SCHEME: 'http',
-      } as never,
-      { waitUntil: vi.fn() } as never
-    );
-
-    expect(response.status).toBe(301);
-    expect(response.headers.get('Location')).toBe('http://kiloclaw.localhost:8795/');
-  });
-
   it('skips host-based routing for reserved labels (e.g. claw) and falls through', async () => {
     // `claw` is reserved for controller check-in + platform traffic that's
     // registered before the catch-all. A request hitting the catch-all on
diff --git a/services/kiloclaw/src/index.ts b/services/kiloclaw/src/index.ts
index 6772c7e76..8e80bbaa9 100644
--- a/services/kiloclaw/src/index.ts
+++ b/services/kiloclaw/src/index.ts
@@ -638,34 +638,6 @@ async function resolveInstance(c: Context<AppEnv>): Promise<{
  */
 const RESERVED_INSTANCE_HOST_LABELS = new Set<string>(['claw']);
 
-/**
- * Labels that should permanently 301 to the apex host (suffix with the
- * leading dot stripped). The wildcard route on `*.kiloclaw.ai/*` catches
- * these before they can surface as "instance not found" 404s, and the
- * redirect target inherits the configured scheme + suffix so dev parity
- * works without hardcoding `kiloclaw.ai`.
- *
- * Example (prod): `www.kiloclaw.ai/foo?q=1` → `https://kiloclaw.ai/foo?q=1`
- */
-const CANONICAL_APEX_REDIRECT_LABELS = new Set<string>(['www']);
-
-/**
- * Build the apex redirect target for a canonical-redirect label.
- * Strips the leading dot from the suffix and pairs it with the configured
- * scheme. Preserves path + search verbatim via the URL setters (not via
- * string construction) to avoid scheme-relative (`//`) open-redirect
- * footguns.
- */
-function buildApexRedirectUrl(requestUrl: URL, env: KiloClawEnv): string {
-  const suffix = env.KILOCLAW_INSTANCE_HOST_SUFFIX ?? '';
-  const apexHost = suffix.startsWith('.') ? suffix.slice(1) : suffix;
-  const scheme = env.KILOCLAW_INSTANCE_URL_SCHEME ?? 'https';
-  const target = new URL(`${scheme}://${apexHost}`);
-  target.pathname = requestUrl.pathname;
-  target.search = requestUrl.search;
-  return target.toString();
-}
-
 /**
  * Resolve the DO key that a host-routed request should proxy to.
  *
@@ -715,13 +687,6 @@ async function handleHostBasedRoute(c: Context<AppEnv>): Promise<Response | null
     return c.json({ error: 'Instance not found' }, 404);
   }
 
-  // Canonical-host redirects (e.g. `www.kiloclaw.ai` → `kiloclaw.ai`).
-  // 301 happens before auth / ownership checks so the redirect target
-  // doesn't depend on request state.
-  if (CANONICAL_APEX_REDIRECT_LABELS.has(label)) {
-    return c.redirect(buildApexRedirectUrl(url, c.env), 301);
-  }
-
   // Reserved labels (e.g. `claw` for controller check-in, platform health
   // probes) are served by earlier-registered routes. If we've reached the
   // catch-all on a reserved label the path wasn't a controller/platform