@cleocode/contracts 2026.9.26 → 2026.10.1

package/dist/nexus-cloud.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nexus-cloud.d.ts","sourceRoot":"","sources":["../src/nexus-cloud.ts"],"names":[],"mappings":"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"}

package/dist/nexus-cloud.js

@@ -0,0 +1,406 @@
+/**
+ * Cleo Nexus remote reads: what `cleo cloud status|whoami|devices|projects`
+ * parse from the API and emit in their LAFS envelopes (cleo-nexus device
+ * contract v2.15, §4.1, §4.2 E2/E3/E5/E13/E14/E15, §4.4), plus the error
+ * mapping table of §4.0.4.
+ *
+ * The response schemas are the client's tolerant reading of §4.1: every field
+ * the CLI reports is named, unknown fields are stripped (never `.strict()`,
+ * §4 preamble), and fields the deployed server does not send on every route
+ * yet (E2's `device` is a subset of `DeviceView`, E13 has no
+ * `lastPresenceAt`) are optional. They are not part of `./cloud`, which
+ * mirrors the server's `@cleo-nexus/shared` package one-to-one.
+ *
+ * Nothing here carries a token, a key or a filesystem path the server sent;
+ * the local paths in {@link CloudStatusLocal} are locations only.
+ *
+ * This file is types + zod schemas + const data only (arch gate 10).
+ *
+ * @task T12871
+ * @epic T12323
+ */
+import { z } from 'zod';
+// ---------- shared pieces (§4.1) ----------
+/** Device states (§4.1 `DeviceState`). */
+export const NEXUS_DEVICE_STATES = ['active', 'signed-out', 'revoked'];
+/** Device-credential profiles (§2.3, §4.1 `DeviceProfile`). */
+export const NEXUS_CLOUD_PROFILES = ['device', 'read-only'];
+/** The `state` filter of `GET /v1/devices` (E5, `ListDevicesQuery.state`). */
+export const NEXUS_DEVICE_LIST_STATES = ['active', 'signed-out', 'revoked', 'all'];
+/** Largest page the list endpoints accept (§4.0.3). */
+export const NEXUS_PAGE_LIMIT_MAX = 200;
+/** Default number of pages a `cleo cloud` list follows before it stops and says so. */
+export const NEXUS_CLOUD_MAX_PAGES = 25;
+/** Seconds within which a replica's presence counts as fresh (§4.1 `PRESENCE_FRESH_SECONDS`). */
+export const NEXUS_PRESENCE_FRESH_SECONDS = 86_400;
+/**
+ * The device state a newer server value parses as. Not `active`, so every
+ * active-only check fails closed instead of the whole command failing.
+ */
+export const NEXUS_DEVICE_STATE_UNKNOWN = 'unknown';
+const isoTime = z.iso.datetime({ offset: true });
+/** A profile the CLI does not know reads as none, never as a parse failure. */
+const profile = z.enum(NEXUS_CLOUD_PROFILES).nullable().catch(null);
+/** A device state; a value added by a newer server reads as `unknown` (not active). */
+const deviceState = z
+    .enum([...NEXUS_DEVICE_STATES, NEXUS_DEVICE_STATE_UNKNOWN])
+    .catch(NEXUS_DEVICE_STATE_UNKNOWN);
+/** `CredentialInfo` (§4.1): the credential that made the request. */
+export const nexusCloudCredentialSchema = z.object({
+    kind: z.enum(['device', 'session']),
+    credentialId: z.string().nullable().optional(),
+    profile: profile.optional(),
+    scopes: z.array(z.string()).default([]),
+    createdAt: isoTime.nullable().optional(),
+    lastUsedAt: isoTime.nullable().optional(),
+    /** When the credential expires if it is not used again; null for sessions. */
+    idleExpiresAt: isoTime.nullable().optional(),
+});
+/** `DeviceView` (§4.1), as far as the CLI reports it. E2 sends a subset. */
+export const nexusCloudDeviceSchema = z.object({
+    deviceId: z.string(),
+    name: z.string(),
+    platform: z.string().optional(),
+    arch: z.string().nullable().optional(),
+    cliVersion: z.string().nullable().optional(),
+    createdAt: isoTime.optional(),
+    lastSeenAt: isoTime.nullable().optional(),
+    state: deviceState,
+    signedOutAt: isoTime.nullable().optional(),
+    /** Base64 device certificate; null until the device holds a key grant. */
+    certificate: z.string().nullable().optional(),
+    /** The current credential's profile, or null with none (signed out or revoked). */
+    profile: profile.optional(),
+    /** True for the device whose credential made this request. */
+    current: z.boolean().default(false),
+    projects: z.number().int().nonnegative().optional(),
+    replicas: z.number().int().nonnegative().optional(),
+    lastSyncAt: isoTime.nullable().optional(),
+    lastPresenceAt: isoTime.nullable().optional(),
+});
+/** `OrganizationSummary` (§4.1). */
+export const nexusCloudOrganizationSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    slug: z.string().nullable().optional(),
+    role: z.string().optional(),
+    personal: z.boolean().optional(),
+});
+/** `AccountUser` (§4.1). */
+export const nexusCloudUserSchema = z.object({
+    id: z.string(),
+    email: z.string(),
+    name: z.string().nullable().optional(),
+});
+/** `Whoami` (E2 `GET /v1/whoami`). */
+export const nexusCloudWhoamiSchema = z.object({
+    serverTime: isoTime.optional(),
+    user: nexusCloudUserSchema,
+    organizations: z.array(nexusCloudOrganizationSchema).default([]),
+    credential: nexusCloudCredentialSchema,
+    /** The calling device; null for a session caller. */
+    device: nexusCloudDeviceSchema.nullable(),
+});
+/** `ListDevicesViewResult` (E5 `GET /v1/devices`), one page. */
+export const nexusCloudDevicePageSchema = z.object({
+    devices: z.array(nexusCloudDeviceSchema),
+    nextCursor: z.string().max(512).nullable().default(null),
+    truncated: z.boolean().default(false),
+});
+/** Path-free replica presence (`ReplicaPresence`), with the R4 `sync` flag; other fields kept as sent. */
+export const nexusCloudPresenceSchema = z.looseObject({
+    observedAt: isoTime.optional(),
+    sync: z.object({ enabled: z.boolean() }).optional(),
+});
+/** `ReplicaRow` (§4.1). */
+export const nexusCloudReplicaSchema = z.object({
+    projectId: z.string(),
+    replicaId: z.string(),
+    deviceId: z.string(),
+    deviceName: z.string(),
+    deviceState: deviceState.optional(),
+    attachedAt: isoTime.optional(),
+    lastSyncAt: isoTime.nullable(),
+    presence: nexusCloudPresenceSchema.nullable(),
+    presenceAt: isoTime.nullable(),
+});
+/** `DeviceCounts` (§4.1): distinct devices holding a replica. */
+export const nexusCloudDeviceCountsSchema = z.object({
+    active: z.number().int().nonnegative(),
+    total: z.number().int().nonnegative(),
+});
+/** The project fields every project view carries (`Project`, §4.1). */
+const projectFields = {
+    projectId: z.string(),
+    label: z.string().nullable(),
+    organizationId: z.string(),
+    organizationName: z.string().optional(),
+    remoteUrl: z.string().nullable().optional(),
+    createdAt: isoTime.optional(),
+};
+/** `ProjectListItem` (§4.1, E13). */
+export const nexusCloudProjectListItemSchema = z.object({
+    ...projectFields,
+    role: z.string(),
+    streamId: z.string().optional(),
+    headSeq: z.number().int().nonnegative().nullable().optional(),
+    openConflicts: z.number().int().nonnegative().optional(),
+    replicas: z.array(nexusCloudReplicaSchema).default([]),
+    devices: nexusCloudDeviceCountsSchema.optional(),
+    replicaCount: z.number().int().nonnegative().optional(),
+    lastSyncAt: isoTime.nullable().optional(),
+    lastPresenceAt: isoTime.nullable().optional(),
+    /** This project's replica list was cut at 50 (T12858). */
+    replicasTruncated: z.boolean().default(false),
+});
+/** `ListProjectsResult` (E13 `GET /v1/projects`), one page. */
+export const nexusCloudProjectPageSchema = z.object({
+    projects: z.array(nexusCloudProjectListItemSchema),
+    nextCursor: z.string().max(512).nullable().default(null),
+    /** Anything in the page was cut (the project list or a replica list). */
+    truncated: z.boolean().default(false),
+    /** The project list itself was cut at 1000 (T12858). */
+    projectsTruncated: z.boolean().default(false),
+});
+/** `ProjectDetail` (E14 `GET /v1/projects/:projectId`). */
+export const nexusCloudProjectDetailSchema = z.object({
+    project: z.object({ ...projectFields, deletedAt: isoTime.nullable().optional() }),
+    role: z.string(),
+    canTrash: z.boolean().optional(),
+    openConflicts: z.number().int().nonnegative(),
+    /** At most 50, oldest attachment first. */
+    replicas: z.array(nexusCloudReplicaSchema),
+    devices: nexusCloudDeviceCountsSchema,
+    replicaCount: z.number().int().nonnegative().optional(),
+    lastSyncAt: isoTime.nullable().optional(),
+    /** `replicas` was cut at 50. */
+    truncated: z.boolean().default(false),
+    stream: z
+        .object({
+        streamId: z.string(),
+        headSeq: z.number().int().nonnegative(),
+        headCheckpointId: z.string().nullable(),
+    })
+        .nullable(),
+});
+/** `ListReplicasResult` (E15 `GET /v1/projects/:projectId/replicas`), one page. */
+export const nexusCloudReplicaPageSchema = z.object({
+    replicas: z.array(nexusCloudReplicaSchema),
+    devices: nexusCloudDeviceCountsSchema.optional(),
+    nextCursor: z.string().max(512).nullable().default(null),
+    truncated: z.boolean().default(false),
+});
+// ---------- status (E3, §4.4) ----------
+/** E3 check ids, in their contract order (§4.1 `StatusCheckId`). */
+export const NEXUS_STATUS_CHECK_IDS = [
+    'credential.valid',
+    'device.registered',
+    'device.active',
+    'device.certified',
+    'project.registered',
+    'project.writable',
+    'replica.attached',
+    'presence.fresh',
+    'replica.synced',
+    'conflicts.none',
+];
+/** The server's verdicts (§4.1 `StatusVerdict`). */
+export const NEXUS_STATUS_VERDICTS = ['ok', 'attention', 'not-linked', 'not-registered'];
+/** `cleo cloud status` verdicts: the server's plus the local `not-signed-in` (§4.4). */
+export const CLOUD_STATUS_VERDICTS = [...NEXUS_STATUS_VERDICTS, 'not-signed-in'];
+const knownCheckId = z.enum(NEXUS_STATUS_CHECK_IDS);
+/** `StatusCheck` (§4.1). Only required checks drive the verdict. */
+export const nexusCloudStatusCheckSchema = z.object({
+    id: z.enum(NEXUS_STATUS_CHECK_IDS),
+    ok: z.boolean(),
+    required: z.boolean(),
+    detail: z.string(),
+});
+/** `NexusStatus` (E3 `GET /v1/status`). */
+export const nexusCloudStatusSchema = z.object({
+    serverTime: isoTime.optional(),
+    apiVersion: z.string().optional(),
+    user: nexusCloudUserSchema,
+    credential: nexusCloudCredentialSchema,
+    device: nexusCloudDeviceSchema.nullable(),
+    project: z
+        .object({
+        projectId: z.string(),
+        registered: z.boolean(),
+        organizationId: z.string().nullable(),
+        organizationName: z.string().nullable(),
+        role: z.string().nullable(),
+    })
+        .nullable(),
+    replica: z
+        .object({
+        replicaId: z.string(),
+        attached: z.boolean(),
+        attachedElsewhere: z.boolean(),
+        attachedAt: isoTime.nullable(),
+        lastSyncAt: isoTime.nullable(),
+        presenceAt: isoTime.nullable(),
+        lastReplicaSeq: z.number().int().nonnegative().nullable().optional(),
+    })
+        .nullable(),
+    stream: z
+        .object({
+        streamId: z.string(),
+        headSeq: z.number().int().nonnegative(),
+        headCheckpointId: z.string().nullable(),
+        openConflicts: z.number().int().nonnegative(),
+        devices: nexusCloudDeviceCountsSchema,
+    })
+        .nullable(),
+    /** Check ids added by a newer server are dropped, never a parse failure. */
+    checks: z.array(nexusCloudStatusCheckSchema.extend({ id: z.string() })).transform((list) => list.flatMap((c) => {
+        const id = knownCheckId.safeParse(c.id);
+        return id.success ? [{ ...c, id: id.data }] : [];
+    })),
+    /** A verdict added by a newer server reads as `attention`: never `ok` by accident. */
+    verdict: z.enum(NEXUS_STATUS_VERDICTS).catch('attention'),
+});
+// ---------- error mapping (§4.0.4) ----------
+/** `details.reason` values of a 401 (§4.0.4 `UnauthenticatedReason`). */
+export const NEXUS_UNAUTHENTICATED_REASONS = [
+    'missing',
+    'invalid',
+    'credential-revoked',
+    'credential-expired',
+    'device-signed-out',
+    'device-revoked',
+    'session-bearer-retired',
+    'session-used',
+];
+/** `details.reason` values of a 403 (§4.0.4 `ForbiddenReason`). */
+export const NEXUS_FORBIDDEN_REASONS = [
+    'insufficient-scope',
+    'session-required',
+    'device-required',
+    'device-mismatch',
+    'not-self',
+    'project-role',
+    'route-undeclared',
+    'bearer-session-required',
+    'session-not-fresh',
+    'device-limit',
+];
+/** `details.revokedReason` values of a 401 `credential-revoked` (§4.0.4, v2.11). */
+export const NEXUS_REVOKED_REASONS = ['signed-out', 'revoked', 'rotated', 'reenrolled'];
+const LOGIN = 'run `cleo login nexus`';
+const COMPROMISED = {
+    code: 'E_NEXUS_CREDENTIAL_COMPROMISED',
+    message: "this device's credential was replaced or revoked elsewhere, possibly used from another machine",
+    fix: 'revoke this device on cleocode.dev and sign in again with `cleo login nexus`',
+};
+const DEVICE_REVOKED = {
+    code: 'E_NEXUS_DEVICE_REVOKED',
+    message: 'this device was revoked',
+    fix: 'run `cleo login nexus` to enrol this machine as a new device',
+};
+const SESSION_EXPIRED_LOGIN = {
+    code: 'E_NEXUS_SESSION_EXPIRED',
+    message: 'the session is too old for this request',
+    fix: 'run `cleo login nexus` (needs a browser: on a headless machine a human must complete the login)',
+};
+const SERVER_REFUSED = {
+    code: 'E_NEXUS_REQUEST_FAILED',
+    message: null,
+    fix: null,
+};
+/**
+ * 401 `credential-revoked`, by `details.revokedReason` (§4.0.4 v2.11). An
+ * absent or unknown reason maps as `rotated`: a revocation the CLI cannot
+ * explain (R2).
+ */
+export const NEXUS_REVOKED_REASON_ERRORS = {
+    reenrolled: {
+        code: 'E_NEXUS_NOT_SIGNED_IN',
+        message: "this device's credential was replaced by a newer login of the same device",
+        fix: LOGIN,
+    },
+    'signed-out': {
+        code: 'E_NEXUS_NOT_SIGNED_IN',
+        message: 'this device was signed out and later signed in again with another credential',
+        fix: LOGIN,
+    },
+    revoked: DEVICE_REVOKED,
+    rotated: COMPROMISED,
+};
+/** 401 `E_UNAUTHENTICATED`, by `details.reason` (§4.0.4). Unknown reasons map as `invalid`. */
+export const NEXUS_UNAUTHENTICATED_ERRORS = {
+    missing: {
+        code: 'E_NEXUS_NOT_SIGNED_IN',
+        message: 'not signed in to Cleo Nexus (the credential is missing or invalid)',
+        fix: LOGIN,
+    },
+    invalid: {
+        code: 'E_NEXUS_NOT_SIGNED_IN',
+        message: 'not signed in to Cleo Nexus (the credential is missing or invalid)',
+        fix: LOGIN,
+    },
+    // Resolved by `details.revokedReason` through NEXUS_REVOKED_REASON_ERRORS.
+    'credential-revoked': COMPROMISED,
+    'credential-expired': {
+        code: 'E_NEXUS_SESSION_EXPIRED',
+        message: 'the device credential expired after 90 days without use',
+        fix: LOGIN,
+    },
+    'device-signed-out': {
+        code: 'E_NEXUS_DEVICE_SIGNED_OUT',
+        message: 'this device was signed out',
+        fix: LOGIN,
+    },
+    'device-revoked': DEVICE_REVOKED,
+    'session-bearer-retired': {
+        code: 'E_NEXUS_SESSION_EXPIRED',
+        message: 'bearer sessions are no longer accepted',
+        fix: 'run `cleo login nexus` with the current CLI',
+    },
+    'session-used': {
+        code: 'E_NEXUS_SESSION_EXPIRED',
+        message: 'the 9.24 session was already used by another enrolment',
+        fix: LOGIN,
+    },
+};
+/** 403 `E_FORBIDDEN`, by `details.reason` (§4.0.4). Unknown reasons are reported as sent. */
+export const NEXUS_FORBIDDEN_ERRORS = {
+    'insufficient-scope': {
+        code: 'E_NEXUS_INSUFFICIENT_SCOPE',
+        message: "this device's credential lacks the scope for that request",
+        fix: 'run `cleo login nexus` without --read-only to enrol with the full device profile',
+    },
+    'session-required': SERVER_REFUSED,
+    'device-required': SERVER_REFUSED,
+    'device-mismatch': SERVER_REFUSED,
+    'not-self': SERVER_REFUSED,
+    'project-role': SERVER_REFUSED,
+    'route-undeclared': SERVER_REFUSED,
+    'bearer-session-required': SESSION_EXPIRED_LOGIN,
+    'session-not-fresh': SESSION_EXPIRED_LOGIN,
+    'device-limit': {
+        code: 'E_NEXUS_REQUEST_FAILED',
+        message: 'the account has reached its device limit',
+        fix: 'revoke unused devices on cleocode.dev, then retry',
+    },
+};
+/**
+ * 409 `E_CONFLICT` reasons the CLI reports with their own code (§4.0.4). Every
+ * other conflict is either handled inside its flow or reported as
+ * `E_NEXUS_REQUEST_FAILED` with the server's message.
+ */
+export const NEXUS_CONFLICT_ERRORS = {
+    'replica-copied': {
+        code: 'E_NEXUS_REPLICA_COPIED',
+        message: 'this project store is attached from another device (a copied store)',
+        fix: null,
+    },
+    'rotation-conflict': COMPROMISED,
+};
+/** No answer at all (network error or timeout, §4.0.4). */
+export const NEXUS_UNREACHABLE_ERROR = {
+    code: 'E_NEXUS_UNREACHABLE',
+    message: null,
+    fix: 'check your network and retry',
+};
+//# sourceMappingURL=nexus-cloud.js.map

