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

package/src/cloud/api.ts

@@ -69,8 +69,45 @@ export type Device = z.infer<typeof Device>;
 export const ListDevicesResult = z.object({ devices: z.array(Device) });
 export type ListDevicesResult = z.infer<typeof ListDevicesResult>;
 
+// ---------- device credential scopes and E3 status (§4.1) ----------
+
+/** What a device credential may do (§2.3). A signed-in session holds every scope. */
+export const DeviceScope = z.enum([
+  'account:read',
+  'devices:read',
+  'projects:read',
+  'projects:write',
+  'sync:read',
+  'sync:write',
+  'keys:read',
+  'keys:write',
+]);
+/** One device credential scope. */
+export type DeviceScope = z.infer<typeof DeviceScope>;
+
+/** E3 `GET /v1/status` query (§4.1): `replicaId` (a UUIDv7) requires `projectId`. */
+export const StatusQuery = z
+  .object({ projectId: ProjectId.optional(), replicaId: ReplicaId.optional() })
+  .refine((q) => q.replicaId === undefined || q.projectId !== undefined, {
+    message: 'replicaId requires projectId',
+  });
+/** The E3 status query. */
+export type StatusQuery = z.infer<typeof StatusQuery>;
+
 // ---------- projects ----------
 
+/**
+ * A new project's first data key, stored in the same transaction as its registration (onboarding B): key
+ * version 1, wrapped by the registrant's account master key. Needs keys:write on top of projects:write, and is
+ * honoured only when the call creates the project. Later versions stay rotations
+ * (PUT /v1/projects/:projectId/keys/:userId).
+ */
+export const InitialProjectKey = z.object({
+  /** The project data key, wrapped by the registrant's master key at key version 1. */
+  wrappedProjectKey: Base64,
+});
+export type InitialProjectKey = z.infer<typeof InitialProjectKey>;
+
 export const RegisterProjectRequest = z.object({
   projectId: ProjectId,
   /**
@@ -87,6 +124,8 @@ export const RegisterProjectRequest = z.object({
    * caller's personal organization, which every account has.
    */
   organizationId: z.string().uuid().optional(),
+  /** The project's first data key (onboarding B). Honoured only when this call creates the project. */
+  initialKey: InitialProjectKey.optional(),
 });
 export type RegisterProjectRequest = z.infer<typeof RegisterProjectRequest>;
 
@@ -103,7 +142,16 @@ export const Project = z.object({
 });
 export type Project = z.infer<typeof Project>;
 
-export const RegisterProjectResult = z.object({ project: Project, streamId: StreamId });
+export const RegisterProjectResult = z.object({
+  project: Project,
+  streamId: StreamId,
+  /**
+   * The key version `initialKey` is stored at for the caller: 1 when this call created the project with it,
+   * or repeated the caller's identical version 1; null when no initialKey was sent, or the project already
+   * existed with no key (initialKey ignored). Absent from servers older than initialKey.
+   */
+  initialKeyVersion: KeyVersion.nullable().optional(),
+});
 export type RegisterProjectResult = z.infer<typeof RegisterProjectResult>;
 
 /**
@@ -162,6 +210,10 @@ export const HomeReplica = z.object({
   lastSyncAt: z.iso.datetime().nullable(),
   presence: ReplicaPresence.nullable(),
   presenceAt: z.iso.datetime().nullable(),
+  /** When the replica was retired (T123), else null. Absent from servers older than retirement. */
+  retiredAt: z.iso.datetime().nullable().optional(),
+  /** The retired replica's named successor, else null (not retired, or retired with none). */
+  successor: ReplicaId.nullable().optional(),
 });
 export type HomeReplica = z.infer<typeof HomeReplica>;
 
@@ -501,6 +553,15 @@ export type CreateCheckpointResult = z.infer<typeof CreateCheckpointResult>;
 export const ListCheckpointsResult = z.object({ checkpoints: z.array(Checkpoint) });
 export type ListCheckpointsResult = z.infer<typeof ListCheckpointsResult>;
 
