feat(kiloclaw): add KiloClawRegistry DO and complete instance-keyed identity migration

kiloclaw/drizzle.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'drizzle-kit';
+export default defineConfig({
+  out: './drizzle',
+  schema: './src/db/sqlite-schema.ts',
+  dialect: 'sqlite',
+  driver: 'durable-sqlite',
+});

kiloclaw/drizzle/0000_messy_grim_reaper.sql

@@ -0,0 +1,7 @@
+CREATE TABLE `instances` (
+	`instance_id` text PRIMARY KEY NOT NULL,
+	`do_key` text NOT NULL,
+	`assigned_user_id` text NOT NULL,
+	`created_at` text NOT NULL,
+	`destroyed_at` text
+);

kiloclaw/drizzle/meta/0000_snapshot.json

@@ -0,0 +1,63 @@
+{
+  "version": "6",
+  "dialect": "sqlite",
+  "id": "f488eead-1986-472a-8973-f487dc7599bf",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "tables": {
+    "instances": {
+      "name": "instances",
+      "columns": {
+        "instance_id": {
+          "name": "instance_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "do_key": {
+          "name": "do_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "assigned_user_id": {
+          "name": "assigned_user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "autoincrement": false
+        },
+        "destroyed_at": {
+          "name": "destroyed_at",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false,
+          "autoincrement": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "checkConstraints": {}
+    }
+  },
+  "views": {},
+  "enums": {},
+  "_meta": {
+    "schemas": {},
+    "tables": {},
+    "columns": {}
+  },
+  "internal": {
+    "indexes": {}
+  }
+}

kiloclaw/drizzle/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "sqlite",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "6",
+      "when": 1774809105002,
+      "tag": "0000_messy_grim_reaper",
+      "breakpoints": true
+    }
+  ]
+}

kiloclaw/drizzle/migrations.js

@@ -0,0 +1,9 @@
+import journal from './meta/_journal.json';
+import m0000 from './0000_messy_grim_reaper.sql';
+
+export default {
+  journal,
+  migrations: {
+    m0000,
+  },
+};

kiloclaw/package.json

@@ -33,6 +33,7 @@
     "@types/node": "^22.19.15",
     "@typescript/native-preview": "catalog:",
     "@vitest/coverage-v8": "^4.1.0",
+    "drizzle-kit": "catalog:",
     "typescript": "catalog:",
     "vitest": "^4.1.0",
     "wrangler": "catalog:"

kiloclaw/src/db/sqlite-schema.ts

@@ -0,0 +1,10 @@
+import { sqliteTable, text } from 'drizzle-orm/sqlite-core';
+
+/** Registry DO SQLite table: tracks instance ownership per registry (user or org). */
+export const registryInstances = sqliteTable('instances', {
+  instance_id: text('instance_id').primaryKey(),
+  do_key: text('do_key').notNull(),
+  assigned_user_id: text('assigned_user_id').notNull(),
+  created_at: text('created_at').notNull(),
+  destroyed_at: text('destroyed_at'),
+});

kiloclaw/src/durable-objects/kiloclaw-instance/index.ts

@@ -22,6 +22,10 @@ import { DEFAULT_INSTANCE_FEATURES } from '../../schemas/instance-config';
 import type { FlyVolume, FlyVolumeSnapshot } from '../../fly/types';
 import * as fly from '../../fly/client';
 import { sandboxIdFromUserId, sandboxIdFromInstanceId } from '../../auth/sandbox-id';
+import {
+  isInstanceKeyedSandboxId,
+  instanceIdFromSandboxId,
+} from '@kilocode/worker-utils/instance-id';
 import { resolveLatestVersion, resolveVersionByTag } from '../../lib/image-version';
 import { lookupCatalogVersion } from '../../lib/catalog-registration';
 import { ImageVariantSchema } from '../../schemas/image-version';
