fix: recover stale runtime adapter claims (#448)

steipete · web-flow · commit 943798f62935 · 2026-06-17T15:09:03.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,7 @@
 
 ### Fixed
 
+- Made new runtime-adapter ticket claims provisional until agent connection or lease registration, allowing authenticated recovery of expired inactive first claims while preserving all existing and confirmed adapter IDs.
 - Separated shared automation tokens from signed user-token keys, preserving shared-token-only automation while requiring distinct session signing material for GitHub login.
 - Required retained coordinator ownership records before orphan sweeps delete AWS or Azure machines or release EC2 Mac hosts, while keeping tag-only and legacy candidates visible in reports.
 - Verified the pinned GitHub CLI release artifacts before installing them in the default Cloudflare sandbox image and preserved true AMD64/ARM64 target selection during cross-platform builds.
diff --git a/docs/commands/adapter.md b/docs/commands/adapter.md
@@ -155,6 +155,14 @@ atomically rotated token is never pinned in the relay process. Coordinator
 authentication may be a static login token or the normal shell-free
 token-command configuration.
 
+The first ticket for a previously unused adapter ID creates a ten-minute
+provisional owner/org claim. A successful agent connection or registered lease
+binding makes that claim durable. Another normally authenticated owner may
+recover an expired provisional claim only when it has no connected agent,
+pending relay request, unexpired ticket, live registered lease, or pending
+workspace deletion. Existing adapter claims created before this contract are
+treated as durable, so upgrades do not change current adapter ownership.
+
 `--local-socket` is required. It must be an absolute, clean Unix-socket path in
 an existing directory owned by the current user and not writable by group or
 others. The socket must also be owned by the current user with mode `0600`.
diff --git a/docs/features/coordinator.md b/docs/features/coordinator.md
@@ -141,9 +141,14 @@ WebVNC/share operation still requires the record to exist.
 
 Runtime adapters connect outbound to `/agent`, so their local lifecycle service
 does not need an inbound public route. The coordinator issues a short-lived,
-single-use ticket after normal owner authentication. The first ticket safely
-claims the adapter ID for that owner and organization; lease registration
-rejects unclaimed IDs and claims owned by another identity. The relay permits
+single-use ticket after normal owner authentication. The first ticket for a new
+adapter ID creates a ten-minute provisional owner/org claim. Agent connection or
+successful registered lease binding confirms it as durable. An expired
+provisional claim can be recovered by another normally authenticated owner only
+when no connected agent, pending relay request, unexpired ticket, live registered
+lease, or pending workspace deletion still uses it. Existing and confirmed
+claims remain durable. Lease registration rejects unclaimed IDs and claims owned
+by another identity. The relay permits
 only the versioned workspace create, inspect, delete, and desktop-connection
 methods. Public proxy `DELETE` requests are rejected; destructive dispatch must
 go through a registered lease release so the coordinator can fence its immutable
diff --git a/docs/features/runtime-adapter-stack.md b/docs/features/runtime-adapter-stack.md
@@ -86,7 +86,10 @@ files, or provider credentials. Keep the bearer token between the fleet UI and
 ### Outbound coordinator control
 
 1. `adapter connect` authenticates to the coordinator using normal Crabbox
-   configuration and obtains a short-lived relay ticket.
+   configuration and obtains a short-lived relay ticket. A new adapter ID starts
+   with a ten-minute provisional owner/org claim; agent connection or successful
+   lease registration makes it durable. Only expired inactive provisional claims
+   are recoverable, and existing adapter claims remain durable across upgrades.
 2. It opens an outbound WebSocket and accepts only the documented typed
    workspace operations.
 3. Each operation is forwarded through the verified, current-user-owned Unix
diff --git a/worker/src/fleet.ts b/worker/src/fleet.ts
@@ -143,6 +143,7 @@ const codeViewerTicketTTLSeconds = 120;
 const codeViewerSessionTTLSeconds = 8 * 60 * 60;
 const egressTicketTTLSeconds = 120;
 const runtimeAdapterTicketTTLSeconds = 120;
+const runtimeAdapterProvisionalClaimTTLSeconds = 10 * 60;
 const runtimeAdapterDeleteRetryBaseMs = 5_000;
 const runtimeAdapterDeleteRetryMaxMs = 60_000;
 const runtimeAdapterDeleteDispatchGraceMs = 1_000;
@@ -257,6 +258,10 @@ interface RuntimeAdapterIdentityRecord {
   owner: string;
   org: string;
   createdAt: string;
+  claimVersion?: 1;
+  claimState?: "provisional" | "confirmed";
+  claimExpiresAt?: string;
+  confirmedAt?: string;
 }
 
 interface RuntimeAdapterPendingRequest {
@@ -3675,6 +3680,7 @@ export class FleetCoordinator {
         { status: 409 },
       );
     }
+    let runtimeAdapterIdentity: RuntimeAdapterIdentityRecord | undefined;
     if (effectiveRuntimeAdapterID && effectiveRuntimeAdapterWorkspaceID) {
       const identity = await this.state.storage.get<RuntimeAdapterIdentityRecord>(
         runtimeAdapterIdentityKey(effectiveRuntimeAdapterID),
@@ -3701,6 +3707,7 @@ export class FleetCoordinator {
           { status: 409 },
         );
       }
+      runtimeAdapterIdentity = identity;
     }
 
     const leases = await this.leaseRecords();
@@ -3817,6 +3824,9 @@ export class FleetCoordinator {
       clearRuntimeAdapterDeleteMetadata(record);
     }
     await this.putLease(record);
+    if (runtimeAdapterIdentity) {
+      await this.confirmRuntimeAdapterIdentity(runtimeAdapterIdentity, nowISO);
+    }
     await this.scheduleAlarm();
     return json({ lease: record }, { status: existing ? 200 : 201 });
   }