package/dist/nexus-cloud.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nexus-cloud.js","sourceRoot":"","sources":["../src/nexus-cloud.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/contracts",
-  "version": "2026.9.26",
+  "version": "2026.10.1",
   "description": "Domain types, interfaces, and contracts for the CLEO ecosystem",
   "type": "module",
   "main": "./dist/index.js",
@@ -198,7 +198,7 @@
   "dependencies": {
     "zod": "^4.3.6",
     "zod-to-json-schema": "^3.25.2",
-    "@cleocode/lafs": "2026.9.26"
+    "@cleocode/lafs": "2026.10.1"
   },
   "scripts": {
     "build": "tsc -b --force && node scripts/copy-assets.mjs && node scripts/emit-schemas.mjs",

package/src/index.ts

@@ -2993,11 +2993,15 @@ export type {
   NexusAccountOrganization,
   NexusAccountStatus,
   NexusAccountUser,
+  NexusDeviceEndOutcome,
+  NexusDeviceLogoutResult,
+  NexusDeviceLogoutRow,
   NexusLoginDevice,
   NexusLoginResult,
   NexusLogoutResult,
   NexusProjectLink,
   NexusProjectLinkResult,
+  NexusReplicaAttachment,
   NexusSessionState,
 } from './nexus-account.js';
 export {
@@ -3009,4 +3013,64 @@ export {
   nexusAccountOrganizationSchema,
   nexusAccountUserSchema,
 } from './nexus-account.js';
+export type {
+  CloudDevicesResult,
+  CloudPaging,
+  CloudProjectShowResult,
+  CloudProjectsResult,
+  CloudStatusLocal,
+  CloudStatusOfflineDetails,
+  CloudStatusResult,
+  CloudStatusSummary,
+  CloudStatusVerdict,
+  CloudWarning,
+  CloudWhoamiResult,
+  NexusCloudCredential,
+  NexusCloudDevice,
+  NexusCloudDeviceCounts,
+  NexusCloudProjectDetail,
+  NexusCloudProjectListItem,
+  NexusCloudReplica,
+  NexusCloudStatus,
+  NexusCloudStatusCheck,
+  NexusCloudWhoami,
+  NexusDeviceListState,
+  NexusErrorMapping,
+  NexusStatusCheckId,
+} from './nexus-cloud.js';
+export {
+  CLOUD_STATUS_VERDICTS,
+  NEXUS_CLOUD_MAX_PAGES,
+  NEXUS_CLOUD_PROFILES,
+  NEXUS_CONFLICT_ERRORS,
+  NEXUS_DEVICE_LIST_STATES,
+  NEXUS_DEVICE_STATE_UNKNOWN,
+  NEXUS_DEVICE_STATES,
+  NEXUS_FORBIDDEN_ERRORS,
+  NEXUS_FORBIDDEN_REASONS,
+  NEXUS_PAGE_LIMIT_MAX,
+  NEXUS_PRESENCE_FRESH_SECONDS,
+  NEXUS_REVOKED_REASON_ERRORS,
+  NEXUS_REVOKED_REASONS,
+  NEXUS_STATUS_CHECK_IDS,
+  NEXUS_STATUS_VERDICTS,
+  NEXUS_UNAUTHENTICATED_ERRORS,
+  NEXUS_UNAUTHENTICATED_REASONS,
+  NEXUS_UNREACHABLE_ERROR,
+  nexusCloudCredentialSchema,
+  nexusCloudDeviceCountsSchema,
+  nexusCloudDevicePageSchema,
+  nexusCloudDeviceSchema,
+  nexusCloudOrganizationSchema,
+  nexusCloudPresenceSchema,
+  nexusCloudProjectDetailSchema,
+  nexusCloudProjectListItemSchema,
+  nexusCloudProjectPageSchema,
+  nexusCloudReplicaPageSchema,
+  nexusCloudReplicaSchema,
+  nexusCloudStatusCheckSchema,
+  nexusCloudStatusSchema,
+  nexusCloudUserSchema,
+  nexusCloudWhoamiSchema,
+} from './nexus-cloud.js';
 export { isStorableTaskId, isTaskId, TASK_ID_REGEX, type TaskId } from './task-id.js';

package/src/nexus-account.ts

@@ -65,8 +65,10 @@ export const NEXUS_ACCOUNT_ERROR_CODES = [
   'E_NEXUS_BUSY',
   /** Several accounts hold a device credential on one origin and none was named. */
   'E_NEXUS_ACCOUNT_AMBIGUOUS',
-  /** An option that needs device credentials (`--read-only`) without `CLEO_NEXUS_DEVICE=1`. */
+  /** An option that needs device credentials (`--read-only`) with `CLEO_NEXUS_DEVICE=0`. */
   'E_NEXUS_DEVICE_REQUIRED',
+  /** `.cleo/nexus-link.json` is in a format this CLEO cannot update (written by a newer CLEO). */
+  'E_NEXUS_LINK_FILE_UNSUPPORTED',
 ] as const;
 
 /** One of {@link NEXUS_ACCOUNT_ERROR_CODES}. */
@@ -161,9 +163,9 @@ export interface NexusLoginResult {
   credentialsPath: string;
   /** Non-fatal problems, e.g. the account lookup failed after a good login. */
   warnings: string[];
-  /** The enrolled device; present only with `CLEO_NEXUS_DEVICE=1` (device credentials). */
+  /** The enrolled device; present only with device credentials (the default; off with `CLEO_NEXUS_DEVICE=0`). */
   device?: NexusLoginDevice;
-  /** Scopes of the stored device credential; present only with `CLEO_NEXUS_DEVICE=1`. */
+  /** Scopes of the stored device credential; present only with device credentials. */
   scopes?: string[];
 }
 
@@ -184,6 +186,56 @@ export interface NexusLogoutResult {
   warnings: string[];
 }
 
+/**
+ * What happened to one device's sign-out (E9) or revoke (E10) in
+ * `cleo logout nexus [--revoke]` with device credentials (the default; `CLEO_NEXUS_DEVICE=0` turns them off) (cleo-nexus
+ * device contract §3.5, M3). Holds no secret.
+ *
+ * - `confirmed`: the server answered 200, or 401 `device-signed-out` /
+ *   `device-revoked` (a revoke accepts only `device-revoked`);
+ * - `pending`: no usable answer (network, timeout, 429, 5xx, or a route the
+ *   server does not have yet); the credentials stay in their slot and the
+ *   next `cleo logout nexus`, `cleo login nexus` or cloud command retries;
+ * - `unconfirmed`: every credential held was refused as stale, so the CLI
+ *   cannot finish it; the slot is kept, and a sign-out or revoke of the
+ *   device on cleocode.dev lets the next retry confirm it;
+ * - `signed-out`: a revoke found the device already signed out (E10 401
+ *   `device-signed-out`). Its credentials are dead, so the CLI cannot revoke
+ *   it; the revoke slot is cleared (never retried) and the device must be
+ *   revoked on cleocode.dev.
+ */
+export type NexusDeviceEndOutcome = 'confirmed' | 'pending' | 'unconfirmed' | 'signed-out';
+
+/** One device row of a {@link NexusDeviceLogoutResult}. */
+export interface NexusDeviceLogoutRow {
+  /** Nexus user id of the entry. */
+  userId: string;
+  /** The device the request ended. */
+  deviceId: string;
+  /** `sign-out` (E9) or `revoke` (E10). */
+  action: 'sign-out' | 'revoke';
+  /** `true` for a replaced device's leftover request retried from `retired`. */
+  retired: boolean;
+  /** Server-side outcome. */
+  outcome: NexusDeviceEndOutcome;
+  /** `true` when a confirmed revoke removed the (origin, user) entry from `nexus-device.json`. */
+  removedLocally: boolean;
+}
+
+/** Result of `cleo logout nexus [--revoke]` with device credentials. Holds no secret. */
+export interface NexusDeviceLogoutResult {
+  /** API origin. */
+  apiUrl: string;
+  /** `sign-out` or `revoke` (`--revoke`). */
+  action: 'sign-out' | 'revoke';
+  /** One row per device request settled or retried in this run, sorted by user then device. */
+  devices: NexusDeviceLogoutRow[];
+  /** The 9.24 session sign-out, when a leftover session was found for the origin. */
+  session: NexusLogoutResult | null;
+  /** Non-fatal problems: every non-`confirmed` row is named here. */
+  warnings: string[];
+}
+
 /**
  * The binding of a local CLEO project to its Nexus registration, persisted in
  * the project's machine-local `.cleo/nexus-link.json`, keyed by API origin.
@@ -203,6 +255,31 @@ export interface NexusProjectLink {
   streamId: string;
   /** ISO time of the last successful link. */
   linkedAt: string;
+  /**
+   * This store's replica id as attached on the server (device contract
+   * §3.6, §3.7). A cache, not the source of truth: the store's active
+   * `_sync_replica` row is. Absent before the first device-credential link.
+   */
+  replicaId?: string;
+  /** The Nexus device id that attached {@link NexusProjectLink.replicaId}. */
+  nexusDeviceId?: string;
+  /** ISO time the replica was last attached or confirmed. */
+  attachedAt?: string;
+}
+
+/**
+ * What `cleo project link` did for this machine's copy of the project with a
+ * device credential (contract §3.6 steps 3 to 5). Holds no path or secret.
+ */
+export interface NexusReplicaAttachment {
+  /** The store's replica id (UUIDv7), now attached on the server. */
+  replicaId: string;
+  /** The Nexus device that holds it. */
+  deviceId: string;
+  /** The retired replica id when this link rebound the store (a copy, or a re-enrolled device). */
+  reboundFrom: string | null;
+  /** Server time the presence report was received, or `null` when sending it failed (see warnings). */
+  presenceAt: string | null;
 }
 
 /** Result of `cleo project link`. */
@@ -217,4 +294,17 @@ export interface NexusProjectLinkResult {
   alreadyLinked: boolean;
   /** Absolute path of the local binding file. */
   linkPath: string;
+  /**
+   * The replica attach and presence report, with device credentials; `null`
+   * with the 9.24 session (`CLEO_NEXUS_DEVICE=0`), which cannot attach.
+   */
+  replica: NexusReplicaAttachment | null;
+  /**
+   * Why this machine's copy was not attached, when device mode tried and
+   * failed (for example `E_NEXUS_REPLICA_COPIED`); `null` otherwise. The same
+   * text is also in {@link NexusProjectLinkResult.warnings}.
+   */
+  attachError: { code: string; message: string; fix: string | null } | null;
+  /** Non-fatal problems (for example, presence could not be sent). */
+  warnings: string[];
 }