@abloatai/humans 0.44.0 → 0.46.0

package/dist/local/transactions/mutations/commitPayload.d.ts

@@ -54,6 +54,8 @@ export interface QueuedMutation {
     status: 'pending' | 'executing' | 'awaiting_delta' | 'completed' | 'failed' | 'rolled_back';
     createdAt: number;
     attempts: number;
+    /** First transient dispatch failure in the current availability incident. */
+    firstTransientFailureAt?: number;
     priority: 'normal' | 'high';
     priorityScore: number;
     writeOptions?: WriteOptions;

package/dist/local/transactions/mutations/failureHandling.d.ts

@@ -4,7 +4,7 @@ import type { QueuedMutation } from './commitPayload.js';
 import type { MutationStore } from './MutationStore.js';
 export interface FailureHandlingContext {
     readonly runtime: RuntimeContext;
-    readonly config: Pick<MutationQueueConfig, 'enableOptimistic' | 'maxRetries' | 'retryBackoff'>;
+    readonly config: Pick<MutationQueueConfig, 'enableOptimistic' | 'maxRetries' | 'retryBackoff' | 'availabilityRetryWindowMs'>;
     readonly store: MutationStore;
     readonly isPermanentError: (error: Error) => boolean;
     readonly rollbackOptimistic: (transaction: QueuedMutation, reason: string, error?: Error) => Promise<void>;
@@ -13,4 +13,5 @@ export interface FailureHandlingContext {
     readonly setLastPermanentErrorSignature: (signature: string) => void;
     readonly emit: (event: string, payload: object) => boolean;
 }
+export declare function transientRetryDelayMs(error: Error, attempt: number, retryBackoff: MutationQueueConfig['retryBackoff']): number;
 export declare function handleFailure(ctx: FailureHandlingContext, transaction: QueuedMutation, error: Error): Promise<void>;

package/dist/local/transactions/mutations/failureHandling.js

@@ -1,5 +1,17 @@
 import { AbloError } from '@abloatai/transaction/errors';
 import { extractStatusCode } from './commitPayload.js';
+export function transientRetryDelayMs(error, attempt, retryBackoff) {
+    const { baseMs, capMs } = retryBackoff;
+    let base = baseMs;
+    try {
+        const status = extractStatusCode(error);
+        if (status === 429 || status === 503)
+            base = Math.max(baseMs, 1_000);
+    }
+    catch { }
+    const ceiling = Math.min(capMs, base * Math.pow(2, Math.max(0, attempt - 1)));
+    return Math.floor(Math.random() * ceiling);
+}
 export async function handleFailure(ctx, transaction, error) {
     transaction.attempts++;
     // Check whether this is a permanent error that should not be retried.
@@ -95,22 +107,15 @@ export async function handleFailure(ctx, transaction, error) {
         ctx.emit(`transaction:failed:${transaction.id}`, { error });
         return;
     }
-    if (transaction.attempts < ctx.config.maxRetries) {
+    transaction.firstTransientFailureAt ??= Date.now();
+    const insideAvailabilityWindow = Date.now() - transaction.firstTransientFailureAt < ctx.config.availabilityRetryWindowMs;
+    if (transaction.attempts < ctx.config.maxRetries || insideAvailabilityWindow) {
         // Exponential backoff with full jitter on every transient retry:
         // `sleep = random(0, min(cap, base * 2^attempt))`. Throttling responses
         // (429/503) use a longer base than other transient errors. The re-enqueue
         // is scheduled rather than awaited, so one backing-off transaction cannot
         // stall unrelated commits.
-        const { baseMs, capMs } = ctx.config.retryBackoff;
-        let base = baseMs;
-        try {
-            const status = extractStatusCode(error);
-            if (status === 429 || status === 503)
-                base = Math.max(baseMs, 1_000);
-        }
-        catch { }
-        const ceiling = Math.min(capMs, base * Math.pow(2, transaction.attempts - 1));
-        const delay = Math.floor(Math.random() * ceiling);
+        const delay = transientRetryDelayMs(error, transaction.attempts, ctx.config.retryBackoff);
         ctx.store.updateStatus(transaction.id, 'pending');
         setTimeout(() => {
             // The queue may have shut down or the tx may have been settled

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/humans",
-  "version": "0.44.0",
+  "version": "0.46.0",
   "description": "The optional human-facing local-state package for Ablo: presence, live queries, and React bindings.",
   "license": "Apache-2.0",
   "type": "module",
@@ -84,7 +84,7 @@
     "directory": "packages/humans"
   },
   "dependencies": {
-    "@abloatai/transaction": "^0.44.0",
+    "@abloatai/transaction": "^0.46.0",
     "mobx": "^6.13.7",
     "uuid": "^11.1.0",
     "zod": "^4.4.3"

package/src/Ablo.ts

@@ -388,6 +388,12 @@ export namespace Ablo {
     export type Held<T = Record<string, unknown>> = import('@abloatai/transaction/types/streams').HeldClaim<T>;
     export type CreateOptions = import('./local/client/resourceTypes.js').ClaimCreateOptions;
     export type WaitOptions = import('./local/client/resourceTypes.js').ClaimWaitOptions;
+    export type ContentionOptions =
+      import('@abloatai/transaction/resources/modelOperations').ClaimContentionOptions;
+    export type AttemptEvent =
+      import('@abloatai/transaction/resources/modelOperations').ClaimAttemptEvent;
+    export type QueueView =
+      import('@abloatai/transaction/resources/modelOperations').ClaimQueueView;
     export type Client = import('./local/client/resourceTypes.js').ClaimResource;
   }
 

package/src/local/client/createModelProxy.ts

@@ -78,6 +78,11 @@ export type {
   ServerRetrieveOptions,
   ClaimTargetOptions,
   ClaimParams,
+  ClaimContentionOptions,
+  ClaimAttemptEvent,
+  ClaimQueueView,
+  ClaimSkipOptions,
+  ClaimSkipParams,
   ClaimLookupParams,
   ClaimReorderParams,
   ClaimOptions,
@@ -97,6 +102,10 @@ import type {
   ClaimLookupParams,
   ClaimOptions,
   ClaimParams,
+  ClaimSkipOptions,
+  ClaimSkipParams,
+  ClaimAttemptEvent,
+  ClaimQueueView,
   ClaimReorderParams,
   JoinOptions,
   LocalCountOptions,
@@ -109,6 +118,10 @@ import type {
   ModelUpdateParams,
   ServerReadOptions,
 } from '@abloatai/transaction/resources/modelOperations';
+import {
+  claimQueueView,
+  resolveClaimContentionOptions,
+} from '@abloatai/transaction/resources/modelOperations';
 import type { HttpModelClient } from '@abloatai/transaction/transport/httpClient';
 import type { ParticipantKind } from '@abloatai/transaction/types/participant';
 
@@ -160,6 +173,8 @@ export interface ModelCollaboration {
     waitTimeoutMs?: number;
     /** Abort the queued wait — rejects with `claim_wait_aborted`. */
     signal?: AbortSignal;
+    /** Request-scoped queued / granted / skipped / failed status events. */
+    onStatus?: (event: ClaimAttemptEvent) => void;
   }): Promise<Claim>;
   createSnapshot(modelKey: string, id: string): Snapshot;
   /**
@@ -557,23 +572,13 @@ export function createModelProxy<T, C>(
       );
     }
     const { id, ...options } = params;
-    // Is someone else already on this target? Read the local coordination
-    // snapshot up front — it decides whether a re-read is needed after the
-    // claim (a free or already-held target cannot have changed underneath us).
+    // Read the local snapshot only to decide whether a post-grant re-read may
+    // be needed. Admission itself always goes to the server: a local presence
+    // snapshot may be stale or incomplete across instances.
     const held = collaboration.state({ model: wireModel, id });
     const contended = !!held && held.heldBy !== collaboration.selfParticipantId;
-    const failFast = options.queue === false;
-
-    // The try-claim (`queue: false`): a held target is an expected outcome,
-    // not an error, so it resolves `null` — the caller reads `if (!claim)`
-    // and moves on; who holds it stays readable via `claim.state`. Best-effort
-    // at the client (a racing claim not yet synced into our snapshot slips
-    // through here) — the commit-time claim guard is the authoritative
-    // backstop that rejects the loser's first write. For work-distribution
-    // dedup that's exactly right: don't wait (that would double-process), skip.
-    if (failFast && contended) {
-      return null;
-    }
+    const contention = resolveClaimContentionOptions(options);
+    const failFast = !contention.wait;
 
     // Ensure the row exists locally before claiming.
     let model = ownRowOrThrow(id);
@@ -599,27 +604,41 @@ export function createModelProxy<T, C>(
 
     // Acquire the lease. By default (`queue` is not false) this goes through the
     // server's fair FIFO queue: `queue: true` resolves only once the lease is
-    // genuinely ours, blocking behind any current holder, with no check-then-act
-    // gap because the server orders contenders. Fail-fast skips the queue: an
-    // observed conflict was already rejected above, so this just records the lease.
-    const lease = await collaboration.createClaim({
-      target: {
-        model: wireModel,
-        id,
-        // The whole sub-entity locator in one move — listing its members here
-        // is what let `fields` die between the caller and the lease, so the
-        // claim covered the whole row while the caller believed it named parts.
-        ...subTarget(options, schemaKey),
-      },
-      description: claimDescription(options),
-      ttl: options.ttl,
-      queue: !failFast,
-      maxQueueDepth: options.maxQueueDepth,
-      // The one wait cap, declared once on ClaimTargetOptions — the socket
-      // wait and the HTTP poll-wait both honor it as `grant_timeout`.
-      waitTimeoutMs: options.waitTimeoutMs,
-      signal: options.signal,
-    });
+    // genuinely ours, blocking behind any current holder. Fail-fast skips the
+    // queue but still awaits the server: a conflict invisible in the local
+    // snapshot resolves `null`, never a speculative handle.
+    let lease: Claim;
+    try {
+      lease = await collaboration.createClaim({
+        target: {
+          model: wireModel,
+          id,
+          // The whole sub-entity locator in one move — listing its members here
+          // is what let `fields` die between the caller and the lease, so the
+          // claim covered the whole row while the caller believed it named parts.
+          ...subTarget(options, schemaKey),
+        },
+        description: claimDescription(options),
+        ttl: options.ttl,
+        queue: contention.wait,
+        maxQueueDepth: contention.maxDepth,
+        // The one wait cap, declared once on ClaimTargetOptions — the socket
+        // wait and the HTTP poll-wait both honor it as `grant_timeout`.
+        waitTimeoutMs: contention.timeoutMs,
+        signal: contention.signal,
+        onStatus: contention.onStatus,
+      });
+    } catch (err) {
+      const normalized = toAbloError(err);
+      if (
+        failFast &&
+        normalized instanceof AbloClaimedError &&
+        normalized.code === 'claim_conflict'
+      ) {
+        return null;
+      }
+      throw normalized;
+    }
 
     // Only when the claim actually waited behind another holder can the row have
     // changed underneath us — re-read so the claimed snapshot reflects what that
@@ -748,22 +767,8 @@ export function createModelProxy<T, C>(
         { code: 'model_claim_not_configured' },
       );
     }
-    // Is someone else already on this target? Read the local coordination
-    // snapshot up front so a `queue: false` caller can reject before announcing
-    // a claim the server would refuse.
-    const held = collaboration.state({ model: wireModel, id });
-    const contended = !!held && held.heldBy !== collaboration.selfParticipantId;
-    const failFast = options.queue === false;
-
-    // The try-claim (`queue: false`): resolve `null` if a holder is already
-    // visible — an expected outcome, not an error. Best-effort at the client —
-    // a row this participant never synced usually carries no local claim state
-    // either, so a peer gets the deterministic `null` only once it has
-    // observed the holder (entered the row's entity scope). The server's
-    // queue is the backstop for the queuing path.
-    if (failFast && contended) {
-      return null;
-    }
+    const contention = resolveClaimContentionOptions(options);
+    const failFast = !contention.wait;
 
     // Enter the entity scope before acquiring the lease so the holder's claim
     // presence broadcasts to everyone in this entity group — the same ordering
@@ -772,24 +777,38 @@ export function createModelProxy<T, C>(
     // to hydrate here and nothing to re-read after the grant.
     await collaboration.pinScope?.({ [schemaKey]: id });
 
-    const lease = await collaboration.createClaim({
-      target: {
-        model: wireModel,
-        id,
-        // The whole sub-entity locator in one move — listing its members here
-        // is what let `fields` die between the caller and the lease, so the
-        // claim covered the whole row while the caller believed it named parts.
-        ...subTarget(options, schemaKey),
-      },
-      description: claimDescription(options),
-      ttl: options.ttl,
-      queue: !failFast,
-      maxQueueDepth: options.maxQueueDepth,
-      // The one wait cap, declared once on ClaimTargetOptions — the socket
-      // wait and the HTTP poll-wait both honor it as `grant_timeout`.
-      waitTimeoutMs: options.waitTimeoutMs,
-      signal: options.signal,
-    });
+    let lease: Claim;
+    try {
+      lease = await collaboration.createClaim({
+        target: {
+          model: wireModel,
+          id,
+          // The whole sub-entity locator in one move — listing its members here
+          // is what let `fields` die between the caller and the lease, so the
+          // claim covered the whole row while the caller believed it named parts.
+          ...subTarget(options, schemaKey),
+        },
+        description: claimDescription(options),
+        ttl: options.ttl,
+        queue: contention.wait,
+        maxQueueDepth: contention.maxDepth,
+        // The one wait cap, declared once on ClaimTargetOptions — the socket
+        // wait and the HTTP poll-wait both honor it as `grant_timeout`.
+        waitTimeoutMs: contention.timeoutMs,
+        signal: contention.signal,
+        onStatus: contention.onStatus,
+      });
+    } catch (err) {
+      const normalized = toAbloError(err);
+      if (
+        failFast &&
+        normalized instanceof AbloClaimedError &&
+        normalized.code === 'claim_conflict'
+      ) {
+        return null;
+      }
+      throw normalized;
+    }
 
     // A watermark-only snapshot: `createSnapshot` still reads the engine's
     // current `lastSyncId` even though the pool holds no row (the bucket is
@@ -881,12 +900,12 @@ export function createModelProxy<T, C>(
   const guardedTakeClaim = guard(takeClaim);
   const guardedTakeRowFreeClaim = guard(takeRowFreeClaim);
   function claim(
-    params: ClaimParams<C> & { queue: false },
+    params: ClaimSkipParams<C>,
   ): Promise<HeldClaim<T> | null>;
   function claim(params: ClaimParams<C>): Promise<HeldClaim<T>>;
   function claim(
     id: string,
-    opts: ClaimOptions<C> & { queue: false },
+    opts: ClaimSkipOptions<C>,
   ): Promise<HeldLease | null>;
   function claim(id: string, opts?: ClaimOptions<C>): Promise<HeldLease>;
   function claim(
@@ -973,11 +992,10 @@ export function createModelProxy<T, C>(
       };
     },
 
-    queue(params: ClaimLookupParams<T>): { readonly object: 'list'; readonly data: readonly Claim[] } {
-      return {
-        object: 'list',
-        data: collaboration?.queue({ model: wireModel, id: params.id }) ?? [],
-      };
+    queue(params: ClaimLookupParams<T>): ClaimQueueView {
+      return claimQueueView(
+        collaboration?.queue({ model: wireModel, id: params.id }) ?? [],
+      );
     },
 
     reorder(params: ClaimReorderParams<T>): void {
@@ -1086,6 +1104,7 @@ export function createModelProxy<T, C>(
         // race — see `takeClaim`). Released with the lease in the `finally`
         // below. Awaited for broadcast ordering; still best-effort.
         await collaboration.pinScope?.({ [schemaKey]: id });
+        const contention = resolveClaimContentionOptions(claim);
         autoLease = await collaboration.createClaim({
           target: {
             model: wireModel,
@@ -1094,8 +1113,11 @@ export function createModelProxy<T, C>(
           },
           description: claimDescription(claim, 'creating'),
           ttl: claim.ttl,
-          queue: claim.queue !== false,
-          maxQueueDepth: claim.maxQueueDepth,
+          queue: contention.wait,
+          maxQueueDepth: contention.maxDepth,
+          waitTimeoutMs: contention.timeoutMs,
+          signal: contention.signal,
+          onStatus: contention.onStatus,
         });
       }
 
@@ -1200,7 +1222,7 @@ export function createModelProxy<T, C>(
           params.claim && !isClaimHandle(params.claim) ? params.claim : null;
         if (autoClaim) {
           const handle = await takeClaim({ ...autoClaim, id: params.id });
-          // A declined try-claim is `null` only on the standalone verb; a
+          // A skipped try-claim is `null` only on the standalone verb; a
           // write that could not take its claim is a failed write.
           if (!handle) {
             throw new AbloClaimedError(

package/src/local/client/reactiveEngine.ts

@@ -62,6 +62,10 @@ import type {
   CreateAgentSessionParams,
   CreateSessionParams,
 } from './resourceTypes.js';
+import {
+  claimAttemptFailure,
+  emitClaimStatus,
+} from '@abloatai/transaction/resources/modelOperations';
 import { createModelProxy, type ModelOperations } from './createModelProxy.js';
 import { assertWriteOptions } from '@abloatai/transaction/resources/writeOptionsSchema';
 import type { AbloClient as Ablo } from '../../client.js';
@@ -409,8 +413,8 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
 	      return Promise.resolve();
 	    };
 	    // The token is server-stamped and arrives on the grant frame, so prefer
-	    // the one `awaitClaimGrant` read there; fall back to any the local handle
-	    // already carried (immediate, non-queued grants).
+	    // the one `awaitClaimGrant` read there; retain the handle fallback for
+	    // wire-compatible transports that already stamped it locally.
 	    const resolvedFenceToken = fenceToken ?? claim.fenceToken;
 	    return {
 	      object: 'claim',
@@ -433,6 +437,38 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
 	  const publicClaims: ClaimResource = Object.assign(claimStream, {
 	    async create(claimOptions: ClaimCreateOptions): Promise<Claim> {
 	      await ready();
+	      // Subscribe before announcing the claim. A fast rejection can arrive
+	      // in the same turn as `send` in tests and on a low-latency socket; if
+	      // the listener is installed afterwards, that authoritative answer is
+	      // lost and the locally minted handle looks like a grant.
+	      const claimId = crypto.randomUUID();
+	      const grant = awaitClaimGrant(transport, claimId, {
+	        timeoutMs: claimOptions.waitTimeoutMs,
+	        maxQueueDepth: claimOptions.maxQueueDepth,
+	        signal: claimOptions.signal,
+	        logger,
+	        onQueued: ({ position }) => {
+	          emitClaimStatus(claimOptions.onStatus, {
+	            type: 'queued',
+	            claimId,
+	            position,
+	            ahead: position + 1,
+	          });
+	        },
+	        onGranted: ({ waited }) => {
+	          emitClaimStatus(claimOptions.onStatus, {
+	            type: 'granted',
+	            claimId,
+	            waited,
+	          });
+	        },
+	        onFailed: (error) => {
+	          emitClaimStatus(
+	            claimOptions.onStatus,
+	            claimAttemptFailure(claimOptions.queue !== false, error),
+	          );
+	        },
+	      });
 	      const claim = claimStream.claim(
 	        {
 	          ...streamTarget(claimOptions.target),
@@ -443,31 +479,17 @@ export function buildReactiveEngine<const S extends SchemaRecord>(
 	          ttl: claimOptions.ttl,
 	          queue: claimOptions.queue,
 	        },
+	        claimId,
 	      );
-	      // With `queue`, the claim is only really *ours* once the server says
-	      // so (`claim_acquired` if the target was free, `claim_granted` once
-	      // we reach the head of the FIFO line). Block here on that grant so
-	      // callers — chiefly `ablo.<model>.claim` — get a handle that already
-	      // holds the lease, never a half-claimed one racing the queue.
-	      let waited = false;
-	      let fenceToken: number | undefined;
-	      let readAt: number | undefined;
-	      if (claimOptions.queue) {
-	        try {
-	          ({ waited, fenceToken, readAt } = await awaitClaimGrant(transport, claim.id, {
-	            timeoutMs: claimOptions.waitTimeoutMs,
-	            maxQueueDepth: claimOptions.maxQueueDepth,
-	            signal: claimOptions.signal,
-	            logger,
-	          }));
-	        } catch (err) {
-	          // Gave up waiting (queue too deep, timed out, or lost) — abandon
-	          // the queued claim so we don't leave a phantom entry in the
-	          // line that would block or mislead other claimers.
-	          claim.revoke?.();
-	          throw err;
-	        }
-	      }
+	      // A claim is ours only after the server says so. This applies equally
+	      // to queued claims and try-claims (`queue: false`): the latter must
+	      // observe `claim_rejected` instead of returning a phantom handle.
+	      const { waited, fenceToken, readAt } = await grant.catch((err: unknown) => {
+	        // Give up the local/reconnect record after any rejection, timeout,
+	        // abort, or lost lease. For queued claims this also leaves the line.
+	        claim.revoke?.();
+	        throw err;
+	      });
 	      return wrapClaimHandle(claim, waited, fenceToken, readAt);
 	    },
 	    list(target?: Partial<ModelTarget>): readonly ModelClaim[] {

package/src/local/client/resourceTypes.ts

@@ -23,6 +23,9 @@ export type {
   ModelDeleteParams,
   ClaimOptions,
   ClaimParams,
+  ClaimContentionOptions,
+  ClaimAttemptEvent,
+  ClaimQueueView,
   ClaimLookupParams,
   ClaimReorderParams,
   Claim,

package/src/local/sync/createClaimStream.ts

@@ -44,6 +44,7 @@ import {
   claimDescription,
   descriptionFromMeta,
   participantKindFromWire,
+  type WireClaimSummary,
 } from '@abloatai/transaction/coordination/schema';
 import {
   isTargetTuple,
@@ -88,13 +89,18 @@ const HEARTBEAT_ACK_TIMEOUT_MS = 10_000;
 
 export interface AttachableClaimStream extends ClaimStream {
   /**
-   * Mints a lease directly: sends the `claim_begin` frame and returns a held
-   * {@link Claim} that carries no row `data` (the resource layer reads the row
-   * and stamps it). This is an internal entry point, not part of the public
+   * Mints the local handle and sends its `claim_begin` frame. The handle is a
+   * request until the resource layer observes the server's grant; it must never
+   * be returned to application code before that acknowledgement. This is an
+   * internal entry point, not part of the public
    * {@link ClaimStream}; application code takes a claim through
    * `ablo.<model>.claim({ id })`, which is built on this.
+   *
+   * `claimId` lets that resource layer subscribe for the acknowledgement before
+   * this method sends. Omitting it preserves the direct stream API's generated
+   * id for internal callers that do not await the grant.
    */
-  claim(target: PresenceTarget, opts?: ClaimOptions): Claim;
+  claim(target: PresenceTarget, opts?: ClaimOptions, claimId?: string): Claim;
   attach(transport: ClaimTransport): void;
   /**
    * Seeds the participant identity once the host resolves it. The stream can
@@ -193,6 +199,38 @@ export function createClaimStream(
     }
   };
 
+  const observeForeignClaim = (
+    heldBy: string,
+    claim: WireClaimSummary,
+    participantKind?: 'user' | 'agent' | 'system',
+    isAgent?: boolean,
+  ): void => {
+    const description =
+      claim.description ??
+      descriptionFromMeta(claim.meta) ??
+      'editing';
+    const { meta, ...details } = subTarget(claim);
+    activeByClaimId.set(claim.claimId, {
+      object: 'claim',
+      id: claim.claimId,
+      status: 'active',
+      heldBy,
+      participantKind: participantKindFromWire(participantKind, isAgent),
+      target: {
+        ...streamTarget(claim),
+        ...details,
+        ...(meta !== undefined ? { meta: declaredMeta(meta) } : {}),
+      },
+      description,
+      ttlSeconds: Math.max(
+        0,
+        Math.floor((claim.expiresAt - Date.now()) / 1000),
+      ),
+      createdAt: claim.declaredAt,
+      expiresAt: claim.expiresAt,
+    });
+  };
+
   // ── Wire wiring ──────────────────────────────────────────────────
   let attached: ClaimTransport | null = null;
   const unsubs: (() => void)[] = [];
@@ -236,37 +274,12 @@ export function createClaimStream(
           // drops it from `others`, which is what resolves a contender's
           // `settled()`. Absent status means active (wire back-compat).
           if (claim.status && claim.status !== 'active') continue;
-          // Resolve the always-present public field, tolerating a frame that
-          // carries the value in `meta` rather than as an explicit description.
-          const description =
-            claim.description ??
-            descriptionFromMeta(claim.meta) ??
-            'editing';
-          // The frame is parsed permissively, on purpose; `declaredMeta` is where
-          // that wire value becomes the shape the program declared.
-          const { meta, ...details } = subTarget(claim);
-          activeByClaimId.set(claim.claimId, {
-            object: 'claim',
-            id: claim.claimId,
-            status: 'active',
-            heldBy: event.userId,
-            participantKind: participantKindFromWire(
-              event.participantKind,
-              event.isAgent,
-            ),
-            target: {
-              ...streamTarget(claim),
-              ...details,
-              ...(meta !== undefined ? { meta: declaredMeta(meta) } : {}),
-            },
-            description,
-            ttlSeconds: Math.max(
-              0,
-              Math.floor((claim.expiresAt - Date.now()) / 1000),
-            ),
-            createdAt: claim.declaredAt,
-            expiresAt: claim.expiresAt,
-          });
+          observeForeignClaim(
+            event.userId,
+            claim,
+            event.participantKind,
+            event.isAgent,
+          );
           mutated = true;
         }
         if (mutated) notifyListeners();
@@ -290,6 +303,22 @@ export function createClaimStream(
         // a claim the server already rejected (would just spam both
         // sides with conflicts).
         ownClaims.delete(rejection.claimId);
+        // A holder on another server may have claimed before this client joined
+        // the row group, so its one-shot presence frame was missed. A conflict
+        // reply carries the authoritative holder summary; seed the same local
+        // state immediately instead of continuing to report the row as free.
+        if (
+          rejection.reason === 'conflict' &&
+          rejection.heldBy &&
+          rejection.heldByClaim
+        ) {
+          observeForeignClaim(
+            rejection.heldBy,
+            rejection.heldByClaim,
+            rejection.heldByKind,
+          );
+          notifyListeners();
+        }
         for (const l of rejectionListeners) {
           try {
             l(rejection);
@@ -523,8 +552,9 @@ export function createClaimStream(
       ttl?: ClaimLeaseOptions['ttl'];
       queue?: boolean;
     },
+    requestedClaimId?: string,
   ): Claim {
-    const claimId = crypto.randomUUID();
+    const claimId = requestedClaimId ?? crypto.randomUUID();
     const estimatedMs = args.ttl !== undefined ? toMs(args.ttl) : undefined;
     // The handle the caller reads back is a public claim, so its `meta` is the
     // declared shape; the `OwnClaim` below stays wire-typed, because that is
@@ -589,6 +619,7 @@ export function createClaimStream(
     claim(
       target: PresenceTarget,
       opts?: ClaimOptions,
+      claimId?: string,
     ): Claim {
       const resolved = resolveTarget(target);
       return mintHandle({
@@ -597,7 +628,7 @@ export function createClaimStream(
         description: claimDescription({ ...opts, meta: resolved.meta }),
         ttl: opts?.ttl,
         queue: opts?.queue,
-      });
+      }, claimId);
     },
     get others() {
       return claimsSnapshot;