@@ -5802,28 +5812,49 @@ export class FleetCoordinator {
     const owner = requestOwner(request);
     const org = requestOrg(request, this.env);
     const identityKey = runtimeAdapterIdentityKey(adapterID);
-    const identity = await this.state.storage.get<RuntimeAdapterIdentityRecord>(identityKey);
+    await this.cleanupExpiredRuntimeAdapterTickets();
+    const now = new Date();
+    let identity = await this.state.storage.get<RuntimeAdapterIdentityRecord>(identityKey);
     if (
       identity &&
       (identity.adapterID !== adapterID || identity.owner !== owner || identity.org !== org)
     ) {
-      return json(
-        {
-          error: "adapter_id_conflict",
-          message: "runtime adapter id belongs to another owner or organization",
-        },
-        { status: 409 },
-      );
+      if (!(await this.runtimeAdapterIdentityReclaimable(identity, adapterID, now.getTime()))) {
+        return json(
+          {
+            error: "adapter_id_conflict",
+            message: "runtime adapter id belongs to another owner or organization",
+          },
+          { status: 409 },
+        );
+      }
+      identity = undefined;
     }
-    await this.cleanupExpiredRuntimeAdapterTickets();
-    const now = new Date();
     if (!identity) {
-      await this.state.storage.put<RuntimeAdapterIdentityRecord>(identityKey, {
+      identity = {
         adapterID,
         owner,
         org,
         createdAt: now.toISOString(),
-      });
+        claimVersion: 1,
+        claimState: "provisional",
+        claimExpiresAt: new Date(
+          now.getTime() + runtimeAdapterProvisionalClaimTTLSeconds * 1000,
+        ).toISOString(),
+      };
+      await this.state.storage.put<RuntimeAdapterIdentityRecord>(identityKey, identity);
+    } else if (
+      identity.claimVersion === 1 &&
+      identity.claimState === "provisional" &&
+      !identity.confirmedAt
+    ) {
+      identity = {
+        ...identity,
+        claimExpiresAt: new Date(
+          now.getTime() + runtimeAdapterProvisionalClaimTTLSeconds * 1000,
+        ).toISOString(),
+      };
+      await this.state.storage.put<RuntimeAdapterIdentityRecord>(identityKey, identity);
     }
     const ticket: RuntimeAdapterTicketRecord = {
       ticket: newRuntimeAdapterTicket(),
@@ -5877,6 +5908,7 @@ export class FleetCoordinator {
         { status: 401 },
       );
     }
+    await this.confirmRuntimeAdapterIdentity(identity, new Date().toISOString());
     const upgrade = this.state.createWebSocketUpgrade({
       maxPayload: runtimeAdapterRelayFrameLimit,
     });
@@ -7421,6 +7453,63 @@ export class FleetCoordinator {
     );
   }
 