@@ -927,7 +931,9 @@ export class KiloClawInstance extends DurableObject<KiloClawEnv> {
     if (!this.s.userId || !this.s.sandboxId) {
       const restoreUserId = userId ?? this.s.userId;
       if (restoreUserId) {
-        await restoreFromPostgres(this.env, this.ctx, this.s, restoreUserId);
+        await restoreFromPostgres(this.env, this.ctx, this.s, restoreUserId, {
+          sandboxId: this.s.sandboxId,
+        });
       }
     }
 
@@ -1300,13 +1306,69 @@ export class KiloClawInstance extends DurableObject<KiloClawEnv> {
     await tryDeleteMachine(flyConfig, this.ctx, this.s, destroyRctx);
     await tryDeleteVolume(flyConfig, this.ctx, this.s, destroyRctx);
 
+    // Capture identity before finalization wipes state
+    const preDestroyUserId = this.s.userId;
+    const preDestroyOrgId = this.s.orgId;
+    const preDestroySandboxId = this.s.sandboxId;
+
     const finalized = await finalizeDestroyIfComplete(
       this.ctx,
       this.s,
       destroyRctx,
       (userId, sandboxId) =>
         markDestroyedInPostgresHelper(this.env, this.ctx, this.s, userId, sandboxId)
     );
+
+    // Clean up registry entry on finalization. This covers both platform-initiated
+    // and alarm-initiated destroys. The platform route's registry cleanup is
+    // redundant but harmless (destroyInstance is idempotent on already-destroyed entries).
+    if (finalized.finalized && preDestroyUserId && preDestroySandboxId) {
+      try {
+        const registryInstanceId = isInstanceKeyedSandboxId(preDestroySandboxId)
+          ? instanceIdFromSandboxId(preDestroySandboxId)
+          : null;
+
+        const registryKeys = [`user:${preDestroyUserId}`];
+        if (preDestroyOrgId) registryKeys.push(`org:${preDestroyOrgId}`);
+
+        for (const registryKey of registryKeys) {
+          const registryStub = this.env.KILOCLAW_REGISTRY.get(
+            this.env.KILOCLAW_REGISTRY.idFromName(registryKey)
+          );
+          if (registryInstanceId) {
+            await registryStub.destroyInstance(registryKey, registryInstanceId);
+            console.log('[DO] Registry entry destroyed on finalization:', {
+              registryKey,
+              instanceId: registryInstanceId,
+            });
+          } else {
+            // Legacy: find active entry by doKey=userId
+            const entries = await registryStub.listInstances(registryKey);
+            const legacyEntry = entries.find(e => e.doKey === preDestroyUserId);
+            if (legacyEntry) {
+              await registryStub.destroyInstance(registryKey, legacyEntry.instanceId);
+              console.log('[DO] Registry entry destroyed on finalization (legacy):', {
+                registryKey,
+                instanceId: legacyEntry.instanceId,
+                doKey: preDestroyUserId,
+              });
+            } else {
+              console.log(
+                '[DO] Registry cleanup: no active entry found (already cleaned or never existed):',
+                {
+                  registryKey,
+                  doKey: preDestroyUserId,
+                  activeEntryCount: entries.length,
+                }
+              );
+            }
+          }
+        }
+      } catch (registryErr) {
+        console.error('[DO] Registry cleanup on finalization failed (non-fatal):', registryErr);
+      }
+    }
+
     if (!finalized.finalized) {
       doWarn(this.s, 'Destroy incomplete, alarm will retry', {
         pendingMachineId: this.s.pendingDestroyMachineId,
@@ -1707,6 +1769,10 @@ export class KiloClawInstance extends DurableObject<KiloClawEnv> {
         snapshotId,
         previousVolumeId,
         region: this.s.flyRegion,
+        instanceId:
+          this.s.sandboxId && isInstanceKeyedSandboxId(this.s.sandboxId)
+            ? instanceIdFromSandboxId(this.s.sandboxId)
+            : undefined,
       });
     } catch (err) {
       this.s.status = previousStatus;

kiloclaw/src/durable-objects/kiloclaw-instance/postgres.ts

@@ -1,21 +1,36 @@
 import type { KiloClawEnv } from '../../types';
 import type { EncryptedEnvelope } from '../../schemas/instance-config';
-import { getWorkerDb, getActiveInstance, markInstanceDestroyed } from '../../db';
+import {
+  getWorkerDb,
+  getActiveInstance,
+  getInstanceBySandboxId,
+  markInstanceDestroyed,
+} from '../../db';
 import { appNameFromUserId } from '../../fly/apps';
 import type { InstanceMutableState } from './types';
 import { getFlyConfig } from './types';
 import { storageUpdate } from './state';
 import { attemptMetadataRecovery } from './reconcile';
 import { doError, doWarn, toLoggable, createReconcileContext } from './log';
 
+type RestoreOpts = {
+  /** If the DO has a stored sandboxId, use it for precise lookup. */
+  sandboxId?: string | null;
+};
+
 /**
  * Restore DO state from Postgres backup if SQLite was wiped.
+ *
+ * Lookup priority:
+ * 1. If opts.sandboxId is provided, look up by sandbox_id (precise, multi-instance safe).
+ * 2. Otherwise, fall back to getActiveInstance(db, userId) (legacy single-instance).
  */
 export async function restoreFromPostgres(
   env: KiloClawEnv,
   ctx: DurableObjectState,
   state: InstanceMutableState,
-  userId: string
+  userId: string,
+  opts?: RestoreOpts
 ): Promise<void> {
   const connectionString = env.HYPERDRIVE?.connectionString;
   if (!connectionString) {
@@ -25,7 +40,11 @@ export async function restoreFromPostgres(
 
   try {
     const db = getWorkerDb(connectionString);
-    const instance = await getActiveInstance(db, userId);
+
+    // Prefer sandboxId lookup (multi-instance safe) over userId lookup (ambiguous).
+    const instance = opts?.sandboxId
+      ? await getInstanceBySandboxId(db, opts.sandboxId)
+      : await getActiveInstance(db, userId);
 
     if (!instance) {
       doWarn(state, 'No active instance found in Postgres', { userId });