@cleocode/contracts 2026.9.22 → 2026.9.24

package/src/index.ts

@@ -362,6 +362,12 @@ export type {
   QueryTasksResult,
   TaskAuditLogQuery,
   TaskAuditLogRow,
+  TaskClaimedDetails,
+  TaskClaimGuard,
+  TaskClaimMode,
+  TaskClaimRequest,
+  TaskConflictChange,
+  TaskConflictDetails,
   TaskFieldUpdates,
   TaskPopulation,
   TaskQueryFilters,
@@ -808,6 +814,7 @@ export type {
   KnowledgeEvidenceRef,
   KnowledgeFileEvidence,
   KnowledgeHealth,
+  KnowledgeHealthSummary,
   KnowledgeRepairAction,
   KnowledgeRepairClass,
   KnowledgeRepairFinding,
@@ -1492,6 +1499,12 @@ export type {
   NexusDiscoverHit,
   NexusDiscoverParams,
   NexusDiscoverResult,
+  NexusFleetDevice,
+  NexusFleetDeviceSummary,
+  NexusFleetFlag,
+  NexusFleetGitSummary,
+  NexusFleetLocation,
+  NexusFleetProject,
   NexusFlowEntry,
   NexusFlowsParams,
   NexusFlowsResult,
@@ -1541,6 +1554,8 @@ export type {
   NexusProjectsCleanRemoval,
   NexusProjectsCleanResult,
   NexusProjectsCleanUnreadable,
+  NexusProjectsFleetParams,
+  NexusProjectsFleetResult,
   NexusProjectsListParams,
   NexusProjectsListResult,
   NexusProjectsRegisterParams,
@@ -1621,6 +1636,7 @@ export type {
   NexusWhyResult,
   NexusWikiParams,
 } from './operations/nexus.js';
+export { NEXUS_FLEET_SCHEMA_VERSION } from './operations/nexus.js';
 // === Nexus Scope Contracts (T9145 + T9146) ===
 export type {
   MetaWithNexusScope,
@@ -2500,6 +2516,7 @@ export type {
   SeverityAttestation,
   SignedSeverityAttestation,
   Task,
+  TaskClaim,
   TaskCreate,
   // T944 new axes (T9072: renamed TaskRole → TaskKind)
   TaskKind,
@@ -2703,6 +2720,7 @@ export type {
   ScoreFactor,
   ScoreTaskContext,
   ScoreTaskInput,
+  ScoreTaskKey,
   ScoreTaskResult,
 } from './tools/score-task-priority.js';
 // === Transport (low-level wire protocol) ===
@@ -2889,12 +2907,22 @@ export {
 export type {
   ChoiceDecisionAnswer,
   ChoiceDecisionQuestion,
+  DecideProfileConnection,
+  DecideProfileListResult,
+  DecideProfileProbe,
+  DecideProfileSummary,
+  DecideProfileUrlSource,
+  DecideProviderState,
   DecisionAnswer,
+  DecisionBatchItem,
   DecisionInstructions,
   DecisionJsonValue,
   DecisionOutcome,
   DecisionOutcomeSource,
+  DecisionProviderCapabilities,
   DecisionProviderConfig,
+  DecisionProviderKind,
+  DecisionProviderUsage,
   DecisionQuestion,
   DecisionQuestionType,
   DecisionRequest,
@@ -2907,7 +2935,11 @@ export type {
 export {
   choiceDecisionAnswerSchema,
   choiceDecisionQuestionSchema,
+  DECIDE_DEFAULT_PROFILE_NAME,
+  DECIDE_PROFILE_DEFAULT_URL,
+  DECIDE_PROFILE_NAME_PATTERN,
   DECISION_OUTCOME_SOURCES,
+  DECISION_PROVIDER_KINDS,
   DECISION_QUESTION_TYPES,
   DECISION_REQUEST_LIMITS,
   decisionAnswerSchema,
@@ -2915,14 +2947,54 @@ export {
   decisionOutcomeSchema,
   decisionOutcomeSourceSchema,
   decisionProviderConfigSchema,
+  decisionProviderKindSchema,
   decisionQuestionSchema,
   decisionQuestionTypeSchema,
   decisionRequestSchema,
   decisionStateSchema,
+  JEV_DEFAULT_BASE_URL,
+  JEV_MINIMUM_CAPABILITIES,
+  LAYAHOST_BASE_URL,
+  LAYAHOST_DEFAULT_MODEL,
   noulDecisionAnswerSchema,
   noulDecisionQuestionSchema,
   scoreDecisionAnswerSchema,
   scoreDecisionQuestionSchema,
 } from './decide.js';
+// T12662: decision-site registry (the decision ladder as code).
+export type {
+  DecisionRung,
+  DecisionSiteActivity,
+  DecisionSiteDefinition,
+  DecisionSiteGoLive,
+  DecisionSiteModeValue,
+  DecisionSiteOwnerEscalation,
+  DecisionSiteQuestionType,
+  DecisionSiteSummary,
+  DecisionSitesListResult,
+  DecisionSiteTextClass,
+} from './decide-sites.js';
+export { DECISION_RUNGS, DECISION_SITE_MODES } from './decide-sites.js';
 
+export type {
+  NexusAccountErrorCode,
+  NexusAccountMe,
+  NexusAccountOrganization,
+  NexusAccountStatus,
+  NexusAccountUser,
+  NexusLoginResult,
+  NexusLogoutResult,
+  NexusProjectLink,
+  NexusProjectLinkResult,
+  NexusSessionState,
+} from './nexus-account.js';
+export {
+  NEXUS_ACCOUNT_ERROR_CODES,
+  NEXUS_CLI_CLIENT_ID,
+  NEXUS_DEFAULT_API_URL,
+  NEXUS_LOGIN_TARGET,
+  nexusAccountMeSchema,
+  nexusAccountOrganizationSchema,
+  nexusAccountUserSchema,
+} from './nexus-account.js';
 export { isStorableTaskId, isTaskId, TASK_ID_REGEX, type TaskId } from './task-id.js';

package/src/knowledge-health.ts

@@ -258,6 +258,28 @@ export interface KnowledgeHealth {
   findings: KnowledgeRepairFinding[];
 }
 
+/**
+ * Orientation summary of {@link KnowledgeHealth} for envelopes that already
+ * carry the coverage object at their top level (`briefing.show`'s
+ * `knowledgeCoverage`, `focus.show`'s `coverage`).
+ *
+ * The coverage object is emitted once per envelope; this summary points at it
+ * through {@link KnowledgeHealthSummary.coverageRef} instead of repeating it
+ * (T12522). Every other field keeps the {@link KnowledgeHealth} meaning. The
+ * full assessment, coverage included, remains available from
+ * `cleo doctor knowledge`.
+ *
+ * @task T12522
+ */
+export interface KnowledgeHealthSummary extends Omit<KnowledgeHealth, 'coverage'> {
+  /**
+   * JSON Pointer, relative to the envelope's `data`, of the coverage object
+   * this summary describes — e.g. `/knowledgeCoverage` (briefing) or
+   * `/coverage` (focus). Prefix `/data` for `cleo ... --field`.
+   */
+  coverageRef: string;
+}
+
 /** Responsibility for resolving a knowledge defect. */
 export type KnowledgeRepairClass = 'automatic' | 'agent-resolvable' | 'owner-decision';
 

package/src/nexus-account.ts

@@ -0,0 +1,181 @@
+/**
+ * Cleo Nexus account contracts: the CLI's signed-in session with the Cleo
+ * Nexus API (device-code login, logout, status, project link).
+ *
+ * The API is a better-auth app: the device-code grant (RFC 8628) issues a
+ * session token that the bearer plugin accepts on every `/v1` route. These
+ * types describe what CLEO emits and persists about that session. None of
+ * them carries the token: results and status rows are secret-free by
+ * construction, so they are safe in LAFS envelopes and logs.
+ *
+ * Not part of `./cloud`: that directory mirrors the server's
+ * `@cleo-nexus/shared` contract one-to-one. The `/v1/account/me` subset
+ * below is read-only and client-side.
+ *
+ * This file is types + zod schemas + const data only (arch gate 10).
+ *
+ * @task T12712
+ * @epic T12322
+ */
+
+import { z } from 'zod';
+
+/** Production Cleo Nexus API origin. */
+export const NEXUS_DEFAULT_API_URL = 'https://api.cleocode.dev';
+
+/** The OAuth client id the Nexus API accepts for the device-code grant. */
+export const NEXUS_CLI_CLIENT_ID = 'cleo-cli';
+
+/**
+ * The reserved `cleo login` target for a Cleo Nexus account. It is checked
+ * before the LLM provider registry, so no provider can shadow it.
+ */
+export const NEXUS_LOGIN_TARGET = 'nexus';
+
+/** Stable error codes of the Nexus account flows. */
+export const NEXUS_ACCOUNT_ERROR_CODES = [
+  'E_NEXUS_INVALID_API_URL',
+  'E_NEXUS_NOT_SIGNED_IN',
+  'E_NEXUS_SESSION_EXPIRED',
+  'E_NEXUS_DEVICE_CODE_START_FAILED',
+  'E_NEXUS_UNTRUSTED_VERIFICATION_URI',
+  'E_NEXUS_DEVICE_CODE_EXPIRED',
+  'E_NEXUS_ACCESS_DENIED',
+  'E_NEXUS_DEVICE_CODE_FAILED',
+  'E_NEXUS_REVOKE_FAILED',
+  'E_NEXUS_REQUEST_FAILED',
+  'E_NEXUS_NOT_A_PROJECT',
+  'E_NEXUS_INVALID_LABEL',
+] as const;
+
+/** One of {@link NEXUS_ACCOUNT_ERROR_CODES}. */
+export type NexusAccountErrorCode = (typeof NEXUS_ACCOUNT_ERROR_CODES)[number];
+
+/** The signed-in user, as `/v1/account/me` reports it. */
+export const nexusAccountUserSchema = z.object({
+  id: z.string(),
+  email: z.string(),
+  name: z.string().nullable().optional(),
+});
+
+/** A user's organization membership, as `/v1/account/me` reports it. */
+export const nexusAccountOrganizationSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  slug: z.string().nullable().optional(),
+  role: z.string().optional(),
+  /** `true` for the personal organization created at sign-up. */
+  personal: z.boolean().optional(),
+});
+
+/**
+ * The subset of `GET /v1/account/me` the CLI reads. Unknown fields are
+ * ignored (zod strips them), so the server can grow the payload freely.
+ */
+export const nexusAccountMeSchema = z.object({
+  user: nexusAccountUserSchema,
+  organizations: z.array(nexusAccountOrganizationSchema).default([]),
+});
+
+/** Parsed `GET /v1/account/me` subset. */
+export type NexusAccountMe = z.infer<typeof nexusAccountMeSchema>;
+
+/** A signed-in user (no secrets). */
+export type NexusAccountUser = z.infer<typeof nexusAccountUserSchema>;
+
+/** An organization reference (no secrets). */
+export type NexusAccountOrganization = z.infer<typeof nexusAccountOrganizationSchema>;
+
+/**
+ * Session state for one API origin.
+ *
+ * - `signed-in`      — a token is stored and, when checked live, the API accepted it.
+ * - `unverified`     — a token is stored but the API could not be reached.
+ * - `expired`        — the API answered 401: the session expired or was revoked.
+ * - `not-signed-in`  — no token is stored for the origin.
+ */
+export type NexusSessionState = 'signed-in' | 'unverified' | 'expired' | 'not-signed-in';
+
+/** Secret-free status row for `cleo status` and `cleo auth list`. */
+export interface NexusAccountStatus {
+  /** API origin the row describes, e.g. `https://api.cleocode.dev`. */
+  apiUrl: string;
+  /** Session state. */
+  state: NexusSessionState;
+  /** Signed-in user's email, when known. */
+  email: string | null;
+  /** Primary organization (the personal one, else the first), when known. */
+  organization: string | null;
+  /** ISO time the stored token expires, when the server said so. */
+  expiresAt: string | null;
+  /** One human line: "signed in as a@b.c (Org)", "session expired", "not signed in". */
+  summary: string;
+}
+
+/** Result of `cleo login nexus` (never carries the token). */
+export interface NexusLoginResult {
+  /** API origin the session belongs to. */
+  apiUrl: string;
+  /** The signed-in user, when `/v1/account/me` answered. */
+  user: NexusAccountUser | null;
+  /** Primary organization, when known. */
+  organization: NexusAccountOrganization | null;
+  /** ISO time the token expires, when the server said so. */
+  expiresAt: string | null;
+  /** Absolute path of the credential store the token was written to. */
+  credentialsPath: string;
+  /** Non-fatal problems, e.g. the account lookup failed after a good login. */
+  warnings: string[];
+}
+
+/** Result of `cleo logout nexus`. */
+export interface NexusLogoutResult {
+  /** API origin the session belonged to. */
+  apiUrl: string;
+  /** `true` when a stored token existed and was deleted locally. */
+  removedLocally: boolean;
+  /**
+   * Server-side revocation outcome: `revoked` (the API ended the session),
+   * `already-invalid` (the API reported it was already gone), `failed`
+   * (network or server error: the local token is deleted anyway), or
+   * `skipped` (nothing was stored).
+   */
+  revocation: 'revoked' | 'already-invalid' | 'failed' | 'skipped';
+  /** Non-fatal problems. */
+  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.
+ */
+export interface NexusProjectLink {
+  /** API origin the project is registered with. */
+  apiUrl: string;
+  /** The local CLEO project id (the tracked `.cleo/project-id`). */
+  localProjectId: string;
+  /** The project id the server returned (the server keys projects by the CLEO id). */
+  remoteProjectId: string;
+  /** Owning organization id. */
+  organizationId: string;
+  /** Plaintext display-name label the server holds, or `null` when it has none. */
+  label: string | null;
+  /** Journal stream id for the project. */
+  streamId: string;
+  /** ISO time of the last successful link. */
+  linkedAt: string;
+}
+
+/** Result of `cleo project link`. */
+export interface NexusProjectLinkResult {
+  /** The persisted binding. */
+  link: NexusProjectLink;
+  /**
+   * `true` when the server already had this project id (HTTP 200; its label
+   * was updated to the one sent), `false` when this call registered it (201).
+   * Linking is idempotent either way.
+   */
+  alreadyLinked: boolean;
+  /** Absolute path of the local binding file. */
+  linkPath: string;
+}

package/src/operations/admin.ts

@@ -1648,6 +1648,11 @@ export interface AdminBackupMutateParams {
   file?: string;
   /** Preview the restore without writing (restore.file only). */
   dryRun?: boolean;
+  /**
+   * Allow a restore run from inside a git worktree to overwrite the owning
+   * project's live store (T12680). Without it such a restore is refused.
+   */
+  confirmOwnerStore?: boolean;
 }
 
 /** Result of `admin.backup` mutate (create action). */

package/src/operations/focus.ts

@@ -15,7 +15,7 @@
 import type {
   KnowledgeCoverage,
   KnowledgeDiagnostic,
-  KnowledgeHealth,
+  KnowledgeHealthSummary,
 } from '../knowledge-health.js';
 import type { MviDigest } from '../mvi.js';
 import type { AttentionScopeKind } from './attention.js';
@@ -195,8 +195,12 @@ export interface FocusBrainContext {
 export interface FocusShowResult {
   /** Assessed graph coverage; absence on legacy responses is not healthy coverage. */
   coverage?: KnowledgeCoverage;
-  /** Bounded deterministic maintenance and sourced repair findings for the foreground caller. */
-  knowledgeHealth?: KnowledgeHealth;
+  /**
+   * Bounded deterministic maintenance and sourced repair findings for the
+   * foreground caller. Its coverage is not repeated: `coverageRef` is
+   * `/coverage`, the single coverage object of this result (T12522).
+   */
+  knowledgeHealth?: KnowledgeHealthSummary;
   /** Failed auxiliary reads are distinct from successfully empty sources. */
   sourceDiagnostics?: Record<string, KnowledgeDiagnostic>;
   /** Core identity of the focused entity. */

package/src/operations/nexus-scope-map.ts

@@ -473,6 +473,15 @@ export const NEXUS_SCOPE_MAP = {
     stores: ['nexus-registry'],
     requiresProject: false,
   },
+  'projects.fleet': {
+    op: 'projects.fleet',
+    description:
+      'Fleet view: every project, where it lives on each device, and its last recorded git state (read-only).',
+    scope: 'global',
+    effect: 'read',
+    stores: ['nexus-registry'],
+    requiresProject: false,
+  },
   'projects.register': {
     op: 'projects.register',
     description: 'Register a project (alias: register).',