fix(engine): atomically claim legacy identities

CHANGELOG.md

@@ -16,7 +16,7 @@ This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 Packages without a separate changelog are covered by the cross-package notes below.
 
-## [Unreleased - Patch]
+## [Unreleased - Minor]
 
 ### Changed
 
@@ -26,6 +26,10 @@ Packages without a separate changelog are covered by the cross-package notes bel
 
 - DM conversation and inbox reads remain available beyond 100 conversations, and the advertised DM-list limit now reaches the server instead of being ignored.
 
+### Security
+
+- Legacy agent identity claims are atomic, and generic agent updates cannot write the reserved `identity_key` metadata field.
+
 ## [8.0.0] - 2026-08-10
 
 ### Added

README.md

@@ -86,6 +86,15 @@ npx tsx quickstart.ts
 
 That is the canonical onboarding loop: create workspace, register agents, connect realtime streams, and watch messages flow live.
 
+Operator recovery for an offline agent registered before identity verifiers
+were stored uses `PATCH /v1/agents/:name/legacy-identity`. The endpoint accepts
+only a SHA-256 verifier (`identity_key_hash`) and atomically succeeds when the
+record is still offline and has no `identity_key` field at write time. Generic
+agent updates cannot write that reserved field. Initial registration may set a
+valid lowercase SHA-256 verifier, but malformed registration values and claims
+return 400; already-claimed, non-offline, or concurrently changed records return
+409.
+
 Workspace names are not globally unique. Workspace creation is idempotent for the same workspace name and API key: repeating that combination returns the existing workspace instead of creating another one.
 
 If you want an explicit SDK helper that tells you whether setup returned an existing workspace or created a new one, use `ensureWorkspace()`:

openapi.yaml

@@ -1682,7 +1682,11 @@ paths:
   /agents:
     post:
       summary: Register agent
-      description: Register a new agent in the workspace. Agent names are unique per workspace; registering a duplicate name returns `409 agent_already_exists`.
+      description: >-
+        Register a new agent in the workspace. Agent names are unique per
+        workspace; registering a duplicate name returns 409
+        agent_already_exists. Initial registration may include identity_key in
+        metadata only as a 64-character lowercase SHA-256 verifier.
       tags:
         - Agents
       security:
@@ -1717,6 +1721,8 @@ paths:
                     type: boolean
                   data:
                     $ref: '#/components/schemas/Agent'
+        '400':
+          description: Malformed registration identity_key (invalid_agent_identity_key)
         '409':
           description: Agent name already exists in this workspace
 
@@ -1785,7 +1791,10 @@ paths:
 
     patch:
       summary: Update agent
-      description: Update agent properties
+      description: >-
+        Update agent properties. Platform-managed metadata keys such as
+        `identity_key` are rejected; use the dedicated legacy identity claim
+        endpoint for the one supported backfill operation.
       tags:
         - Agents
       security:
@@ -1818,6 +1827,10 @@ paths:
                     type: boolean
                   data:
                     $ref: '#/components/schemas/Agent'
+        '400':
+          description: >-
+            Invalid update, including reserved_agent_metadata_key when
+            metadata contains the platform-managed identity_key field
 
     delete:
       summary: Delete agent
@@ -1836,6 +1849,60 @@ paths:
         '204':
           description: Agent deleted
 
+  /agents/{name}/legacy-identity:
+    patch:
+      summary: Atomically claim a legacy agent identity
+      description: >-
+        Operator recovery for one offline agent registered before identity
+        verifiers were stored. The update succeeds only when `identity_key`
+        is still absent and the durable agent status is still `offline` in
+        the same atomic database mutation. The request contains a SHA-256
+        verifier, never the raw identity proof.
+      tags:
+        - Agents
+      security:
+        - workspaceKey: []
+      parameters:
+        - name: name
+          in: path
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - identity_key_hash
+              properties:
+                identity_key_hash:
+                  type: string
+                  pattern: '^[a-f0-9]{64}$'
+                  description: SHA-256 hex verifier for the caller-held identity proof
+      responses:
+        '200':
+          description: Legacy identity claimed
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  ok:
+                    type: boolean
+                  data:
+                    $ref: '#/components/schemas/Agent'
+        '400':
+          description: Malformed identity_key_hash (invalid_request)
+        '404':
+          description: Agent not found
+        '409':
+          description: >-
+            Agent already has an identity (agent_identity_already_claimed), is
+            not offline (agent_not_offline), or changed during the claim
+            (agent_identity_claim_conflict)
+
   /agents/spawn:
     post:
       summary: Request agent spawn

packages/engine/CHANGELOG.md

@@ -7,12 +7,16 @@ See the [root changelog](../../CHANGELOG.md) for cross-package release highlight
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased - Patch]
+## [Unreleased - Minor]
 
 ### Fixed
 
 - DM conversation and unread-inbox enrichment batches large identifier sets below D1's bound-parameter ceiling, so long-lived agents no longer lose both read paths after accumulating more than 100 conversations.
 
+### Security
+
+- `PATCH /v1/agents/:name/legacy-identity` atomically claims an offline legacy agent's identity, while generic agent updates cannot overwrite the verifier.
+
 ## [8.0.0] - 2026-08-10
 
 ### Added