+  private async runtimeAdapterIdentityReclaimable(
+    identity: RuntimeAdapterIdentityRecord,
+    adapterID: string,
+    now: number,
+  ): Promise<boolean> {
+    if (
+      identity.adapterID !== adapterID ||
+      identity.claimVersion !== 1 ||
+      identity.claimState !== "provisional" ||
+      identity.confirmedAt !== undefined ||
+      !Number.isFinite(Date.parse(identity.claimExpiresAt ?? "")) ||
+      Date.parse(identity.claimExpiresAt ?? "") > now ||
+      this.runtimeAdapterAgents.has(adapterID) ||
+      [...this.runtimeAdapterPending.values()].some((pending) => pending.adapterID === adapterID)
+    ) {
+      return false;
+    }
+    const [tickets, leases] = await Promise.all([
+      this.state.storage.list<RuntimeAdapterTicketRecord>({
+        prefix: runtimeAdapterTicketPrefix(),
+      }),
+      this.leaseRecords(),
+    ]);
+    if (
+      [...tickets.values()].some(
+        (ticket) => ticket.adapterID === adapterID && Date.parse(ticket.expiresAt) > now,
+      )
+    ) {
+      return false;
+    }
+    return !leases.some(
+      (lease) =>
+        lease.runtimeAdapterID === adapterID &&
+        (leaseIsLive(lease) || Boolean(lease.runtimeAdapterDeleteRequestedAt)),
+    );
+  }
+
+  private async confirmRuntimeAdapterIdentity(
+    identity: RuntimeAdapterIdentityRecord,
+    confirmedAt: string,
+  ): Promise<void> {
+    if (
+      identity.claimVersion !== 1 ||
+      identity.claimState !== "provisional" ||
+      identity.confirmedAt !== undefined
+    ) {
+      return;
+    }
+    const confirmed: RuntimeAdapterIdentityRecord = {
+      ...identity,
+      claimState: "confirmed",
+      confirmedAt,
+    };
+    delete confirmed.claimExpiresAt;
+    await this.state.storage.put(runtimeAdapterIdentityKey(identity.adapterID), confirmed);
+  }
+
   private async consumeWebVNCTicket(
     request: Request,
     identifier: string,
diff --git a/worker/test/coordinator-runtime.test.ts b/worker/test/coordinator-runtime.test.ts
@@ -39,6 +39,10 @@ class MemoryStorage implements CoordinatorStorage {
         .map(([key, value]) => [key, value as T]),
     );
   }
+
+  value<T>(key: string): T | undefined {
+    return this.values.get(key) as T | undefined;
+  }
 }
 
 class MemoryRuntime implements CoordinatorRuntime {
@@ -148,6 +152,11 @@ describe("coordinator runtimes", () => {
     expect(runtime.upgradeOptions).toEqual({ maxPayload: runtimeAdapterRelayFrameLimit });
     expect(runtime.acceptedTags).toEqual(["adapter:example-adapter", "runtime-adapter-agent"]);
     expect(runtime.acceptedAttachment).toMatchObject({ desktopTimeoutMs: 180_000 });
+    expect(runtime.storage.value("runtime-adapter-identity:example-adapter")).toMatchObject({
+      claimVersion: 1,
+      claimState: "confirmed",
+      confirmedAt: expect.any(String),
+    });
   });
 
   it("keeps provider-backed portal requests outside the lifecycle queue", () => {
diff --git a/worker/test/fleet.test.ts b/worker/test/fleet.test.ts
