@cleocode/contracts 2026.10.3 → 2026.10.5-rc.ci.672

package/dist/tasks.d.ts

@@ -525,8 +525,8 @@ export declare const completionCriterionEvaluationSchema: z.ZodObject<{
     targetTaskStatus: z.ZodOptional<z.ZodEnum<{
         pending: "pending";
         cancelled: "cancelled";
-        active: "active";
         blocked: "blocked";
+        active: "active";
         done: "done";
         archived: "archived";
         proposed: "proposed";
@@ -549,8 +549,8 @@ export declare const completionCriterionEvaluationSchema: z.ZodObject<{
     replacementTaskStatus: z.ZodOptional<z.ZodEnum<{
         pending: "pending";
         cancelled: "cancelled";
-        active: "active";
         blocked: "blocked";
+        active: "active";
         done: "done";
         archived: "archived";
         proposed: "proposed";
@@ -571,8 +571,8 @@ export declare const unsatisfiedCompletionCriterionSchema: z.ZodObject<{
     targetTaskStatus: z.ZodOptional<z.ZodEnum<{
         pending: "pending";
         cancelled: "cancelled";
-        active: "active";
         blocked: "blocked";
+        active: "active";
         done: "done";
         archived: "archived";
         proposed: "proposed";
@@ -595,8 +595,8 @@ export declare const unsatisfiedCompletionCriterionSchema: z.ZodObject<{
     replacementTaskStatus: z.ZodOptional<z.ZodEnum<{
         pending: "pending";
         cancelled: "cancelled";
-        active: "active";
         blocked: "blocked";
+        active: "active";
         done: "done";
         archived: "archived";
         proposed: "proposed";
@@ -618,8 +618,8 @@ export declare const completionEvaluationSchema: z.ZodObject<{
     taskStatus: z.ZodEnum<{
         pending: "pending";
         cancelled: "cancelled";
-        active: "active";
         blocked: "blocked";
+        active: "active";
         done: "done";
         archived: "archived";
         proposed: "proposed";
@@ -657,8 +657,8 @@ export declare const completionEvaluationSchema: z.ZodObject<{
         targetTaskStatus: z.ZodOptional<z.ZodEnum<{
             pending: "pending";
             cancelled: "cancelled";
-            active: "active";
             blocked: "blocked";
+            active: "active";
             done: "done";
             archived: "archived";
             proposed: "proposed";
@@ -681,8 +681,8 @@ export declare const completionEvaluationSchema: z.ZodObject<{
         replacementTaskStatus: z.ZodOptional<z.ZodEnum<{
             pending: "pending";
             cancelled: "cancelled";
-            active: "active";
             blocked: "blocked";
+            active: "active";
             done: "done";
             archived: "archived";
             proposed: "proposed";
@@ -702,8 +702,8 @@ export declare const completionEvaluationSchema: z.ZodObject<{
         targetTaskStatus: z.ZodOptional<z.ZodEnum<{
             pending: "pending";
             cancelled: "cancelled";
-            active: "active";
             blocked: "blocked";
+            active: "active";
             done: "done";
             archived: "archived";
             proposed: "proposed";
@@ -726,8 +726,8 @@ export declare const completionEvaluationSchema: z.ZodObject<{
         replacementTaskStatus: z.ZodOptional<z.ZodEnum<{
             pending: "pending";
             cancelled: "cancelled";
-            active: "active";
             blocked: "blocked";
+            active: "active";
             done: "done";
             archived: "archived";
             proposed: "proposed";
@@ -770,8 +770,8 @@ export declare const completionEvaluationSchema: z.ZodObject<{
         targetTaskStatus: z.ZodOptional<z.ZodEnum<{
             pending: "pending";
             cancelled: "cancelled";
-            active: "active";
             blocked: "blocked";
+            active: "active";
             done: "done";
             archived: "archived";
             proposed: "proposed";
@@ -794,8 +794,8 @@ export declare const completionEvaluationSchema: z.ZodObject<{
         replacementTaskStatus: z.ZodOptional<z.ZodEnum<{
             pending: "pending";
             cancelled: "cancelled";
-            active: "active";
             blocked: "blocked";
+            active: "active";
             done: "done";
             archived: "archived";
             proposed: "proposed";
@@ -829,8 +829,8 @@ export declare const completionEvaluationSchema: z.ZodObject<{
         targetTaskStatus: z.ZodOptional<z.ZodEnum<{
             pending: "pending";
             cancelled: "cancelled";
-            active: "active";
             blocked: "blocked";
+            active: "active";
             done: "done";
             archived: "archived";
             proposed: "proposed";
@@ -853,8 +853,8 @@ export declare const completionEvaluationSchema: z.ZodObject<{
         replacementTaskStatus: z.ZodOptional<z.ZodEnum<{
             pending: "pending";
             cancelled: "cancelled";
-            active: "active";
             blocked: "blocked";
+            active: "active";
             done: "done";
             archived: "archived";
             proposed: "proposed";
@@ -903,8 +903,8 @@ export declare const completionExplanationSchema: z.ZodObject<{
         targetTaskStatus: z.ZodOptional<z.ZodEnum<{
             pending: "pending";
             cancelled: "cancelled";
-            active: "active";
             blocked: "blocked";
+            active: "active";
             done: "done";
             archived: "archived";
             proposed: "proposed";
@@ -927,8 +927,8 @@ export declare const completionExplanationSchema: z.ZodObject<{
         replacementTaskStatus: z.ZodOptional<z.ZodEnum<{
             pending: "pending";
             cancelled: "cancelled";
-            active: "active";
             blocked: "blocked";
+            active: "active";
             done: "done";
             archived: "archived";
             proposed: "proposed";
@@ -981,8 +981,8 @@ export declare const completionListResultSchema: z.ZodObject<{
         targetTaskStatus: z.ZodOptional<z.ZodEnum<{
             pending: "pending";
             cancelled: "cancelled";
-            active: "active";
             blocked: "blocked";
+            active: "active";
             done: "done";
             archived: "archived";
             proposed: "proposed";
@@ -1005,8 +1005,8 @@ export declare const completionListResultSchema: z.ZodObject<{
         replacementTaskStatus: z.ZodOptional<z.ZodEnum<{
             pending: "pending";
             cancelled: "cancelled";
-            active: "active";
             blocked: "blocked";
+            active: "active";
             done: "done";
             archived: "archived";
             proposed: "proposed";

package/dist/workgraph.d.ts

@@ -531,8 +531,8 @@ export declare const workGraphSliceSchema: z.ZodObject<{
         status: z.ZodEnum<{
             pending: "pending";
             cancelled: "cancelled";
-            active: "active";
             blocked: "blocked";
+            active: "active";
             done: "done";
             archived: "archived";
             proposed: "proposed";
@@ -599,8 +599,8 @@ export declare const workGraphReadinessResultSchema: z.ZodObject<{
             status: z.ZodEnum<{
                 pending: "pending";
                 cancelled: "cancelled";
-                active: "active";
                 blocked: "blocked";
+                active: "active";
                 done: "done";
                 archived: "archived";
                 proposed: "proposed";
@@ -618,8 +618,8 @@ export declare const workGraphReadinessResultSchema: z.ZodObject<{
                 status: z.ZodEnum<{
                     pending: "pending";
                     cancelled: "cancelled";
-                    active: "active";
                     blocked: "blocked";
+                    active: "active";
                     done: "done";
                     archived: "archived";
                     proposed: "proposed";
@@ -649,8 +649,8 @@ export declare const workGraphReadinessResultSchema: z.ZodObject<{
             status: z.ZodEnum<{
                 pending: "pending";
                 cancelled: "cancelled";
-                active: "active";
                 blocked: "blocked";
+                active: "active";
                 done: "done";
                 archived: "archived";
                 proposed: "proposed";
@@ -668,8 +668,8 @@ export declare const workGraphReadinessResultSchema: z.ZodObject<{
                 status: z.ZodEnum<{
                     pending: "pending";
                     cancelled: "cancelled";
-                    active: "active";
                     blocked: "blocked";
+                    active: "active";
                     done: "done";
                     archived: "archived";
                     proposed: "proposed";
@@ -736,8 +736,8 @@ export declare const workGraphContextPackSchema: z.ZodObject<{
             status: z.ZodEnum<{
                 pending: "pending";
                 cancelled: "cancelled";
-                active: "active";
                 blocked: "blocked";
+                active: "active";
                 done: "done";
                 archived: "archived";
                 proposed: "proposed";
@@ -834,8 +834,8 @@ export declare const workGraphContextPackSchema: z.ZodObject<{
                 status: z.ZodEnum<{
                     pending: "pending";
                     cancelled: "cancelled";
-                    active: "active";
                     blocked: "blocked";
+                    active: "active";
                     done: "done";
                     archived: "archived";
                     proposed: "proposed";
@@ -853,8 +853,8 @@ export declare const workGraphContextPackSchema: z.ZodObject<{
                     status: z.ZodEnum<{
                         pending: "pending";
                         cancelled: "cancelled";
-                        active: "active";
                         blocked: "blocked";
+                        active: "active";
                         done: "done";
                         archived: "archived";
                         proposed: "proposed";
@@ -884,8 +884,8 @@ export declare const workGraphContextPackSchema: z.ZodObject<{
                 status: z.ZodEnum<{
                     pending: "pending";
                     cancelled: "cancelled";
-                    active: "active";
                     blocked: "blocked";
+                    active: "active";
                     done: "done";
                     archived: "archived";
                     proposed: "proposed";
@@ -903,8 +903,8 @@ export declare const workGraphContextPackSchema: z.ZodObject<{
                     status: z.ZodEnum<{
                         pending: "pending";
                         cancelled: "cancelled";
-                        active: "active";
                         blocked: "blocked";
+                        active: "active";
                         done: "done";
                         archived: "archived";
                         proposed: "proposed";
@@ -948,8 +948,8 @@ export declare const workGraphContextPackSchema: z.ZodObject<{
             byStatus: z.ZodRecord<z.ZodEnum<{
                 pending: "pending";
                 cancelled: "cancelled";
-                active: "active";
                 blocked: "blocked";
+                active: "active";
                 done: "done";
                 archived: "archived";
                 proposed: "proposed";
@@ -966,8 +966,8 @@ export declare const workGraphContextPackSchema: z.ZodObject<{
             byStatus: z.ZodRecord<z.ZodEnum<{
                 pending: "pending";
                 cancelled: "cancelled";
-                active: "active";
                 blocked: "blocked";
+                active: "active";
                 done: "done";
                 archived: "archived";
                 proposed: "proposed";
@@ -1239,8 +1239,8 @@ export declare const tasksTraverseResultSchema: z.ZodObject<{
         status: z.ZodEnum<{
             pending: "pending";
             cancelled: "cancelled";
-            active: "active";
             blocked: "blocked";
+            active: "active";
             done: "done";
             archived: "archived";
             proposed: "proposed";
@@ -1292,8 +1292,8 @@ export declare const tasksTreeResultSchema: z.ZodObject<{
         status: z.ZodEnum<{
             pending: "pending";
             cancelled: "cancelled";
-            active: "active";
             blocked: "blocked";
+            active: "active";
             done: "done";
             archived: "archived";
             proposed: "proposed";
@@ -1325,8 +1325,8 @@ export declare const tasksRollupParamsSchema: z.ZodObject<{
         byStatus: z.ZodRecord<z.ZodEnum<{
             pending: "pending";
             cancelled: "cancelled";
-            active: "active";
             blocked: "blocked";
+            active: "active";
             done: "done";
             archived: "archived";
             proposed: "proposed";
@@ -1347,8 +1347,8 @@ export declare const tasksRollupResultSchema: z.ZodObject<{
         byStatus: z.ZodRecord<z.ZodEnum<{
             pending: "pending";
             cancelled: "cancelled";
-            active: "active";
             blocked: "blocked";
+            active: "active";
             done: "done";
             archived: "archived";
             proposed: "proposed";
@@ -1365,8 +1365,8 @@ export declare const tasksRollupResultSchema: z.ZodObject<{
         byStatus: z.ZodRecord<z.ZodEnum<{
             pending: "pending";
             cancelled: "cancelled";
-            active: "active";
             blocked: "blocked";
+            active: "active";
             done: "done";
             archived: "archived";
             proposed: "proposed";
@@ -1419,8 +1419,8 @@ export declare const tasksFrontierResultSchema: z.ZodObject<{
             status: z.ZodEnum<{
                 pending: "pending";
                 cancelled: "cancelled";
-                active: "active";
                 blocked: "blocked";
+                active: "active";
                 done: "done";
                 archived: "archived";
                 proposed: "proposed";
@@ -1438,8 +1438,8 @@ export declare const tasksFrontierResultSchema: z.ZodObject<{
                 status: z.ZodEnum<{
                     pending: "pending";
                     cancelled: "cancelled";
-                    active: "active";
                     blocked: "blocked";
+                    active: "active";
                     done: "done";
                     archived: "archived";
                     proposed: "proposed";
@@ -1469,8 +1469,8 @@ export declare const tasksFrontierResultSchema: z.ZodObject<{
             status: z.ZodEnum<{
                 pending: "pending";
                 cancelled: "cancelled";
-                active: "active";
                 blocked: "blocked";
+                active: "active";
                 done: "done";
                 archived: "archived";
                 proposed: "proposed";
@@ -1488,8 +1488,8 @@ export declare const tasksFrontierResultSchema: z.ZodObject<{
                 status: z.ZodEnum<{
                     pending: "pending";
                     cancelled: "cancelled";
-                    active: "active";
                     blocked: "blocked";
+                    active: "active";
                     done: "done";
                     archived: "archived";
                     proposed: "proposed";
@@ -1578,8 +1578,8 @@ export declare const tasksWorkGraphAuditResultSchema: z.ZodObject<{
             status: z.ZodEnum<{
                 pending: "pending";
                 cancelled: "cancelled";
-                active: "active";
                 blocked: "blocked";
+                active: "active";
                 done: "done";
                 archived: "archived";
                 proposed: "proposed";
@@ -1625,8 +1625,8 @@ export declare const tasksWorkGraphAuditResultSchema: z.ZodObject<{
                 status: z.ZodEnum<{
                     pending: "pending";
                     cancelled: "cancelled";
-                    active: "active";
                     blocked: "blocked";
+                    active: "active";
                     done: "done";
                     archived: "archived";
                     proposed: "proposed";
@@ -1644,8 +1644,8 @@ export declare const tasksWorkGraphAuditResultSchema: z.ZodObject<{
                     status: z.ZodEnum<{
                         pending: "pending";
                         cancelled: "cancelled";
-                        active: "active";
                         blocked: "blocked";
+                        active: "active";
                         done: "done";
                         archived: "archived";
                         proposed: "proposed";
@@ -1675,8 +1675,8 @@ export declare const tasksWorkGraphAuditResultSchema: z.ZodObject<{
                 status: z.ZodEnum<{
                     pending: "pending";
                     cancelled: "cancelled";
-                    active: "active";
                     blocked: "blocked";
+                    active: "active";
                     done: "done";
                     archived: "archived";
                     proposed: "proposed";
@@ -1694,8 +1694,8 @@ export declare const tasksWorkGraphAuditResultSchema: z.ZodObject<{
                     status: z.ZodEnum<{
                         pending: "pending";
                         cancelled: "cancelled";
-                        active: "active";
                         blocked: "blocked";
+                        active: "active";
                         done: "done";
                         archived: "archived";
                         proposed: "proposed";
@@ -1739,8 +1739,8 @@ export declare const tasksWorkGraphAuditResultSchema: z.ZodObject<{
             byStatus: z.ZodRecord<z.ZodEnum<{
                 pending: "pending";
                 cancelled: "cancelled";
-                active: "active";
                 blocked: "blocked";
+                active: "active";
                 done: "done";
                 archived: "archived";
                 proposed: "proposed";
@@ -1757,8 +1757,8 @@ export declare const tasksWorkGraphAuditResultSchema: z.ZodObject<{
             byStatus: z.ZodRecord<z.ZodEnum<{
                 pending: "pending";
                 cancelled: "cancelled";
-                active: "active";
                 blocked: "blocked";
+                active: "active";
                 done: "done";
                 archived: "archived";
                 proposed: "proposed";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/contracts",
-  "version": "2026.10.3",
+  "version": "2026.10.5-rc.ci.672",
   "description": "Domain types, interfaces, and contracts for the CLEO ecosystem",
   "type": "module",
   "main": "./dist/index.js",
@@ -26,6 +26,10 @@
       "types": "./dist/cloud/index.d.ts",
       "import": "./dist/cloud/index.js"
     },
+    "./ledger": {
+      "types": "./dist/ledger/index.d.ts",
+      "import": "./dist/ledger/index.js"
+    },
     "./config.js": {
       "types": "./dist/config/index.d.ts",
       "import": "./dist/config/index.js"
@@ -198,7 +202,7 @@
   "dependencies": {
     "zod": "^4.3.6",
     "zod-to-json-schema": "^3.25.2",
-    "@cleocode/lafs": "2026.10.3"
+    "@cleocode/lafs": "2026.10.5-rc.ci.672"
   },
   "scripts": {
     "build": "tsc -b --force && node scripts/copy-assets.mjs && node scripts/emit-schemas.mjs",

package/src/__tests__/cloud-replica-retirement.test.ts

@@ -0,0 +1,135 @@
+/**
+ * Cloud contract mirror of cleo-nexus #41 (T123 replica retirement, contract
+ * v2.28; T13284): the E31 request and answer, the stored retirement, and the
+ * `retiredAt` / `successor` fields home replicas gain, as the server validates
+ * them.
+ *
+ * @task T13284
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+  AttachHomeReplicaResult,
+  HomeReplica,
+  ListHomeReplicasResult,
+  ReplicaRetirement,
+  RetireReplicaRequest,
+  RetireReplicaResult,
+} from '../cloud/index.js';
+import { NEXUS_REPLICA_RETIREMENT_REASONS } from '../nexus-vault.js';
+
+const DEVICE = '0192f1c2-7d3e-4abc-8def-0000000000b0';
+const R1 = '0192f1c2-7d3e-7abc-8def-0000000000a1';
+const R2 = '0192f1c2-7d3e-7abc-8def-0000000000b1';
+const STREAM = 'project:0192f1c2-7d3e-7abc-8def-0123456789ab';
+const SIG = Buffer.alloc(64, 7).toString('base64');
+
+const request = {
+  deviceId: DEVICE,
+  successor: R2,
+  lastReplicaSeq: 4,
+  txnId: `${R1}:17`,
+  signature: SIG,
+};
+
+describe('RetireReplicaRequest (T13284)', () => {
+  it('takes a successor, lastReplicaSeq and txn id, each nullable', () => {
+    expect(RetireReplicaRequest.safeParse(request).success).toBe(true);
+    expect(
+      RetireReplicaRequest.safeParse({
+        ...request,
+        successor: null,
+        lastReplicaSeq: null,
+        txnId: null,
+      }).success,
+    ).toBe(true);
+  });
+
+  it('refuses a negative or fractional lastReplicaSeq and a malformed txn id', () => {
+    expect(RetireReplicaRequest.safeParse({ ...request, lastReplicaSeq: -1 }).success).toBe(false);
+    expect(RetireReplicaRequest.safeParse({ ...request, lastReplicaSeq: 1.5 }).success).toBe(false);
+    for (const txnId of [
+      R1,
+      `${R1}:`,
+      `${R1}:01`,
+      `${R1}:-1`,
+      `not-a-uuid:3`,
+      `${R1}:12345678901234567`,
+    ]) {
+      expect(RetireReplicaRequest.safeParse({ ...request, txnId }).success).toBe(false);
+    }
+    // Any UUID may emit the transaction (the successor on a rebind), not only a v7 replica id.
+    expect(RetireReplicaRequest.safeParse({ ...request, txnId: `${DEVICE}:0` }).success).toBe(true);
+  });
+
+  it('a successor must be a replica id (UUIDv7)', () => {
+    expect(RetireReplicaRequest.safeParse({ ...request, successor: DEVICE }).success).toBe(false);
+  });
+});
+
+describe('ReplicaRetirement and RetireReplicaResult (T13284)', () => {
+  const stored = {
+    streamId: STREAM,
+    replicaId: R1,
+    successor: R2,
+    lastReplicaSeq: null,
+    signerDeviceId: DEVICE,
+    txnId: null,
+    signature: SIG,
+    retiredAt: '2026-10-06T07:00:00.000Z',
+  };
+
+  it('is the stored record, wrapped as { retirement }', () => {
+    expect(ReplicaRetirement.safeParse(stored).success).toBe(true);
+    expect(RetireReplicaResult.safeParse({ retirement: stored }).success).toBe(true);
+    expect(RetireReplicaResult.safeParse(stored).success).toBe(false);
+    const { retiredAt: _retiredAt, ...undated } = stored;
+    expect(ReplicaRetirement.safeParse(undated).success).toBe(false);
+  });
+});
+
+describe('home replicas carry retiredAt and successor (T13284)', () => {
+  const replica = {
+    replicaId: R1,
+    deviceId: DEVICE,
+    deviceState: 'active',
+    attachedAt: '2026-10-01T00:00:00.000Z',
+    lastSyncAt: null,
+    presence: null,
+    presenceAt: null,
+  };
+
+  it('parses an older server without them, and a retired replica with them', () => {
+    expect(HomeReplica.safeParse(replica).success).toBe(true);
+    const retired = { ...replica, retiredAt: '2026-10-06T07:00:00.000Z', successor: R2 };
+    expect(HomeReplica.parse(retired)).toMatchObject({
+      retiredAt: retired.retiredAt,
+      successor: R2,
+    });
+    expect(HomeReplica.safeParse({ ...replica, retiredAt: null, successor: null }).success).toBe(
+      true,
+    );
+    expect(HomeReplica.safeParse({ ...replica, successor: DEVICE }).success).toBe(false);
+  });
+
+  it('the attach answer and the list follow HomeReplica', () => {
+    expect(AttachHomeReplicaResult).toBe(HomeReplica);
+    expect(ListHomeReplicasResult.shape.replicas.element).toBe(HomeReplica);
+  });
+});
+
+describe('E31 refusal reasons (T13284)', () => {
+  it('are the seven server reasons', () => {
+    expect([...NEXUS_REPLICA_RETIREMENT_REASONS].sort()).toEqual(
+      [
+        'not-pinned-or-owner',
+        'replica-retired',
+        'retire-below-head',
+        'retired',
+        'successor-other-user',
+        'successor-retired',
+        'successor-taken',
+      ].sort(),
+    );
+  });
+});

package/src/__tests__/cloud-status-checkpoint-reads.test.ts

@@ -0,0 +1,60 @@
+/**
+ * Cloud contract mirrors of cleo-nexus #38 (`DeviceScope`, `StatusQuery`;
+ * T13282) and #39 (`GetCheckpointResult`; T13283): the shapes the server
+ * validates, so a client that parses with them agrees with it.
+ *
+ * @task T13282
+ * @task T13283
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+  DeviceScope,
+  GetCheckpointResult,
+  ListCheckpointsResult,
+  StatusQuery,
+} from '../cloud/index.js';
+
+const PROJECT = '0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b';
+const REPLICA = '0198a1b2-0000-7000-8000-0000000000a1';
+
+describe('DeviceScope and StatusQuery (T13282)', () => {
+  it('DeviceScope is the eight §2.3 scopes and nothing else', () => {
+    expect(DeviceScope.options).toEqual([
+      'account:read',
+      'devices:read',
+      'projects:read',
+      'projects:write',
+      'sync:read',
+      'sync:write',
+      'keys:read',
+      'keys:write',
+    ]);
+    expect(DeviceScope.safeParse('admin').success).toBe(false);
+  });
+
+  it('StatusQuery: both optional, replicaId requires projectId and must be a UUIDv7', () => {
+    expect(StatusQuery.safeParse({}).success).toBe(true);
+    expect(StatusQuery.safeParse({ projectId: PROJECT }).success).toBe(true);
+    expect(StatusQuery.safeParse({ projectId: PROJECT, replicaId: REPLICA }).success).toBe(true);
+    const orphan = StatusQuery.safeParse({ replicaId: REPLICA });
+    expect(orphan.success).toBe(false);
+    expect(orphan.error?.issues[0]?.message).toBe('replicaId requires projectId');
+    // A UUIDv4 is not a replica id.
+    expect(
+      StatusQuery.safeParse({
+        projectId: PROJECT,
+        replicaId: '0198a1b2-0000-4000-8000-0000000000a1',
+      }).success,
+    ).toBe(false);
+  });
+});
+
+describe('GetCheckpointResult (T13283)', () => {
+  it('is one checkpoint shaped exactly as a list item', () => {
+    const listItem = ListCheckpointsResult.shape.checkpoints.element;
+    expect(GetCheckpointResult.shape.checkpoint).toBe(listItem);
+    expect(Object.keys(GetCheckpointResult.shape)).toEqual(['checkpoint']);
+    expect(GetCheckpointResult.safeParse({ checkpoints: [] }).success).toBe(false);
+  });
+});

package/src/agent-registry.ts

@@ -47,7 +47,11 @@ export interface AgentCredential {
    * device). Re-register with `cleo agent register --id <id> --api-key <key>`.
    */
   requiresReauth?: boolean;
-  /** Base URL of the messaging API (default: api.signaldock.io). */
+  /**
+   * Base URL of the cloud messaging API, or `'local'` for none. Rows from
+   * before T13169 may still hold the retired `https://api.signaldock.io`;
+   * CLEO never calls a SignalDock host.
+   */
   apiBaseUrl: string;
   /** Agent classification from the registry (e.g. 'code_dev', 'orchestrator'). */
   classification?: string;