+/**
+ * E29 `GET …/checkpoints/head` and E30 `GET …/checkpoints/:checkpointId` (cleo-nexus T122, contract
+ * v2.27): one checkpoint, shaped as a list item. Both answer 404 when there is no head, or the id is
+ * unknown, malformed or on another stream.
+ */
+export const GetCheckpointResult = z.object({ checkpoint: Checkpoint });
+/** One checkpoint read by id or as the head. */
+export type GetCheckpointResult = z.infer<typeof GetCheckpointResult>;
+
 // ---------- blobs ----------
 
 export const PresignUploadRequest = z.object({
@@ -585,6 +646,69 @@ export type ListedLease = z.infer<typeof ListedLease>;
 export const ListLeasesResult = z.object({ leases: z.array(ListedLease) });
 export type ListLeasesResult = z.infer<typeof ListLeasesResult>;
 
+// ---------- replica retirement (T123; cleocode journal spec §1.3, §3.5 D5) ----------
+
+/**
+ * A journal transaction id, `<emittingReplicaId>:<localTxnSeq>`: the replica that emitted the transaction and its own
+ * transaction counter. Only the format is checked: the emitting replica may be the successor (a rebind), not the
+ * retired one.
+ */
+const JournalTxnId = z
+  .string()
+  .regex(
+    /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}:(0|[1-9][0-9]{0,15})$/,
+    'expected <uuid>:<non-negative integer>',
+  );
+
+/**
+ * E31 `POST /v1/streams/:streamId/replicas/:replicaId/retirements` (cleo-nexus T123, contract v2.28): the replica
+ * writes no segment past `lastReplicaSeq` (none at all when it is null). The journal's own `retire` transaction
+ * travels E2E-encrypted; this is the server's signed copy, so it can refuse later appends and show the retirement in
+ * the reads.
+ */
+export const RetireReplicaRequest = z.object({
+  /** The signing device. It must be the calling device. */
+  deviceId: DeviceId,
+  /** The replica that carries on this one's history, or null. Never the retired replica itself. */
+  successor: ReplicaId.nullable(),
+  /**
+   * The replica's last segment: at least its highest appended replicaSeq, and late segments up to it still land. Null
+   * when the replica wrote nothing: then no segment of it is stored, and none may land.
+   */
+  lastReplicaSeq: z.number().int().nonnegative().nullable(),
+  /**
+   * The journal transaction that carries the retire (`${emittingReplicaId}:${localTxnSeq}`), or null for an owner's
+   * retirement with no journal transaction.
+   */
+  txnId: JournalTxnId.nullable(),
+  /** Ed25519 by the calling device over replicaRetireMessage(...). */
+  signature: Base64,
+});
+/** The E31 request body. */
+export type RetireReplicaRequest = z.infer<typeof RetireReplicaRequest>;
+
+/** A stored retirement: one per (stream, replica), insert-only. */
+export const ReplicaRetirement = z.object({
+  streamId: StreamId,
+  replicaId: ReplicaId,
+  successor: ReplicaId.nullable(),
+  /** Null: the replica wrote nothing. */
+  lastReplicaSeq: z.number().int().nonnegative().nullable(),
+  /** The device that signed it: the replica's own, a project owner's, or (home streams) another of the account's. */
+  signerDeviceId: DeviceId,
+  txnId: JournalTxnId.nullable(),
+  /** The signer's Ed25519 over replicaRetireMessage(...), so a client or an auditor can verify the record. */
+  signature: Base64,
+  retiredAt: z.iso.datetime(),
+});
+/** A stored replica retirement. */
+export type ReplicaRetirement = z.infer<typeof ReplicaRetirement>;
+
+/** 201 for a new retirement, 200 with the stored one for a repeat with the same successor and lastReplicaSeq. */
+export const RetireReplicaResult = z.object({ retirement: ReplicaRetirement });
+/** The E31 answer. */
+export type RetireReplicaResult = z.infer<typeof RetireReplicaResult>;
+
 // ---------- keys (wrapped project keys; the account master key is escrowed on the server, T082: encryption at rest, not end-to-end) ----------
 
 /**

package/src/dispatch/operations-registry.ts

@@ -9,7 +9,7 @@
  * @since SG-ARCH-SOLID Saga T9831 · E-CLI-BOUNDARY T9833 · T10061
  */
 
-import { DOCS_LIFECYCLE_STATUSES } from '../operations/docs.js';
+import { DOCS_LIFECYCLE_STATUSES } from '../operations/docs-lifecycle.js';
 import { OUTPUT_CONTRACTS } from '../operations/output-contracts-data.js';
 import { tasksUpdateInputContract } from '../operations/tasks.js';
 import type { CanonicalDomain, Gateway, OperationDef, ParamDef, Tier } from './operation-def.js';

package/src/doctor.ts

@@ -699,11 +699,10 @@ export interface DbSubstrateProjectSurvey {
   /** Absolute path to the project root that was surveyed. */
   projectRoot: string;
   /**
-   * Stable identifier for the project — currently the `base64url(path)`
-   * truncated to 32 chars, matching the convention used by `cleo nexus`
-   * project resolution.
+   * Declared portable project identity, or null when identity is missing.
+   * A survey never creates an identity or derives it from a filesystem path.
    */
-  projectId: string;
+  projectId: string | null;
   /** Per-role survey result, keyed by canonical role name. */
   dbs: Readonly<Record<string, DbSubstrateEntry>>;
 }
@@ -1125,8 +1124,71 @@ export interface SupersededStoreConflict {
   targetTable: string;
   /** Legacy rows left uncopied. */
   rows: number;
-  /** Why they were left. */
-  reason: 'live-authoritative' | 'collides-with-live';
+  /**
+   * Why they were left. `id-collision-undecided` (full mode, T13172): a live
+   * task holds the legacy task's id and one of the two creation times does
+   * not parse, so the run cannot tell whether they are the same task; it
+   * neither renumbers nor copies the legacy task. `withheld-undecided`: a
+   * task-graph table such a run did not copy at all, so the undecided task's
+   * children, dependencies and criteria cannot attach to the live task.
+   */
+  reason:
+    | 'live-authoritative'
+    | 'collides-with-live'
+    | 'id-collision-undecided'
+    | 'withheld-undecided';
+  /** The legacy ids left uncopied, when the run can name them. */
+  ids?: string[];
+}
+
+/**
+ * A legacy task recovered under a fresh id because a DIFFERENT live task holds
+ * its id (a task written into the empty store after a deferred exodus, T13172).
+ * The renumbering happens in a scratch copy of the legacy file, with every
+ * reference to the task re-pointed; the legacy file and live rows are untouched.
+ *
+ * @task T13172
+ */
+export interface SupersededStoreIdRemap {
+  /** Logical legacy source. */
+  sourceDb: string;
+  /** The legacy task's id, which the live store uses for another task. */
+  legacyId: string;
+  /** The id the legacy task is recovered under. */
+  newId: string;
+  /** The legacy task's title. */
+  legacyTitle: string;
+  /** Title of the live task that holds `legacyId`. */
+  liveTitle: string;
+  /** `true` when a previous run already recovered it as `newId` (nothing new is copied). */
+  alreadyRecovered: boolean;
+  /** Legacy rows re-pointed from `legacyId` to `newId` (children, dependencies, criteria, …). */
+  referencesRepointed: number;
+  /**
+   * The legacy task's creation time and type, which a later run (and
+   * `cleo show <legacy id>`) checks against the recovered task before trusting
+   * this record (T13183). Absent in receipts written before T13183.
+   */
+  legacyCreatedAt?: string;
+  legacyType?: string | null;
+}
+
+/**
+ * One bare legacy table of the live store a reconcile carried: its row count
+ * and key digest when the run verified (T13319). The run records it in the
+ * store (T13320) and in its receipt; the sync refusal for stranded bare rows
+ * stands down for a table that still matches, so a row the runtime later
+ * deletes from the prefixed twin is never mistaken for one never carried.
+ *
+ * @task T13319
+ */
+export interface SupersededStoreBareAccount {
+  /** The bare table, e.g. `task_labels`. */
+  table: string;
+  /** Its rows when the run carried it. */
+  rows: number;
+  /** sha256 of its primary-key values in order (every column if keyless). */
+  digest: string;
 }
 
 /**
@@ -1162,8 +1224,17 @@ export interface SupersededStoreReconcileResult {
    * touch the live task graph, and list everything left in `conflicts`.
    */
   mode: 'full' | 'additive';
-  /** Legacy rows deliberately left uncopied (additive mode); empty in full mode. */
+  /**
+   * Legacy rows deliberately left uncopied: additive mode's live-authoritative
+   * tables, and in full mode the task-id collisions the run cannot decide.
+   */
   conflicts: SupersededStoreConflict[];
+  /**
+   * Legacy tasks whose id a different live task holds, recovered (full mode)
+   * or to be recovered (dry-run) under a new id. Empty in additive mode, which
+   * never writes the task graph.
+   */
+  remaps: SupersededStoreIdRemap[];
   /** `true` when nothing was written. */
   dryRun: boolean;
   /** Absolute project root. */
@@ -1186,4 +1257,11 @@ export interface SupersededStoreReconcileResult {
   receiptPath: string | null;
   /** Human-readable explanation, suitable for printing verbatim. */
   reason: string;
+  /**
+   * The live store's bare tables this run carried, on a `reconciled` receipt
+   * that copied the bare family (T13319). Audit only: the sync check reads the
+   * record the run wrote into the store itself, which travels with backups
+   * (T13320).
+   */
+  accounted?: SupersededStoreBareAccount[];
 }

package/src/heavy-command-hook.ts

@@ -19,9 +19,10 @@
  *
  * - `rewrite` — DEFAULT. Wrap it in place as
  *   `cleo run --wait --passthrough --class <c> -- <cmd>`, when the harness
- *   runs in `bypassPermissions` or `auto` mode and no deny or ask rule names
- *   the command (otherwise the hook warns: a rewrite would change which
- *   permission rules match).
+ *   runs in `bypassPermissions` or `auto` mode, or (Claude Code `default`,
+ *   `acceptEdits`, `dontAsk`) when the user's allow rules already approve the
+ *   command, and no deny or ask rule names it. Otherwise the hook warns: a
+ *   rewrite would change which permission rules match.
  * - `warn` — leave the command alone; add a context line naming the governed
  *   form.
  * - `off` — do nothing (the installer also removes the hook entry).
@@ -124,9 +125,13 @@ export interface OpencodeHeavyCommandAnswer {
 export interface PreToolUseHookOutput {
   readonly hookSpecificOutput: {
     readonly hookEventName: 'PreToolUse';
-    /** Omitted unless the provider requires it (Codex rewrites need `allow`). */
+    /**
+     * Omitted unless needed: Codex rewrites need `allow`, Kimi's "re-run it"
+     * is a `deny`, and a Claude Code rewrite carries `allow` only when the
+     * user's allow rules already approve the original command (T13124).
+     */
     readonly permissionDecision?: 'allow' | 'deny';
-    /** Shown to the agent on `deny`. */
+    /** Shown to the agent on `deny`; written to Claude Code's debug log on `allow`. */
     readonly permissionDecisionReason?: string;
     /** Replaces the whole tool input. */
     readonly updatedInput?: ShellToolInput;
@@ -134,3 +139,168 @@ export interface PreToolUseHookOutput {
     readonly additionalContext?: string;
   };
 }
+
+// ---------------------------------------------------------------------------
+// Project-level delivery (T13124)
+// ---------------------------------------------------------------------------
+
+/**
+ * What delivering the hook to one provider did in one project.
+ *
+ * - `installed` / `updated` / `removed` / `unchanged` — the config file was
+ *   written, refreshed, cleaned (mode `off`) or already current.
+ * - `skipped` — not applicable: the provider is not in use on this machine or
+ *   project, or the project is the user's home directory (whose provider
+ *   configs are user-global, which CLEO never writes).
+ * - `blocked` — a path the hook must live under exists but is not a
+ *   directory (a stray `.codex` file, say); nothing was written.
+ * - `unsupported` — the provider cannot take a project-level hook (Kimi reads
+ *   hooks only from its global config).
+ * - `needs-consent` — the config is the project's own (Codex's committable
+ *   `.codex/hooks.json`, tracked or holding anything CLEO did not write), so
+ *   CLEO does not write or hide it; `snippet` is the entry to add by hand.
+ * - `failed` — any other error, such as a config file that is not valid JSON
+ *   (left untouched).
+ */
+export type HeavyHookDeliveryStatus =
+  | 'installed'
+  | 'updated'
+  | 'removed'
+  | 'unchanged'
+  | 'skipped'
+  | 'blocked'
+  | 'unsupported'
+  | 'needs-consent'
+  | 'failed';
+
+/** One provider's result from syncing the hook into a project. */
+export interface HeavyHookDeliveryOutcome {
+  /** The harness. */
+  readonly provider: HeavyCommandHookProvider;
+  /** What the sync did. */
+  readonly status: HeavyHookDeliveryStatus;
+  /** The config file (or plugin file) the hook lives in, absolute. */
+  readonly target: string;
+  /** Why it was skipped, blocked, unsupported or failed. */
+  readonly reason?: string;
+  /** The exact step that fixes a `blocked`, `unsupported`, `needs-consent` or `failed` outcome. */
+  readonly remedy?: string;
+  /** `needs-consent`: the exact JSON entry to add to the config by hand. */
+  readonly snippet?: string;
+}
+
+/**
+ * The hook's state for one provider in one project, as `cleo doctor` reports it.
+ *
+ * - `installed` — present and identical to what this CLEO would write.
+ * - `outdated` — present but written by another CLEO build, only in a legacy
+ *   location, or visible to git as an untracked file (gh#1805: it widens
+ *   `cleo verify`'s evidence scope); `cleo upgrade` refreshes it.
+ * - `missing` — the provider is in use and the hook is absent.
+ * - `blocked` — see {@link HeavyHookDeliveryStatus}.
+ * - `unreadable` — the config file exists but cannot be read or parsed.
+ * - `unsupported` — the provider cannot take a project-level hook.
+ * - `needs-consent` — see {@link HeavyHookDeliveryStatus}; `snippet` holds the entry.
+ * - `disabled` — `resources.heavyCommandHook` is `off`, and no CLEO hook is left.
+ * - `not-detected` — the provider is not in use here; nothing is expected.
+ */
+export type HeavyHookInstallState =
+  | 'installed'
+  | 'outdated'
+  | 'missing'
+  | 'blocked'
+  | 'unreadable'
+  | 'unsupported'
+  | 'needs-consent'
+  | 'disabled'
+  | 'not-detected';
+
+/** One provider's hook state in one project. */
+export interface HeavyHookInspection {
+  /** The harness. */
+  readonly provider: HeavyCommandHookProvider;
+  /** Whether the provider is in use on this machine or in this project. */
+  readonly detected: boolean;
+  /** The hook's state. */
+  readonly state: HeavyHookInstallState;
+  /** The config file (or plugin file) the hook lives in, absolute. */
+  readonly target: string;
+  /** One line saying what was found. */
+  readonly detail: string;
+  /** The exact step that fixes the state, when one is needed. */
+  readonly remedy?: string;
+  /** `needs-consent`: the exact JSON entry to add to the config by hand. */
+  readonly snippet?: string;
+}
+
+/**
+ * Whether the `cleo` a hook finds on PATH can answer it.
+ *
+ * - `current` — it answers `cleo hook heavy-command`.
+ * - `older` — it predates `cleo hook` (and `cleo run`): the hook lets every
+ *   command run ungoverned. The hook's own marker (exit 127, "Unknown
+ *   command") or a direct probe says so.
+ * - `missing` — no `cleo` on PATH: the hook stays silent.
+ * - `unknown` — the probe failed some other way (a broken version-manager
+ *   shim, a timeout, a crash). The hook fails open, so it governs nothing
+ *   while this lasts.
+ */
+export type HeavyHookCliState = 'current' | 'older' | 'missing' | 'unknown';
+
+/** The result of probing the `cleo` on PATH from a project directory. */
+export interface HeavyHookCliProbe {
+  /** What the probe found. */
+  readonly state: HeavyHookCliState;
+  /** The `cleo` the hook resolves on PATH, or `null`. */
+  readonly path: string | null;
+  /** One line saying what was found. */
+  readonly detail: string;
+  /** The exact step that fixes (or diagnoses) a CLI that is not `current`. */
+  readonly remedy?: string;
+}
+
+/** Options for the project-level delivery functions (all injectable for tests). */
+export interface HeavyHookDeliveryOptions {
+  /** Environment for provider detection (`PATH`, `HOME`, `CODEX_HOME`, …). Default `process.env`. */
+  readonly env?: Readonly<Record<string, string | undefined>>;
+  /** Providers to consider. Default: every provider CLEO knows. */
+  readonly providers?: readonly HeavyCommandHookProvider[];
+  /**
+   * Inspection only: run the git checks (a hook file git can see, a shared
+   * Codex `hooks.json`). Default `true`; the session briefing passes `false`
+   * to skip their git spawns (`cleo doctor` keeps them).
+   */
+  readonly gitChecks?: boolean;
+}
+
+/**
+ * The project-level delivery surface `@cleocode/adapters` exports at
+ * `@cleocode/adapters/heavy-command-hook`. `@cleocode/core` loads it at run
+ * time (adapters builds on core, so core cannot import it statically) for
+ * `cleo init`, `cleo upgrade`, `cleo doctor` and the session briefing.
+ */
+export interface HeavyHookDeliveryApi {
+  /**
+   * Install, refresh or (mode `off`) remove CLEO's hook for every provider in
+   * use, each independently. Never throws: every provider gets an outcome.
+   */
+  readonly syncProjectHeavyCommandHooks: (
+    projectDir: string,
+    mode: HeavyCommandHookMode,
+    options?: HeavyHookDeliveryOptions,
+  ) => Promise<readonly HeavyHookDeliveryOutcome[]>;
+  /** Read-only: the hook's state for every provider. Never throws. */
+  readonly inspectProjectHeavyCommandHooks: (
+    projectDir: string,
+    mode: HeavyCommandHookMode,
+    options?: HeavyHookDeliveryOptions,
+  ) => readonly HeavyHookInspection[];
+  /**
+   * Whether the `cleo` on PATH (as the hook resolves it from `projectDir`)
+   * can answer the hook. Starts that `cleo` once. Never throws.
+   */
+  readonly probeHeavyHookCli: (
+    projectDir: string,
+    options?: HeavyHookDeliveryOptions,
+  ) => HeavyHookCliProbe;
+}

package/src/index.ts

@@ -514,7 +514,9 @@ export type {
   SagaAuditResult,
   SagaAuditViolation,
   SagaAuditViolationKind,
+  SupersededStoreBareAccount,
   SupersededStoreConflict,
+  SupersededStoreIdRemap,
   SupersededStoreReconcileOutcome,
   SupersededStoreReconcileResult,
   SupersededStoreTableCount,
@@ -780,6 +782,14 @@ export type {
   HeavyCommandHookProvider,
   HeavyCommandPlan,
   HeavyCommandSegment,
+  HeavyHookCliProbe,
+  HeavyHookCliState,
+  HeavyHookDeliveryApi,
+  HeavyHookDeliveryOptions,
+  HeavyHookDeliveryOutcome,
+  HeavyHookDeliveryStatus,
+  HeavyHookInspection,
+  HeavyHookInstallState,
   HookJsonValue,
   OpencodeHeavyCommandAnswer,
   PreToolUseHookInput,
@@ -2270,6 +2280,10 @@ export * from './render/index.js';
 export type {
   AdmissionResult,
   GovernorMode,
+  HeavyHeapSource,
+  HeavyLeverChange,
+  HeavyToolResourcePlan,
+  MemoryPressureReading,
   ResourceClass,
   ResourceDeferral,
   ResourceGrant,
@@ -2309,7 +2323,13 @@ export type {
 // === Row Identity Types (T12341 — uid merge keys) ===
 export type {
   RowIdentityKind,
+  RowIdentityNexusAnswer,
   RowIdentityRef,
+  RowIdentityRefillCounts,
+  RowIdentityRefillReport,
+  RowIdentityShareSignal,
+  RowIdentityShareSignalCode,
+  RowIdentityShareState,
   RowIdentitySpec,
   StoredRefUid,
   SymmetricEdge,
@@ -2450,6 +2470,14 @@ export {
   // Terminal state sets
   TERMINAL_TASK_STATUSES,
 } from './status-registry.js';
+// === Store restore (T13240 — restore cleo.db from a named snapshot or backup id) ===
+export type {
+  StoreRecoverResult,
+  StoreRestoreKept,
+  StoreRestoreResult,
+  StoreRestoreSource,
+  StoreRestoreVerification,
+} from './store-restore.js';
 // === Sub-Accessor Contracts (T9188) ===
 export type {
   AgentRegistrySubAccessor,
@@ -3009,6 +3037,8 @@ export type {
   NexusAccountErrorCode,
   NexusAccountMe,
   NexusAccountOrganization,
+  NexusAccountSetup,
+  NexusAccountSetupStep,
   NexusAccountStatus,
   NexusAccountUser,
   NexusDeviceEndOutcome,
@@ -3036,12 +3066,21 @@ export type {
   CloudPaging,
   CloudProjectShowResult,
   CloudProjectsResult,
+  CloudRetiredReplica,
   CloudStatusGlobalStore,
+  CloudStatusHolder,
   CloudStatusLocal,
   CloudStatusOfflineDetails,
   CloudStatusResult,
   CloudStatusSummary,
+  CloudStatusSync,
+  CloudStatusSyncStream,
   CloudStatusVerdict,
+  CloudSyncFact,
+  CloudSyncFlags,
+  CloudSyncKnown,
+  CloudSyncLag,
+  CloudSyncUnknown,
   CloudWarning,
   CloudWhoamiResult,
   NexusCloudCredential,
@@ -3065,6 +3104,7 @@ export {
   NEXUS_DEVICE_LIST_STATES,
   NEXUS_DEVICE_STATE_UNKNOWN,
   NEXUS_DEVICE_STATES,
+  NEXUS_FEATURE_PROJECT_INITIAL_KEY,
   NEXUS_FORBIDDEN_ERRORS,
   NEXUS_FORBIDDEN_REASONS,
   NEXUS_PAGE_LIMIT_MAX,
@@ -3092,9 +3132,24 @@ export {
   nexusCloudUserSchema,
   nexusCloudWhoamiSchema,
 } from './nexus-cloud.js';
+// === Guided first run of `cleo login nexus` (T13102) ===
+export {
+  NEXUS_FIRST_RUN_STATES,
+  type NexusFirstRunBackup,
+  type NexusFirstRunChoice,
+  type NexusFirstRunOffer,
+  type NexusFirstRunRestore,
+  type NexusFirstRunResult,
+  type NexusFirstRunState,
+  type NexusNamedProject,
+  type NexusProjectNameSource,
+} from './nexus-first-run.js';
 export {
   type CloudActivityItem,
   type CloudActivityResult,
+  type CloudConflict,
+  type CloudConflictResolveResult,
+  type CloudConflictsResult,
   type CloudLeaseReleaseResult,
   type CloudPushResult,
   type CloudRestoreResult,
@@ -3104,9 +3159,12 @@ export {
   type CloudVaultStatusResult,
   type CloudVaultTable,
   type CloudVaultTableDiff,
+  type CloudVerifyDeepCheck,
   type CloudVerifyResult,
+  NEXUS_REPLICA_RETIREMENT_REASONS,
   NEXUS_VAULT_LEASE_ROLE,
   type NexusActivityEvent,
+  type NexusReplicaRetirementReason,
   nexusActivityEventSchema,
   nexusActivityPageSchema,
   nexusLeaseAcquireSchema,